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 o id 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
uo_bar.of_add_button(/*key*/ "save", /*image_file*/ "mono:img\packimages.dll:svg/samples/save", /*text*/ "Save")
uo_bar.of_add_button(/*key*/ "find", /*image_file*/ "mono:img\packimages.dll:svg/samples/find", /*text*/ "Find")
uo_bar.of_add_button(/*key*/ "copy", /*image_file*/ "", /*text*/ "Copy") // no icon
// 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 |
|---|---|---|---|
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 |
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. Um predefinido desativado ou oculto não toma o Enter: a tecla fica com a janela. 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_image_file, string as_text) → long | Adiciona um botão de comando (id, ficheiro de imagem, rótulo) no fim da barra. mono: na imagem recolore-a ao tema; um rótulo vazio faz um botão só ícone. Devolve 0, -5 com chave vazia, uma chave que contém / ou uma barra vertical, uma chave já presente na barra ou sem imagem nem texto |
of_insert_button (string as_key, integer ai_index, string as_image_file, string as_text) → long | Insere um botão de comando na posição ai_index (a partir de 1), deslocando os restantes. Devolve 0, -5 com chave vazia, uma chave que contém / ou uma barra vertical, uma chave já presente na barra ou 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) 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_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 ou não desenhado em modo demo), -2 se não criado |
of_register_shortcut (string as_chord, string as_key) → long | Dá a UM botão um atalho de teclado (Ctrl+S, F5…): premido em qualquer ponto da janela, aciona o botão (ue_clicked), mesmo com o foco noutro lado. É independente da letra Alt do botão: desativá-lo, mudar a sua letra ou reativá-lo nunca lhe toca. Uma combinação vazia remove-o. Numa barra um atalho nomeia sempre um botão: a forma com um argumento, ou uma chave que não nomeia nenhum botão, devolve -5. Devolve 0, -2 se não criado |
of_button (string as_key) → n_pbt_buttonbar_button | Devolve o handle de um botão (por id) para ler ou alterar as suas propriedades (ver abaixo) |
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 |
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 o Enter, nem o Esc, nem o seu atalho o acionam |
ib_visible | boolean | true | Mostra ou oculta um botão; oculto, mantém o lugar e regressa onde estava |
is_text | string | "" | Rótulo do botão; alterar após adicionar. 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 |
il_badge | long | 0 | Pequeno emblema de contagem no canto do botão (0 = nenhum) |
is_shortcut | string | "" | Mnemónico deste botão: Alt+a letra aciona-o, de qualquer ponto da janela, e a letra é sublinhada na sua etiqueta. Uma letra (usa-se a primeira); vazio = nenhuma. Um atalho registado explicitamente para a mesma tecla (of_register_shortcut) passa à frente da letra; um menu PB que usa a mesma letra perde-a enquanto o botão puder acionar-se. Enquanto o botão está desativado, oculto ou não desenhado em modo demo, a sua letra fica para a janela |
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 (-1 = 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 |