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)
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_enregistrer()
    case "main/find" ; of_rechercher()
    case "main/help" ; of_aide()
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.

uo_toolbar.of_bar("main").of_item("save").ib_enabled = false

Las adiciones también se hacen sobre el handle del elemento padre: se añade una herramienta a una barra, no a la barra de herramientas. Consulte Base común · Los items para el principio general.

Propiedades #

Propiedad	Tipo	Predeterminado	Función
`is_theme_style`	string	`fluent`	Estilo visual del componente (constantes `THEME_STYLE_*`)
`is_theme_mode`	string	`light`	Variante clara u oscura (constantes `THEME_MODE_*`)
`il_theme_accent`	long	`-1`	Color de acento de este componente (`-1` = acento 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, siempre disponible sin necesidad de crearla

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)
`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 lanza `ue_clicked`. Devuelve `0` una vez aplicado, `-5` ante un argumento no válido (clave vacía, dirección errónea), `-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
`of_add_bar (string as_key)` → `long`	Añade una barra y devuelve `0` (`-5` ante un argumento no válido, `-2` si el componente no está creado)
`of_add_bar (string as_key, integer ai_band, integer ai_index)` → `long`	Añade una barra en una banda y una posición determinadas (ambas contadas a partir de 1). Devuelve `0` una vez aplicado, `-2` si el componente no está creado
`of_remove_bar (string as_key)`	Elimina una barra y sus herramientas. Las demás conservan su estado activo, y las bandas se juntan detrás de la que se va. No es lo mismo que ocultarla (`ib_visible` en su handle): ocultar la mantiene en el modelo, lista para volver exactamente donde estaba; eliminar la olvida. Devuelve `0` una vez aplicado, `-5` ante un argumento no válido (clave vacía, dirección errónea), `-2` si el componente no está creado
`of_get_layout ()`	Vuelve a leer la disposición actual en JSON: qué barra en qué banda, en qué rango y visible o no. Guárdela y devuélvala con `of_set_layout`
`of_set_layout (string as_layout_json)`	Restaura una disposición de barras recibida anteriormente mediante `ue_layout_changed`. Devuelve `0` una vez aplicado, `-5` ante un argumento no válido (clave vacía, dirección errónea), `-2` si el componente no está creado
`of_clear ( )`	Elimina todas las barras y todas las herramientas. 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 activa `ue_toggled`. Devuelve `0` una vez aplicado, `-5` ante un argumento no válido (clave vacía, dirección errónea), `-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; una elección activa `ue_menu_selected`. Devuelve `0` una vez aplicado, `-5` ante un argumento no válido (clave vacía, dirección errónea), `-2` si el componente no está creado
`of_add_label (string as_keys, string as_text)` → `long`	Etiqueta informativa, no se puede pulsar. Devuelve `0` una vez aplicado, `-5` ante un argumento no válido (clave vacía, dirección errónea), `-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 pérdida del foco activa `ue_text_changed`. `ai_width` en píxeles. Devuelve `0` una vez aplicado, `-5` ante un argumento no válido (clave vacía, dirección errónea), `-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 activa `ue_date_changed`. Fechas con el formato `"aaaa-mm-dd"`. Devuelve `0` una vez aplicado, `-5` ante un argumento no válido (clave vacía, dirección errónea), `-2` si el componente no está creado
`of_add_separator (string as_keys)`	Trazo vertical de separación. Devuelve `0` una vez aplicado, `-5` ante un argumento no válido (clave vacía, dirección errónea), `-2` si el componente no está creado
`of_insert_button (string as_keys, string as_text, string as_image, string as_tooltip, integer ai_index)` → `long`	Boton anadido en la posicion elegida (primero = 1) en lugar de al final. Devuelve `0` una vez aplicado, `-5` ante un argumento no válido (clave vacía, dirección errónea), `-2` si el componente no está creado
`of_move_item (string as_keys, integer ai_index)`	Mueve una herramienta a otra posicion en esta barra (primero = 1). Conserva su tipo, su menu y su estado vivo: la herramienta cambia de sitio, no se reconstruye. Vale para todos los tipos, asi que los `of_add_` sin `of_insert_` insertan anadiendo y luego moviendo. Devuelve `0` una vez aplicado, `-5` ante un argumento no válido (clave vacía, dirección errónea), `-2` si el componente no está creado
`of_remove_item (string as_keys)`	Elimina una herramienta de esta barra. La barra permanece, y todo lo demás con ella, incluido el estado activo — solo se va la herramienta indicada. Para hacerla ir y venir, `ib_visible` en su handle la mantiene en el modelo. Devuelve `0` una vez aplicado, `-5` ante un argumento no válido (clave vacía, dirección errónea), `-2` si el componente no está creado
`of_add_menu_item (string as_keys, string as_label, string as_image)`	Entrada del menú de un botón desplegable ; entrada en cascada, colocada bajo una entrada existente. Devuelve `0` una vez aplicado, `-5` ante un argumento no válido (clave vacía, dirección errónea), `-2` si el componente no está creado
`of_add_menu_separator (string as_keys)`	Trazo de separación en el menú. Devuelve `0` una vez aplicado, `-5` ante un argumento no válido (clave vacía, dirección errónea), `-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

Las imágenes admiten todas las formas reconocidas por la biblioteca: ruta, mono:, tint:, recurso de una DLL.

Eventos #

Evento	Se activa cuando
`ue_clicked (string as_keys)`	Se pulsa un botón (o se activa mediante su atajo)
`ue_toggled (string as_keys, boolean ab_checked)`	Un conmutador cambia de estado; `ab_checked` contiene el nuevo estado
`ue_menu_selected (string as_keys)`	Se elige una entrada de un menú desplegable
`ue_text_changed (string as_keys, string as_text)`	Se confirma un campo de entrada (Intro o pérdida del foco)
`ue_date_changed (string as_keys, string as_date)`	Se elige una fecha (`"aaaa-mm-dd"`)
`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. Lleva la disposición entera, no solo lo que se movió
`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 #



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_key = "bold" then of_appliquer_gras(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*/ "")

// event ue_menu_selected de uo_toolbar : (as_keys)
n_pbt_utils lnv_utils   // autoinstantiate : nada que crear, nada que destruir
string ls_ids[]

if lnv_utils.of_split_path(as_keys, ls_ids) = 3 then
	if ls_ids[2] = "export" then of_exporter(ls_ids[3])
end if

Campo de búsqueda y selector de fecha #



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)")

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_key = "search" then of_filtrer(as_text)

// event ue_date_changed de uo_toolbar : as_date con el formato "aaaa-mm-dd"
if as_key = "due" then id_echeance = Date(as_date)

Dos barras y disposición memorizada #

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.



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_disposition = as_layout_json

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

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_contenu.y      = uo_toolbar.y + al_height
uo_contenu.height = parent.workspaceheight() - uo_contenu.y

Consulte Base común.

Buenas prácticas #

Utilice MAIN_BAR mientras una sola barra sea suficiente: ya existe, no hace falta añadirla.
Acceda siempre a una herramienta por su ruta — of_bar(...).of_item(...) — 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() 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.