toolbar — `u_pbt_toolbar` #

← Referencia de componentes · Índice de la guía

Barra de herramientas plana: varias barras repartidas en bandas, botones, conmutadores, menús desplegables, campos de entrada, desbordamiento automático y desplazamiento mediante el asa.

▶ Verlo en vivo — Aplicación de demostración, mosaico Toolbar: la vista previa, el código que lo genera y esta página, uno al lado del otro.

De un vistazo #

Userobject	`u_pbt_toolbar`
Clases de items	`n_pbt_toolbar_bar` (barra) → `n_pbt_toolbar_item` (herramienta) → `n_pbt_toolbar_menu_item` (entrada de menú)
Sirve para	Sustituir una barra de herramientas clásica por una barra moderna, con tema, repartida en varias filas reorganizables
Altura	Intrínseca: la barra se ajusta siempre a sus filas, no hay nada que activar — véase Altura automática

Inicio rápido #

// event open de la ventana

// MAIN_BAR es la barra predeterminada, siempre presente : la direccion parte de ella
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*/ "Buscar")
uo_toolbar.of_add_separator(/*keys*/ uo_toolbar.MAIN_BAR)
uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/help", /*text*/ "Ayuda",  /*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

El modelo: barras, bandas, herramientas #

Una barra de herramientas contiene una o varias barras. Cada barra se coloca sobre una banda (una fila) y ocupa una posición dentro de esa fila: dos barras en la misma banda se reparten la fila, dos barras en bandas distintas se apilan — exactamente como las barras de herramientas clásicas de Office.

Las herramientas (botones, conmutadores, menús, campos) pertenecen a una barra. Su identificador solo es único dentro de su propia barra: por lo tanto, el acceso pasa siempre por la ruta completa.

// 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

Todo se hace desde el componente, por direcciones: una herramienta se añade en la suya (of_add_button("main/save", …)), una entrada de menú en la suya ("main/export/pdf", un nivel más por cascada), y cada nivel tiene su getter — of_bar, of_item, of_menu_item. Consulte Base común · Los items para el principio general.

Listas desplegables #

Una lista desplegable (of_add_combo) es un campo y su flecha, como el combo de la cinta. No editable, el usuario elige en la lista (un clic en el campo, Intro, F4 o Alt+Abajo la abren); editable, también puede escribir un valor propio. Cada elección vuelve en ue_combo_changed; plegada en el chevron de una barra demasiado estrecha, la lista sigue funcionando.

// 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

Propiedades #

Propiedad	Tipo	Predeterminado	Función
`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
`ib_reorderable`	boolean	`false`	Permite al usuario reorganizar las barras con el ratón: los tiradores de desplazamiento aparecen y una barra puede arrastrarse a otra banda. Desactivado de forma predeterminada — una barra de herramientas desmontada por accidente es una llamada al soporte. Su código las reorganiza en cualquier caso (`of_set_layout`, `of_add_bar`): la autorización afecta al usuario, nunca a la aplicación

Constante #

Constante	Valor	Función
`MAIN_BAR`	`"main"`	Identificador de la barra predeterminada, que se direcciona sin haberla creado: nace con su primera herramienta. Para colocarla, añádala primero — `of_add_bar(MAIN_BAR, 1, 1)`

Métodos #

Método	Función
`of_bar (string as_key)` → `n_pbt_toolbar_bar`	Devuelve el handle de una barra (creada en el primer acceso): `ii_band`, `ii_index`, `ib_visible`
`of_add_button (string as_keys, string as_text, string as_image, string as_tooltip)` → `long`	Botón de acción en su dirección, `"main/save"`: la barra y luego su propio identificador. El clic dispara `ue_clicked`. Devuelve `0` una vez añadido, `-5` si la dirección se rechaza (no es `barra/herramienta`, una barra nunca añadida — salvo `main` —, una dirección ya ocupada), `-2` si el componente no está creado
`of_item (string as_keys)` → `n_pbt_toolbar_item`	Devuelve el handle de una herramienta, por su dirección `barra/herramienta`. Una dirección de otra profundidad no designa ninguna herramienta: una barra es `of_bar`, una entrada de menú `of_menu_item`
`of_menu_item (string as_keys)` → `n_pbt_toolbar_menu_item`	Devuelve el handle de una entrada de un menú desplegable, por su dirección `barra/desplegable/entrada` — un nivel más por cascada. Dos cascadas pueden tener cada una su propio `pdf`: la dirección designa uno de ellos, nunca los dos
`of_add_bar (string as_key)` → `long`	Añade una barra, en una banda propia tras las demás. Devuelve `0` una vez añadida, `-5` si la clave se rechaza (vacía, con `/` o `	`, que empieza por` __ `o ya ocupada),` -2 `si el componente no está creado. La barra predeterminada` main `nace con su primera herramienta: para colocarla, añádala antes de cualquier herramienta (`of_add_bar(MAIN_BAR, 1, 1)`); después está ocupada (`-5`) y se mueve con` of_bar(MAIN_BAR)`
`of_add_bar (string as_key, integer ai_band, integer ai_index)` → `long`	Añade una barra en una banda y una posición precisas (ambas contadas desde 1); la barra que ocupaba ese rango pasa un puesto a la derecha. Mismos códigos que arriba
`of_remove_bar (string as_key)` → `long`	Retira una barra y sus herramientas, con sus handles y sus atajos. Las demás conservan su estado vivo, y las bandas se reagrupan tras la que se va. No es ocultarla (`ib_visible` en su handle): ocultarla la mantiene en el modelo, lista para volver exactamente donde estaba; retirarla la olvida. Devuelve `0` una vez retirada, `-5` para una barra que no existe, `-2` si el componente no está creado
`of_get_layout ()` → `string`	Relee la disposición actual en JSON: qué barra en qué banda, en qué rango, y visible o no. Bandas y rangos contados desde 1, como `ii_band` / `ii_index`: guárdela tal cual y devuélvala a `of_set_layout` — una ida y vuelta devuelve la misma cadena
`of_set_layout (string as_layout_json)` → `long`	Restaura una disposición leída con `of_get_layout` o recibida por `ue_layout_changed`, devuelta tal cual. Una barra que no nombra se queda donde está. Se lanza `ue_layout_changed`, como en todo cambio de la disposición. Devuelve `0` una vez aplicado, `-5` con una cadena vacía, `-2` si el componente no está creado. Un texto que no es JSON también devuelve `-5`
`of_clear ( )` → `long`	Elimina todas las barras, herramientas y menús, con los handles entregados y los atajos de las herramientas y entradas; cada dirección puede añadirse de nuevo. Devuelve `0` una vez aplicado, `-2` si el componente no está creado
`of_reset ( )`	Vacía el contenido y restablece las propiedades a sus valores predeterminados. Devuelve `0` una vez aplicado, `-2` si el componente no está creado
`of_add_toggle (string as_keys, string as_text, string as_image, string as_tooltip)` → `long`	Conmutador de dos estados; el clic dispara `ue_toggled`. Devuelve `0` una vez añadido, `-5` si la dirección se rechaza (no es `barra/herramienta`, una barra nunca añadida — salvo `main` —, una dirección ya ocupada), `-2` si el componente no está creado
`of_add_dropdown (string as_keys, string as_text, string as_image, string as_tooltip)` → `long`	Botón con menú desplegable, rellenado con `of_add_menu_item`; una elección dispara `ue_menu_selected`. Devuelve `0` una vez añadido, `-5` si la dirección se rechaza (no es `barra/herramienta`, una barra nunca añadida — salvo `main` —, una dirección ya ocupada), `-2` si el componente no está creado. Un desplegable sin ninguna entrada visible se dibuja atenuado
`of_add_split_button (string as_keys, string as_text, string as_image, string as_tooltip)` → `long`	Botón dividido: su parte principal es un botón (`ue_clicked`), su flecha abre un menú rellenado con `of_add_menu_item` como el de un desplegable (`ue_menu_selected`). Su atajo dispara la parte principal; plegado en el chevron, abre una lista cuya primera línea es su propia acción. Devuelve `0` una vez añadido, `-5` si la dirección se rechaza (no es `barra/herramienta`, una barra nunca añadida — salvo `main` —, una dirección ya ocupada), `-2` si el componente no está creado
`of_add_label (string as_keys, string as_text)` → `long`	Etiqueta informativa, no clicable. Devuelve `0` una vez añadido, `-5` si la dirección se rechaza (no es `barra/herramienta`, una barra nunca añadida — salvo `main` —, una dirección ya ocupada), `-2` si el componente no está creado
`of_add_textbox (string as_keys, string as_text, integer ai_width, string as_tooltip)` → `long`	Campo de entrada; Intro o la pérdida del foco dispara `ue_text_changed`, Escape devuelve el texto validado. `ai_width` en píxeles. Devuelve `0` una vez añadido, `-5` si la dirección se rechaza (no es `barra/herramienta`, una barra nunca añadida — salvo `main` —, una dirección ya ocupada), `-2` si el componente no está creado
`of_add_combo (string as_keys, integer ai_width, boolean ab_editable, string as_tooltip)` → `long`	Lista desplegable (combo): un campo y su flecha, el combo de la cinta. `ab_editable = false`, el usuario solo elige en la lista; `true`, también puede escribir un valor propio, validado con Intro o al salir del campo. La lista se rellena con `of_add_combo_item`, una elección dispara `ue_combo_changed`, `is_text` fija y relee el valor. `ai_width` en píxeles (0 = ancho predeterminado). Plegada en el chevron, sigue siendo una lista operativa. Devuelve `0` una vez añadida, `-5` si la dirección se rechaza (no es `barra/herramienta`, una barra nunca añadida — salvo `main` —, una dirección ya ocupada), `-2` si el componente no está creado
`of_add_combo_item (string as_keys, string as_label)` → `long`	Añade una opción a la lista de una lista desplegable: `as_keys` nombra la lista (`"main/zoom"`). Una opción tiene como clave su etiqueta, así que su dirección es `"main/zoom/150%"` (`of_remove_combo_item`, `of_has`); `of_count` y `of_keys_at` sobre la lista recorren sus opciones. En modo demo la lista muestra 6 opciones. Devuelve `0` una vez añadida, `-5` si `as_keys` no es una lista desplegable, o si la etiqueta está vacía, contiene `/` o `	`, o ya está en la lista,` -2` si el componente no está creado
`of_add_datepicker (string as_keys, string as_date, string as_tooltip)` → `long`	Selector de fecha; una elección dispara `ue_date_changed`, `is_date` lee y fija la fecha. Fechas con el formato `"aaaa-mm-dd"`. Devuelve `0` una vez añadido, `-5` si la dirección se rechaza (no es `barra/herramienta`, una barra nunca añadida — salvo `main` —, una dirección ya ocupada), `-2` si el componente no está creado
`of_add_separator (string as_keys)` → `long`	Línea vertical de separación en una barra (`as_keys` la nombra). Un separador no tiene ni clave ni rango. Devuelve `0` una vez añadido, `-5` para una barra nunca añadida (salvo `main`), `-2` si el componente no está creado. Un separador que las herramientas ocultas dejarían al principio, al final o duplicado no se dibuja
`of_insert_button (string as_keys, string as_text, string as_image, string as_tooltip, integer ai_index)` → `long`	Botón añadido en la posición elegida (primero = 1) en lugar de al final. Devuelve `0` una vez añadido, `-5` si la dirección se rechaza (no es `barra/herramienta`, una barra nunca añadida — salvo `main` —, una dirección ya ocupada), `-2` si el componente no está creado
`of_move_item (string as_keys, integer ai_index)` → `long`	Mueve una herramienta a otra posición en su barra (primero = 1; el rango cuenta las herramientas, un separador no ocupa ninguno). Conserva su tipo, su menú y su estado vivo: la herramienta cambia de lugar, no se reconstruye. Devuelve `0` una vez aplicado, `-5` si ninguna herramienta vive en esa dirección, `-2` si el componente no está creado
`of_remove_item (string as_keys)` → `long`	Retira una herramienta (`"main/save"`) o una entrada de menú (`"main/export/pdf"`, con su cascada), con sus handles y su atajo. Todo lo demás permanece, estado vivo incluido. Para que una herramienta vaya y venga, `ib_visible` en su handle la mantiene en el modelo. Devuelve `0` una vez retirada, `-5` si nada vive en esa dirección, `-2` si el componente no está creado
`of_remove_combo_item (string as_keys)` → `long`	Retira una opción de una lista desplegable, nombrada por su dirección `"main/zoom/150%"`; el valor mostrado se mantiene. `of_remove_item` hace lo mismo. Devuelve `0` una vez retirada, `-5` si esa lista no tiene tal opción, `-2` si el componente no está creado
`of_add_menu_item (string as_keys, string as_label, string as_image)` → `long`	Entrada del menú de un botón desplegable, en su dirección `barra/desplegable/entrada`; cada nivel más la coloca en cascada bajo la entrada anterior, a cualquier profundidad. Una etiqueta vacía muestra la clave. Devuelve `0` una vez añadida, `-5` si la dirección se rechaza (nivel vacío o con `	`, desplegable o entrada padre nunca añadidos, dirección ya ocupada),` -2 `si el componente no está creado. Vale también para el menú de un botón dividido (`of_add_split_button`)
`of_add_menu_separator (string as_keys)` → `long`	Línea de separación al final del menú de un desplegable (`"main/export"`), o de la cascada de una entrada (`"main/export/img"`). Devuelve `0` una vez añadida, `-5` si la dirección no nombra ninguno de los dos, `-2` si el componente no está creado. Vale también para el menú de un botón dividido (`of_add_split_button`)
`of_clear_menu (string as_keys)` → `long`	Vacía el menú de un desplegable (`"main/recent"`) y conserva el botón: la manera de reconstruir una lista de archivos recientes. Los handles y atajos de sus entradas se van con ellas. Devuelve `0` una vez aplicado, `-5` si la dirección no nombra ningún desplegable, `-2` si el componente no está creado. Vale también para el menú de un botón dividido (`of_add_split_button`)
`of_clear_combo (string as_keys)` → `long`	Vacía la lista de una lista desplegable (`"main/zoom"`); el valor mostrado se mantiene. La forma de reconstruir una lista que sigue al documento. Devuelve `0` una vez aplicado, `-5` si `as_keys` no es una lista desplegable, `-2` si el componente no está creado
`of_register_shortcut (string as_chord, string as_keys)` → `long`	En una toolbar el atajo toma la dirección de lo que dispara: una herramienta (`barra/herramienta` — como `is_shortcut` en su handle) o una entrada de menú (`barra/desplegable/entrada`). Responde dondequiera que esté el foco en la ventana y se muestra en el tooltip o a la derecha de la entrada; `""` lo retira. Una barra de herramientas no tiene nada que disparar para sí misma: la forma de un argumento devuelve `-5`. Devuelve `0` una vez aplicado, `-5` si la dirección no nombra ninguna herramienta ni entrada, o nombra una etiqueta, `-2` si el componente no está creado
`of_clear_shortcuts ( )` → `long`	Retira todos los atajos de la barra de herramientas — los de sus herramientas y de sus entradas de menú: ya no responden, ya no se muestran, y `is_shortcut` relee `""`. Devuelve `0` una vez aplicado, `-2` si el componente no está creado

En una barra — `n_pbt_toolbar_bar` #

Miembro	Tipo	Predeterminado	Función
`ii_band`	integer	`1`	Banda (fila) que aloja la barra; `1` = primera fila
`ii_index`	integer	`1`	Posición de la barra dentro de su banda; `1` = la primera
`ib_visible`	boolean	`true`	Muestra u oculta una barra. Una barra oculta conserva su banda, su rango y sus elementos: volver a mostrarla la devuelve exactamente a donde estaba, sin reconstruir nada — esa es la diferencia con `of_clear`, que los perdería

En una herramienta — `n_pbt_toolbar_item` #

Miembro	Tipo	Predeterminado	Función
`ib_visible`	boolean	`true`	Muestra u oculta un elemento. Conserva su rango en la barra: volver a mostrarlo lo devuelve exactamente a donde estaba, no al final. No confundir con `ib_enabled`, que lo deja en su sitio, atenuado — oculte lo que no se aplica, atenúe lo que está momentáneamente no disponible
`ib_enabled`	boolean	`true`	Herramienta activa o atenuada
`ib_checked`	boolean	`false`	Estado de un conmutador (sin efecto en los demás tipos)
`is_text`	string	`""`	Etiqueta, se admite texto enriquecido con etiquetas
`is_shortcut`	string	`""`	Atajo de teclado (`"Ctrl+S"`), mostrado en el tooltip y activo; se relee tal como se escribió. Una herramienta oculta, desactivada o más allá del límite de la demo no responde. Necesita Ctrl o Alt (Mayús se añade), o es de F1 a F24: una tecla sola — una letra, Supr, Intro — es escritura, nunca un atajo. Un botón o un conmutador se dispara; un campo de entrada recibe el cursor, con su texto seleccionado; un selector de fecha abre su calendario; una etiqueta no admite ninguno
`is_date`	string	`""`	Fecha de un selector de fecha, `"aaaa-mm-dd"` (`""` vacía el campo). Relee la fecha mostrada — la que eligió el usuario igual que la fijada aquí. Una fecha mal formada se ignora; los demás tipos de herramienta no tienen fecha y releen `""`
`is_image`	string	`""`	Icono de la herramienta (mismas formas que al añadirla: ruta, `mono:`, `tint:`…); `""` lo retira. Un conmutador Reproducir que pasa a Pausa, un botón que pasa a un icono de error — sin quitar ni volver a añadir la herramienta
`is_group`	string	`""`	Grupo de un conmutador: los conmutadores de una misma barra que comparten un grupo son exclusivos, como los botones de alineación de un editor — pulsar uno libera los demás, pulsar el que ya está pulsado lo deja pulsado. Solo el conmutador pulsado dispara `ue_toggled`. `ib_checked = true` puesto por su código también libera los demás, sin evento. `""` (predeterminado): sin grupo
`ib_editable`	boolean	`false`	Una lista desplegable (`of_add_combo`): `true`, el usuario puede escribir un valor propio además de las opciones de la lista; `false`, solo elige. Cualquier otra herramienta lee `false` y lo ignora

En una entrada de menú — `n_pbt_toolbar_menu_item` #

Miembro	Tipo	Predeterminado	Función
`ib_enabled`	boolean	`true`	Desactivada, la entrada permanece en el menú y ya no puede elegirse — ni con el ratón, ni con el teclado, ni con su atajo
`ib_visible`	boolean	`true`	Oculta, la entrada sale del menú (con su cascada); conserva su lugar y su estado, y vuelve donde estaba
`ib_checked`	boolean	`false`	Una marca delante de la entrada. La decide la aplicación: elegir la entrada no la invierte
`is_text`	string	`""`	Etiqueta de la entrada, se admite texto enriquecido con etiquetas; relee la clave si la entrada se añadió sin etiqueta
`is_shortcut`	string	`""`	Atajo mostrado a la derecha de la entrada y activo: la elige esté donde esté el foco y lanza `ue_menu_selected` como un clic — no si la entrada, un nivel superior o su desplegable está desactivado u oculto. Se relee tal como se escribió; `""` lo retira. Misma regla que para una herramienta: Ctrl o Alt, o de F1 a F24
`is_image`	string	`""`	Icono de la entrada, mostrado en la próxima apertura del menú; `""` lo retira

Las imágenes admiten todas las formas reconocidas por la biblioteca: ruta, mono:, tint:, recurso de una DLL. Una entrada de menú admite los cinco colores de elemento (il_back_color, il_text_color, sus variantes al pasar el ratón, il_accent), dibujados en el menú; no muestra tooltip — un menú nativo no lo tiene.

Eventos #

Evento	Se activa cuando
`ue_clicked (string as_keys)`	Un botón — o la parte principal de un botón dividido — se dispara: con un clic, con su atajo, o desde el panel del chevron cuando está plegado. `as_keys` es su dirección, `"main/save"`
`ue_toggled (string as_keys, boolean ab_checked)`	Un conmutador cambia de estado; `ab_checked` contiene el nuevo estado. Lo dispara solo un gesto del usuario: poner `ib_checked` no lo dispara. En un grupo (`is_group`), solo el conmutador pulsado lo dispara
`ue_menu_selected (string as_keys)`	Se elige una entrada de menú desplegable — con el ratón, el teclado o su atajo, en la barra como en el panel del chevrón. `as_keys` es su dirección completa, `"main/export/img/png"`. Vale para el menú de un botón dividido como para el de un desplegable; la entrada misma es el último nivel de la dirección
`ue_text_changed (string as_keys, string as_text)`	Se valida un campo de entrada (Intro o pérdida del foco); Intro se detiene en el campo y no pulsa el botón predeterminado de la ventana. Esc devuelve al campo su texto sin dispararlo, y poner `is_text` no lo dispara
`ue_date_changed (string as_keys, string as_date)`	Se elige una fecha (`"aaaa-mm-dd"`). Lo dispara solo una elección del usuario en el calendario; poner `is_date` no lo dispara
`ue_combo_changed (string as_keys, string as_text)`	El usuario eligió un valor en la lista de una lista desplegable, o escribió uno en una lista editable y lo validó (Intro, o al salir del campo) — en la barra o en el panel del chevron. `as_text` es el valor, `as_keys` = `barra/herramienta`. Un valor escrito solo lo dispara si ha cambiado; Escape devuelve el valor sin dispararlo; `is_text` puesto por su código no dispara nada. El evento de la cinta: mismo nombre, mismo sentido
`ue_bar_reordered (string as_key, integer ai_band, integer ai_index)`	El usuario ha arrastrado una barra por su tirador a otra banda u otro rango (requiere `ib_reorderable`). Indica qué barra se ha movido y dónde ha aterrizado, mientras que `ue_layout_changed` lleva toda la disposición. Banda y rango empiezan en 1, como `ii_band` e `ii_index`
`ue_layout_changed (string as_layout_json)`	La disposición ha cambiado — el usuario ha arrastrado una barra por su asa, o su propio código ha movido u ocultado una, o ha restaurado una disposición con `of_set_layout`. Lleva la disposición entera, no solo lo que se movió, bandas y rangos contados desde 1: se guarda tal cual y se devuelve a `of_set_layout`. Añadir una barra que desplaza a otra también lo dispara; no se dispara nada cuando nada se ha movido (volver a mostrar una barra ya visible)
`ue_item_rclicked (string as_keys)`	Clic derecho sobre una herramienta (una atenuada no dice nada); `as_keys` es su dirección. Abra aquí su propio menú contextual. Un clic derecho fuera de toda herramienta dispara `ue_rclicked` en su lugar — nunca ambos
`ue_rclicked ( )`	Clic derecho en la barra fuera de toda herramienta (un clic derecho en una herramienta lanza solo `ue_item_rclicked`)
`ue_mouse_enter ( )`	El ratón entra en la barra
`ue_mouse_leave ( )`	El ratón sale de la barra
`ue_auto_height (long al_height)`	La altura ideal ha cambiado y la barra se ha ajustado a ella — siempre activo: el número de filas dicta la altura
`ue_ready ( )`	El componente ha terminado de cargarse; todo lo enviado antes se ha reproducido
`ue_runtime_missing ( )`	El runtime WebView2 está ausente: el componente permanece vacío
`ue_bg_color (long al_color)`	El componente ha calculado el color de fondo de su tema; el userobject ya lo ha adoptado (`backcolor`)

Ejemplos #

Conmutadores ya marcados y herramienta atenuada #

// Dos conmutadores, un separador y un boton
uo_toolbar.of_add_toggle(/*keys*/ uo_toolbar.MAIN_BAR + "/bold",   /*text*/ "", /*image*/ "mono:img\bold.svg",   /*tooltip*/ "Negrita")
uo_toolbar.of_add_toggle(/*keys*/ uo_toolbar.MAIN_BAR + "/italic", /*text*/ "", /*image*/ "mono:img\italic.svg", /*tooltip*/ "Cursiva")
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*/ "Deshacer")

// Cada herramienta se controla por su handle, obtenido desde SU barra
uo_toolbar.of_item(/*keys*/ uo_toolbar.MAIN_BAR + "/bold").ib_checked = true    // conmutador ya marcado
uo_toolbar.of_item(/*keys*/ uo_toolbar.MAIN_BAR + "/undo").ib_enabled = false   // por ahora no hay nada que deshacer

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

Menú desplegable en cascada #

// El menu se rellena desde el componente : tres niveles, barra/desplegable/entrada
uo_toolbar.of_add_dropdown(/*keys*/ uo_toolbar.MAIN_BAR + "/export", /*text*/ "Exportar", &
                                   /*image*/ "mono:img\save.svg", /*tooltip*/ "Exportar el expediente")
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 : un CUARTO nivel, la entrada bajo la que se aloja
uo_toolbar.of_add_menu_item(/*keys*/ uo_toolbar.MAIN_BAR + "/export/exp_img", /*label*/ "Imagen...", /*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*/ "")

// Una entrada se controla con SU handle, en su direccion
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 que crear, nada que destruir
string ls_ids[]

// Una entrada del menu Export : su hoja indica el 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 búsqueda y selector de fecha #

// Un boton con su atajo y luego un 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"    // atajo activo y mostrado
uo_toolbar.of_add_separator(/*keys*/ uo_toolbar.MAIN_BAR)

// 160 px de ancho ; la entrada se notifica al confirmar
uo_toolbar.of_add_textbox(/*keys*/ uo_toolbar.MAIN_BAR + "/search", /*text*/ "", /*width*/ 160, /*tooltip*/ "Buscar (Intro para confirmar)")

// Una etiqueta delante de un selector de fecha
uo_toolbar.of_add_label(/*keys*/ uo_toolbar.MAIN_BAR + "/lbl_due", /*text*/ "Vencimiento:")
uo_toolbar.of_add_datepicker(/*keys*/ uo_toolbar.MAIN_BAR + "/due", /*date*/ "2026-07-11", /*tooltip*/ "Fecha de vencimiento")

// 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 con el formato "aaaa-mm-dd"
if as_keys = "main/due" then id_due_date = Date(as_date)

Dos barras y disposición memorizada #

Con ib_reorderable = true, el usuario puede agarrar una barra por su asa (a la izquierda de la barra) y desplazarla a otra banda o a otra posición. Conserve la disposición al cerrar y restitúyala al abrir.

// Sin esta linea no hay asa : el usuario no puede mover nada
uo_toolbar.ib_reorderable = true

// La barra principal y sus dos botones
uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/new",  /*text*/ "Nuevo", /*image*/ "", /*tooltip*/ "")
uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/open", /*text*/ "Abrir",  /*image*/ "", /*tooltip*/ "")

// Segunda barra, colocada en la banda 2 (segunda fila), en primera posicion
uo_toolbar.of_add_bar(/*key*/ "format", /*band*/ 2, /*index*/ 1)
uo_toolbar.of_add_toggle(/*keys*/ "format/bold", /*text*/ "N", /*image*/ "", /*tooltip*/ "Negrita")

// Tambien se puede recolocar una barra en cualquier momento mediante sus propiedades
uo_toolbar.of_bar(/*key*/ "format").ii_band  = 1
uo_toolbar.of_bar(/*key*/ "format").ii_index = 2    // segunda barra de la primera fila

// event ue_layout_changed de uo_toolbar : conservar la disposicion elegida
is_layout = as_layout_json

// En la siguiente apertura : restituir lo que el usuario habia organizado
if is_layout <> "" then uo_toolbar.of_set_layout(/*layout_json*/ is_layout)

Botón dividido y conmutadores exclusivos #

// Pegar : la parte principal pega enseguida, la flecha propone las otras maneras
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*/ "")

// Los conmutadores de alineacion comparten un grupo : uno solo pulsado a la 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 : la parte principal del boton dividido
if as_keys = "edit/paste" then of_paste()

// event ue_toggled de uo_toolbar : solo el conmutador pulsado lo dispara
if ab_checked and Left(as_keys, 5) = "edit/" then of_align(Mid(as_keys, 6))

Desbordamiento: «Más herramientas» #

Cuando el ancho ya no es suficiente, las herramientas que no caben se recogen en un menú Más herramientas señalado por un galón al final de la barra. Es automático, no hay nada que programar: las herramientas recogidas se pueden seguir pulsando y activan los mismos eventos. Un campo recogido —cuadro de texto o selector de fecha— sigue siendo un campo real: se escribe en él, se elige una fecha en él, y el evento se activa igual que si la herramienta se hubiera quedado en la barra.

Altura automática #

No hay nada que activar: el número de filas (of_set_layout) dicta la altura, la barra se ajusta sola y le avisa.

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

Consulte Base común.

Buenas prácticas #

Use MAIN_BAR mientras baste una sola barra: nace con su primera herramienta, no hace falta añadirla. Para colocarla en otro lugar que detrás de las demás barras, añádala antes de cualquier herramienta — of_add_bar(MAIN_BAR, 1, 1); una vez nacida, of_add_bar(MAIN_BAR) devuelve -5 y se mueve con of_bar(MAIN_BAR).ii_band.
En una toolbar, of_register_shortcut toma la dirección de la herramienta o de la entrada que dispara. Un atajo necesita Ctrl o Alt, o una tecla de F1 a F24: una tecla sola queda para la escritura.
Acceda siempre a una herramienta por su ruta — of_item("main/save") — y nunca solo por su identificador: es lo que hace que los identificadores sean reutilizables de una barra a otra.
Agrupe las herramientas afines con of_add_separator("main") en lugar de con barras adicionales.
En los botones con solo icono, rellene siempre el tooltip: es la única etiqueta de la que dispone el usuario.
Si deja que el usuario reorganice las barras, memorice ue_layout_changed y reproduzca of_set_layout al abrir; de lo contrario, el esfuerzo se pierde en cada arranque.
Llame a of_reset() antes de reconstruir por completo la barra de herramientas para otro contexto.
Cuando los comandos son demasiado numerosos para una barra, pase a la cinta de opciones, organizada por pestañas y grupos.

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

Dos ayudas no se heredan: of_icon y of_escape_markup viven en n_pbt_utils. Declare uno — n_pbt_utils lnv_utils, nada que crear — y llámelas sobre él.