buttonbar — u_pbt_buttonbar #
← Referência dos componentes · Índice do guia
buttonbar alinha uma fila de botões de comando — ícone, rótulo ou ambos — num único componente. Um clique reporta a chave do botão (
ue_clicked); cada botão é controlado por um handle (of_button) para o desativar, colorir ou ocultar. O componente a preferir assim que há vários botões: um WebView2 para toda a barra, onde Nbuttonseparados custariam N.
▶ Ver ao vivo — Aplicação de demonstração, mosaico Button bar, com o código e esta página lado a lado.
Início rápido #
// A command bar in three lines : key, label, icon
// ("&Save" underlines the S : Alt+S fires the button from anywhere in the window)
uo_bar.of_add_button(/*key*/ "save", /*text*/ "&Save", /*image*/ "mono:img\packimages.dll:svg/samples/save")
uo_bar.of_add_button(/*key*/ "find", /*text*/ "&Find", /*image*/ "mono:img\packimages.dll:svg/samples/find")
uo_bar.of_add_button(/*key*/ "copy", /*text*/ "&Copy")
// A chord : Ctrl+S fires Save, whatever control has the focus
uo_bar.of_button(/*key*/ "save").is_shortcut = "Ctrl+S"
// Grey out a button
uo_bar.of_button(/*key*/ "copy").ib_enabled = false
// React : ue_clicked carries the button key
// (in the ue_clicked event of the component)
CHOOSE CASE as_key
CASE "save" ; wf_save()
CASE "find" ; wf_find()
END CHOOSEPropriedades #
| Propriedade | Tipo | Predefinido | Descrição |
|---|---|---|---|
ib_enabled | boolean | true | A barra inteira ativa ou desativada. Desativada, nenhum botão responde — nem clique, nem Enter, Esc, letra Alt ou atalho: essas teclas ficam para a janela — e a barra sai da ordem de tabulação. Cada botão mantém o seu próprio ib_enabled |
ii_padding_x | integer | 12 | Recuo esquerdo/direito da barra, em pixels: o espaço antes do primeiro botão e depois do último. 0 cola os botões às bordas; -1 = o do tema |
ii_padding_y | integer | 12 | Recuo superior/inferior da barra, em pixels. Um botão PREENCHE a altura da barra: este recuo decide a altura dos botões (barra mais alta ou recuo menor = botões mais altos). 12 por predefinição; -1 = o do tema |
ii_gap | integer | -1 | Espaço ENTRE dois botões, em pixels. -1 (predefinição) = o do tema. 0 junta os botões, separados por uma linha quando o tema a tem |
ii_image_size | integer | 0 | Tamanho dos ícones dos botões, em pixels; 0 = o do tema (18) |
ii_badge_size | integer | 0 | Altura dos emblemas, em pixels — o seu texto acompanha; 0 = a do tema (16) |
is_align | string | end | Alinha a fila: start (esquerda), center, end (direita, predefinição, como uma caixa de diálogo) ou justify (botões de igual largura em toda a largura). Valores lógicos (RTL) — constantes ALIGN_* |
is_default | string | "" | Chave do botão predefinido — a ação principal, pintada com o acento, que Enter aciona (como o OK de uma caixa de diálogo). Quando um botão da barra tem o foco do teclado, Enter aciona ESSE botão, que passa a ter o aspeto predefinido (a convenção do Windows); is_default relido continua a ser a chave posta. Sem botão predefinido, o botão com o foco mantém apenas o seu anel de foco. Um predefinido desativado ou oculto não toma o Enter: a tecla fica com a janela — nunca vai para o botão predefinido de OUTRA barra, mesmo que seja o único. Quando duas barras da mesma janela têm um botão predefinido (duas folhas MDI, dois painéis), o Enter vai para a do lado do foco. O papel sai com o seu botão: removê-lo, ou esvaziar a barra, esvazia is_default. Vazio = nenhum; apenas um botão predefinido de cada vez |
is_cancel | string | "" | Chave do botão cancelar — o que Esc aciona (como o Cancelar de uma caixa de diálogo). Desativado ou oculto, não toma o Esc. O papel sai com o seu botão: removê-lo, ou esvaziar a barra, esvazia is_cancel. Vazio = nenhum; apenas um botão cancelar de cada vez |
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 | Função |
|---|---|
of_add_button (string as_key, string as_text {, string as_image}) → long | Adiciona um botão de comando no fim da barra: a sua chave, o seu rótulo e, opcionalmente, o seu ícone (ficheiro de imagem; mono: recolore-o ao tema). O rótulo aceita marcação rica; &Save sublinha o S e faz Alt+S acionar o botão, && é um & literal. Um rótulo vazio dá um botão só com ícone. Devolve 0, -5 numa chave vazia, numa chave com / ou uma barra vertical, numa chave já na barra, ou num botão sem imagem nem texto |
of_insert_button (string as_key, string as_text, string as_image, integer ai_index) → long | Insere um botão de comando na posição ai_index (a partir de 1), deslocando os seguintes; além do último vai para o fim, em 0 ou menos para o início. Devolve 0, -5 numa chave vazia, numa chave com / ou uma barra vertical, numa chave já na barra, ou num botão sem imagem nem texto |
of_remove_button (string as_key) → long | Remove um botão pela sua chave; os restantes mantêm o seu estado vivo. A sua letra Alt, os atalhos que a aplicação lhe deu, o seu papel predefinido / cancelar, as suas cores e a sua tooltip saem com ele. Devolve 0, -5 com chave vazia ou uma chave que não nomeia nenhum botão |
of_move_button (string as_key, integer ai_index) → long | Move um botão para a posição ai_index (a partir de 1; além do último = no fim, 0 ou menos = no início) sem perder o seu estado vivo. Devolve 0, -5 com chave vazia ou uma chave que não nomeia nenhum botão |
of_clear_buttons ( ) → long | Remove todos os botões da barra, com as suas letras Alt, os atalhos que a aplicação lhes deu, os papéis predefinido / cancelar, cores e tooltips. Devolve 0, -2 se não criado |
of_clear_shortcuts ( ) → long | Remove o atalho de TODOS os botões: já não responde, já não aparece no tooltip, e is_shortcut relê-se vazio. As letras Alt ficam. Devolve 0, -2 se não criado |
of_focus_button (string as_key) → long | Põe o foco do teclado num ÚNICO botão — Não em vez de Sim perante uma pergunta destrutiva, para que o Enter responda Não. Devolve 0, -5 com chave vazia ou que não nomeia nenhum botão, -4 se o botão não o pode tomar (desativado, oculto, numa barra desativada ou não desenhado em modo demo), -2 se não criado |
of_register_shortcut (string as_chord, string as_key) → long | Dá um atalho de teclado (Ctrl+S, F5…) a UM botão, como o seu is_shortcut: premido em qualquer lugar da janela, aciona o botão (ue_clicked), mesmo quando o foco está noutro sítio, e junta-se ao seu tooltip. É independente da letra Alt do botão. Enquanto o botão não puder acionar-se (desativado, oculto, não desenhado), a tecla fica para a janela. Um atalho vazio remove-o. Numa barra um atalho nomeia sempre um botão: a forma de um argumento, ou uma chave que não nomeia nenhum botão, devolve -5; um atalho que a janela nunca pode lançar (uma letra sozinha, Ctrl+Shift) devolve -5 e mantém o atalho existente. Devolve 0, -2 se não criado |
of_button (string as_key) → n_pbt_buttonbar_button | Devolve o handle de um botão (pela sua chave) para ler ou mudar as suas propriedades (ver abaixo). Uma chave que não nomeia nenhum botão recebe um handle neutro partilhado: o que lhe é dado não vai para lado nenhum. of_count, of_keys_at e of_has contam também os botões ocultos |
Eventos #
| Evento | Quando |
|---|---|
ue_clicked (string as_key) | Um botão foi usado: um clique, Enter (o botão predefinido, ou o que tem o foco), Esc (o botão cancelar), a sua letra Alt ou um atalho registado nele. A sua chave é passada: uma aplicação que liga o Cancelar deve esperá-lo também pelo Esc. Um botão desativado não emite nada |
ue_button_rclicked (string as_key, long al_x, long al_y) | Clique direito sobre UM botão, ou tecla Menu sobre o que tem o foco, com a sua chave: o lugar para abrir o menu desse botão. Um botão desativado não responde. É o único evento desse clique direito: ue_rclicked não é lançado além dele; al_x, al_y: onde abrir o menu, em píxeis de ecrã — o ponteiro, ou pelo teclado (tecla Menu, Shift+F10) o canto inferior esquerdo do botão; um contextmenu abre-se aí tal como estão (uo_menu.of_show(al_x, al_y)) |
ue_rclicked ( ) | Clique direito na barra FORA de qualquer botão. Um clique direito num botão lança apenas ue_button_rclicked: um menu escrito em ambos nunca abre duas vezes |
Propriedades de um botão (of_button) #
| Propriedade | Tipo | Predefinido | Descrição |
|---|---|---|---|
ib_enabled | boolean | true | Ativa ou desativa um botão; desativado, não se clica e nem Enter, nem Esc, nem a sua letra Alt, nem o seu atalho o acionam — essas teclas ficam para a janela; as setas saltam-no |
ib_visible | boolean | true | Mostra ou oculta um botão; oculto, mantém o lugar e regressa onde estava |
is_text | string | "" | O rótulo do botão, marcação rica aceite; muda-se depois de adicionar. &Save sublinha o S e faz Alt+S acionar o botão de qualquer lugar da janela, como um CommandButton PowerBuilder; && é um & literal. Um botão mantém um rótulo ou um ícone: esvaziar o rótulo de um botão sem ícone é recusado, e o rótulo relê-se inalterado |
is_image | string | "" | Ícone do botão (ficheiro de imagem; mono: segue o tema); alterar após adicionar. Esvaziar o ícone de um botão sem rótulo é recusado. Um botão só com ícone é anunciado ao leitor de ecrã pela sua tooltip (is_tooltip), senão pela sua chave |
is_style | string | standard | O aspeto do botão: standard, primary (o bloco de destaque), flat (sem moldura em repouso) ou danger (uma ação destrutiva, na cor de perigo do tema) — constantes STYLE_*; um valor desconhecido relê-se standard. Um botão desativado perde o preenchimento |
is_badge | string | "" | Um pequeno emblema no canto do botão: um número (3; além de 99 mostra 99+) ou uma palavra curta (New, !). "" ou 0 = nenhum. Um leitor de ecrã ouve-o com o nome do botão |
il_badge | long | 0 | O mesmo emblema, como número (0 = nenhum); um emblema-palavra relê-se 0 aqui |
il_badge_color | long | -1 | Cor do emblema DESTE botão; -1 = a do tema, 0 é o preto. O texto por cima é escolhido para continuar legível |
is_mnemonic | string | "" | A letra Alt do botão quando não é o & do seu rótulo — prevalece sobre ele: uma letra ou um dígito, a primeira da sua espécie no rótulo é sublinhada. Vazio = o & do rótulo. Enquanto o botão não puder acionar-se, a sua letra fica para a janela |
is_shortcut | string | "" | Um ATALHO de teclado para este botão — Ctrl+S, F5, Ctrl+Shift+P: premido em qualquer lugar da janela, aciona o botão e junta-se ao seu tooltip (Save (Ctrl+S)). Relê-se na sua forma canónica (ctrl+s); um atalho que a janela nunca pode lançar é recusado e relê-se vazio. Como of_register_shortcut(chord, key). A letra Alt é o & do rótulo, ou is_mnemonic |
il_back_color | long | -1 | Fundo DESTE botão (-1 = o do componente, que segue o tema) |
il_text_color | long | -1 | Cor do texto DESTE botão (-1 = a do componente) |
il_back_color_hover | long | -1 | Fundo DESTE botão ao passar (-1 = o do componente) |
il_text_color_hover | long | -1 | Cor do texto DESTE botão ao passar (-1 = a do componente) |
il_accent | long | -1 | Destaque DESTE botão: pinta o seu emblema e, quando é o botão predefinido (ou no estilo primary), o seu preenchimento (-1 = o destaque do componente) |
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 |
is_accessible_name · is_accessible_description | O nome e a descrição que um leitor de ecrã diz | 3.4 Propriedades e eventos opcionais |