menubar — `u_pbt_menubar` #

← Referência dos componentes · Índice do guia

Barra de menus da aplicação: menus, submenus, entradas marcáveis, separadores, ícones e atalhos — tudo desenhado pela biblioteca, sem qualquer menu do Windows.

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

Em resumo #

Userobject	`u_pbt_menubar`
Classe de itens	`n_pbt_menubar_item` (uma entrada) · `n_pbt_menubar_menu` (um menu da barra)
Serve para	Dar à sua janela a barra de menus da aplicação, com o mesmo tema de tudo o resto
Princípio	Declara os menus e depois as suas entradas; cada entrada volta a encontrar-se pelo endereço `menu/id`

Início rápido #

// evento open da janela
uo_menus.of_add_menu(/*key*/ "file", /*text*/ "Ficheiro")
uo_menus.of_add_item(/*keys*/ "file/open", /*text*/ "Abrir")
uo_menus.of_add_item(/*keys*/ "file/save", /*text*/ "Guardar")

// event ue_item_selected : (string as_keys)
choose case as_keys
	case "file/open"; of_open_document()
	case "file/save"; of_save_document()
end choose

O modelo: três níveis, uma chave por nível #

Uma barra de menus tem três níveis, e cada um indica-se pela sua chave:

Nível	Acrescentado por	Chave
O menu da barra	`of_add_menu`	a sua chave, `file`
A entrada de um menu	`of_add_item`	o endereço `menu/entrada`, `file/open`
A subentrada de uma entrada	`of_add_item`	o endereço `menu/entrada/subentrada`, `file/export/pdf` — tão fundo quanto for preciso

Uma chave só é única sob o seu pai: por isso uma entrada designa-se sempre pelo seu endereço completo, primeiro o menu — nunca pela chave sozinha. Dois menus podem assim ter cada um a sua entrada open, e dois submenus o seu próprio pdf (file/export/pdf, file/print/pdf), sem se estorvarem. Uma chave não contém / nem |, não está vazia e não começa por __: as adições recusam-na (-5), tal como um endereço já ocupado ou um pai nunca adicionado.

Um separador não tem chave: of_add_separator traça uma linha no fim de um menu (file) ou da cascata de uma entrada (file/export), e depois não há nada a reler.

Propriedades #

Propriedade	Tipo	Predefinição	Papel
`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	`""`	Dica simples apresentada ao passar sobre o componente
`is_super_tooltip_title`	string	`""`	Título da dica enriquecida (prevalece sobre `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Texto da dica enriquecida (marcação rica aceite)
`is_super_tooltip_image`	string	`""`	Imagem da dica enriquecida
`ib_wrap`	boolean	`false`	`false` (predefinição): a barra fica numa só linha; os títulos que não cabem, a partir do fim, passam para o menu de um chevron na sua ponta (as suas entradas em cascata), e a altura deixa de mudar. `true`: a barra quebra a linha e anuncia a sua nova altura (`ue_auto_height`) — o que fazia antes da 4.0
`ib_track_hover`	boolean	`false`	Subscrição de `ue_item_hover`: sem ela os menus nem sequer comunicam a entrada apontada — um evento despoletado a cada movimento do ponteiro só é enviado a uma aplicação que o pediu

Propriedades de uma entrada — `n_pbt_menubar_item` #

Obtidas através de of_item(endereço) — of_item("file/export/pdf"). Um endereço de um só nível designa um menu, não uma entrada: o seu handle não muda nada, use of_menu.

Propriedade	Tipo	Predefinição	Papel
`is_text`	string	—	Muda a etiqueta da entrada, a quente
`ib_enabled`	boolean	`true`	Entrada ativa; uma entrada desativada deixa de responder ao clique
`ib_visible`	boolean	`true`	Entrada retirada da lista sem ser eliminada — submenu e atalho adormecidos com ela; mantém a sua chave e volta tal como estava. Um atalho adormecido mantém a sua combinação: também não chega à sua aplicação; `is_shortcut = ""` devolve-lha
`is_shortcut`	string	`""`	O acelerador mostrado à direita da entrada (`Ctrl+S`) — e activo: a combinação levanta `ue_item_selected` para essa entrada, esteja onde estiver o foco. Num menu aprendem-se os atalhos de uma aplicação; uma tecla mostrada que nada faz ensina o contrário. Teclas: uma letra, um algarismo, de `F1` a `F24`, `Enter`, `Esc`, `Del`, `Insert`, `Home`, `End`, `PageUp`, `PageDown`, e com Ctrl ou Alt também `+`, `-`, `,`, `.`, as setas (`Left`…), `Space`, `Tab`, `Backspace` (`Ctrl++` para o zoom). Um atalho vai numa folha: numa entrada que abre uma cascata não é mostrado nem disparado. A cadeia vazia retira ambos
`ib_checked`	boolean	`false`	Marca apresentada à frente da entrada — para uma opção que se liga e desliga
`is_image`	string	`""`	O ícone da entrada, mudado a quente: a entrada mantém o seu lugar na lista. Mesmos caminhos que `of_add_item` (`mono:`, `tint:`, `ficheiro.dll:NOME`); a cadeia vazia retira-o
`is_group`	string	`""`	Faz da entrada uma entrada de opção: as entradas de um mesmo grupo sob o mesmo pai excluem-se — marcar uma (`ib_checked = true`, ou a escolha do utilizador) desmarca as outras, e uma bolinha redonda substitui o visto. `ue_item_selected` continua a dizer qual foi escolhida. A cadeia vazia torna-a de novo uma entrada comum
`il_accent`	long	`-1`	Acento desta entrada: o seu visto e a sua margem quando apontada (`-1` = o do tema)
`il_back_color`	long	`-1`	Fundo desta entrada no menu pendente, em repouso
`il_text_color`	long	`-1`	Cor do texto desta entrada
`il_back_color_hover`	long	`-1`	Fundo desta entrada quando apontada
`il_text_color_hover`	long	`-1`	Cor do texto desta entrada quando apontada
`is_tooltip`	string	`""`	Guardada e relida, mas uma entrada do menu pendente não mostra nenhuma dica: o menu pendente nativo não tem. Só os títulos dos menus mostram a sua (`of_menu`)
`is_super_tooltip_title`	string	`""`	Título da sua dica enriquecida — guardado, não mostrado (ver `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Texto da sua dica enriquecida — guardado, não mostrado
`is_super_tooltip_image`	string	`""`	Imagem da sua dica enriquecida — guardada, não mostrada

Propriedades de um menu — `n_pbt_menubar_menu` #

Obtidas através de of_menu(chave) — of_menu("file"). Cores e dica aparecem no título do menu na barra.

Propriedade	Tipo	Predefinição	Papel
`is_text`	string	—	Rótulo do menu, `&` incluído (mnemónica), mudado sem reconstruir a barra
`ib_enabled`	boolean	`true`	Menu esbatido: já não abre, as suas entradas e os seus atalhos com ele; o teclado salta-o
`ib_visible`	boolean	`true`	O menu sai da barra — entradas e atalhos adormecidos com ele — e volta tal e qual. Os atalhos adormecidos mantêm a sua combinação: também não chega à sua aplicação
`is_align`	string	`"start"`	`u_pbt_menubar.ALIGN_END` coloca o menu no fim da barra, como Ajuda — com os que o seguem no mesmo alinhamento, depois dele; `ALIGN_START` (predefinição) devolve-o para junto dos outros. Lógico: o fim é o lado esquerdo num layout da direita para a esquerda. Com o chevron, os títulos do fim recolhem-se primeiro
`il_accent`	long	`-1`	Acento deste menu: uma linha sob o seu título enquanto o menu pendente está aberto (`-1` = nenhum)
`il_back_color`	long	`-1`	Fundo do seu título, em repouso
`il_text_color`	long	`-1`	Cor do texto do seu título, em repouso
`il_back_color_hover`	long	`-1`	Fundo do seu título sob o ponteiro ou aberto
`il_text_color_hover`	long	`-1`	Cor do texto do seu título sob o ponteiro ou aberto
`is_tooltip`	string	`""`	Dica mostrada quando o ponteiro pousa no seu título
`is_super_tooltip_title`	string	`""`	Título da dica enriquecida do seu título
`is_super_tooltip_text`	string	`""`	Texto dessa dica enriquecida (marcação rica aceite)
`is_super_tooltip_image`	string	`""`	Imagem dessa dica enriquecida

Métodos #

Método	Papel
`of_add_menu (string as_key, string as_text)`	Acrescenta um menu à barra. Devolve `0` depois de aplicado, `-5` se a chave for recusada (vazia, com `/` ou uma barra vertical, a começar por `__`, ou já ocupada), `-2` se o componente não estiver criado
`of_add_item (string as_keys, string as_text)`	Acrescenta uma entrada no seu endereço: `file/open` no menu File, `file/export/pdf` sob a entrada Export, tão fundo quanto for preciso. Devolve `0` depois de aplicado, `-5` se o endereço for recusado: menos de dois níveis, um nível vazio, uma chave com `/` ou uma barra vertical ou a começar por `__`, um menu ou uma entrada pai nunca adicionados, ou um endereço já ocupado. `-2` se o componente não estiver criado
`of_add_item (string as_keys, string as_text, string as_image, boolean ab_checked)`	O mesmo, com o ícone e o visto. Para esbater a entrada, agora ou mais tarde, use o seu handle: `of_item(endereço).ib_enabled = false`. Devolve `0` depois de aplicado, `-5` se o endereço for recusado: menos de dois níveis, um nível vazio, uma chave com `/` ou uma barra vertical ou a começar por `__`, um menu ou uma entrada pai nunca adicionados, ou um endereço já ocupado. `-2` se o componente não estiver criado
`of_add_separator (string as_keys)`	Traça uma linha de separação no fim de um menu (`file`) ou da cascata de uma entrada (`file/export`). Devolve `0` depois de aplicado, `-5` se nada foi adicionado nesse endereço, `-2` se o componente não estiver criado
`of_add_header (string as_keys, string as_text)` → `long`	Acrescenta um cabeçalho de secção no fim de um menu (`view`) ou da cascata de uma entrada (`view/panels`): uma linha de título por cima das entradas que o seguem, até ao próximo cabeçalho ou separador. Não é uma entrada — nunca escolhido, nunca contado por `of_count`, nem no limite de demonstração — e não é desenhado quando todas as entradas que encabeça estão ocultas. Devolve `0` uma vez adicionado, `-5` se nada foi criado nesse endereço, `-2` se o componente não estiver criado
`of_item (string as_keys)` → `n_pbt_menubar_item`	Handle de uma entrada, pelo seu endereço — `of_item("file/export/pdf")` —, para ler ou definir as suas propriedades. É exatamente o que `ue_item_selected` devolve: o argumento volta tal e qual para aqui. Nunca a chave sozinha: dois submenus podem ter cada um o seu `pdf`, e só o endereço os distingue. Um endereço de um nível designa um menu: o seu handle não muda nada, use `of_menu`
`of_menu (string as_key)` → `n_pbt_menubar_menu`	Handle de um menu de primeiro nível, para o renomear ou apagar. `of_add_menu` só o podia fazer na criação: esbater Admin ao terminar sessão obrigava a reconstruir toda a barra; `ib_visible` retira-o da barra, entradas e atalhos adormecidos com ele
`of_remove_item (string as_keys)` → `long`	Retira uma entrada, no seu endereço (`file/open`, `file/export/pdf`) — com a sua cascata; as outras ficam. Os seus handles são libertados e o seu atalho desarmado: a tecla volta à sua aplicação. Sem ela só havia `of_clear`, que esvazia tudo — o menu dinâmico mais comum, uma lista de ficheiros recentes, obrigava a arrasar a barra inteira a cada documento aberto. Devolve `0` depois de aplicado, `-5` se nenhuma entrada viver nesse endereço, `-2` se o componente não estiver criado
`of_remove_menu (string as_key)` → `long`	Retira um menu de primeiro nível, com as suas entradas — handles libertados, atalhos desarmados. A barra é redesenhada e a sua altura reanunciada. Devolve `0` depois de aplicado, `-5` para um menu nunca adicionado, `-2` se o componente não estiver criado
`of_clear ( )`	Esvazia a barra — menus e entradas; os seus handles são libertados e os atalhos das entradas desarmados. Devolve `0` depois de aplicado, `-2` se o componente não estiver criado
`of_reset ( )`	Esvazia a barra e repõe todas as propriedades no seu valor predefinido. Devolve `0` depois de aplicado, `-2` se o componente não estiver criado
`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	Disparado quando
`ue_menu_opening (string as_key)`	Levantado quando um menu de primeiro nível está prestes a abrir — e o menu pendente espera: só abre quando o evento tiver regressado. Active, esbata ou preencha aqui as suas entradas: a mudança vê-se nesta abertura, não na seguinte. Sem ele era preciso manter toda a barra a par do estado da aplicação em permanência, ou mostrar entradas que mentem
`ue_menu_closed (string as_key)`	O menu pendente de um menu de primeiro nível fechou-se sem escolha: pelo utilizador (clique fora, Esc, ou deslize para o menu vizinho), ou pelo seu código que remove, esvazia, oculta ou desativa o menu aberto (`of_remove_menu`, `of_clear`, `ib_visible`, `ib_enabled`) — uma ordem também o levanta. Desfaça aqui o que `ue_menu_opening` tinha preparado (uma pré-visualização, uma seleção). Uma escolha levanta `ue_item_selected` em vez disso, e `of_reset` não levanta nada
`ue_item_selected (string as_keys)`	O utilizador escolheu uma entrada, ou premiu o seu atalho. `as_keys` é o seu endereço, primeiro o menu — `file/open`, `file/export/pdf`: a chave sozinha não diz de que submenu sai, e dois submenus podem ter cada um a sua. Esse mesmo texto volta tal e qual a `of_item`. Uma entrada esbatida, oculta ou retirada enquanto o seu menu pendente estava aberto não levanta nada
`ue_item_hover (string as_keys)`	Com `ib_track_hover = true`: a entrada sob o ponteiro ou o teclado num menu aberto, pelo seu endereço (`file/export/pdf`) — também uma entrada desativada, a sua ajuda pode dizer porquê. Despoletado uma vez por entrada, depois com um endereço vazio quando o menu se fecha (antes de `ue_item_selected` numa escolha): escreva o texto de ajuda de uma barra de estado e depois esvazie-o
`ue_auto_height (long al_height)`	A barra anuncia a altura de que precisa — 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 está ausente: o componente fica vazio
`ue_bg_color (long al_color)`	O componente calculou a sua cor de fundo do tema; o userobject já a adotou (`backcolor`)

Uma linha, por predefinição. Os títulos que não cabem passam para o chevron no fim da barra (ib_wrap = false, a predefinição): a altura continua a ser a de uma linha e ue_auto_height é despoletado uma vez. Com ib_wrap = true a barra quebra a linha: nunca desliza, a sua altura acompanha as filas e ue_auto_height indica-lhe quanto a cada mudança de largura.

Com o teclado #

Tecla	Efeito
Alt · F10	Dá o teclado à barra e sublinha as letras dos menus, como em qualquer aplicação Windows; um segundo toque devolve-o
»	O chevron dos títulos que não cabem: as setas param nele como num título, Enter ou Baixo abre a lista dos menus ocultos, e Alt + a letra de um menu oculto abre esse menu a partir do chevron
Alt + letra	Abre o menu dessa letra (`&Ficheiro`) a partir de qualquer controlo da janela — um campo, um DataWindow. Um atalho `Alt+letra` registado pela sua aplicação vem primeiro. Dois menus na mesma letra: a faixa passa de um para o outro, Enter abre. Uma letra acentuada ou não latina tecla-se como no teclado (`&Édition`: Alt + a tecla do É)
Setas	Percorrem os menus e as suas entradas, saltando os menus esbatidos; a direita abre uma subentrada, a esquerda sobe. Em escrita da direita para a esquerda (`RTL`) tudo se inverte: na barra, no menu pendente (alinhado pela borda direita do seu título) e nas cascatas, que se abrem à esquerda — a esquerda abre, a direita sobe
Enter	Num menu pendente: escolhe a entrada realçada (`ue_item_selected`). Sobre um título da barra, Enter, Espaço ou Seta para baixo abrem o menu. Espaço não escolhe uma entrada — é também a regra do Windows
Esc	Fecha o menu aberto e depois devolve o foco ao controlo que o tinha

Uma barra de menus nunca fica com o foco. Um clique num título e depois uma escolha com o rato: o teclado volta ao controlo onde se escrevia antes de ue_item_selected partir. Editar > Colar cola portanto no campo em edição, e GetFocus() nomeia-o no evento.

Exemplos #

Uma barra de menus completa #

// Congelar o desenho durante a construcao
uo_menus.of_set_redraw(/*on*/ false)

// O menu Ficheiro, com um icone em Abrir e uma linha antes de Sair
uo_menus.of_add_menu(/*key*/ "file", /*text*/ "&Ficheiro")
uo_menus.of_add_item(/*keys*/ "file/open", /*text*/ "&Abrir...", /*image*/ "mono:img\packimages.dll:svg/samples/folder-open", /*checked*/ false)
uo_menus.of_add_separator(/*keys*/ "file")
uo_menus.of_add_item(/*keys*/ "file/quit", /*text*/ "&Sair")

// Um submenu: Exportar, e depois os seus dois formatos
uo_menus.of_add_item(/*keys*/ "file/export", /*text*/ "&Exportar")
uo_menus.of_add_item(/*keys*/ "file/export/csv", /*text*/ "CSV")
uo_menus.of_add_item(/*keys*/ "file/export/pdf", /*text*/ "PDF")

// O menu Ver: uma opcao que se marca
uo_menus.of_add_menu(/*key*/ "view", /*text*/ "&Ver")
uo_menus.of_add_item(/*keys*/ "view/grid", /*text*/ "&Grelha", /*image*/ "", /*checked*/ true)

// Um unico redesenho, com tudo
uo_menus.of_set_redraw(/*on*/ true)

Marcar, desmarcar, desativar #

// O utilizador inverteu a apresentacao da grelha
uo_menus.of_item(/*keys*/ "view/grid").ib_checked = not uo_menus.of_item(/*keys*/ "view/grid").ib_checked

// Uma entrada que deixou de fazer sentido e desativada, nao desaparece:
// o utilizador tem de poder ver que existe
uo_menus.of_item(/*keys*/ "file/save").ib_enabled = false

Entradas de opção e um atalho de zoom #

// Duas entradas DE OPCAO: marcar uma desmarca a outra, uma bolinha substitui o visto
uo_menus.of_add_item(/*keys*/ "view/small", /*text*/ "Icones &pequenos")
uo_menus.of_add_item(/*keys*/ "view/large", /*text*/ "Icones &grandes")
uo_menus.of_item(/*keys*/ "view/small").is_group = "size"
uo_menus.of_item(/*keys*/ "view/large").is_group = "size"
uo_menus.of_item(/*keys*/ "view/large").ib_checked = true

// O zoom: Ctrl++ e mostrado E activo, esteja onde estiver o foco
uo_menus.of_add_item(/*keys*/ "view/zoomin", /*text*/ "&Ampliar")
uo_menus.of_item(/*keys*/ "view/zoomin").is_shortcut = "Ctrl++"

Reconstruir a barra #

// Mudar de area de trabalho: esvazia-se e volta-se a por
// of_set_redraw evita repintar em cada linha
uo_menus.of_set_redraw(/*on*/ false)
uo_menus.of_clear()
uo_menus.of_add_menu(/*key*/ "tools", /*text*/ "&Ferramentas")
uo_menus.of_set_redraw(/*on*/ true)

Uma barra estreita, Ajuda no fim, um texto de ajuda na barra de estado #

// Help at the end of the bar ; what does not fit goes into the chevron
uo_menubar.of_menu(/*key*/ "help").is_align = u_pbt_menubar.ALIGN_END

// Section headers in View
uo_menubar.of_add_header(/*keys*/ "view", /*text*/ "Panels")
uo_menubar.of_add_item(/*keys*/ "view/tree", /*text*/ "Tree")
uo_menubar.of_add_item(/*keys*/ "view/output", /*text*/ "Output")

// A help text in the status bar for the pointed entry
uo_menubar.ib_track_hover = true

// ue_item_hover (string as_keys) of uo_menubar
choose case as_keys
	case "file/save"
		st_status.Text = "Saves the document"
	case ""
		st_status.Text = ""
end choose

Boas práticas #

Dê uma chave de negócio estável a cada nível (file, save): ue_item_selected devolve o endereço file/save, nunca o rótulo — não muda com a língua.
Desative em vez de retirar: uma entrada ausente deixa o utilizador à procura, uma desativada diz-lhe que existe e que lhe falta alguma coisa.
Enquadre a construção com of_set_redraw(false) / of_set_redraw(true): uma barra completa são trinta chamadas em pouco tempo.
Reposicione o que está sob a barra no ue_auto_height — a altura depende do tema e do corpo de letra, não é a mesma em todo o lado.
Os rótulos são seus: traduza-os antes de of_add_item, ou mude-os a quente com of_item(...).is_text / of_menu(...).is_text. of_set_translation só traduz os textos próprios de um componente, e a barra de menus não tem nenhum.
Ponha um & em cada título (&Ficheiro): Alt + a letra abre o menu de qualquer lado, como em qualquer aplicação Windows.

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.