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) · `n_pbt_menubar_menu` (un menú de la barra)
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 "file/open"; of_open_document()
	case "file/save"; of_save_document()
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 clave, `file`
La entrada de un menú	`of_add_item`	la dirección `menu/entrada`, `file/open`
La subentrada de una entrada	`of_add_item`	la dirección `menu/entrada/subentrada`, `file/export/pdf` — tan profunda como haga falta

Una clave solo es única bajo su padre: por eso una entrada se designa siempre por su dirección completa, primero el menú — nunca por su clave sola. Dos menús pueden así tener cada uno su entrada open, y dos submenús su propio pdf (file/export/pdf, file/print/pdf), sin estorbarse. Una clave no contiene ni / ni |, no está vacía y no empieza por __: las altas la rechazan (-5), igual que una dirección ya ocupada o un padre nunca añadido.

Un separador no tiene clave: of_add_separator traza una línea al final de un menú (file) o de la cascada de una entrada (file/export), y después no hay nada que releer.

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	`""`	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
`ib_wrap`	boolean	`false`	`false` (predeterminado): la barra se queda en una línea; los títulos que no caben, desde el final, pasan al desplegable de un chevron en su extremo (sus entradas en cascada), y la altura ya no cambia. `true`: la barra salta de línea y anuncia su nueva altura (`ue_auto_height`) — lo que hacía antes de la 4.0
`ib_track_hover`	boolean	`false`	Suscripción a `ue_item_hover`: sin ella los desplegables ni siquiera informan de la entrada señalada — un evento disparado a cada movimiento del puntero solo se envía a una aplicación que lo ha pedido

Propiedades de una entrada — `n_pbt_menubar_item` #

Obtenidas mediante of_item(dirección) — of_item("file/export/pdf"). Una dirección de un solo nivel designa un menú, no una entrada: su handle no cambia nada, use of_menu.

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. Un atajo dormido conserva su combinación: tampoco llega a su aplicación; `is_shortcut = ""` se la devuelve
`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. Teclas: una letra, una cifra, de `F1` a `F24`, `Enter`, `Esc`, `Del`, `Insert`, `Home`, `End`, `PageUp`, `PageDown`, y con Ctrl o Alt también `+`, `-`, `,`, `.`, las flechas (`Left`…), `Space`, `Tab`, `Backspace` (`Ctrl++` para el zoom). Un atajo va en una hoja: en una entrada que abre una cascada no se muestra ni se dispara. 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_image`	string	`""`	El icono de la entrada, cambiado en caliente: la entrada conserva su lugar en la lista. Mismas rutas que `of_add_item` (`mono:`, `tint:`, `archivo.dll:NOMBRE`); la cadena vacía lo retira
`is_group`	string	`""`	Convierte la entrada en una entrada de opción: las entradas de un mismo grupo bajo el mismo padre se excluyen — marcar una (`ib_checked = true`, o la elección del usuario) desmarca las demás, y una viñeta redonda sustituye a la marca. `ue_item_selected` sigue diciendo cuál se eligió. La cadena vacía la vuelve una entrada normal
`il_accent`	long	`-1`	Acento de esta entrada: su marca y su borde cuando está señalada (`-1` = el del tema)
`il_back_color`	long	`-1`	Fondo de esta entrada en el desplegable, en reposo
`il_text_color`	long	`-1`	Color del texto de esta entrada
`il_back_color_hover`	long	`-1`	Fondo de esta entrada cuando está señalada
`il_text_color_hover`	long	`-1`	Color del texto de esta entrada cuando está señalada
`is_tooltip`	string	`""`	Se guarda y se relee, pero una entrada del desplegable no muestra ninguna información sobre herramientas: el desplegable nativo no tiene. Solo los títulos de los menús muestran la suya (`of_menu`)
`is_super_tooltip_title`	string	`""`	Título de su información enriquecida — guardado, no mostrado (ver `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Texto de su información enriquecida — guardado, no mostrado
`is_super_tooltip_image`	string	`""`	Imagen de su información enriquecida — guardada, no mostrada

Propiedades de un menú — `n_pbt_menubar_menu` #

Obtenidas mediante of_menu(clave) — of_menu("file"). Colores e información sobre herramientas se muestran en el título del menú en la barra.

Propiedad	Tipo	Predeterminado	Función
`is_text`	string	—	Texto del menú, `&` incluido (mnemónico), cambiado sin reconstruir la barra
`ib_enabled`	boolean	`true`	Menú atenuado: ya no se abre, sus entradas y sus atajos con él; el teclado lo salta
`ib_visible`	boolean	`true`	El menú sale de la barra — entradas y atajos dormidos con él — y vuelve tal cual. Los atajos dormidos conservan su combinación: tampoco llega a su aplicación
`is_align`	string	`"start"`	`u_pbt_menubar.ALIGN_END` coloca el menú al final de la barra, como Ayuda — con los que lo siguen en la misma alineación, después de él; `ALIGN_START` (predeterminado) lo devuelve entre los demás. Lógico: el final es el lado izquierdo en un diseño de derecha a izquierda. Con el chevron, los títulos del final se pliegan primero
`il_accent`	long	`-1`	Acento de este menú: una línea bajo su título mientras su desplegable está abierto (`-1` = ninguno)
`il_back_color`	long	`-1`	Fondo de su título, en reposo
`il_text_color`	long	`-1`	Color del texto de su título, en reposo
`il_back_color_hover`	long	`-1`	Fondo de su título al pasar el ratón o abierto
`il_text_color_hover`	long	`-1`	Color del texto de su título al pasar el ratón o abierto
`is_tooltip`	string	`""`	Información mostrada cuando el puntero se detiene en su título
`is_super_tooltip_title`	string	`""`	Título de la información enriquecida de su título
`is_super_tooltip_text`	string	`""`	Texto de esa información enriquecida (se admite marcado enriquecido)
`is_super_tooltip_image`	string	`""`	Imagen de esa 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, `-5` si la clave se rechaza (vacía, con `/` o una barra vertical, que empieza por `__`, o ya ocupada), `-2` si el componente no está creado
`of_add_item (string as_keys, string as_text)`	Añade una entrada en su dirección: `file/open` en el menú File, `file/export/pdf` bajo la entrada Export, tan profunda como haga falta. Devuelve `0` una vez aplicado, `-5` si la dirección se rechaza: menos de dos niveles, un nivel vacío, una clave con `/` o una barra vertical o que empieza por `__`, un menú o una entrada padre nunca añadidos, o una dirección ya ocupada. `-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 y la marca. Para atenuar la entrada, ahora o más tarde, use su handle: `of_item(dirección).ib_enabled = false`. Devuelve `0` una vez aplicado, `-5` si la dirección se rechaza: menos de dos niveles, un nivel vacío, una clave con `/` o una barra vertical o que empieza por `__`, un menú o una entrada padre nunca añadidos, o una dirección ya ocupada. `-2` si el componente no está creado
`of_add_separator (string as_keys)`	Traza una línea de separación al final de un menú (`file`) o de la cascada de una entrada (`file/export`). Devuelve `0` una vez aplicado, `-5` si no se añadió nada en esa dirección, `-2` si el componente no está creado
`of_add_header (string as_keys, string as_text)` → `long`	Añade un encabezado de sección al final de un menú (`view`) o de la cascada de una entrada (`view/panels`): una línea de título sobre las entradas que lo siguen, hasta el siguiente encabezado o separador. No es una entrada — nunca se elige, nunca la cuenta `of_count`, ni en el límite de demo — y no se dibuja cuando todas las entradas que encabeza están ocultas. Devuelve `0` una vez añadido, `-5` si no se creó nada en esa dirección, `-2` si el componente no está creado
`of_item (string as_keys)` → `n_pbt_menubar_item`	Handle de una entrada, por su dirección — `of_item("file/export/pdf")` —, para leer o fijar sus propiedades. Es exactamente lo que devuelve `ue_item_selected`: el argumento se vuelve a dar tal cual aquí. Nunca la clave sola: dos submenús pueden tener cada uno su `pdf`, y solo la dirección los distingue. Una dirección de un nivel designa un menú: su handle no cambia nada, use `of_menu`
`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, en su dirección (`file/open`, `file/export/pdf`) — con su cascada; las demás se quedan. Sus handles se liberan y su atajo se desarma: la tecla vuelve a su aplicación. Sin ella solo existía `of_clear`, que lo vacía todo — el menú dinámico más corriente, una lista de archivos recientes, obligaba a arrasar toda la barra en cada documento abierto. Devuelve `0` una vez aplicado, `-5` si ninguna entrada vive en esa dirección, `-2` si el componente no está creado
`of_remove_menu (string as_key)` → `long`	Quita un menú de primer nivel, con sus entradas — handles liberados, atajos desarmados. La barra se vuelve a dibujar y su altura se vuelve a anunciar. Devuelve `0` una vez aplicado, `-5` para un menú nunca añadido, `-2` si el componente no está creado
`of_clear ( )`	Vacía la barra — menús y entradas; sus handles se liberan y los atajos de las entradas se desarman. 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 cuando un menú de primer nivel va a abrirse — y el desplegable espera: solo se abre cuando el evento ha vuelto. Active, atenúe o rellene aquí sus entradas: el cambio se ve en esta apertura, no en la siguiente. 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_menu_closed (string as_key)`	El desplegable de un menú de primer nivel se cerró sin elección: por el usuario (clic fuera, Esc, o deslizamiento hacia el menú vecino), o por su código que retira, vacía, oculta o desactiva el menú abierto (`of_remove_menu`, `of_clear`, `ib_visible`, `ib_enabled`) — una orden también lo lanza. Deshaga aquí lo que `ue_menu_opening` había preparado (una vista previa, una selección). Una elección lanza `ue_item_selected` en su lugar, y `of_reset` no lanza nada
`ue_item_selected (string as_keys)`	El usuario ha elegido una entrada, o pulsado su atajo. `as_keys` es su dirección, primero el menú — `file/open`, `file/export/pdf`: la clave sola no dice de qué submenú sale, y dos submenús pueden tener cada uno la suya. Ese mismo texto se vuelve a dar tal cual a `of_item`. Una entrada atenuada, oculta o quitada mientras su desplegable estaba abierto no lanza nada
`ue_item_hover (string as_keys)`	Con `ib_track_hover = true`: la entrada bajo el puntero o el teclado en un desplegable abierto, por su dirección (`file/export/pdf`) — también una entrada atenuada, su ayuda puede decir por qué. Se dispara una vez por entrada, y luego con una dirección vacía al cerrarse el desplegable (antes de `ue_item_selected` en una elección): escriba el texto de ayuda de una barra de estado y luego vacíelo
`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`)

Una línea, por defecto. Los títulos que no caben pasan al chevron al final de la barra (ib_wrap = false, el valor predeterminado): la altura sigue siendo la de una línea y ue_auto_height se dispara una vez. Con ib_wrap = true la barra salta de línea: nunca se desplaza, su altura sigue las filas y ue_auto_height le indica cuánto en cada cambio de ancho.

Con el teclado #

Tecla	Efecto
Alt · F10	Da el teclado a la barra y subraya las letras de los menús, como en cualquier aplicación de Windows; una segunda pulsación lo devuelve
»	El chevron de los títulos que no caben: las flechas se detienen en él como en un título, Intro o Abajo abre la lista de los menús ocultos, y Alt + la letra de un menú oculto abre ese menú desde el chevron
Alt + letra	Abre el menú de esa letra (`&Archivo`) desde cualquier control de la ventana — un campo, un DataWindow. Un atajo `Alt+letra` registrado por su aplicación va primero. Dos menús con la misma letra: la banda pasa de uno a otro, Intro abre. Una letra acentuada o no latina se teclea como en el teclado (`&Édition`: Alt + la tecla de la É)
Flechas	Recorren los menús y sus entradas, saltando los menús atenuados; la derecha abre una subentrada, la izquierda vuelve arriba. En escritura de derecha a izquierda (`RTL`) todo se invierte: en la barra, en el desplegable (alineado con el borde derecho de su título) y en las cascadas, que se abren a la izquierda — la izquierda abre, la derecha vuelve arriba
Intro	En un desplegable: elige la entrada resaltada (`ue_item_selected`). Sobre un título de la barra, Intro, Espacio o Flecha abajo abren el menú. Espacio no elige una entrada — también es la regla de Windows
Esc	Cierra el menú abierto y luego devuelve el foco al control que lo tenía

Una barra de menús nunca se queda con el foco. Un clic en un título y luego una elección con el ratón: el teclado vuelve al control donde se tecleaba antes de que se lance ue_item_selected. Edición > Pegar pega pues en el campo en edición, y GetFocus() lo nombra en el evento.

Ejemplos #

Una barra de menús completa #

// Congelar el dibujo durante la construccion
uo_menus.of_set_redraw(/*on*/ false)

// El menu Archivo, con un icono en Abrir y una linea antes de Salir
uo_menus.of_add_menu(/*key*/ "file", /*text*/ "&Archivo")
uo_menus.of_add_item(/*keys*/ "file/open", /*text*/ "&Abrir...", /*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*/ "&Salir")

// Un submenu: Exportar, y luego sus dos formatos
uo_menus.of_add_item(/*keys*/ "file/export", /*text*/ "&Exportar")
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*/ "&Ver")
uo_menus.of_add_item(/*keys*/ "view/grid", /*text*/ "&Cuadricula", /*image*/ "", /*checked*/ true)

// Un solo redibujado, con todo
uo_menus.of_set_redraw(/*on*/ 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

Entradas de opción y un atajo de zoom #

// Dos entradas DE OPCION: marcar una desmarca la otra, una vineta redonda sustituye a la marca
uo_menus.of_add_item(/*keys*/ "view/small", /*text*/ "Iconos &pequenos")
uo_menus.of_add_item(/*keys*/ "view/large", /*text*/ "Iconos &grandes")
uo_menus.of_item(/*keys*/ "view/small").is_group = "size"
uo_menus.of_item(/*keys*/ "view/large").is_group = "size"
uo_menus.of_item(/*keys*/ "view/large").ib_checked = true

// El zoom: Ctrl++ se muestra Y esta activo, este donde este el foco
uo_menus.of_add_item(/*keys*/ "view/zoomin", /*text*/ "&Acercar")
uo_menus.of_item(/*keys*/ "view/zoomin").is_shortcut = "Ctrl++"

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(/*on*/ false)
uo_menus.of_clear()
uo_menus.of_add_menu(/*key*/ "tools", /*text*/ "&Herramientas")
uo_menus.of_set_redraw(/*on*/ true)

Una barra estrecha, Ayuda al final, un texto de ayuda en la barra de estado #

// Help at the end of the bar ; what does not fit goes into the chevron
uo_menubar.of_menu(/*key*/ "help").is_align = u_pbt_menubar.ALIGN_END

// Section headers in View
uo_menubar.of_add_header(/*keys*/ "view", /*text*/ "Panels")
uo_menubar.of_add_item(/*keys*/ "view/tree", /*text*/ "Tree")
uo_menubar.of_add_item(/*keys*/ "view/output", /*text*/ "Output")

// A help text in the status bar for the pointed entry
uo_menubar.ib_track_hover = true

// ue_item_hover (string as_keys) of uo_menubar
choose case as_keys
	case "file/save"
		st_status.Text = "Saves the document"
	case ""
		st_status.Text = ""
end choose

Buenas prácticas #

Dé una clave de negocio estable a cada nivel (file, save): ue_item_selected devuelve la dirección file/save, nunca la etiqueta — no 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.
Las etiquetas son suyas: tradúzcalas antes de of_add_item, o cámbielas en caliente con of_item(...).is_text / of_menu(...).is_text. of_set_translation solo traduce los textos propios de un componente, y la barra de menús no tiene ninguno.
Ponga un & en cada título (&Archivo): Alt + la letra abre el menú desde cualquier sitio, como en toda aplicación de Windows.

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.