toolbar — `u_pbt_toolbar` #

← Referência dos componentes · Índice do guia

Barra de ferramentas plana: várias barras distribuídas por bandas, botões, alternadores, menus pendentes, campos de introdução, excedente automático e deslocação pela pega.

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

Em resumo #

Userobject	`u_pbt_toolbar`
Classes de items	`n_pbt_toolbar_bar` (barra) → `n_pbt_toolbar_item` (ferramenta) → `n_pbt_toolbar_menu_item` (entrada de menu)
Serve para	Substituir uma barra de ferramentas clássica por uma barra moderna, com tema, em várias filas reorganizáveis
Altura	Intrínseca: a barra ajusta-se sempre às suas filas, nada há para ativar — ver Altura automática

Início rápido #

// event open da janela

// MAIN_BAR e a barra por omissao, sempre presente : o endereco parte dela
uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/save", /*text*/ "", /*image*/ "mono:img\save.svg", /*tooltip*/ "Guardar")
uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/find", /*text*/ "", /*image*/ "mono:img\find.svg", /*tooltip*/ "Procurar")
uo_toolbar.of_add_separator(/*keys*/ uo_toolbar.MAIN_BAR)
uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/help", /*text*/ "Ajuda",  /*image*/ "", /*tooltip*/ "Acerca de")

// event ue_clicked de uo_toolbar : (string as_keys)
choose case as_keys
    case "main/save" ; of_save()
    case "main/find" ; of_find()
    case "main/help" ; of_help()
end choose

O modelo: barras, bandas, ferramentas #

Uma barra de ferramentas contém uma ou várias barras. Cada barra assenta numa banda (uma fila) e ocupa uma posição nessa fila: duas barras na mesma banda partilham a fila, duas barras em bandas diferentes empilham-se — exatamente como as barras de ferramentas clássicas do Office.

As ferramentas (botões, alternadores, menus, campos) pertencem a uma barra. O respetivo identificador só é único dentro da sua barra: o acesso faz-se, por isso, sempre pelo caminho completo.

// Gray out a tool, or one entry of its menu
uo_toolbar.of_item(/*keys*/ "main/save").ib_enabled = false
uo_toolbar.of_menu_item(/*keys*/ "main/export/pdf").ib_enabled = false

Tudo se faz a partir do componente, por endereços: uma ferramenta acrescenta-se no seu (of_add_button("main/save", …)), uma entrada de menu no seu ("main/export/pdf", um nível a mais por cascata), e cada nível tem o seu getter — of_bar, of_item, of_menu_item. Ver Base comum · Os items para o princípio geral.

Listas pendentes #

Uma lista pendente (of_add_combo) é um campo e a sua seta, como a combo do friso. Não editável, o utilizador escolhe na lista (um clique no campo, Enter, F4 ou Alt+Baixo abrem-na); editável, pode também escrever um valor seu. Cada escolha regressa em ue_combo_changed; recolhida no chevron de uma barra demasiado estreita, a lista continua funcional.

// A font the user only chooses, a size he may also type
uo_toolbar.of_add_combo(/*keys*/ "main/font", /*width*/ 130, /*editable*/ false, /*tooltip*/ "Font")
uo_toolbar.of_add_combo_item(/*keys*/ "main/font", /*label*/ "Segoe UI")
uo_toolbar.of_add_combo_item(/*keys*/ "main/font", /*label*/ "Arial")
uo_toolbar.of_item(/*keys*/ "main/font").is_text = "Segoe UI"
uo_toolbar.of_add_combo(/*keys*/ "main/size", /*width*/ 60, /*editable*/ true, /*tooltip*/ "Size")
uo_toolbar.of_add_combo_item(/*keys*/ "main/size", /*label*/ "10")
uo_toolbar.of_add_combo_item(/*keys*/ "main/size", /*label*/ "12")

// ue_combo_changed (string as_keys, string as_text) of uo_toolbar
st_status.Text = as_keys + " = " + as_text

Propriedades #

Propriedade	Tipo	Predefinição	Função
`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
`ib_reorderable`	boolean	`false`	Permite ao utilizador reorganizar as barras com o rato: as pegas de deslocação aparecem e uma barra pode ser arrastada para outra banda. Desativado por predefinição — uma barra de ferramentas desmontada por acidente é uma chamada ao suporte. O seu código reorganiza-as de qualquer forma (`of_set_layout`, `of_add_bar`): a autorização incide sobre o utilizador, nunca sobre a aplicação

Constante #

Constante	Valor	Função
`MAIN_BAR`	`"main"`	Identificador da barra predefinida, que se endereça sem a ter criado: nasce com a sua primeira ferramenta. Para a posicionar, acrescente-a primeiro — `of_add_bar(MAIN_BAR, 1, 1)`

Métodos #

Método	Função
`of_bar (string as_key)` → `n_pbt_toolbar_bar`	Devolve o handle de uma barra (criada no primeiro acesso): `ii_band`, `ii_index`, `ib_visible`
`of_add_button (string as_keys, string as_text, string as_image, string as_tooltip)` → `long`	Botão de ação no seu endereço, `"main/save"`: a barra e depois o seu próprio identificador. O clique despoleta `ue_clicked`. Devolve `0` uma vez adicionado, `-5` se o endereço for recusado (não é `barra/ferramenta`, uma barra nunca adicionada — exceto `main` —, um endereço já ocupado), `-2` se o componente não estiver criado
`of_item (string as_keys)` → `n_pbt_toolbar_item`	Devolve o handle de uma ferramenta, pelo seu endereço `barra/ferramenta`. Um endereço de outra profundidade não designa nenhuma ferramenta: uma barra é `of_bar`, uma entrada de menu `of_menu_item`
`of_menu_item (string as_keys)` → `n_pbt_toolbar_menu_item`	Devolve o handle de uma entrada de um menu pendente, pelo seu endereço `barra/pendente/entrada` — um nível a mais por cascata. Duas cascatas podem ter cada uma o seu `pdf`: o endereço designa um deles, nunca os dois
`of_add_bar (string as_key)` → `long`	Acrescenta uma barra, numa banda própria depois das outras. Devolve `0` uma vez adicionada, `-5` se a chave for recusada (vazia, com `/` ou `	`, a começar por` __ `ou já ocupada),` -2 `se o componente não estiver criado. A barra predefinida` main `nasce com a sua primeira ferramenta: para a posicionar, acrescente-a antes de qualquer ferramenta (`of_add_bar(MAIN_BAR, 1, 1)`); depois fica ocupada (`-5`) e desloca-se por` of_bar(MAIN_BAR)`
`of_add_bar (string as_key, integer ai_band, integer ai_index)` → `long`	Acrescenta uma barra numa banda e numa posição precisas (ambas contadas a partir de 1); a barra que ocupava essa posição passa um lugar para a direita. Mesmos códigos que acima
`of_remove_bar (string as_key)` → `long`	Retira uma barra e as suas ferramentas, com os respetivos handles e atalhos. As outras mantêm o seu estado vivo, e as bandas cerram fileiras atrás da que sai. Não é ocultá-la (`ib_visible` no seu handle): ocultar mantém-na no modelo, pronta a voltar exatamente onde estava; retirar esquece-a. Devolve `0` uma vez retirada, `-5` para uma barra que não existe, `-2` se o componente não estiver criado
`of_get_layout ()` → `string`	Relê a disposição corrente em JSON: que barra em que banda, em que posição, e visível ou não. Bandas e posições contadas a partir de 1, como `ii_band` / `ii_index`: guardá-la tal como vem e devolvê-la a `of_set_layout` — uma ida e volta devolve a mesma cadeia
`of_set_layout (string as_layout_json)` → `long`	Repõe uma disposição lida por `of_get_layout` ou recebida por `ue_layout_changed`, devolvida tal como veio. Uma barra que não nomeia fica onde está. É levantado `ue_layout_changed`, como em qualquer mudança da disposição. Devolve `0` uma vez aplicado, `-5` numa cadeia vazia, `-2` se o componente não estiver criado. Um texto que não é JSON também devolve `-5`
`of_clear ( )` → `long`	Elimina todas as barras, ferramentas e menus, com os handles distribuídos e os atalhos das ferramentas e das entradas; cada endereço pode ser acrescentado de novo. Devolve `0` uma vez aplicado, `-2` se o componente não estiver criado
`of_reset ( )`	Esvazia o conteúdo e repõe as propriedades nos respetivos valores por omissão. Devolve `0` depois de aplicado, `-2` se o componente não estiver criado
`of_add_toggle (string as_keys, string as_text, string as_image, string as_tooltip)` → `long`	Alternador de dois estados; o clique despoleta `ue_toggled`. Devolve `0` uma vez adicionado, `-5` se o endereço for recusado (não é `barra/ferramenta`, uma barra nunca adicionada — exceto `main` —, um endereço já ocupado), `-2` se o componente não estiver criado
`of_add_dropdown (string as_keys, string as_text, string as_image, string as_tooltip)` → `long`	Botão com menu pendente, preenchido com `of_add_menu_item`; uma escolha despoleta `ue_menu_selected`. Devolve `0` uma vez adicionado, `-5` se o endereço for recusado (não é `barra/ferramenta`, uma barra nunca adicionada — exceto `main` —, um endereço já ocupado), `-2` se o componente não estiver criado. Um menu pendente sem nenhuma entrada visível é desenhado a cinzento
`of_add_split_button (string as_keys, string as_text, string as_image, string as_tooltip)` → `long`	Botão dividido: a sua parte principal é um botão (`ue_clicked`), a sua seta abre um menu preenchido por `of_add_menu_item` como o de um menu pendente (`ue_menu_selected`). O seu atalho despoleta a parte principal; recolhido no chevron, abre uma lista cuja primeira linha é a sua própria ação. Devolve `0` uma vez adicionado, `-5` se o endereço for recusado (não é `barra/ferramenta`, uma barra nunca adicionada — exceto `main` —, um endereço já ocupado), `-2` se o componente não estiver criado
`of_add_label (string as_keys, string as_text)` → `long`	Etiqueta informativa, não clicável. Devolve `0` uma vez adicionado, `-5` se o endereço for recusado (não é `barra/ferramenta`, uma barra nunca adicionada — exceto `main` —, um endereço já ocupado), `-2` se o componente não estiver criado
`of_add_textbox (string as_keys, string as_text, integer ai_width, string as_tooltip)` → `long`	Campo de introdução; Enter ou a perda do foco despoleta `ue_text_changed`, Escape repõe o texto validado. `ai_width` em píxeis. Devolve `0` uma vez adicionado, `-5` se o endereço for recusado (não é `barra/ferramenta`, uma barra nunca adicionada — exceto `main` —, um endereço já ocupado), `-2` se o componente não estiver criado
`of_add_combo (string as_keys, integer ai_width, boolean ab_editable, string as_tooltip)` → `long`	Lista pendente (combo): um campo e a sua seta, a combo do friso. `ab_editable = false`, o utilizador apenas escolhe na lista; `true`, pode também escrever um valor seu, validado por Enter ou ao sair do campo. A lista preenche-se com `of_add_combo_item`, uma escolha despoleta `ue_combo_changed`, `is_text` define e relê o valor. `ai_width` em píxeis (0 = largura predefinida). Recolhida no chevron, continua a ser uma lista funcional. Devolve `0` uma vez adicionada, `-5` se o endereço for recusado (não é `barra/ferramenta`, uma barra nunca adicionada — exceto `main` —, um endereço já ocupado), `-2` se o componente não estiver criado
`of_add_combo_item (string as_keys, string as_label)` → `long`	Acrescenta uma escolha à lista de uma lista pendente: `as_keys` nomeia a lista (`"main/zoom"`). Uma escolha tem como chave a sua etiqueta, pelo que o seu endereço é `"main/zoom/150%"` (`of_remove_combo_item`, `of_has`); `of_count` e `of_keys_at` sobre a lista percorrem as suas escolhas. Em modo de demonstração a lista mostra 6 escolhas. Devolve `0` uma vez adicionada, `-5` se `as_keys` não for uma lista pendente, ou se a etiqueta estiver vazia, contiver `/` ou `	`, ou já estiver na lista,` -2` se o componente não estiver criado
`of_add_datepicker (string as_keys, string as_date, string as_tooltip)` → `long`	Seletor de data; uma escolha despoleta `ue_date_changed`, `is_date` lê e define a data. Datas no formato `"aaaa-mm-dd"`. Devolve `0` uma vez adicionado, `-5` se o endereço for recusado (não é `barra/ferramenta`, uma barra nunca adicionada — exceto `main` —, um endereço já ocupado), `-2` se o componente não estiver criado
`of_add_separator (string as_keys)` → `long`	Linha vertical de separação numa barra (`as_keys` nomeia-a). Um separador não tem chave nem posição. Devolve `0` uma vez adicionado, `-5` para uma barra nunca adicionada (exceto `main`), `-2` se o componente não estiver criado. Um separador que ferramentas ocultas deixariam no início, no fim ou duplicado não é desenhado
`of_insert_button (string as_keys, string as_text, string as_image, string as_tooltip, integer ai_index)` → `long`	Botão acrescentado na posição escolhida (primeiro = 1) em vez de no fim. Devolve `0` uma vez adicionado, `-5` se o endereço for recusado (não é `barra/ferramenta`, uma barra nunca adicionada — exceto `main` —, um endereço já ocupado), `-2` se o componente não estiver criado
`of_move_item (string as_keys, integer ai_index)` → `long`	Desloca uma ferramenta para outra posição na sua barra (primeiro = 1; a posição conta as ferramentas, um separador não ocupa nenhuma). Mantém o tipo, o menu e o estado vivo: a ferramenta muda de lugar, não é reconstruída. Devolve `0` uma vez aplicado, `-5` se nenhuma ferramenta viver nesse endereço, `-2` se o componente não estiver criado
`of_remove_item (string as_keys)` → `long`	Retira uma ferramenta (`"main/save"`) ou uma entrada de menu (`"main/export/pdf"`, com a sua cascata), com os seus handles e o seu atalho. Tudo o resto permanece, estado vivo incluído. Para fazer uma ferramenta ir e vir, `ib_visible` no seu handle mantém-na no modelo. Devolve `0` uma vez retirada, `-5` se nada viver nesse endereço, `-2` se o componente não estiver criado
`of_remove_combo_item (string as_keys)` → `long`	Retira uma escolha de uma lista pendente, nomeada pelo seu endereço `"main/zoom/150%"`; o valor mostrado mantém-se. `of_remove_item` faz o mesmo. Devolve `0` uma vez retirada, `-5` se essa lista não tiver essa escolha, `-2` se o componente não estiver criado
`of_add_menu_item (string as_keys, string as_label, string as_image)` → `long`	Entrada do menu de um botão pendente, no seu endereço `barra/pendente/entrada`; cada nível a mais coloca-a em cascata sob a entrada anterior, a qualquer profundidade. Uma etiqueta vazia mostra a chave. Devolve `0` uma vez adicionada, `-5` se o endereço for recusado (nível vazio ou com `	`, pendente ou entrada-mãe nunca adicionados, endereço já ocupado),` -2 `se o componente não estiver criado. Vale também para o menu de um botão dividido (`of_add_split_button`)
`of_add_menu_separator (string as_keys)` → `long`	Linha de separação no fim do menu de um pendente (`"main/export"`), ou da cascata de uma entrada (`"main/export/img"`). Devolve `0` uma vez adicionada, `-5` se o endereço não nomear nenhum dos dois, `-2` se o componente não estiver criado. Vale também para o menu de um botão dividido (`of_add_split_button`)
`of_clear_menu (string as_keys)` → `long`	Esvazia o menu de um pendente (`"main/recent"`) e mantém o botão: a forma de reconstruir uma lista de ficheiros recentes. Os handles e atalhos das suas entradas vão com elas. Devolve `0` uma vez aplicado, `-5` se o endereço não nomear nenhum pendente, `-2` se o componente não estiver criado. Vale também para o menu de um botão dividido (`of_add_split_button`)
`of_clear_combo (string as_keys)` → `long`	Esvazia a lista de uma lista pendente (`"main/zoom"`); o valor mostrado mantém-se. A forma de reconstruir uma lista que acompanha o documento. Devolve `0` uma vez aplicado, `-5` se `as_keys` não for uma lista pendente, `-2` se o componente não estiver criado
`of_register_shortcut (string as_chord, string as_keys)` → `long`	Numa toolbar o atalho recebe o endereço do que despoleta: uma ferramenta (`barra/ferramenta` — como `is_shortcut` no seu handle) ou uma entrada de menu (`barra/pendente/entrada`). Responde onde quer que esteja o foco na janela e aparece na dica ou à direita da entrada; `""` retira-o. Uma barra de ferramentas não tem nada a despoletar para si mesma: a forma de um argumento devolve `-5`. Devolve `0` uma vez aplicado, `-5` se o endereço não nomear nenhuma ferramenta nem entrada, ou nomear uma etiqueta, `-2` se o componente não estiver criado
`of_clear_shortcuts ( )` → `long`	Retira todos os atalhos da barra de ferramentas — os das suas ferramentas e das suas entradas de menu: deixam de responder, deixam de ser mostrados, e `is_shortcut` relê `""`. Devolve `0` uma vez aplicado, `-2` se o componente não estiver criado

Numa barra — `n_pbt_toolbar_bar` #

Membro	Tipo	Predefinição	Função
`ii_band`	integer	`1`	Banda (fila) que suporta a barra; `1` = primeira fila
`ii_index`	integer	`1`	Posição da barra na respetiva banda; `1` = a primeira
`ib_visible`	boolean	`true`	Mostra ou oculta uma barra. Uma barra oculta mantém a sua banda, a sua posição e os seus itens: voltar a mostrá-la coloca-a exatamente onde estava, sem reconstruir nada — é a diferença face a `of_clear`, que os perderia

Numa ferramenta — `n_pbt_toolbar_item` #

Membro	Tipo	Predefinição	Função
`ib_visible`	boolean	`true`	Mostra ou oculta um item. Mantém a sua posição na barra: voltar a mostrá-lo coloca-o exatamente onde estava, não no fim. Não confundir com `ib_enabled`, que o deixa no lugar, esbatido — oculte o que não se aplica, esbata o que está momentaneamente indisponível
`ib_enabled`	boolean	`true`	Ferramenta ativa ou desativada
`ib_checked`	boolean	`false`	Estado de um alternador (sem efeito nos restantes tipos)
`is_text`	string	`""`	Etiqueta, com texto formatado com etiquetas aceite
`is_shortcut`	string	`""`	Atalho de teclado (`"Ctrl+S"`), mostrado no tooltip e ativo; relido tal como foi escrito. Uma ferramenta oculta, desativada ou para lá do limite da demonstração não responde. Precisa de Ctrl ou Alt (Shift junta-se-lhes), ou é de F1 a F24: uma tecla sozinha — uma letra, Delete, Enter — é escrita, nunca um atalho. Um botão ou um alternador é despoletado; um campo de introdução recebe o cursor, com o texto selecionado; um seletor de data abre o seu calendário; uma etiqueta não aceita nenhum
`is_date`	string	`""`	Data de um seletor de data, `"aaaa-mm-dd"` (`""` esvazia o campo). Relê a data mostrada — a escolhida pelo utilizador tal como a definida aqui. Uma data mal formada é ignorada; os outros tipos de ferramenta não têm data e releem `""`
`is_image`	string	`""`	Ícone da ferramenta (as mesmas formas que ao acrescentar: caminho, `mono:`, `tint:`…); `""` retira-o. Um alternador Reproduzir que passa a Pausa, um botão que passa a um ícone de erro — sem retirar nem voltar a acrescentar a ferramenta
`is_group`	string	`""`	Grupo de um alternador: os alternadores de uma mesma barra que partilham um grupo são exclusivos, como os botões de alinhamento de um editor — premir um liberta os outros, premir o que já está premido deixa-o premido. Só o alternador premido despoleta `ue_toggled`. `ib_checked = true` posto pelo seu código também liberta os outros, sem evento. `""` (predefinição): sem grupo
`ib_editable`	boolean	`false`	Uma lista pendente (`of_add_combo`): `true`, o utilizador pode escrever um valor seu para além das escolhas da lista; `false`, apenas escolhe. Qualquer outra ferramenta lê `false` e ignora-o

Numa entrada de menu — `n_pbt_toolbar_menu_item` #

Membro	Tipo	Predefinição	Função
`ib_enabled`	boolean	`true`	Desativada, a entrada fica no menu e já não pode ser escolhida — nem com o rato, nem com o teclado, nem pelo seu atalho
`ib_visible`	boolean	`true`	Oculta, a entrada sai do menu (com a sua cascata); mantém o lugar e o estado, e volta onde estava
`ib_checked`	boolean	`false`	Um visto à frente da entrada. É a aplicação que o decide: escolher a entrada não o inverte
`is_text`	string	`""`	Etiqueta da entrada, com texto formatado com etiquetas aceite; relê a chave se a entrada foi acrescentada sem etiqueta
`is_shortcut`	string	`""`	Atalho mostrado à direita da entrada e ativo: escolhe-a onde quer que esteja o foco e levanta `ue_menu_selected` como um clique — não se a entrada, um nível acima ou o seu pendente estiver desativado ou oculto. Relido tal como foi escrito; `""` retira-o. A mesma regra que para uma ferramenta: Ctrl ou Alt, ou de F1 a F24
`is_image`	string	`""`	Ícone da entrada, mostrado na próxima abertura do menu; `""` retira-o

As imagens aceitam todas as formas reconhecidas pela biblioteca: caminho, mono:, tint:, recurso de DLL. Uma entrada de menu aceita as cinco cores de item (il_back_color, il_text_color, as suas variantes ao passar o rato, il_accent), desenhadas no menu; não mostra dica — um menu nativo não a tem.

Eventos #

Evento	Acionado quando
`ue_clicked (string as_keys)`	Um botão — ou a parte principal de um botão dividido — é despoletado: por um clique, pelo seu atalho, ou a partir do painel do chevron quando está recolhido. `as_keys` é o seu endereço, `"main/save"`
`ue_toggled (string as_keys, boolean ab_checked)`	Um alternador muda de estado; `ab_checked` transporta o novo estado. Despoletado apenas por um gesto do utilizador: pôr `ib_checked` não o despoleta. Num grupo (`is_group`), só o alternador premido o despoleta
`ue_menu_selected (string as_keys)`	É escolhida uma entrada de menu pendente — com o rato, o teclado ou o seu atalho, na barra como no painel da seta. `as_keys` é o seu endereço completo, `"main/export/img/png"`. Vale para o menu de um botão dividido como para o de um menu pendente; a própria entrada é o último nível do endereço
`ue_text_changed (string as_keys, string as_text)`	Um campo de introdução é validado (Enter ou perda do foco); o Enter fica no campo e não aciona o botão predefinido da janela. Esc devolve ao campo o seu texto sem o despoletar, e pôr `is_text` não o despoleta
`ue_date_changed (string as_keys, string as_date)`	Uma data é escolhida (`"aaaa-mm-dd"`). Despoletado apenas por uma escolha do utilizador no calendário; pôr `is_date` não o despoleta
`ue_combo_changed (string as_keys, string as_text)`	O utilizador escolheu um valor na lista de uma lista pendente, ou escreveu um numa lista editável e validou-o (Enter, ou ao sair do campo) — na barra ou no painel do chevron. `as_text` é o valor, `as_keys` = `barra/ferramenta`. Um valor escrito só o despoleta se tiver mudado; Escape repõe o valor sem o despoletar; `is_text` posto pelo seu código não despoleta nada. O evento do friso: mesmo nome, mesmo sentido
`ue_bar_reordered (string as_key, integer ai_band, integer ai_index)`	O utilizador arrastou uma barra pela sua pega para outra banda ou outro rango (requer `ib_reorderable`). Diz qual barra se moveu e onde aterrou, enquanto `ue_layout_changed` transporta toda a disposição. Banda e rango começam em 1, como `ii_band` e `ii_index`
`ue_layout_changed (string as_layout_json)`	A disposição mudou — o utilizador arrastou uma barra pela pega, ou o seu próprio código moveu ou ocultou uma, ou repôs uma disposição com `of_set_layout`. Transporta a disposição inteira, não apenas o que se moveu, bandas e posições contadas a partir de 1: a guardar tal como vem e a devolver a `of_set_layout`. Acrescentar uma barra que empurra outra também o despoleta; nada é despoletado quando nada se moveu (voltar a mostrar uma barra já visível)
`ue_item_rclicked (string as_keys)`	Clique direito numa ferramenta (uma a cinzento não diz nada); `as_keys` é o seu endereço. Abra aqui o seu próprio menu de contexto. Um clique direito fora de qualquer ferramenta despoleta `ue_rclicked` em vez disso — nunca os dois
`ue_rclicked ( )`	Clique direito na barra fora de qualquer ferramenta (um clique direito numa ferramenta lança só `ue_item_rclicked`)
`ue_mouse_enter ( )`	O rato entra na barra
`ue_mouse_leave ( )`	O rato sai da barra
`ue_auto_height (long al_height)`	A altura ideal mudou e a barra ajustou-se a ela — sempre ativo: o número de filas dita a altura
`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 #

Alternadores previamente ativados e ferramenta desativada #

// Dois interruptores, um separador e um botao
uo_toolbar.of_add_toggle(/*keys*/ uo_toolbar.MAIN_BAR + "/bold",   /*text*/ "", /*image*/ "mono:img\bold.svg",   /*tooltip*/ "Negrito")
uo_toolbar.of_add_toggle(/*keys*/ uo_toolbar.MAIN_BAR + "/italic", /*text*/ "", /*image*/ "mono:img\italic.svg", /*tooltip*/ "Italico")
uo_toolbar.of_add_separator(/*keys*/ uo_toolbar.MAIN_BAR)
uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/undo",   /*text*/ "", /*image*/ "mono:img\undo.svg",   /*tooltip*/ "Anular")

// Cada ferramenta e controlada pelo seu handle, obtido a partir da SUA barra
uo_toolbar.of_item(/*keys*/ uo_toolbar.MAIN_BAR + "/bold").ib_checked = true    // alternador previamente ativado
uo_toolbar.of_item(/*keys*/ uo_toolbar.MAIN_BAR + "/undo").ib_enabled = false   // nada a anular por agora

// event ue_toggled de uo_toolbar
if as_keys = "main/bold" then of_apply_bold(ab_checked)

// O menu preenche-se a partir do componente : tres niveis, barra/pendente/entrada
uo_toolbar.of_add_dropdown(/*keys*/ uo_toolbar.MAIN_BAR + "/export", /*text*/ "Exportar", &
                                   /*image*/ "mono:img\save.svg", /*tooltip*/ "Exportar o processo")
uo_toolbar.of_add_menu_item(/*keys*/ uo_toolbar.MAIN_BAR + "/export/exp_pdf", /*label*/ "PDF",  /*image*/ "")
uo_toolbar.of_add_menu_item(/*keys*/ uo_toolbar.MAIN_BAR + "/export/exp_csv", /*label*/ "CSV",  /*image*/ "")
uo_toolbar.of_add_menu_separator(/*keys*/ uo_toolbar.MAIN_BAR + "/export")

// Submenu : um QUARTO nivel, a entrada sob a qual se aninha
uo_toolbar.of_add_menu_item(/*keys*/ uo_toolbar.MAIN_BAR + "/export/exp_img", /*label*/ "Imagem...", /*image*/ "")
uo_toolbar.of_add_menu_item(/*keys*/ uo_toolbar.MAIN_BAR + "/export/exp_img/exp_png", /*label*/ "PNG", /*image*/ "")
uo_toolbar.of_add_menu_item(/*keys*/ uo_toolbar.MAIN_BAR + "/export/exp_img/exp_jpg", /*label*/ "JPEG", /*image*/ "")

// Uma entrada controla-se pelo SEU handle, no seu endereco
uo_toolbar.of_menu_item(/*keys*/ uo_toolbar.MAIN_BAR + "/export/exp_csv").ib_enabled = false

// event ue_menu_selected de uo_toolbar : (as_keys)
n_pbt_utils lnv_utils   // autoinstantiate: nada a criar, nada a destruir
string ls_ids[]

// Uma entrada do menu Export : a sua folha indica o formato
if lnv_utils.of_split_path(/*keys*/ as_keys, /*out*/ ls_ids) >= 3 then
	if ls_ids[2] = "export" then of_export(ls_ids[UpperBound(ls_ids)])
end if

Campo de pesquisa e seletor de data #

// Um botao com o seu atalho e depois um separador
uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/save", /*text*/ "", /*image*/ "mono:img\save.svg", /*tooltip*/ "Guardar")
uo_toolbar.of_item(/*keys*/ uo_toolbar.MAIN_BAR + "/save").is_shortcut = "Ctrl+S"    // atalho ativo e apresentado
uo_toolbar.of_add_separator(/*keys*/ uo_toolbar.MAIN_BAR)

// 160 px de largura ; o texto introduzido sobe na validacao
uo_toolbar.of_add_textbox(/*keys*/ uo_toolbar.MAIN_BAR + "/search", /*text*/ "", /*width*/ 160, /*tooltip*/ "Procurar (Enter para validar)")

// Uma etiqueta antes de um seletor de data
uo_toolbar.of_add_label(/*keys*/ uo_toolbar.MAIN_BAR + "/lbl_due", /*text*/ "Prazo :")
uo_toolbar.of_add_datepicker(/*keys*/ uo_toolbar.MAIN_BAR + "/due", /*date*/ "2026-07-11", /*tooltip*/ "Data limite")

// event ue_text_changed de uo_toolbar
if as_keys = "main/search" then of_filter(as_text)

// event ue_date_changed de uo_toolbar : as_date no formato "aaaa-mm-dd"
if as_keys = "main/due" then id_due_date = Date(as_date)

Duas barras e disposição memorizada #

Com ib_reorderable = true, o utilizador pode agarrar numa barra pela respetiva pega (à esquerda da barra) e deslocá-la para outra banda ou para outra posição. A disposição deve ser conservada ao fechar e reposta ao abrir.

// Sem esta linha nao ha pega : o utilizador nao pode deslocar nada
uo_toolbar.ib_reorderable = true

// A barra principal e os seus dois botoes
uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/new",  /*text*/ "Novo",  /*image*/ "", /*tooltip*/ "")
uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/open", /*text*/ "Abrir", /*image*/ "", /*tooltip*/ "")

// Segunda barra, colocada na banda 2 (segunda fila), na primeira posicao
uo_toolbar.of_add_bar(/*key*/ "format", /*band*/ 2, /*index*/ 1)
uo_toolbar.of_add_toggle(/*keys*/ "format/bold", /*text*/ "N", /*image*/ "", /*tooltip*/ "Negrito")

// Tambem e possivel recolocar uma barra a qualquer momento pelas suas propriedades
uo_toolbar.of_bar(/*key*/ "format").ii_band  = 1
uo_toolbar.of_bar(/*key*/ "format").ii_index = 2    // segunda barra da primeira fila

// event ue_layout_changed de uo_toolbar : conservar a disposicao escolhida
is_layout = as_layout_json

// Na abertura seguinte : repor o que o utilizador tinha organizado
if is_layout <> "" then uo_toolbar.of_set_layout(/*layout_json*/ is_layout)

Botão dividido e alternadores exclusivos #

// Colar : a parte principal cola de imediato, a seta propoe as outras formas
uo_toolbar.of_add_split_button(/*keys*/ "edit/paste", /*text*/ "", /*image*/ "mono:img\paste.svg", /*tooltip*/ "Paste")
uo_toolbar.of_add_menu_item(/*keys*/ "edit/paste/plain", /*label*/ "Plain text", /*image*/ "")
uo_toolbar.of_add_menu_item(/*keys*/ "edit/paste/special", /*label*/ "Paste special...", /*image*/ "")

// Os alternadores de alinhamento partilham um grupo : um so premido de cada vez
uo_toolbar.of_add_toggle(/*keys*/ "edit/left", /*text*/ "", /*image*/ "mono:img\left.svg", /*tooltip*/ "Left")
uo_toolbar.of_add_toggle(/*keys*/ "edit/center", /*text*/ "", /*image*/ "mono:img\center.svg", /*tooltip*/ "Center")
uo_toolbar.of_add_toggle(/*keys*/ "edit/right", /*text*/ "", /*image*/ "mono:img\right.svg", /*tooltip*/ "Right")
uo_toolbar.of_item(/*keys*/ "edit/left").is_group = "align"
uo_toolbar.of_item(/*keys*/ "edit/center").is_group = "align"
uo_toolbar.of_item(/*keys*/ "edit/right").is_group = "align"
uo_toolbar.of_item(/*keys*/ "edit/left").ib_checked = true

// event ue_clicked de uo_toolbar : a parte principal do botao dividido
if as_keys = "edit/paste" then of_paste()

// event ue_toggled de uo_toolbar : so o alternador premido o despoleta
if ab_checked and Left(as_keys, 5) = "edit/" then of_align(Mid(as_keys, 6))

Excedente: «Mais ferramentas» #

Quando a largura deixa de ser suficiente, as ferramentas que não cabem são recolhidas num menu Mais ferramentas assinalado por um galão no fim da barra. É automático, não há nada a programar: as ferramentas recolhidas continuam clicáveis e acionam os mesmos eventos. Um campo recolhido — caixa de texto ou seletor de data — continua a ser um campo real: escreve-se nele, escolhe-se nele uma data, e o evento é acionado como se a ferramenta tivesse ficado na barra.

Altura automática #

Não há nada para ativar: o número de filas (of_set_layout) dita a altura, a barra ajusta-se sozinha e avisa-o.

// event ue_auto_height de uo_toolbar
uo_content.y      = uo_toolbar.y + al_height
uo_content.height = parent.workspaceheight() - uo_content.y

Ver Base comum.

Boas práticas #

Utilize MAIN_BAR enquanto uma só barra bastar: nasce com a sua primeira ferramenta, não é preciso acrescentá-la. Para a posicionar noutro lugar que não depois das outras barras, acrescente-a antes de qualquer ferramenta — of_add_bar(MAIN_BAR, 1, 1); uma vez nascida, of_add_bar(MAIN_BAR) devolve -5 e desloca-se por of_bar(MAIN_BAR).ii_band.
Numa toolbar, of_register_shortcut recebe o endereço da ferramenta ou da entrada que despoleta. Um atalho precisa de Ctrl ou Alt, ou de uma tecla de F1 a F24: uma tecla sozinha fica para a escrita.
Aceder sempre a uma ferramenta pelo seu caminho — of_item("main/save") — e não apenas pelo identificador: é isso que torna os identificadores reutilizáveis de uma barra para outra.
Agrupar as ferramentas afins com of_add_separator("main") em vez de recorrer a barras suplementares.
Nos botões apenas com ícone, preencher sempre o tooltip: é a única etiqueta de que o utilizador dispõe.
Se for permitido ao utilizador reorganizar as barras, memorizar ue_layout_changed e voltar a aplicar of_set_layout na abertura, caso contrário o esforço perde-se em cada arranque.
Chamar of_reset() antes de reconstruir integralmente a barra de ferramentas para outro contexto.
Quando os comandos se tornam demasiado numerosos para uma barra, passar para o ribbon, organizado por separadores e grupos.

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.