tilesbox — `u_pbt_tilesbox` #

← Referência dos componentes · Índice do guia

Painel de mosaicos agrupados ao estilo de um ecrã inicial: quatro tamanhos de mosaico, cores, emblemas, mosaicos animados, grupos recolhíveis e reorganização com o rato.

▶ Ver ao vivo — Aplicação de demonstração, mosaico Tiles box: a pré-visualização, o código que o produz e esta página, lado a lado.

Em resumo #

Userobject	`u_pbt_tilesbox`
Classes de items	`n_pbt_tilesbox_group` (grupo) → `n_pbt_tilesbox_tile` (mosaico)
Serve para	Oferecer um ecrã inicial ou um lançador de funções: mosaicos clicáveis, legíveis à distância, arrumados por tema
Opções opt-in	—

Início rápido #

// event open da janela

// Um mosaico adiciona-se no seu ENDERECO : o grupo, e depois o seu proprio identificador
uo_tuiles.of_add_group(/*key*/ "gestion", /*title*/ "Gestão")

uo_tuiles.of_add_tile(/*keys*/ "gestion/clients",   /*label*/ "Clientes", /*icon_file*/ "mono:img\clients.svg",   /*size*/ "medium")
uo_tuiles.of_add_tile(/*keys*/ "gestion/factures",  /*label*/ "Faturas",  /*icon_file*/ "mono:img\factures.svg",  /*size*/ "medium")
uo_tuiles.of_add_tile(/*keys*/ "gestion/stock",     /*label*/ "Stock",    /*icon_file*/ "mono:img\stock.svg",     /*size*/ "small")

// event ue_tile_clicked de uo_tuiles: (string as_keys)
choose case as_keys
    case "gestion/clients"  ; open(w_clients)
    case "gestion/factures" ; open(w_factures)
    case "gestion/stock"    ; open(w_stock)
end choose

O modelo: grupos e mosaicos #

O painel contém grupos, cada um com o seu título e o seu cabeçalho recolhível. Os mosaicos pertencem a um grupo: o respetivo identificador só é único dentro desse grupo. O acesso passa, portanto, sempre pelo caminho completo. As adições vivem no componente: um handle só transporta propriedades.

// Caminho obrigatorio: grupo e depois mosaico
uo_tuiles.of_tile("gestion/factures").is_badge = "12"

Os eventos transportam igualmente o endereço completo (as_keys, o grupo seguido do mosaico). Ver Base comum · Os items.

Propriedades #

Propriedade	Tipo	Predefinição	Função
`ib_reorderable`	boolean	`false`	Autoriza o utilizador a deslocar os mosaicos com o rato (aciona `ue_tile_moved`)
`is_scroll`	string	`SCROLL_VERTICAL`	Sentido de deslocamento: `SCROLL_VERTICAL` (os mosaicos mudam de linha) ou `SCROLL_HORIZONTAL` (colunas ao estilo de um ecrã inicial)
`ib_show_group_headers`	boolean	`true`	`false` oculta os cabeçalhos de grupo. Útil quando o painel contém um único grupo: não há nada a nomear e o cabeçalho apenas consome altura. Sem cabeçalho deixa de haver galão: os grupos apresentam-se sempre expandidos
`ii_anim_duration`	integer	`180`	Duração em milissegundos da animação de recolher / expandir um grupo; `0` = instantâneo
`ii_tile_unit`	integer	`0`	Tamanho base de um mosaico, em pixels: cada formato (pequeno, médio, largo, grande) é um múltiplo dele, pelo que um valor torna todo o quadro mais denso ou mais arejado. `0` devolve-o ao tema
`ii_badge_size`	integer	`0`	Altura dos emblemas dos mosaicos em píxeis, para toda a caixa (`0` = o tamanho que vem do tema). O tamanho da letra acompanha sozinho. A cor de um emblema pertence ao mosaico porque significa alguma coisa; o seu tamanho não
`is_theme_style`	string	`fluent`	Estilo visual do componente (constantes `THEME_STYLE_*`)
`is_theme_mode`	string	`light`	Variante clara ou escura (constantes `THEME_MODE_*`)
`il_theme_accent`	long	`-1`	Cor de destaque deste componente (`-1` = destaque do tema)
`is_tooltip`	string	`""`	Tooltip simples apresentado ao passar sobre o componente
`is_super_tooltip_title`	string	`""`	Título do tooltip enriquecido (prevalece sobre `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Texto do tooltip enriquecido (aceita marcação enriquecida)
`is_super_tooltip_image`	string	`""`	Imagem do tooltip enriquecido

Métodos #

Método	Função
`of_group (string as_key)` → `n_pbt_tilesbox_group`	Devolve o handle de um grupo (criado no primeiro acesso)
`of_add_group (string as_key, string as_title)` → `long`	Adiciona um grupo e devolve `0` (`-5` perante um argumento inválido, `-2` se o componente não estiver criado)
`of_add_tile (string as_keys, string as_text, string as_image, string as_size)` → `long`	Adiciona um mosaico no seu endereço, `"gestion/clients"`: o grupo onde aterra, e depois o seu próprio identificador. Devolve `0` (`-5` perante um argumento inválido, `-2` se o componente não estiver criado) — `-5` se o pai não for um grupo. Uma sobrecarga omite o ícone e o tamanho
`of_tile (string as_keys)` → `n_pbt_tilesbox_tile`	Devolve o handle de um mosaico, pelo seu endereço (criado no primeiro acesso)
`of_add_live_item (string as_keys, string as_text)` → `long`	Adiciona uma face à banda animada de um mosaico, no seu endereço; a partir de duas faces, o mosaico fá-las desfilar. Devolve `0` depois de aplicado, `-5` perante um argumento inválido (chave vazia, endereço errado), `-2` se o componente não estiver criado
`of_clear_live_items (string as_keys)` → `long`	Esvazia a banda animada de um mosaico: deixa de desfilar e volta à sua face simples. Devolve `0` depois de aplicado, `-5` perante um argumento inválido (chave vazia, endereço errado), `-2` se o componente não estiver criado
`of_remove_group (string as_key)`	Elimina um grupo e todos os seus mosaicos. Devolve `0` depois de aplicado, `-2` se o componente não estiver criado
`of_insert_tile (string as_keys, string as_text, integer ai_index)`	Insere um mosaico numa posição precisa dentro do seu grupo (posição contada a partir de 0). Devolve `0` depois de aplicado, `-5` perante um argumento inválido (chave vazia, endereço errado), `-2` se o componente não estiver criado
`of_insert_tile (string as_keys, string as_text, string as_image, string as_size, integer ai_index)`	Idem, com o ícone e o tamanho (`small` / `medium` / `wide` / `large`): um mosaico é uma imagem com uma etiqueta por baixo, e o seu tamanho vê-se na grelha. Devolve `0` depois de aplicado, `-5` perante um argumento inválido (chave vazia, endereço errado), `-2` se o componente não estiver criado
`of_move_tile (string as_keys, integer ai_index)`	Desloca um mosaico existente para outra posição do seu grupo, conservando o respetivo estado. Devolve `0` depois de aplicado, `-5` perante um argumento inválido (chave vazia, endereço errado), `-2` se o componente não estiver criado
`of_remove_tile (string as_keys)`	Elimina um único mosaico, o resto do painel é preservado. Devolve `0` depois de aplicado, `-5` perante um argumento inválido (chave vazia, endereço errado), `-2` se o componente não estiver criado
`of_clear ( )`	Esvazia o painel (grupos e mosaicos). Devolve `0` depois de aplicado, `-2` se o componente não estiver criado
`of_get_layout ( )`	Relê a disposição atual em JSON: grupos, mosaicos, ordem e tamanhos. Guarde-a e devolva-a com `of_set_layout`
`of_set_layout (string as_state_json)`	Repõe uma disposição lida com `of_get_layout` ou recebida com `ue_layout_changed`. Devolve `0` depois de aplicado, `-5` perante um argumento inválido (chave vazia, endereço errado), `-2` se o componente não estiver criado
`of_reset ( )`	Esvazia o conteúdo e repõe as propriedades na respetiva predefinição. Devolve `0` depois de aplicado, `-2` se o componente não estiver criado

Num grupo — `n_pbt_tilesbox_group` #

Membro	Tipo	Predefinição	Função
`is_title`	string	`""`	Título apresentado no cabeçalho, formatação com etiquetas aceite
`ib_collapsed`	boolean	`false`	Grupo recolhido: os seus mosaicos ficam ocultos sob o cabeçalho
`ib_enabled`	boolean	`true`	Grupo inteiro esbatido e inerte
`ib_visible`	boolean	`true`	Grupo oculto, sem ser eliminado do modelo

Num mosaico — `n_pbt_tilesbox_tile` #

Membro	Tipo	Predefinição	Função
`is_title`	string	`""`	Texto mostrado no mosaico. Posto por `of_add_tile`; escrevê-lo aqui altera-o, lê-lo diz o que o mosaico mostra agora
`is_image`	string	`""`	Ícone do mosaico (caminho em disco ou `resources.dll:nome`). Uma cadeia vazia retira o ícone
`is_size`	string	`SIZE_MEDIUM`	Tamanho: `SIZE_SMALL`, `SIZE_MEDIUM`, `SIZE_WIDE`, `SIZE_LARGE`
`il_back_color` · `il_text_color`	long	`-1`	Fundo e texto deste mosaico, como `RGB(r,g,b)` (`-1` = o que o tema der)
`il_back_color_hover` · `il_text_color_hover`	long	`-1`	Os mesmos dois, mas sob o ponteiro
`is_badge`	string	`""`	Emblema apresentado no canto do mosaico (um contador, um estado curto)
`il_badge_color`	long	`0`	Fundo do emblema, em RGB do PowerBuilder (`0` = a cor que vem do tema)
`is_live_text`	string	`""`	Texto sobreposto ao mosaico, formatação com etiquetas aceite
`ib_enabled`	boolean	`true`	Mosaico esbatido e não clicável
`ib_visible`	boolean	`true`	Mosaico oculto, sem ser retirado do seu grupo

Os ícones aceitam todas as formas reconhecidas pela biblioteca: caminho, mono:, tint:, recurso de DLL. Num mosaico grande, é preferível uma imagem nítida em alta definição ou um SVG.

Os quatro tamanhos #

Tamanho	Espaço ocupado	Utilização típica
`small`	1 célula	Atalho secundário; a etiqueta não é apresentada, o tooltip assume esse papel
`medium`	2 × 2 células	Tamanho de referência: ícone e etiqueta
`wide`	4 × 2 células	Mosaico alongado, ideal para um texto animado
`large`	4 × 4 células	Mosaico de destaque do ecrã

Eventos #

Evento	Acionado quando
`ue_tile_clicked (string as_keys)`	Um mosaico é clicado
`ue_tile_moved (string as_keys, string as_to_keys, long al_index)`	Um mosaico foi deslocado: `as_keys` é o endereço de partida, `as_to_keys` o grupo de destino, `al_index` a nova posição
`ue_group_toggled (string as_key, boolean ab_collapsed)`	Um grupo é recolhido ou expandido a partir do seu cabeçalho
`ue_tile_context (string as_keys)`	Clique com o botão direito num mosaico
`ue_tile_resized (string as_keys, string as_size)`	O tamanho de um mosaico mudou; `as_size` transporta o novo tamanho
`ue_layout_changed (string as_layout_json)`	A disposição mudou — o utilizador moveu ou redimensionou um mosaico. Transporta a disposição inteira, não apenas o que se moveu
`ue_ready ( )`	O componente terminou o carregamento; tudo o que foi enviado antes foi reproduzido
`ue_runtime_missing ( )`	O runtime WebView2 está ausente: o componente permanece vazio
`ue_bg_color (long al_color)`	O componente calculou a cor de fundo do respetivo tema; o userobject já a adotou (`backcolor`)

Exemplos #

Tamanhos misturados num mesmo grupo #


uo_tuiles.of_clear()
uo_tuiles.of_add_group(/*key*/ "accueil", /*title*/ "Início")

uo_tuiles.of_add_tile(/*keys*/ "accueil/tableau", /*label*/ "Painel de controlo", /*icon_file*/ "mono:img\chart.svg",  /*size*/ "large")
uo_tuiles.of_add_tile(/*keys*/ "accueil/clients", /*label*/ "Clientes",           /*icon_file*/ "mono:img\users.svg",  /*size*/ "medium")
uo_tuiles.of_add_tile(/*keys*/ "accueil/agenda",  /*label*/ "Agenda",             /*icon_file*/ "mono:img\cal.svg",    /*size*/ "wide")
uo_tuiles.of_add_tile(/*keys*/ "accueil/aide",    /*label*/ "Ajuda",              /*icon_file*/ "mono:img\help.svg",   /*size*/ "small")

Emblema, cor e mosaico animado #

n_pbt_tilesbox_tile lnv_tuile

// Um emblema assinala um numero de elementos em espera
uo_tuiles.of_group("accueil").of_tile("clients").is_badge = String(ll_nouveaux)

// Vermelho quando o atraso se torna critico, cor do tema caso contrario (0)
if ll_nouveaux > 50 then
    uo_tuiles.of_group("accueil").of_tile("clients").il_badge_color = RGB(200, 30, 30)
else
    uo_tuiles.of_group("accueil").of_tile("clients").il_badge_color = 0
end if

// Uma cor propria destaca um mosaico : fundo, texto e aquilo em que cada um
// se torna sob o ponteiro
lnv_tuile = uo_tuiles.of_group("accueil").of_tile("tableau")
lnv_tuile.il_back_color = RGB(0, 103, 192)
lnv_tuile.il_back_color_hover = RGB(0, 80, 150)
lnv_tuile.il_text_color = RGB(255, 255, 255)

// Mosaico ANIMADO: cada face adicionada desfila a sua vez no mosaico
lnv_tuile = uo_tuiles.of_group("accueil").of_tile("agenda")
lnv_tuile.of_clear_live_items()
lnv_tuile.of_add_live_item(/*text*/ "3 reuniões hoje")
lnv_tuile.of_add_live_item(/*text*/ "Reunião de equipa às 14h00")
lnv_tuile.of_add_live_item(/*text*/ "2 lembretes em atraso")

Um texto fixo em vez de um desfile #

// is_live_text coloca UM texto permanente no mosaico (formatacao com etiquetas aceite)
uo_tuiles.of_group("accueil").of_tile("tableau").is_live_text = "[b]48[/b] encomendas do dia"

Grupos recolhíveis #


uo_tuiles.of_add_group(/*key*/ "admin", /*title*/ "Administração")
uo_tuiles.of_add_tile(/*keys*/ "admin/users",  /*label*/ "Utilizadores", /*icon_file*/ "mono:img\users.svg", /*size*/ "medium")
uo_tuiles.of_add_tile(/*keys*/ "admin/params", /*label*/ "Parâmetros",   /*icon_file*/ "mono:img\gear.svg",  /*size*/ "medium")

// Este grupo comeca recolhido: o utilizador abre-o se precisar
lnv_admin.ib_collapsed = true

// Um grupo inteiro pode tambem ser esbatido consoante os direitos
lnv_admin.ib_enabled = (is_profil = "ADMIN")

// event ue_group_toggled de uo_tuiles
if as_keys = "admin" and not ab_collapsed then of_tracer("Abertura do painel de administração")

Um painel de grupo único, sem cabeçalho #

// Um so grupo nao tem nada a nomear: o seu cabecalho apenas consome altura.
// Sem cabecalho, tambem deixa de haver galao: os mosaicos ficam sempre visiveis.
uo_tuiles.ib_show_group_headers = false
uo_tuiles.of_add_group(/*key*/ "tout", /*title*/ "")

Deslocar um mosaico entre dois grupos #

Com ib_reorderable = true, o utilizador arrasta um mosaico para onde quiser, incluindo de um grupo para outro. O evento ue_tile_moved fornece os dois grupos e a nova posição.

uo_tuiles.ib_reorderable = true    // false por omissao : e preciso pedir

// event ue_tile_moved de uo_tuiles
// as_keys = de onde vem, as_to_keys = para onde vai, al_index = posicao
n_pbt_utils lnv_utils   // autoinstantiate: nada a criar, nada a destruir
if as_keys <> as_to_keys then
    of_tracer("Mosaico " + lnv_utils.of_leaf(as_keys) + " deslocado de " + lnv_utils.of_parent(as_keys) + " para " + as_to_keys)
end if
uo_tuiles.of_get_layout()    // solicitar a disposicao para a conservar

// event ue_layout_changed de uo_tuiles: conservar a disposicao escolhida
is_disposition = as_layout_json

// Na abertura seguinte: repor o ecra tal como o utilizador o tinha arrumado
if is_disposition <> "" then uo_tuiles.of_set_layout(is_disposition)

Para fixar o ecrã, basta desativar a reorganização:

uo_tuiles.ib_reorderable = false

Reorganizar a partir do código #

// Colocar o mosaico "aide" no inicio do seu grupo (posicoes contadas a partir de 0)
uo_tuiles.of_move_tile(/*group*/ "accueil", /*key*/ "aide", /*index*/ 0)

// Inserir um novo mosaico na segunda posicao
uo_tuiles.of_insert_tile(/*group*/ "accueil", /*key*/ "devis", /*text*/ "Orçamentos", /*index*/ 1)

// Retirar um mosaico sem mexer no resto
uo_tuiles.of_remove_tile(/*group*/ "accueil", /*key*/ "aide")

Reagir ao clique com o botão direito #

// event ue_tile_context de uo_tuiles: (as_keys)
// Reter o mosaico visado e abrir em seguida o seu proprio menu contextual
n_pbt_utils lnv_utils   // autoinstantiate: nada a criar, nada a destruir
// Um so endereco : dividi-lo se as duas metades forem precisas.
is_groupe_vise = lnv_utils.of_parent(as_keys)
is_tuile_visee = lnv_utils.of_leaf(as_keys)
of_ouvrir_menu_tuile(PointerX(), PointerY())

Boas práticas #

Um único mosaico large por ecrã é suficiente: é o ponto de entrada principal, o resto deve manter-se legível.
Os mosaicos small não apresentam a sua etiqueta — o tooltip do item deve ser preenchido sistematicamente.
il_back_color deve ser reservado aos mosaicos que precisam de sobressair: para além de duas ou três cores, o ecrã perde a sua hierarquia. E se puser um fundo claro, ponha também il_text_color — o texto do tema não é garantidamente legível por cima.
É preferível of_add_live_item (desfile) a is_live_text (texto fixo) quando há várias informações a transmitir no mesmo mosaico.
Se a reorganização for deixada ativa, a disposição deve ser conservada através de of_get_layout / ue_layout_changed e of_set_layout reexecutado na abertura.
Devem utilizar-se ib_visible e ib_enabled (grupo ou mosaico) para adaptar o painel aos direitos do utilizador, em vez de o reconstruir.
Quando falta espaço para mosaicos, é preferível a navegação lateral compacta da listbar; para as ações frequentes, a toolbar.

Herdado da base comum #

Estes membros existem em todos os componentes visuais — não são próprios deste. São detalhados uma só vez, nos capítulos transversais; esta tabela apenas diz onde os ler.

Membros	Função	Detalhado em
`of_count` · `of_keys_at` · `of_has`	Percorrer o que o componente contém	3.2 Os items
`of_reset`	Repor o componente a zero	3.6 Repor um componente a zero: `of_reset()`
`of_register_shortcut` · `of_clear_shortcuts`	Atalhos de teclado do componente	3.5 Os atalhos de teclado
`of_is_created` · `of_is_ready` · `of_get_last_error`	Se nasceu, se está pronto, o que falhou	3.7 Diagnóstico
`of_save_as_png` · `of_save_as_jpg`	Exportar a renderização como imagem	3.8 Exportar a representação como imagem
`of_set_redraw`	Agrupar as alterações num único repinte	3.10 Boas práticas
`of_preload_icons`	Ícones mostrados sem atraso	Apresentação instantânea: `of_icon`
`of_set_translation`	Traduzir uma legenda do componente	5.2 Adaptar uma etiqueta: `of_set_translation`
`of_focus_webview`	Dar o foco ao componente	6.4 Teclado e focus
`of_print` · `of_print_to_pdf`	Imprimir, ou escrever um PDF	6.9 Imprimir

Duas ajudas não são herdadas: of_icon e of_escape_markup vivem em n_pbt_utils. Declare um — n_pbt_utils lnv_utils, nada a criar — e chame-as nele.