menubar — `u_pbt_menubar` #

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

Barra de menús de la aplicación: menús, submenús, entradas marcables, separadores, iconos y atajos — todo dibujado por la biblioteca, sin ningún menú de Windows.

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

De un vistazo #

Userobject	`u_pbt_menubar`
Clase de ítems	`n_pbt_menubar_item` (una entrada)
Sirve para	Dar a su ventana la barra de menús de la aplicación, con el mismo tema que todo lo demás
Principio	Usted declara los menús y luego sus entradas; cada entrada se recupera por su dirección `menu/id`

Inicio rápido #

// evento open de la ventana
uo_menus.of_add_menu(/*key*/ "file", /*text*/ "Archivo")
uo_menus.of_add_item(/*keys*/ "file/open", /*text*/ "Abrir")
uo_menus.of_add_item(/*keys*/ "file/save", /*text*/ "Guardar")

// event ue_item_selected : (string as_keys)
choose case as_keys
	case "open"; of_ouvrir()
	case "save"; of_enregistrer()
end choose

El modelo: tres niveles, una clave por nivel #

Una barra de menús tiene tres niveles, y cada uno se indica con su clave:

Nivel	Añadido por	Clave
El menú de la barra	`of_add_menu`	su `id`
La entrada de un menú	`of_add_item`	la dirección `menu/id`
La subentrada de una entrada	`of_add_item`	la dirección `menu/entrada/subentrada` — tres niveles

Un id de entrada solo es único dentro de su menú: por eso of_item pide dos. Dos menús pueden así tener cada uno su entrada "open" sin estorbarse.

Un separador no tiene clave: of_add_separator traza una línea donde usted lo llama, y después no hay nada que releer.

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	`""`	Información sobre herramientas sencilla al pasar por el componente
`is_super_tooltip_title`	string	`""`	Título de la información enriquecida (prevalece sobre `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Texto de la información enriquecida (se acepta marcado enriquecido)
`is_super_tooltip_image`	string	`""`	Imagen de la información enriquecida

Propiedades de una entrada — `n_pbt_menubar_item` #

Obtenidas mediante of_item(menu/id):

Propiedad	Tipo	Predeterminado	Función
`is_text`	string	—	Cambia la etiqueta de la entrada, en caliente
`ib_enabled`	boolean	`true`	Entrada activa; una entrada atenuada ya no responde al clic
`ib_visible`	boolean	`true`	Entrada retirada de la lista sin ser eliminada — submenú y atajo dormidos con ella; conserva su clave y vuelve tal cual
`is_shortcut`	string	`""`	El acelerador mostrado a la derecha de la entrada (`Ctrl+S`) — y activo: la combinación lanza `ue_item_selected` para esa entrada, esté donde esté el foco. En un menú se aprenden los atajos de una aplicación; una tecla mostrada que no hace nada enseña lo contrario. La cadena vacía retira ambos
`ib_checked`	boolean	`false`	Marca de verificación delante de la entrada — para una opción que se activa y se desactiva
`is_tooltip`	string	`""`	Información sobre herramientas de esta entrada
`is_super_tooltip_title`	string	`""`	Título de su información enriquecida
`is_super_tooltip_text`	string	`""`	Texto de su información enriquecida (se acepta marcado enriquecido)
`is_super_tooltip_image`	string	`""`	Imagen de su información enriquecida

Métodos #

Método	Función
`of_add_menu (string as_key, string as_text)`	Añade un menú a la barra. Devuelve `0` una vez aplicado, `-2` si el componente no está creado
`of_add_item (string as_keys, string as_text)`	Añade una entrada a un 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
`of_add_item (string as_keys, string as_text, string as_image, boolean ab_checked)`	Lo mismo, con el icono, la marca y el estado inicial. 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)`	Traza una línea de separación al final del menú. Devuelve `0` una vez aplicado, `-2` si el componente no está creado
`of_item (string as_keys)` → `n_pbt_menubar_item`	Handle de una entrada, para fijar sus propiedades. `as_key` acepta las dos escrituras: el identificador desnudo de la hoja y la ruta completa con las claves unidas por `/` — `of_item("file", "export/pdf")`. Es la ruta que devuelve `ue_item_selected`: sus dos argumentos se vuelven a dar tal cual aquí. Un identificador desnudo sólo es único dentro de su submenú
`of_menu (string as_key)` → `n_pbt_menubar_menu`	Handle de un menú de primer nivel, para renombrarlo o apagarlo. `of_add_menu` solo podía hacerlo al crearlo: atenuar Admin al cerrar sesión obligaba a reconstruir toda la barra; `ib_visible` lo retira de la barra, entradas y atajos dormidos con él
`of_remove_item (string as_keys)` → `long`	Quita una entrada; las demás quedan. `as_key` acepta las dos escrituras de `of_item`: la ruta completa (`export/pdf`) o el id desnudo. Sin ella solo existía `of_clear`, que lo vacía todo — el menú dinámico más común, una lista de archivos recientes, obligaba a arrasar toda la barra en cada documento abierto. 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_menu (string as_key)` → `long`	Quita un menú de primer nivel, con sus entradas. La barra se redibuja y su altura se vuelve a anunciar. Devuelve `0` una vez aplicado, `-2` si el componente no está creado
`of_clear ( )`	Vacía la barra — menús y entradas. Devuelve `0` una vez aplicado, `-2` si el componente no está creado
`of_reset ( )`	Vacía la barra y devuelve todas las propiedades a su valor predeterminado. Devuelve `0` una vez aplicado, `-2` si el componente no está creado
`of_set_redraw (boolean)`	Agrupa una ráfaga de cambios en un solo renderizado. Devuelve `0` una vez aplicado, `-2` si el componente no está creado
`of_save_as_png (string)` · `of_save_as_jpg (string)`	Exporta el renderizado como imagen. Devuelve `0` una vez escrita la imagen, `-4` si la escritura falla, `-2` si el componente no está creado

Eventos #

Evento	Se dispara cuando
`ue_menu_opening (string as_key)`	Lanzado en el instante en que se pulsa un menú de primer nivel, antes de que se construya su desplegable. Es el momento de activar, atenuar o rellenar sus entradas justo a tiempo — sin él había que mantener toda la barra al día con el estado de la aplicación en permanencia, o mostrar entradas que mienten
`ue_item_selected (string as_keys)`	El usuario ha elegido una entrada. `as_key` es una ruta en cuanto la entrada está anidada — `export/pdf`, no `pdf`: la hoja sola no dice de qué submenú sale, y dos submenús pueden tener cada uno la suya. Una entrada de primer nivel conserva su identificador desnudo. Ese mismo texto se devuelve tal cual a `of_item`
`ue_auto_height (long al_height)`	La barra anuncia la altura que necesita — recoloque lo que haya debajo
`ue_ready ( )`	El componente terminó de cargar; todo lo enviado antes se ha reproducido
`ue_runtime_missing ( )`	Falta el runtime WebView2: el componente queda vacío
`ue_bg_color (long al_color)`	El componente calculó su color de fondo de tema; el userobject ya lo adoptó (`backcolor`)

La altura no se fija, se anuncia. Una barra de menús no se desplaza: una altura fija solo puede producir espacio vacío bajo la barra o menús truncados. Por eso siempre se ajusta, y ue_auto_height le dice en cuánto.

Con el teclado #

Tecla	Efecto
Alt	Da el foco a la barra, como en cualquier aplicación de Windows
Flechas	Recorren los menús y sus entradas; la derecha abre una subentrada, la izquierda vuelve arriba
Intro o Espacio	Elige la entrada con el foco (`ue_item_selected`)
Esc	Cierra el menú abierto y luego devuelve el foco

Ejemplos #

Una barra de menús completa #

uo_menus.of_set_redraw(false)

// El menu Archivo, con un icono en Abrir y una linea antes de Salir
uo_menus.of_add_menu(/*key*/ "file", /*text*/ "F")
uo_menus.of_add_item(/*keys*/ "file/open", /*text*/ "O", /*image*/ "mono:img\packimages.dll:svg/samples/folder-open", /*checked*/ false)
uo_menus.of_add_separator(/*keys*/ "file")
uo_menus.of_add_item(/*keys*/ "file/quit", /*text*/ "Q")

// Un submenu: Exportar, y luego sus dos formatos
uo_menus.of_add_item(/*keys*/ "file/export", /*text*/ "E")
uo_menus.of_add_item(/*keys*/ "file/export/csv", /*text*/ "CSV")
uo_menus.of_add_item(/*keys*/ "file/export/pdf", /*text*/ "PDF")

// El menu Ver: una opcion que se marca
uo_menus.of_add_menu(/*key*/ "view", /*text*/ "V")
uo_menus.of_add_item(/*keys*/ "view/grid", /*text*/ "G", /*image*/ "", /*checked*/ true)

uo_menus.of_set_redraw(true)

Marcar, desmarcar, atenuar #

// El usuario ha invertido la visualizacion de la cuadricula
uo_menus.of_item(/*keys*/ "view/grid").ib_checked = not uo_menus.of_item(/*keys*/ "view/grid").ib_checked

// Una entrada que ya no tiene sentido se atenua, no desaparece:
// el usuario debe poder ver que existe
uo_menus.of_item(/*keys*/ "file/save").ib_enabled = false

Reconstruir la barra #

// Cambiar de espacio de trabajo: se vacia y se vuelve a poner
// of_set_redraw evita repintar en cada linea
uo_menus.of_set_redraw(false)
uo_menus.of_clear()
uo_menus.of_add_menu(/*key*/ "tools", /*text*/ "T")
uo_menus.of_set_redraw(true)

Buenas prácticas #

Dé a cada entrada un identificador de negocio estable ("save"): es el que recibe en ue_item_selected, no una etiqueta que cambia con el idioma.
Atenúe en lugar de retirar: una entrada ausente deja al usuario buscando, una atenuada le dice que existe y que le falta algo.
Encuadre la construcción con of_set_redraw(false) / of_set_redraw(true): una barra completa son treinta llamadas enseguida.
Recoloque lo que hay bajo la barra en ue_auto_height — la altura depende del tema y del tamaño de letra, no es la misma en todas partes.
Para las etiquetas, pase por of_set_translation si su aplicación es multilingüe: vea el capítulo de idioma.

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

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.