buttonbar — u_pbt_buttonbar #
← Referencia de componentes · Índice de la guía
buttonbar alinea una fila de botones de comando — icono, etiqueta o ambos — en un solo componente. Un clic informa la clave del botón (
ue_clicked); cada botón se controla con un handle (of_button) para deshabilitarlo, colorearlo u ocultarlo. El componente a preferir en cuanto hay varios botones: un WebView2 para toda la barra, donde Nbuttonseparados costarían N.
▶ Verlo en vivo — Aplicación de demostración, mosaico Button bar, con el código y esta página lado a lado.
Inicio 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 CHOOSEPropiedades #
| Propiedad | Tipo | Predeterminado | Descripción |
|---|---|---|---|
ib_enabled | boolean | true | La barra entera habilitada o deshabilitada. Deshabilitada, ningún botón responde — ni clic, ni Intro, Esc, letra Alt o atajo: esas teclas se quedan en la ventana — y la barra sale del orden de tabulación. Cada botón conserva su propio ib_enabled |
ii_padding_x | integer | 12 | Sangría izquierda/derecha de la barra, en píxeles: el espacio antes del primer botón y después del último. 0 pega los botones a los bordes; -1 = la del tema |
ii_padding_y | integer | 12 | Sangría superior/inferior de la barra, en píxeles. Un botón LLENA la altura de la barra: esta sangría decide la altura de los botones (barra más alta o sangría menor = botones más altos). 12 por defecto; -1 = la del tema |
ii_gap | integer | -1 | Espacio ENTRE dos botones, en píxeles. -1 (por defecto) = el del tema. 0 junta los botones, separados por una línea cuando el tema la tiene |
ii_image_size | integer | 0 | Tamaño de los iconos de los botones, en píxeles; 0 = el del tema (18) |
ii_badge_size | integer | 0 | Altura de las insignias, en píxeles — su texto sigue; 0 = la del tema (16) |
is_align | string | end | Alinea la fila: start (izquierda), center, end (derecha, predeterminado, como un cuadro de diálogo) o justify (botones de igual ancho en todo el ancho). Valores lógicos (RTL) — constantes ALIGN_* |
is_default | string | "" | Clave del botón predeterminado — la acción principal, pintada con el acento, que Intro activa (como el Aceptar de un cuadro de diálogo). Cuando un botón de la barra tiene el foco del teclado, Intro activa ESE botón, que lleva entonces el aspecto predeterminado (la convención de Windows); is_default releído sigue siendo la clave puesta. Sin botón predeterminado, el botón con el foco solo conserva su anillo de foco. Un predeterminado deshabilitado u oculto no toma Intro: la tecla se queda en la ventana — nunca va al botón predeterminado de OTRA barra, aunque sea el único. Cuando dos barras de una misma ventana tienen un botón predeterminado (dos hojas MDI, dos paneles), Intro va a la del lado del foco. El rol se va con su botón: quitarlo, o vaciar la barra, vacía is_default. Vacío = ninguno; solo un botón predeterminado a la vez |
is_cancel | string | "" | Clave del botón cancelar — el que Esc activa (como el Cancelar de un cuadro de diálogo). Deshabilitado u oculto, no toma Esc. El rol se va con su botón: quitarlo, o vaciar la barra, vacía is_cancel. Vacío = ninguno; solo un botón cancelar a la vez |
is_theme_style | string | "" | Estilo visual del componente (constantes THEME_STYLE_*); vacío = el de la aplicación, seguido en cada cambio |
is_theme_mode | string | "" | Variante clara u oscura (constantes THEME_MODE_*); vacío = la de la aplicación, seguida en cada cambio |
il_theme_accent | long | -1 | Color de acento de este componente (-1 = acento de la aplicación, o el del tema) |
is_tooltip | string | "" | Tooltip simple mostrado al pasar el ratón por el componente |
is_super_tooltip_title | string | "" | Título del tooltip enriquecido (prevalece sobre is_tooltip) |
is_super_tooltip_text | string | "" | Texto del tooltip enriquecido (se acepta el marcado enriquecido) |
is_super_tooltip_image | string | "" | Imagen del tooltip enriquecido |
Métodos #
| Método | Función |
|---|---|
of_add_button (string as_key, string as_text {, string as_image}) → long | Agrega un botón de comando al final de la barra: su clave, su etiqueta y, opcionalmente, su icono (archivo de imagen; mono: lo recolorea al tema). La etiqueta acepta marcado enriquecido; &Save subraya la S y hace que Alt+S active el botón, && es un & literal. Una etiqueta vacía da un botón de solo icono. Devuelve 0, -5 con una clave vacía, una clave que contiene / o una barra vertical, una clave ya en la barra, o un botón sin imagen ni texto |
of_insert_button (string as_key, string as_text, string as_image, integer ai_index) → long | Inserta un botón de comando en la posición ai_index (desde 1), desplazando los siguientes; más allá del último va al final, en 0 o menos al principio. Devuelve 0, -5 con una clave vacía, una clave que contiene / o una barra vertical, una clave ya en la barra, o un botón sin imagen ni texto |
of_remove_button (string as_key) → long | Quita un botón por su clave; los demás conservan su estado vivo. Su letra Alt, los atajos que la aplicación le dio, su rol predeterminado / cancelar, sus colores y su tooltip se van con él. Devuelve 0, -5 con clave vacía o una clave que no nombra ningún botón |
of_move_button (string as_key, integer ai_index) → long | Mueve un botón a la posición ai_index (a partir de 1; más allá del último = al final, 0 o menos = al principio) sin perder su estado vivo. Devuelve 0, -5 con clave vacía o una clave que no nombra ningún botón |
of_clear_buttons ( ) → long | Quita todos los botones de la barra, con sus letras Alt, los atajos que la aplicación les dio, los roles predeterminado / cancelar, colores y tooltips. Devuelve 0, -2 si no está creado |
of_clear_shortcuts ( ) → long | Quita el atajo de TODOS los botones: ya no responde, ya no aparece en el tooltip, y is_shortcut se relee vacío. Las letras Alt se quedan. Devuelve 0, -2 si no está creado |
of_focus_button (string as_key) → long | Pone el foco del teclado en UN botón — No en lugar de Sí ante una pregunta destructiva, para que Intro responda No. Devuelve 0, -5 con clave vacía o que no nombra ningún botón, -4 si el botón no puede tomarlo (deshabilitado, oculto, en una barra deshabilitada o no dibujado en modo demo), -2 si no está creado |
of_register_shortcut (string as_chord, string as_key) → long | Da un atajo de teclado (Ctrl+S, F5…) a UN botón, como su is_shortcut: pulsado en cualquier parte de la ventana, activa el botón (ue_clicked), aunque el foco esté en otro sitio, y se une a su tooltip. Es independiente de la letra Alt del botón. Mientras el botón no pueda activarse (deshabilitado, oculto, no dibujado), la tecla se queda en la ventana. Un atajo vacío lo quita. En una barra un atajo nombra siempre un botón: la forma de un argumento, o una clave que no nombra ningún botón, devuelve -5; un atajo que la ventana nunca puede lanzar (una letra sola, Ctrl+Shift) devuelve -5 y conserva el atajo existente. Devuelve 0, -2 si no está creado |
of_button (string as_key) → n_pbt_buttonbar_button | Devuelve el handle de un botón (por su clave) para leer o cambiar sus propiedades (ver más abajo). Una clave que no nombra ningún botón recibe un handle neutro compartido: lo que se le da no va a ninguna parte. of_count, of_keys_at y of_has cuentan también los botones ocultos |
Eventos #
| Evento | Cuándo |
|---|---|
ue_clicked (string as_key) | Se ha usado un botón: un clic, Intro (el botón predeterminado, o el que tiene el foco), Esc (el botón cancelar), su letra Alt o un atajo registrado en él. Se pasa su clave: una aplicación que conecta Cancelar debe esperarlo también desde Esc. Un botón deshabilitado no emite nada |
ue_button_rclicked (string as_key, long al_x, long al_y) | Clic derecho sobre UN botón, o tecla Menú sobre el que tiene el foco, con su clave: el lugar donde abrir el menú de ese botón. Un botón deshabilitado no responde. Es el único evento de ese clic derecho: ue_rclicked no se lanza además; al_x, al_y: dónde abrir el menú, en píxeles de pantalla — el puntero, o con el teclado (tecla Menú, Mayús+F10) la esquina inferior izquierda del botón; un contextmenu se abre allí tal cual (uo_menu.of_show(al_x, al_y)) |
ue_rclicked ( ) | Clic derecho sobre la barra FUERA de cualquier botón. Un clic derecho sobre un botón lanza solo ue_button_rclicked: un menú escrito en ambos nunca se abre dos veces |
Propiedades de un botón (of_button) #
| Propiedad | Tipo | Predeterminado | Descripción |
|---|---|---|---|
ib_enabled | boolean | true | Habilita o deshabilita un botón; deshabilitado, no se puede pulsar y ni Intro, ni Esc, ni su letra Alt, ni su atajo lo activan — esas teclas se quedan en la ventana; las flechas lo saltan |
ib_visible | boolean | true | Muestra u oculta un botón; oculto, conserva su lugar y vuelve donde estaba |
is_text | string | "" | La etiqueta del botón, marcado enriquecido aceptado; se cambia después de agregarlo. &Save subraya la S y hace que Alt+S active el botón desde cualquier parte de la ventana, como un CommandButton de PowerBuilder; && es un & literal. Un botón conserva una etiqueta o un icono: vaciar la etiqueta de un botón sin icono se rechaza, y la etiqueta se relee sin cambios |
is_image | string | "" | Icono del botón (archivo de imagen; mono: sigue el tema); se cambia tras agregarlo. Vaciar el icono de un botón sin etiqueta se rechaza. Un botón de solo icono se anuncia al lector de pantalla por su tooltip (is_tooltip), si no por su clave |
is_style | string | standard | El aspecto del botón: standard, primary (el bloque de acento), flat (sin marco en reposo) o danger (una acción destructiva, en el color de peligro del tema) — constantes STYLE_*; un valor desconocido se relee standard. Un botón deshabilitado pierde su relleno |
is_badge | string | "" | Una pequeña insignia en la esquina del botón: un número (3; más allá de 99 muestra 99+) o una palabra corta (New, !). "" o 0 = ninguna. Un lector de pantalla la oye con el nombre del botón |
il_badge | long | 0 | La misma insignia, como número (0 = ninguna); una insignia de palabra se relee 0 aquí |
il_badge_color | long | -1 | Color de la insignia de ESTE botón; -1 = el del tema, 0 es el negro. El texto encima se elige para que siga legible |
is_mnemonic | string | "" | La letra Alt del botón cuando no es el & de su etiqueta — prevalece sobre él: una letra o un dígito, la primera de su clase en la etiqueta se subraya. Vacío = el & de la etiqueta. Mientras el botón no pueda activarse, su letra se queda en la ventana |
is_shortcut | string | "" | Un ATAJO de teclado para este botón — Ctrl+S, F5, Ctrl+Shift+P: pulsado en cualquier parte de la ventana, activa el botón y se une a su tooltip (Save (Ctrl+S)). Se relee en su forma canónica (ctrl+s); un atajo que la ventana nunca puede lanzar se rechaza y se relee vacío. Como of_register_shortcut(chord, key). La letra Alt es el & de la etiqueta, o is_mnemonic |
il_back_color | long | -1 | Fondo de ESTE botón (-1 = el del componente, que sigue el tema) |
il_text_color | long | -1 | Color del texto de ESTE botón (-1 = el del componente) |
il_back_color_hover | long | -1 | Fondo de ESTE botón al pasar (-1 = el del componente) |
il_text_color_hover | long | -1 | Color del texto de ESTE botón al pasar (-1 = el del componente) |
il_accent | long | -1 | Acento de ESTE botón: tiñe su insignia y, cuando es el botón predeterminado (o en estilo primary), su relleno (-1 = el acento del componente) |
Heredado de la base común #
Estos miembros existen en todos los componentes visuales — no son propios de este. Se detallan una sola vez, en los capítulos transversales; esta tabla solo dice dónde leerlos.
| Miembros | Función | Detallado en |
|---|---|---|
of_count · of_keys_at · of_has | Recorrer lo que el componente contiene | 3.2 Los items |
of_reset | Poner el componente a cero | 3.6 Poner un componente a cero: of_reset() |
of_register_shortcut · of_clear_shortcuts | Atajos de teclado del componente | 3.5 Los atajos de teclado |
of_is_created · of_is_ready · of_get_last_error | Si ha nacido, si está listo, qué ha fallado | 3.7 Diagnóstico |
of_save_as_png · of_save_as_jpg | Exportar el render como imagen | 3.8 Exportar la representación como imagen |
of_set_redraw | Agrupar los cambios en un solo repintado | 3.10 Buenas prácticas |
of_preload_icons | Iconos mostrados sin retardo | Visualización instantánea: of_icon |
of_set_translation | Traducir una etiqueta del componente | 5.2 Adaptar una etiqueta: of_set_translation |
of_focus_webview | Dar el foco al componente | 6.4 Teclado y foco |
of_print · of_print_to_pdf | Imprimir, o escribir un PDF | 6.9 Imprimir |
of_set_property · of_get_property · of_component_name | Controlar una propiedad por su nombre | 3.1 El motor de propiedades |
is_accessible_name · is_accessible_description | El nombre y la descripción que dice un lector de pantalla | 3.4 Propiedades y eventos opcionales |