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 #

Início rápido #

// event open da janela

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

// Depois os seus mosaicos, cada um com o seu tamanhouo_tiles.of_add_tile(/*keys*/ "office/clients",   /*label*/ "Clientes", /*icon_file*/ "mono:img\clients.svg",   /*size*/ "medium")
uo_tiles.of_add_tile(/*keys*/ "office/invoices",  /*text*/ "Faturas",  /*image*/ "mono:img\factures.svg",  /*size*/ "medium")
uo_tiles.of_add_tile(/*keys*/ "office/stock",     /*text*/ "Stock",    /*image*/ "mono:img\stock.svg",     /*size*/ "small")

// event ue_tile_clicked de uo_tiles: (string as_keys)
choose case as_keys
    case "office/clients"  ; open(w_clients)
    case "office/invoices" ; open(w_invoices)
    case "office/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_tiles.of_tile(/*keys*/ "office/invoices").is_badge = "12"

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

Propriedades #

Métodos #

Num grupo — n_pbt_tilesbox_group #

Num mosaico — n_pbt_tilesbox_tile #

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 #

Eventos #

Exemplos #

Tamanhos misturados num mesmo grupo #

// Partir de uma caixa vazia, com um grupo
uo_tiles.of_clear()
uo_tiles.of_add_group(/*key*/ "home", /*title*/ "Início")

// Quatro mosaicos, de quatro tamanhos
uo_tiles.of_add_tile(/*keys*/ "home/dashboard", /*text*/ "Painel de controlo", /*image*/ "mono:img\chart.svg",  /*size*/ "large")
uo_tiles.of_add_tile(/*keys*/ "home/clients", /*text*/ "Clientes",           /*image*/ "mono:img\users.svg",  /*size*/ "medium")
uo_tiles.of_add_tile(/*keys*/ "home/agenda",  /*text*/ "Agenda",             /*image*/ "mono:img\cal.svg",    /*size*/ "wide")
uo_tiles.of_add_tile(/*keys*/ "home/help",    /*text*/ "Ajuda",              /*image*/ "mono:img\help.svg",   /*size*/ "small")

Emblema, cor e mosaico animado #

// Local variables
n_pbt_tilesbox_tile lnv_tile

// Um emblema assinala um numero de elementos em espera
uo_tiles.of_tile(/*keys*/ "home/clients").is_badge = String(ll_new_count)

// Vermelho quando o atraso se torna critico, cor do tema caso contrario (-1)
if ll_new_count > 50 then
    uo_tiles.of_tile(/*keys*/ "home/clients").il_badge_color = RGB(/*red*/ 200, /*green*/ 30, /*blue*/ 30)
else
    uo_tiles.of_tile(/*keys*/ "home/clients").il_badge_color = -1
end if

// Uma cor propria destaca um mosaico : fundo, texto e aquilo em que cada um
// se torna sob o ponteiro
lnv_tile = uo_tiles.of_tile(/*keys*/ "home/dashboard")
lnv_tile.il_back_color = RGB(/*red*/ 0, /*green*/ 103, /*blue*/ 192)
lnv_tile.il_back_color_hover = RGB(/*red*/ 0, /*green*/ 80, /*blue*/ 150)
lnv_tile.il_text_color = RGB(/*red*/ 255, /*green*/ 255, /*blue*/ 255)

// Mosaico ANIMADO: cada face adicionada desfila a sua vez no mosaico. Uma
// face adiciona-se a partir do COMPONENTE, no endereco do mosaico
uo_tiles.of_clear_live_items(/*keys*/ "home/agenda")
uo_tiles.of_add_live_item(/*keys*/ "home/agenda", /*text*/ "3 reuniões hoje")
uo_tiles.of_add_live_item(/*keys*/ "home/agenda", /*text*/ "Reunião de equipa às 14h00")
uo_tiles.of_add_live_item(/*keys*/ "home/agenda", /*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_tiles.of_tile(/*keys*/ "home/dashboard").is_live_text = "[b]48[/b] encomendas do dia"

Grupos recolhíveis #

// Local variables
n_pbt_tilesbox_group lnv_admin

// Um grupo e os seus dois mosaicos, e depois um handle do grupo
uo_tiles.of_add_group(/*key*/ "admin", /*title*/ "Administração")
uo_tiles.of_add_tile(/*keys*/ "admin/users",  /*text*/ "Utilizadores", /*image*/ "mono:img\users.svg", /*size*/ "medium")
uo_tiles.of_add_tile(/*keys*/ "admin/params", /*text*/ "Parâmetros", /*image*/ "mono:img\gear.svg",  /*size*/ "medium")
lnv_admin = uo_tiles.of_group(/*key*/ "admin")

// 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_profile = "ADMIN")

// event ue_group_toggled de uo_tiles
if as_key = "admin" and not ab_collapsed then of_trace("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_tiles.ib_show_group_headers = false
uo_tiles.of_add_group(/*key*/ "all", /*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. Pelo teclado, o mosaico com o foco avança ou recua uma posição com Ctrl+Esquerda/Direita (no sentido de leitura: invertido da direita para a esquerda) e passa para o grupo anterior ou seguinte com Ctrl+Cima/Baixo — o mesmo ue_tile_moved, as mesmas recusas (chave já tomada, grupo desativado ou recolhido). A tecla Tab só para uma vez por grupo: as setas percorrem os mosaicos.

// Deixar o utilizador reordenar os mosaicos : false por omissao, e preciso pedir
uo_tiles.ib_reorderable = true

// event ue_tile_moved de uo_tiles
// as_keys = de onde vem, as_to_key = para onde vai, al_index = posicao
n_pbt_utils lnv_utils   // autoinstantiate: nada a criar, nada a destruir
if lnv_utils.of_parent(/*keys*/ as_keys) <> as_to_key then
    of_trace("Mosaico " + lnv_utils.of_leaf(/*keys*/ as_keys) + " deslocado de " + lnv_utils.of_parent(/*keys*/ as_keys) + " para " + as_to_key)
end if

// event ue_layout_changed de uo_tiles: conservar a disposicao escolhida
is_layout_json = as_layout_json

// Na abertura seguinte: repor o ecra tal como o utilizador o tinha arrumado
if is_layout_json <> "" then uo_tiles.of_set_layout(/*state_json*/ is_layout_json)

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

// Freeze the screen : the tiles stay where they are
uo_tiles.ib_reorderable = false

Reorganizar a partir do código #

// Colocar o mosaico "help" no inicio do seu grupo (posicoes contadas a partir de 1)
uo_tiles.of_move_tile(/*keys*/ "home/help", /*index*/ 1)

// Inserir um novo mosaico na segunda posicao
uo_tiles.of_insert_tile(/*keys*/ "home/quotes", /*text*/ "Orçamentos", /*index*/ 2)

// Retirar um mosaico sem mexer no resto
uo_tiles.of_remove_tile(/*keys*/ "home/help")

// Cada chamada devolve -5 se o endereco nao nomear nada (ou, na insercao, uma chave ja tomada)

Reagir ao clique com o botão direito #

// event ue_tile_context de uo_tiles: (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_target_group = lnv_utils.of_parent(/*keys*/ as_keys)
is_target_tile = lnv_utils.of_leaf(/*keys*/ as_keys)
of_open_tile_menu(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.

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.

← Referência dos componentes · Índice do guia