breadcrumb — `u_pbt_breadcrumb` #

← Referência dos componentes · Índice do guia

Trilho de navegação: o caminho clicável que diz ao utilizador onde está, e que o leva de volta com um clique a qualquer nível acima.

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

Em resumo #

Userobject	`u_pbt_breadcrumb`
Classe dos itens	`n_pbt_breadcrumb_item` (`of_item(endereço)`) · `n_pbt_breadcrumb_child` (`of_child(endereço)`)
Serve para	Dizer onde se está numa hierarquia, e permitir sair dela para cima
Princípio	O senhor descreve o caminho; a dobragem, o menu e a paginação são nossos

Início rápido #

// Sempre que o utilizador desce um nivel
uo_crumbs.of_add_item(/*keys*/ "home",                /*text*/ "H")
uo_crumbs.of_add_item(/*keys*/ "home/clients",        /*text*/ "C")
uo_crumbs.of_add_item(/*keys*/ "home/clients/dupont", /*text*/ "D")

// O ultimo acrescentado passa a ser o local actual, e e clicavel

Um segmento é nomeado pelo seu endereço: as chaves desde a raiz, unidas por / — "home/clients/dupont". Uma chave nua já não chega assim que se repete em dois níveis do mesmo trilho: o componente recusa então adivinhar, em vez de o levar para outro lado.

É exactamente o que ue_item_clicked lhe devolve, e exactamente o que of_truncate, of_item ou of_add_child voltam a receber: o que recebe reinjecta-se tal e qual.

Um clique comunica, não corta #

Clicar num segmento não encurta o trilho. Subir significa deixar um ecrã, e deixar um ecrã quer muitas vezes dizer gravar primeiro — o que nenhum clique pode decidir. O componente diz-lhe o que foi clicado; quem corta é o senhor, através de of_truncate, assim que as suas verificações passarem.

É a mesma divisão de papéis da stepbar, e pela mesma razão. Um componente que se desloca sozinho obriga a aplicação a desfazer um movimento já feito, em vez de simplesmente escolher se ele acontece.

Dois segmentos nunca comunicam nada: um segmento desactivado, um escondido. O último — onde se está — responde como os outros, até que ib_last_clickable diga que não.

// event ue_item_clicked : (string as_keys)
// Primeiro as suas verificacoes - deixar o ecra decide-o o senhor, nao um clique
if not of_can_leave() then return
uo_crumbs.of_truncate(/*keys*/ as_keys)
of_open_screen(as_keys)

Quando o caminho é demasiado longo #

Um caminho é tão longo quanto os dados o fizerem, e a largura é a que é. is_overflow_mode diz o que cede.

Constante	O que acontece
`OVERFLOW_COLLAPSE`	O meio dobra-se num `…` que abre o que esconde — a predefinição
`OVERFLOW_SCROLL`	As etiquetas ficam inteiras, a faixa desliza (também com a roda do rato)
`OVERFLOW_SHRINK`	Os segmentos do meio cedem terreno, até uma letra e reticências; o primeiro e o local actual cedem por último. Com espaço de sobra, nada é cortado

Nem o primeiro segmento nem o último se dobram alguma vez. Perder a raiz é perder a âncora a que todos voltam; perder o fim é perder o sítio onde se está.

Um segmento dobrado comunica exactamente como os outros: escolhê-lo no … levanta o mesmo ue_item_clicked. Estar escondido pela largura não muda o que um segmento significa.

ii_max_visible impõe um tecto firme, seja qual for o espaço. Deixe-o a 0 — a predefinição — para que a largura decida, que é o que um trilho de navegação deve normalmente seguir.

of_add_child dá a um segmento o seu próprio menu pendente: os outros ramos desse nível. É o que evita subir à raiz só para voltar a descer à pasta ao lado.

O chevron que segue o segmento passa então a ser o botão que os abre — é o mesmo do separador, como no explorador do Windows: um só chevron, um só sentido a aprender. Escolher um ramo levanta ue_child_clicked, e também aqui o trilho não se mexe sozinho. No teclado, Seta para baixo num segmento abre os seus ramos, e no … o que ele esconde.

// Two branches under Clients : its chevron lists them
uo_crumbs.of_add_child(/*keys*/ "home/clients/durand", /*text*/ "D")
uo_crumbs.of_add_child(/*keys*/ "home/clients/martin", /*text*/ "M")

Os ramos a pedido #

Colocar todos os ramos de antemão não aguenta numa árvore profunda, nem numa base de dados. O explorador do Windows só lê uma pasta quando o seu chevron se abre; o trilho faz o mesmo: marque um segmento com ib_has_children, o seu chevron aparece logo, e abri-lo levanta ue_children_needed. Coloca os ramos nesse evento, e o menu abre-se no seu regresso com o que o segmento tem nesse instante. Uma pasta grande não é um problema: acrescentar 30 000 ramos não relê nada, e no menu aberto escrever as primeiras letras («Win») salta para o primeiro ramo que começa assim, como no explorador.

// O segmento promete : o chevron aparece, nada e lido
uo_crumbs.of_item(/*keys*/ "home/clients").ib_has_children = true

// Em ue_children_needed(as_keys) : lido agora, depois o menu abre-se
uo_crumbs.of_clear_children(/*keys*/ as_keys)
uo_crumbs.of_add_child(/*keys*/ as_keys + "/durand", /*text*/ "Durand SARL")

Escrever o caminho #

Com ib_editable, a parte vazia da barra comporta-se como a barra de endereço do explorador do Windows: um clique (ou F2, ou of_edit) transforma o trilho num campo de texto com o endereço mostrado — as chaves unidas por /, o que of_path devolve. Enter levanta ue_path_entered com o texto tal como escrito; Esc cancela. O trilho não se mexe sozinho, pela mesma razão por que um clique não o encurta: só a sua aplicação sabe o que as palavras querem dizer. ii_edit_skip deixa os primeiros segmentos fora do campo — a raiz que nomeia a máquina — e repõe-nos à frente do que foi escrito ao reportar.

Propriedades #

Propriedade	Tipo	Predefinição	Papel
`is_separator`	string	`chevron`	O sinal entre segmentos (constantes `SEPARATOR_*`). Vira-se sozinho numa língua que se escreve da direita para a esquerda: escolha um significado, não uma direcção. Um separador que abre ramos mantém o sinal escolhido: são a passagem do rato e o ponteiro que dizem que se abre
`is_overflow_mode`	string	`collapse`	O que cede quando o caminho já não cabe (constantes `OVERFLOW_*`). Em `scroll`, a faixa segue o local actual
`ii_max_visible`	integer	`0`	Tecto firme do número de segmentos mostrados, sem contar o `…`. `0` deixa-o à largura
`ib_last_clickable`	boolean	`true`	O último segmento — onde se está — responde ao clique? Verdadeiro por omissão: um trilho serve também para recarregar o que se vê, e o que o clique faz é assunto da sua aplicação. Ponha-o a falso quando o seu trilho apenas navega
`ib_editable`	boolean	`false`	O caminho pode ser escrito? Verdadeiro: um clique na parte vazia da barra (ou `F2`, ou `of_edit`) transforma o trilho num campo de texto com o endereço do local actual (o que `of_path` devolve); `Enter` levanta `ue_path_entered`, tal como sair do campo depois de o alterar; `Esc` cancela. Um campo deixado sem alterações não diz nada; um clique noutro controlo da aplicação valida o texto, passar para outra aplicação mantém o que foi escrito. O trilho nunca se move sozinho
`ib_allow_drop`	boolean	`false`	Opt-in: aceita ficheiros largados do Explorador do Windows sobre um segmento. O segmento sob o ponteiro acende durante o arrasto, e `ue_drop_files` nomeia-o com os caminhos completos
`ii_edit_skip`	integer	`0`	Número de segmentos iniciais deixados fora do campo de texto — uma raiz que nomeia a máquina não se escreve. São repostos à frente do que foi escrito ao reportar: o endereço mantém-se completo
`is_theme_style`	string	`""`	Estilo visual do componente (constantes `THEME_STYLE_*`); vazio = o da aplicação, seguido a cada mudança
`is_theme_mode`	string	`""`	Variante clara ou escura (constantes `THEME_MODE_*`); vazio = a da aplicação, seguida a cada mudança
`il_theme_accent`	long	`-1`	Cor de destaque deste componente (`-1` = destaque da aplicação, ou o 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	Papel
`of_add_item (string as_keys, string as_text)`	Acrescenta um segmento no fim: passa a ser o local actual. `as_keys` é uma chave simples ou um endereço; um endereço só é aceite se chegar onde diz — os seus níveis acima do último têm de ser o endereço do último segmento. Devolve `0` depois de aplicado, `-5` perante uma chave vazia, uma chave com `	`ou um endereço que iria parar a outro sítio,` -2` se o componente não estiver criado
`of_add_item (string as_keys, string as_text, string as_image)`	O mesmo, com o ícone mostrado antes da etiqueta — terceiro argumento, como em toda a biblioteca. Uma etiqueta vazia dá um segmento só com ícone (a casa da raiz). Devolve `0` depois de aplicado, `-5` perante uma chave vazia, uma chave com `	`ou um endereço que iria parar a outro sítio,` -2` se o componente não estiver criado
`of_insert_item (string as_keys, string as_text, integer ai_index)`	Insere na posição escolhida (primeira posição = 1). Uma sobrecarga aceita também o ícone. Um endereço só é aceite se os seus níveis acima do último forem o endereço do segmento que segue. Os segmentos seguintes descem um nível: os seus endereços mudam, os seus handles são libertados, as suas cores e tooltips seguem-nos. Devolve `0` depois de aplicado, `-5` perante uma chave vazia, uma chave com `	`ou um endereço que iria parar a outro sítio,` -2` se o componente não estiver criado
`of_remove_item (string as_keys)`	Retira um segmento, pelo seu endereço; os outros mantêm o seu estado. Os que o seguiam sobem um nível: os handles do segmento retirado e de tudo o que o seguia são libertados. Devolve `0` depois de aplicado, `-5` se o endereço não designar nenhum segmento (desconhecido, ou chave simples repetida), `-2` se o componente não estiver criado
`of_truncate (string as_keys)`	Elimina tudo o que segue esse segmento, que passa a ser o local actual. É o gesto para o qual um trilho de navegação existe; um endereço desconhecido ou uma chave simples repetida não muda nada e devolve `-5`. Os handles dos segmentos eliminados são libertados. Devolve `0` depois de aplicado, `-5` se o endereço não designar nenhum segmento, `-2` se o componente não estiver criado
`of_clear ( )`	Esvazia o trilho; os handles entregues para os seus segmentos e ramos são libertados. Devolve `0` depois de aplicado, `-2` se o componente não estiver criado
`of_add_child (string as_keys, string as_text)`	Acrescenta um ramo irmão no endereço indicado: o segmento acima ganha um chevron que os abre. Uma sobrecarga aceita também o ícone. Devolve `0` depois de aplicado, `-5` se o segmento acima não existir, se a chave do ramo já estiver ocupada sob ele ou contiver `	`,` -2` se o componente não estiver criado
`of_add_children (string as_keys, string as_child_keys[], string as_texts[])`	Acrescenta todo um nível de ramos irmãos sob o segmento `as_keys`, numa única chamada: cada texto de `as_texts` (e cada imagem, na sobrecarga que recebe também uma lista de imagens) vai com a chave da mesma posição em `as_child_keys`; um texto ausente mostra a chave. Os mesmos ramos que um ciclo de `of_add_child`, sem uma ida e volta para cada um: uma pasta de 30 000 subpastas abre o seu menu de imediato. Devolve `0` depois de aplicado (uma lista vazia não acrescenta nada), `-5` se o endereço não designar nenhum segmento, ou se uma chave estiver vazia, contiver `/` ou `	`, já estiver ocupada sob o segmento ou aparecer duas vezes na lista — nesse caso nada é acrescentado,` -2` se o componente não estiver criado
`of_clear_children (string as_keys)`	Retira os ramos irmãos de um segmento, e os seus handles; o seu separador volta a ser um simples traço. Devolve `0` depois de aplicado, `-5` se o endereço não designar nenhum segmento, `-2` se o componente não estiver criado
`of_remove_child (string as_keys)`	Retira um ramo irmão, pelo seu próprio endereço, e o seu handle; retirado o último, o chevron volta a ser um simples separador. Devolve `0` depois de aplicado, `-5` se o segmento ou o ramo não existir, `-2` se o componente não estiver criado
`of_child (string as_keys)`	O handle de um ramo irmão — o endereço que `of_add_child` recebeu — para o renomear, desactivar ou esconder. O menu é um popup nativo: desenha texto, imagem, desactivado e escondido, nada mais — o tooltip e as cores que um handle herda são aí ignorados. Um endereço com um só nível não tem segmento acima: o seu handle é inerte
`of_path ( )`	Onde se está, sob a forma de endereço: as chaves de todos os segmentos até ao último visível, separadas por `/`. Um segmento escondido fica nele — faz parte do endereço — e o limite da versão de demonstração nunca o corta: `of_truncate(of_path())` acerta sempre. Lido em directo: uma aplicação que reconstruísse esta cadeia à mão acabaria por não dizer o mesmo que o trilho
`of_edit ( )`	Abre o campo de texto do caminho — o mesmo que um clique na parte vazia da barra — a partir de uma entrada de menu ou de um botão seu. Requer `ib_editable`. Devolve `0` depois de aplicado, `-4` se `ib_editable` for falso (nada se abre), `-2` se o componente não estiver criado
`of_item (string as_keys)`	O handle de um segmento, para o renomear, desactivar ou esconder mais tarde. Vive tanto quanto o seu segmento: `of_clear`, `of_remove_item` e `of_truncate` libertam os handles dos segmentos que retiram
`of_set_redraw (boolean)`	Agrupa uma rajada de alterações num único desenho. Devolve `0` depois de aplicado, `-2` se o componente não estiver criado
`of_save_as_png (string)` · `of_save_as_jpg (string)`	Exporta o desenho como imagem. Devolve `0` depois de a imagem ser escrita, `-4` se a escrita falhar, `-2` se o componente não estiver criado

Eventos #

Evento	Accionado quando
`ue_item_clicked (string as_keys)`	Um segmento foi clicado — no trilho, ou no `…` que o esconde. O trilho não se encurta sozinho: chame `of_truncate` assim que as suas verificações passarem
`ue_item_rclicked (string as_keys)`	Clique direito num segmento — normalmente um menu de contexto seu. `as_keys` é o seu endereço completo, como em `ue_item_clicked`
`ue_child_clicked (string as_keys)`	Foi escolhido um ramo irmão no menu de um segmento; `as_keys` é o endereço do ramo, pronto a voltar a `of_add_item`
`ue_children_needed (string as_keys)`	O chevron de um segmento marcado com `ib_has_children` abre-se: coloque os seus ramos agora (`of_add_child`), o menu abre-se no regresso do evento, com o que o segmento tem nesse instante. Perguntado a cada abertura: esvazie e reponha quando os ramos possam ter mudado, não faça nada quando o que lá está ainda vale
`ue_path_entered (string as_path)`	O utilizador escreveu um caminho na barra (`ib_editable`) e premiu Enter — ou saiu do campo depois de o alterar; `as_path` é o texto tal como escrito, com os primeiros `ii_edit_skip` segmentos repostos à frente. Um clique noutro controlo da aplicação conta como sair do campo. `Esc`, um campo inalterado ou outra aplicação trazida para a frente não comunicam nada. O trilho não se move sozinho: verifique as palavras e depois reconstrua-o com `of_clear` e `of_add_item` se estiver de acordo
`ue_drop_files (string as_keys, string as_files[])`	Foram largados ficheiros do Explorador sobre um segmento (`ib_allow_drop`): `as_keys` é o endereço do segmento sob o ponteiro, vazio se o largar caiu ao lado do trilho; `as_files` os caminhos completos
`ue_drag_enter ( )` · `ue_drag_leave ( )`	Um arrastamento de ficheiros a partir do Explorador entrou no componente, ou saiu dele sem largar — largar levanta apenas `ue_drop_files`
`ue_auto_height (long al_height)`	A barra anuncia a altura de que precisa — uma linha, decidida pela fonte e pelo tema; o userobject já está redimensionado, reposicione o que estiver por baixo
`ue_ready ( )`	O componente acabou de carregar; tudo o que foi enviado antes foi reproduzido
`ue_runtime_missing ( )`	O runtime WebView2 não está presente: o componente fica vazio
`ue_bg_color (long al_color)`	O componente calculou a sua cor de fundo do tema; o userobject já a adoptou (`backcolor`)

O trilho não navega. Diz onde se está e comunica o que lhe é pedido; é a sua aplicação que abre o ecrã — a mesma acção, accionada a partir de um menu ou do trilho, passa pelo mesmo código.

Propriedades de item #

Propriedade	Tipo	Predefinição	Papel
`is_text`	string	`""`	A etiqueta do segmento, alterável sem reconstruir o trilho (marcação rica aceite: uma etiqueta que vem dos DADOS — um nome de pasta — passa primeiro por `of_escape_markup` de `n_pbt_utils`, senão `[b]Rascunhos` apareceria a negrito sem os parênteses rectos)
`is_image`	string	`""`	O ícone mostrado antes da etiqueta (prefixos `mono:` e `tint:` aceites)
`ib_enabled`	boolean	`true`	Um segmento desactivado aparece a cinzento e não comunica nada: o nível existe no caminho, mas não se pode voltar a ele (permissões, uma ficha em edição). O seu chevron também não abre nada, e um arrastamento de ficheiros não o realça
`ib_visible`	boolean	`true`	Um segmento escondido sai do trilho, separador incluído — útil para um nível técnico que não diz respeito ao utilizador. É conservado: voltar a mostrá-lo não exige reconstrução
`ib_has_children`	boolean	`false`	Marcado: há algo sob este segmento. O seu chevron aparece ainda sem nada atrás, e abri-lo levanta `ue_children_needed`, onde os ramos são lidos nesse instante. Um segmento cujos ramos foram colocados com `of_add_child` não precisa da marca

Propriedades de um filho #

Obtida com of_child(endereço). O menu é um popup nativo: uma propriedade alterada enquanto está aberto vê-se na abertura seguinte.

Propriedade	Tipo	Predefinição	Papel
`is_text`	string	`""`	O rótulo do ramo no menu
`is_image`	string	`""`	O ícone mostrado antes do rótulo
`ib_enabled`	boolean	`true`	Um ramo acinzentado fica no menu e não pode ser escolhido — sem direitos sobre esse ramo
`ib_visible`	boolean	`true`	Um ramo escondido sai do menu sem ser eliminado; o último escondido fecha o chevron

Exemplos #

Segui-lo enquanto se navega #

// Rebuild the trail in a single redraw : freeze, clear, add, insert, redraw
uo_crumbs.of_set_redraw(/*on*/ false)
uo_crumbs.of_clear()
uo_crumbs.of_add_item(/*keys*/ "home", /*text*/ "H", /*image*/ "mono:img\packimages.dll:svg/samples/folder-open")
uo_crumbs.of_insert_item(/*keys*/ "home/region", /*text*/ "R", /*index*/ 2)
uo_crumbs.of_set_redraw(/*on*/ true)

Subir num clique #

// Cut the trail after Clients, then read the path that remains
uo_crumbs.of_truncate(/*keys*/ "home/clients")
ls_path = uo_crumbs.of_path()

Um nível proibido, um escondido #

// O nivel existe, mas nao se pode voltar a ele
uo_crumbs.of_item(/*keys*/ "home/clients/orders").ib_enabled = false

// E este nao diz respeito ao utilizador : fora do trilho, separador incluido
uo_crumbs.of_item(/*keys*/ "home").ib_visible = false

// Slash separator, scrolling on overflow, at most 4 segments shown, last one not clickable
uo_crumbs.is_separator = uo_crumbs.SEPARATOR_SLASH
uo_crumbs.is_overflow_mode = uo_crumbs.OVERFLOW_SCROLL
uo_crumbs.ii_max_visible = 4
uo_crumbs.ib_last_clickable = false

// Remove one segment, then the branches offered under another
uo_crumbs.of_remove_item(/*keys*/ "home/region")
uo_crumbs.of_clear_children(/*keys*/ "home/clients")

Boas práticas #

Dê a cada segmento a chave do ecrã que abre: o seu ue_item_clicked torna-se um choose case que se lê, e o mesmo código serve o menu.
Chame of_truncate dentro do seu tratador de clique, não antes: é o que garante que um ecrã nunca é deixado sem as suas verificações.
Deixe ii_max_visible a 0 a menos que um desenho o imponha. Um trilho que segue a largura mostra sempre o máximo do que cabe.
Dê aos segmentos nomes que o utilizador reconheça — o nome do cliente, não o seu identificador. Um trilho lê-se, não se decifra.
Ponha nele apenas níveis a que se possa realmente voltar. Um segmento que falha uma vez em cada duas faz perder a confiança em todo o trilho; se um nível está temporariamente proibido, ib_enabled di-lo sem mentir.
Um trilho de navegação diz um lugar, não uma progressão: para « passo 2 de 5 » é a stepbar que serve.

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
`of_set_property` · `of_get_property` · `of_component_name`	Controlar uma propriedade pelo nome	3.1 O motor de propriedades

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.