ribbon — `u_pbt_ribbon` #

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

Cinta de opciones estilo Office: pestañas, grupos, doce tipos de controles enriquecidos, menú de aplicación, barra de acceso rápido, pestañas contextuales con banda y keytips.

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

De un vistazo #

Userobject	`u_pbt_ribbon`
Clases de items	`n_pbt_ribbon_tab` (pestaña), `n_pbt_ribbon_group` (grupo), `n_pbt_ribbon_item` (control), `n_pbt_ribbon_menu_item` (entrada de menú), `n_pbt_ribbon_ctx_group` (grupo de pestañas contextuales), `n_pbt_ribbon_app_menu_item` (entrada del menú de aplicación)
Sirve para	Sustituir una barra de menús y sus barras de herramientas por una interfaz de comandos moderna, legible y jerarquizada
Altura	Intrínseca: la cinta de opciones se ajusta siempre a su contenido, no hay nada que activar — véase Altura automática
Límite en modo demo	2 pestañas como máximo — véase El modo demo

La regla de oro: todo pasa por la ruta #

La cinta de opciones es una jerarquía de cuatro niveles: pestaña → grupo → control → entrada de menú. No hay ningún identificador global que gestionar: cada objeto se alcanza mediante la ruta que conduce hasta él y cada adición se realiza sobre el componente, en la dirección del elemento padre.

// Leer o gobernar un control : siempre la ruta completa
uo_ribbon.of_item(/*keys*/ "home/clipboard/paste").ib_enabled = false

Dos consecuencias prácticas y cómodas: dos grupos distintos pueden usar el mismo identificador de control sin estorbarse, y los eventos le entregan la ruta completa — siempre sabe de dónde procede el clic.

Inicio rápido #

// event open de la ventana

// Una pestana
uo_ribbon.of_add_tab(/*key*/ "home", /*title*/ "Inicio")

// Un grupo: un boton grande y dos pequenos
uo_ribbon.of_add_group(/*keys*/ "home/clipboard", /*title*/ "Portapapeles")
uo_ribbon.of_add_big_button(/*keys*/ "home/clipboard/paste", /*label*/ "Pegar", /*image*/ "mono:img\paste.svg")
uo_ribbon.of_add_button(/*keys*/ "home/clipboard/cut", /*label*/ "Cortar", /*image*/ "mono:img\cut.svg")
uo_ribbon.of_add_button(/*keys*/ "home/clipboard/copy", /*label*/ "Copiar", /*image*/ "mono:img\copy.svg")

// Mostrar la pestana
uo_ribbon.of_select_tab(/*key*/ "home")

// event ue_clicked de uo_ribbon : (string as_keys)
choose case as_keys
    case "home/clipboard/paste" ; of_paste()
    case "home/clipboard/cut" ; of_cut()
    case "home/clipboard/copy" ; of_copy()
end choose

Propiedades #

Propiedad	Tipo	Predeterminado	Función
`is_app_button`	string	`""`	Etiqueta del botón de aplicación, arriba a la izquierda, que abre el menú de aplicación. Renombrarlo conserva su menú; una cadena vacía retira el botón, con su menú. Las entradas del menú de aplicación necesitan antes el botón
`ib_minimized`	boolean	`false`	`true` repliega la cinta de opciones dejando solo los encabezados de las pestañas; un clic en una pestaña la despliega temporalmente. Asignado por código, activa `ue_minimized` como el gesto del usuario — nada cuando la cinta ya está en ese estado; `ue_size_changed` indica la nueva altura
`ib_veto_gallery`	boolean	`false`	Preguntar antes de que se retenga un mosaico de galería — por el usuario o por `of_select_gallery_item` (activa `ue_gallery_selection_changing`, que puede rechazarlo; un `of_select_gallery_item` rechazado devuelve `-4`). Inactivo de forma predeterminada, como todo evento cancelable: cada pregunta cuesta una ida y vuelta hasta PowerBuilder (~35 ms). Póngalo a `true` cuando su aplicación responda
`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

Constante — ACCENT_LIGHT (-1): se pasa como color de una pestaña o de un grupo contextual para que siga el color de acento del tema, aclarado, en lugar de un color fijo.

Propiedades de una pestaña — `n_pbt_ribbon_tab` #

Obtenidas mediante of_tab("tab"), se modifican en caliente.

Propiedad	Tipo	Predeterminado	Función
`ib_visible`	boolean	`true`	`false` oculta la pestaña sin eliminarla — es el mecanismo mismo de las pestañas contextuales
`is_title`	string	`""`	Título de la pestaña. Puesto por `of_add_tab`; escribirlo aquí lo cambia, leerlo dice lo que muestra
`is_keytip`	string	`""`	Tecla de acceso rápido mostrada tras pulsar Alt (`"I"` para Inicio). Una letra o varias (`"FP"`, como en Office), tecleadas una tras otra; Retroceso deshace la última. Solo letras A-Z y cifras: cualquier otro carácter se rechaza — nada cambia, y `of_get_last_error` de la cinta dice por qué
`il_accent`	long	`-1`	Color de acento de esta pestaña (`-1` = el del tema)
`il_back_color`	long	`-1`	Fondo de esta pestaña, en reposo
`il_text_color`	long	`-1`	Color del texto de esta pestaña
`il_back_color_hover`	long	`-1`	Fondo de esta pestaña bajo el puntero
`il_text_color_hover`	long	`-1`	Color del texto de esta pestaña bajo el puntero
`is_tooltip`	string	`""`	Información sobre herramientas simple, mostrada cuando el puntero se detiene sobre la pestaña
`is_super_tooltip_title`	string	`""`	Título de su información enriquecida (tiene prioridad sobre `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Texto de su información enriquecida (se admite el texto enriquecido)
`is_super_tooltip_image`	string	`""`	Imagen de su información enriquecida

Propiedades de un grupo — `n_pbt_ribbon_group` #

Obtenidas mediante of_group("tab/group").

Propiedad	Tipo	Predeterminado	Función
`ib_visible`	boolean	`true`	`false` oculta el grupo y todos sus controles
`is_title`	string	`""`	Rótulo bajo el grupo. Puesto por `of_add_group`; escribirlo aquí lo cambia
`ib_launcher`	boolean	`false`	Muestra la pequeña flecha en la parte inferior derecha del grupo — el iniciador del cuadro de diálogo (activa `ue_launcher`). La flecha vive en la barra de título del grupo, y un grupo que la cinta ha tenido que plegar por falta de espacio la conserva en el mismo sitio — además viaja al panel que abre el grupo plegado.
`il_accent`	long	`-1`	Color de acento de este grupo (`-1` = el del tema)
`il_back_color`	long	`-1`	Fondo de este grupo, en reposo
`il_text_color`	long	`-1`	Color del texto de este grupo
`il_back_color_hover`	long	`-1`	Fondo de este grupo bajo el puntero
`il_text_color_hover`	long	`-1`	Color del texto de este grupo bajo el puntero
`is_tooltip`	string	`""`	Información sobre herramientas simple, mostrada cuando el puntero se detiene sobre el título del grupo (y sobre su botón cuando el grupo está replegado)
`is_super_tooltip_title`	string	`""`	Título de su información enriquecida (tiene prioridad sobre `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Texto de su información enriquecida (se admite el texto enriquecido)
`is_super_tooltip_image`	string	`""`	Imagen de su información enriquecida

Constantes de modo del selector de color: COLORMODE_PALETTE (muestrario de casillas, modo predeterminado) y COLORMODE_OPEN (paleta completa con confirmación).

Propiedades de un control — `n_pbt_ribbon_item` #

Obtenidas mediante of_item("tab/group/control"). Se aplican a todos los tipos de controles; las propiedades que no vienen al caso para un tipo dado simplemente se ignoran.

Propiedad	Tipo	Predeterminado	Función
`is_label`	string	`""`	Etiqueta del control. Admite el texto enriquecido con etiquetas — en la cinta como en el panel de un grupo replegado; pase un texto del usuario por `of_escape_markup`
`is_image`	string	`""`	Imagen del control (botón, botón grande, botón dividido, botón desplegable, casilla, selector de color, botón de la barra de acceso rápido), con los mismos prefijos que al añadirlo (`mono:`, `tint:`). `""` la quita. Se lee en directo
`ib_enabled`	boolean	`true`	`false` atenúa el control y bloquea su activación
`ib_checked`	boolean	`false`	Estado pulsado de un conmutador o marcado de una casilla
`is_group`	string	`""`	Solo conmutador: los conmutadores de un mismo grupo de la cinta que comparten un nombre son excluyentes, como los botones de alineación de un editor — pulsar uno suelta los demás (`ue_toggled` para el que se enciende, nada para los que se sueltan), pulsar el que ya está pulsado lo deja pulsado. `ib_checked = true` por código también suelta los demás, en silencio. Una cadena vacía (por defecto) abandona el grupo
`ib_visible`	boolean	`true`	`false` oculta el control; los vecinos se compactan
`is_text`	string	`""`	Texto escrito o seleccionado en un cuadro combinado
`id_value`	double	`0`	Valor numérico de un control de número
`id_min`	double	`0`	Solo control de número: límite inferior del rango, modificable en cualquier momento. El valor se devuelve al nuevo rango de inmediato, en silencio (ningún `ue_value_changed`, como `id_value` escrito por código). En cualquier otro control, sin efecto y se lee `0` — un mínimo por encima del máximo arrastra el máximo consigo (gana el límite escrito, como en un NumericUpDown): los dos límites se ponen en cualquier orden
`id_max`	double	`0`	Solo control de número: límite superior del rango, modificable en cualquier momento; el valor se devuelve al rango en silencio, como con `id_min`. En cualquier otro control, sin efecto y se lee `0` — un máximo por debajo del mínimo arrastra el mínimo consigo (gana el límite escrito)
`id_step`	double	`0`	Solo control de número: paso de las flechas y de las teclas Arriba / Abajo, modificable en cualquier momento. Un paso de `0` o menos se rechaza: nada cambia, y `of_get_last_error` de la cinta dice por qué. En cualquier otro control, sin efecto y se lee `0`
`is_mask`	string	`""`	Solo control de número: su máscara de entrada, una máscara numérica en la sintaxis de PowerBuilder (EditMask, formato DataWindow): `#` un dígito opcional, `0` un dígito obligatorio, `,` la agrupación, `.` el separador decimal, `%` el número mostrado por 100, literales (`$`, un texto entre comillas, `\x`) y secciones `positivo;negativo` (`"$#,##0;($#,##0)"`). La coma y el punto designan los separadores del idioma de visualización. Al teclear, la agrupación aparece a medida que llegan los dígitos, los decimales se limitan a la máscara, las letras se rechazan, el cursor conserva su lugar entre los dígitos y un número pegado se lee en el idioma de visualización; al salir del campo la máscara completa (`12` pasa a `12,00`). El valor conserva el número tal como lo escribe el código (`"1234.5"`), sin agrupación ni símbolo. Un rango que empieza en 0 o más rechaza el signo menos; las flechas conservan la máscara; `id_value` y `ue_value_changed` conservan el número desnudo; la máscara sigue al control en el panel de un grupo contraído. Vacío (por defecto): el campo se teclea según su `is_format` sin sus literales (`$#,##0.00` se teclea `#,##0.00`, `#,##0 "px"` se teclea `#,##0`; un `%` se queda, es una escala), si no el número tal cual. En cualquier otro control, sin efecto y se lee vacío
`is_format`	string	`""`	Solo control de número: su formato de visualización, cómo se muestra el número mientras el campo no tiene el teclado — la misma sintaxis que `is_mask`, con sus literales: `0 "pt"` muestra `11 pt`, `0%` una tasa. Cuando el campo toma el teclado su texto pasa a ser el de `is_mask` (`11`), el cursor conserva su lugar entre los dígitos; al salir vuelve el texto de visualización. El cambio nunca modifica el valor y no lanza nada: `id_value` y `ue_value_changed` conservan el número desnudo; el formato sigue al control en el panel de un grupo contraído. Vacío (por defecto): el control muestra su `is_mask`. En cualquier otro control, sin efecto y se lee vacío
`il_color`	long	`-1`	Color actual de un selector de color
`ii_visible_items`	integer	`3`	Solo galería: número de mosaicos que la banda plegada muestra de una vez. Los demás siguen siendo accesibles mediante las flechas, o en la cuadrícula desplegada
`is_keytip`	string	`""`	Tecla de acceso rápido del control, mostrada tras Alt y la letra de la pestaña. Una letra o varias (`"FP"`, como en Office), tecleadas una tras otra; Retroceso deshace la última. Solo letras A-Z y cifras: cualquier otro carácter se rechaza — nada cambia, y `of_get_last_error` de la cinta dice por qué. Un botón de la barra de acceso rápido recibe su letra con las pestañas, en el primer nivel. Un control de un grupo replegado conserva su tecla: abre el panel del grupo
`is_tooltip`	string	`""`	Tooltip simple mostrado al pasar el ratón por el item
`is_super_tooltip_title`	string	`""`	Título del tooltip enriquecido del item (prevalece sobre `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Texto del tooltip enriquecido del item (se acepta el marcado enriquecido)
`is_super_tooltip_image`	string	`""`	Imagen del tooltip enriquecido del item
`il_accent`	long	`-1`	Color de acento de este control (`-1` = el del tema)
`il_back_color`	long	`-1`	Fondo de este control, en reposo
`il_text_color`	long	`-1`	Color del texto de este control
`il_back_color_hover`	long	`-1`	Fondo de este control bajo el puntero
`il_text_color_hover`	long	`-1`	Color del texto de este control bajo el puntero

Propiedades de una entrada de menú — `n_pbt_ribbon_menu_item` #

Obtenidas mediante of_menu_item("tab/group/control/entry").

Propiedad	Tipo	Predeterminado	Función
`is_image`	string	`""`	Imagen de la entrada de menú. Una cadena vacía la quita
`of_is_separator ( )` → `boolean`	—	—	¿La entrada es una línea de separación? Solo lectura: lo que una entrada es se decidió al añadirla
`of_is_header ( )` → `boolean`	—	—	¿La entrada es un título no pulsable? Solo lectura, misma razón
`of_is_checkable ( )` → `boolean`	—	—	¿La entrada lleva una marca? Solo lectura; `ib_checked` dice si está puesta
`ib_enabled`	boolean	`true`	`false` atenúa la entrada
`ib_visible`	boolean	`true`	`false` retira la entrada del menú en su próxima apertura — cascada incluida — sin eliminarla
`ib_checked`	boolean	`false`	Marca de una entrada creada con `of_add_menu_check`
`is_group`	string	`""`	Hace de la entrada una entrada de opción: las entradas de un grupo bajo el mismo padre se excluyen — elegir una (o `ib_checked = true` por código) la marca y desmarca las demás, y un punto redondo sustituye a la marca. `ue_menu_selected` indica `ab_checked = true`. Una cadena vacía (por defecto) la vuelve una entrada normal
`il_accent`	long	`-1`	Color de acento de esta entrada en el menú (`-1` = el del tema)
`il_back_color`	long	`-1`	Fondo de esta entrada en el menú, en reposo
`il_text_color`	long	`-1`	Color del texto de esta entrada en el menú
`il_back_color_hover`	long	`-1`	Fondo de esta entrada en el menú bajo el puntero
`il_text_color_hover`	long	`-1`	Color del texto de esta entrada en el menú bajo el puntero
`is_tooltip`	string	`""`	Se guarda y se lee, pero una entrada de menú no muestra ninguna información: el menú nativo no tiene
`is_super_tooltip_title`	string	`""`	Título de su información enriquecida — se guarda, no se muestra (ver `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Texto de su información enriquecida — se guarda, no se muestra
`is_super_tooltip_image`	string	`""`	Imagen de su información enriquecida — se guarda, no se muestra

Propiedades de una entrada del menú de aplicación — `n_pbt_ribbon_app_menu_item` #

Obtenidas mediante of_app_menu_item("recent/a.txt"). Se modifican en caliente: el menú las toma en su próxima apertura.

Propiedad	Tipo	Predeterminado	Función
`is_label`	string	`""`	Texto de la entrada
`is_image`	string	`""`	Imagen de la entrada. Una cadena vacía la retira
`ib_enabled`	boolean	`true`	`false` atenúa la entrada: mostrada, nunca elegida — Guardar mientras no hay nada que guardar
`ib_checked`	boolean	`false`	Marca de verificación delante de la entrada
`ib_visible`	boolean	`true`	`false` saca la entrada del menú en su próxima apertura — submenú incluido — sin eliminarla
`of_is_separator ( )` → `boolean`	—	—	¿Es la entrada una línea de separación? Solo lectura
`of_keys_at (long al_index)` → `string`	—	—	La dirección de la entrada en la posición `al_index` (desde 1) bajo esta — o en el primer nivel para `of_app_menu_item("")` —, `""` más allá del final: la dirección que reciben `of_app_menu_item` y `of_remove_app_menu_item`
`il_accent`	long	`-1`	Color de acento de esta entrada en el menú (`-1` = el del tema)
`il_back_color`	long	`-1`	Fondo de esta entrada en el menú, en reposo
`il_text_color`	long	`-1`	Color del texto de esta entrada en el menú
`il_back_color_hover`	long	`-1`	Fondo de esta entrada en el menú bajo el puntero
`il_text_color_hover`	long	`-1`	Color del texto de esta entrada en el menú bajo el puntero
`is_tooltip`	string	`""`	Se guarda y se lee, pero una entrada de menú no muestra ninguna información: el menú nativo no tiene
`is_super_tooltip_title`	string	`""`	Título de su información enriquecida — se guarda, no se muestra (ver `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Texto de su información enriquecida — se guarda, no se muestra
`is_super_tooltip_image`	string	`""`	Imagen de su información enriquecida — se guarda, no se muestra

Los doce tipos de controles #

Todos se añaden en la dirección de un grupo — "home/clipboard" — y devuelven 0 (-5 ante un argumento no válido, -2 si el componente no está creado); un menú o una lista se rellena después en la dirección del control.

Método del componente	Control obtenido	Evento
`of_add_big_button (string as_keys, string as_label, string as_image)` → `long`	Botón grande de altura completa, icono encima de la etiqueta. 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	`ue_clicked`
`of_add_big_split (string as_keys, string as_label, string as_image)` → `long`	Botón grande dividido: la parte superior actúa, la flecha abre 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	`ue_clicked` · `ue_menu_selected`
`of_add_big_dropdown (string as_keys, string as_label, string as_image)` → `long`	Botón grande con menú desplegable. 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	`ue_menu_selected`
`of_add_button (string as_keys, string as_label, string as_image)` → `long`	Botón pequeño (apilado en columnas de tres). 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	`ue_clicked`
`of_add_toggle (string as_keys, string as_label, string as_image)` → `long`	Pequeño conmutador que permanece pulsado. 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	`ue_toggled`
`of_add_dropdown (string as_keys, string as_label, string as_image)` → `long`	Botón pequeño con menú desplegable. 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	`ue_menu_selected`
`of_add_checkbox (string as_keys, string as_label)` → `long`	Casilla de verificació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	`ue_toggled`
`of_add_separator (string as_keys)` → `long`	Separador vertical entre dos bloques de controles. 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_combo (string as_keys, integer ai_width_px, boolean ab_editable)` → `long`	Cuadro combinado, editable o no. 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	`ue_combo_changed`
`of_add_spinner (string as_keys, integer ai_width_px, double ad_min, double ad_max, double ad_step, double ad_value)` → `long`	Control de número con flechas. Un valor fuera del rango se devuelve a él. Devuelve `0` una vez aplicado, `-5` ante un argumento no válido (clave vacía, dirección errónea, un paso de 0 o menos, un mínimo por encima del máximo), `-2` si el componente no está creado	`ue_value_changed`
`of_add_colorpicker (string as_keys, string as_label, string as_image, long al_color)` → `long`	Botón de color dividido: el clic vuelve a aplicar, la flecha abre el muestrario. 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	`ue_clicked` · `ue_color_changed`
`of_add_gallery (string as_keys, integer ai_width_px, integer ai_tile_w, integer ai_tile_h)` → `long`	Banda desplazable de mosaicos ilustrados. 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	`ue_gallery_selection_changed`

of_add_colorpicker admite un quinto argumento as_mode: COLORMODE_PALETTE (muestrario de casillas) o COLORMODE_OPEN (paleta completa con los botones Aceptar y Cancelar).

Métodos #

Construir la cinta de opciones #

Método	Función
`of_add_tab (string as_key, string as_title)`	Añade una pestaña y devuelve `0` (`-5` ante un argumento no válido, `-2` si el componente no está creado): los grupos se añaden después en su dirección
`of_insert_tab (string as_key, string as_title, integer ai_index)`	Añade una pestaña en la posición que usted elige (`1` = la primera) en lugar de al final, y devuelve `0` (`-5` ante un argumento no válido, `-2` si el componente no está creado) como `of_add_tab`. Un id ya ocupado se rechaza
`of_tab (string as_key)`	Handle de una pestaña existente (creada en el primer acceso)
`of_add_group (string as_keys, string as_title)`	Añade un grupo con título a una pestaña — `"home/clipboard"` — y devuelve `0` (`-5` ante un argumento no válido, `-2` si el componente no está creado)
`of_group (string as_keys)`	Handle de un grupo existente, por su dirección
`of_item (string as_keys)`	Handle de un control existente, por su dirección — `"home/clipboard/paste"`
`of_select_tab (string as_key)`	Activa una pestaña, como un clic en ella: sigue `ue_selection_changed` (justo después de su script, desde la cola de eventos; nada cuando la pestaña ya está activa), y `of_selected_key` la relee enseguida. A diferencia de un clic, no despliega una cinta replegada. Devuelve `0` una vez aplicado, `-5` para una pestaña desconocida u oculta, `-2` si el componente no está creado
`of_selected_key ( )`	Clave de la pestaña activa, `""` si no hay ninguna. Leída en vivo en el componente: desde `ue_selection_changed`, o justo después de `of_select_tab`, ya nombra la nueva pestaña
`of_remove_group (string as_keys)`	Retira un grupo y todos sus controles, por su dirección; los handles de lo que se va quedan liberados. Devuelve `0` una vez aplicado, `-5` cuando ningún grupo vive en esa dirección, `-2` si el componente no está creado
`of_remove_item (string as_keys)`	Retira un control por su dirección (`pestaña/grupo/control`), o un botón de la barra de acceso rápido solo por su clave; su handle queda liberado. Devuelve `0` una vez aplicado, `-5` cuando nada de ese tipo vive en esa dirección, `-2` si el componente no está creado
`of_remove_tab (string as_key)`	Retira una pestaña y todo su contenido; los handles de lo que se va quedan liberados. Devuelve `0` una vez aplicado, `-5` cuando ninguna pestaña lleva esa clave, `-2` si el componente no está creado
`of_clear ( )`	Vacía por completo la cinta de opciones: pestañas, grupos, controles, barra de acceso rápido, menú de aplicación. Devuelve `0` una vez aplicado, `-2` si el componente no está creado

Llenar los menús y las listas #

Todos estos métodos se invocan sobre el componente, con la dirección del control (pestaña/grupo/control) — la entrada, la opción o el mosaico como cuarto nivel.

Método	Función
`of_add_menu_item (string as_keys, string as_label, string as_image)`	Entrada del menú de un botón desplegable o dividido: `pestaña/grupo/control/entrada`, un nivel más por cascada. Devuelve `0` una vez aplicado, `-5` ante una dirección errónea, un padre que no es ni un desplegable ni una entrada, o una clave ya tomada en ese menú, `-2` si el componente no está creado
`of_add_menu_check (string as_keys, string as_label)` · `(string as_keys, string as_label, string as_image)`	Entrada marcable: el clic invierte su estado y lo comunica en `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_menu_header (string as_keys, string as_label)`	Línea de título en la que no se puede hacer clic, para dividir un menú largo. 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)`	Línea de separación en un menú: `as_keys` nombra el control para su propio menú, o una entrada para la cascada situada debajo. 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_item (string as_keys)`	Retira una entrada de un menú, con su cascada (`pestaña/grupo/control/entrada`, más profunda para una entrada en cascada); sus handles quedan liberados. Devuelve `0` una vez aplicado, `-5` cuando ninguna entrada vive en esa dirección, `-2` si el componente no está creado
`of_clear_menu (string as_keys)`	Vacía el menú de un botón desplegable o dividido (`pestaña/grupo/control`): una lista «Archivos recientes» se reconstruye entrada por entrada, sin volver a crear el control. Devuelve `0` una vez aplicado, `-5` cuando la dirección no es ni un desplegable ni un botón dividido, `-2` si el componente no está creado
`of_menu_item (string as_keys)`	Handle de una entrada de menú, para atenuarla o marcarla en caliente
`of_add_combo_item (string as_keys, string as_label)`	Añade una opción a la lista de un cuadro combinado; una opción tiene como clave su etiqueta. Devuelve `0` una vez aplicado, `-5` cuando la dirección no es un cuadro combinado, o ante una etiqueta ya en la lista, vacía, o que contiene `/` o una barra vertical, `-2` si el componente no está creado
`of_remove_combo_item (string as_keys)`	Retira una opción de un cuadro combinado: `pestaña/grupo/lista/etiqueta`. Devuelve `0` una vez aplicado, `-5` cuando la lista no tiene esa opción, `-2` si el componente no está creado
`of_clear_combo (string as_keys)`	Vacía la lista de un cuadro combinado (`pestaña/grupo/lista`); su texto se queda. Devuelve `0` una vez aplicado, `-5` cuando la dirección no es un cuadro combinado, `-2` si el componente no está creado
`of_add_gallery_item (string as_keys, string as_image, string as_label)`	Añade un mosaico a una galería (`pestaña/grupo/galería/mosaico`); su etiqueta es también su nombre para un lector de pantalla. Devuelve `0` una vez aplicado, `-5` ante una dirección errónea, un tercer nivel que no es una galería, o un mosaico ya tomado, `-2` si el componente no está creado
`of_remove_gallery_item (string as_keys)`	Retira un mosaico de una galería (`pestaña/grupo/galería/mosaico`). Cuando se va el mosaico seleccionado, ya no queda nada seleccionado. Devuelve `0` una vez aplicado, `-5` cuando ese mosaico no existe, `-2` si el componente no está creado
`of_select_gallery_item (string as_keys)`	Selecciona un mosaico de galería por programa, por su dirección de cuatro niveles, como una elección: con `ib_veto_gallery` activo, primero se plantea `ue_gallery_selection_changing`; después sigue `ue_gallery_selection_changed`. Mosaico ya seleccionado: no se pregunta ni se lanza nada. Devuelve `0` una vez aplicado (o si ya estaba seleccionado), `-4` si su `ue_gallery_selection_changing` lo rechazó (el mosaico se queda), `-5` para otra profundidad o un mosaico que `of_add_gallery_item` nunca añadió, `-2` si el componente no está creado
`of_open (string as_keys)`	Abre por programa el menú, la lista o la paleta del control en esa dirección (`pestaña/grupo/control`); la dirección de un grupo (`pestaña/grupo`) abre su panel cuando una ventana demasiado estrecha lo ha replegado. Devuelve `0` una vez aplicado, `-5` para una dirección que no nombra ni un control ni un grupo (un botón de la barra de acceso rápido no tiene menú que abrir), `-2` si el componente no está creado

Menú de aplicación y barra de acceso rápido #

Método	Función
`of_add_app_menu_item (string as_keys, string as_label, string as_image)`	Entrada del menú de aplicación (el que abre el botón `is_app_button`), por su dirección: `recent` en la raíz, `recent/a.txt` en el submenú de `recent`. Devuelve `0` una vez aplicado, `-5` ante una clave no válida (vacía, `/` o barra vertical en un nivel, que empieza por `__`), una clave ya tomada, una entrada padre desconocida, o sin botón de aplicación, `-2` si el componente no está creado
`of_add_app_menu_separator (string as_keys)`	Línea de separación en el menú de aplicación. `as_keys` es su dirección, como la de una entrada: `s1` en la raíz, `saveas/s1` en el submenú de `saveas`; una dirección vacía recibe una clave propia. Devuelve `0` una vez aplicado, `-5` ante una clave ya tomada, una entrada padre desconocida, o sin botón de aplicación, `-2` si el componente no está creado
`of_remove_app_menu_item (string as_keys)`	Retira una entrada (o línea de separación) del menú de aplicación por su dirección, con su submenú; sus handles quedan liberados. Devuelve `0` una vez aplicado, `-5` cuando esa entrada no existe, `-2` si el componente no está creado
`of_app_menu_item (string as_keys)`	Handle de una entrada del menú de aplicación (`save`, `recent/a.txt`), para atenuarla, marcarla, ocultarla o renombrarla en caliente — véase más abajo. `of_app_menu_item("")` representa el propio menú: `of_count` y `of_keys_at` recorren su primer nivel
`of_add_qat (string as_key, string as_image, string as_tooltip)`	Botón de la barra de acceso rápido, encima de las pestañas; su tooltip es también su nombre para un lector de pantalla. Devuelve `0` una vez aplicado, `-5` ante una clave no válida (vacía, `/` o barra vertical en un nivel, que empieza por `__`) o una clave ya en la barra, `-2` si el componente no está creado
`of_qat_item (string as_key)`	Handle de un botón de acceso rápido, para atenuarlo u ocultarlo en caliente

Pestañas contextuales #

Método	Función
`of_add_contextual_tab (string as_key, string as_title, long al_color)`	Pestaña contextual aislada: creada oculta, marcada con un filete de color. Pase `ACCENT_LIGHT` para seguir el acento del tema. Devuelve `0` una vez aplicado, `-5` ante una clave no válida (vacía, `/` o barra vertical en un nivel, que empieza por `__`) o una clave ya tomada, `-2` si el componente no está creado
`of_add_contextual_group (string as_key, string as_title)` · `(string as_key, string as_title, long al_color)`	Grupo de pestañas contextuales: una banda de color con título corona sus pestañas. Devuelve `0` una vez aplicado, `-5` ante una clave no válida (vacía, `/` o barra vertical en un nivel, que empieza por `__`) o una clave ya tomada (su color cambia con `of_ctx_group(clave).il_color`), `-2` si el componente no está creado
`of_ctx_group (string as_key)`	Recupera el handle de un grupo contextual ya creado, por su clave — sobre él se establecen sus propiedades
`of_remove_contextual_group (string as_key)`	Retira un grupo de pestañas contextuales y las pestañas que corona — le pertenecen; sus handles quedan liberados. Devuelve `0` una vez aplicado, `-5` cuando `of_add_contextual_group` nunca creó ese grupo, `-2` si el componente no está creado
`of_add_contextual_tab (string as_key, string as_title, string as_group_key)`	Añade una pestaña bajo un grupo contextual: creada oculta, coronada por la banda de color del grupo. Devuelve `0` una vez aplicado, `-5` ante una clave no válida o ya tomada, o un grupo que `of_add_contextual_group` nunca creó, `-2` si el componente no está creado
`il_color` (propiedad)	Sobre un handle de grupo contextual: vuelve a colorear la banda en caliente (`ACCENT_LIGHT` para regresar al color de acento)
`is_title` (propiedad)	Sobre un handle de grupo contextual: cambia el título de la banda en caliente (un cambio de idioma); su color se mantiene. Su información (`is_tooltip`, `is_super_tooltip_*`) aparece cuando el puntero se detiene sobre la banda, y un clic en la banda trae su primera pestaña al frente

Comunes #

Método	Función
`of_reset ( )`	Vacía la cinta de opciones y la devuelve a su estado inicial, propiedades incluidas. Devuelve `0` una vez aplicado, `-2` si el componente no está creado
`of_set_redraw (boolean)`	Agrupa una ráfaga de modificaciones en una única representación. Devuelve `0` una vez aplicado, `-2` si el componente no está creado
`of_preload_icons (string as_icons[])`	Precalienta un lote de iconos al arrancar: una pestaña abierta más tarde muestra los suyos al instante. Devuelve `0` una vez aplicado, `-2` si el componente no está creado
`of_save_as_png (string)` · `of_save_as_jpg (string)`	Exporta la representación como imagen. Devuelve `0` una vez escrita la imagen, `-4` si la escritura falla, `-2` si el componente no está creado

Eventos #

Todos los eventos de control llevan consigo la ruta completa: nunca necesita un identificador único en toda la aplicación.

Evento	Se activa cuando
`ue_clicked (string as_keys)`	El usuario hace clic en un botón, un botón grande, la parte principal de un botón dividido o un botón de la barra de acceso rápido — en la cinta, en el panel de un grupo replegado, o mediante su tecla de acceso rápido. `as_keys` es la dirección `pestaña/grupo/control`, o solo la clave de un botón de acceso rápido
`ue_toggled (string as_keys, boolean ab_checked)`	El usuario alterna un botón de alternancia o una casilla (en la cinta o en el panel de un grupo replegado); `ab_checked` lleva el nuevo estado. Escribir `ib_checked` por código no activa nada. Un conmutador de un grupo de opción (`is_group`) lanza un solo evento, para el que se enciende; los que se sueltan no lanzan nada
`ue_menu_selected (string as_keys, boolean ab_checked)`	El usuario elige una entrada del menú de un botón desplegable o dividido. `as_keys` es su dirección completa: pestaña, grupo, control portador y luego la entrada — un nivel más por cascada. Una entrada marcable cambia primero, y `ab_checked` lleva su nuevo estado. Una entrada atenuada u oculta no se elige. Una entrada de opción (`is_group`) se marca y desmarca las demás de su grupo: `ab_checked` vale entonces `true`
`ue_combo_changed (string as_keys, string as_text)`	El usuario valida el texto de un cuadro combinado: una opción de su lista, Intro en el campo, o la salida del campo tras teclear. Escape abandona lo tecleado sin activar nada; escribir `is_text` por código tampoco activa nada. Un texto escrito por código mientras el campo tiene el foco se muestra de inmediato — salvo si el usuario está tecleando: gana lo tecleado; salir del campo sin teclear no lanza nada
`ue_value_changed (string as_keys, double ad_value)`	El usuario cambia el valor de un contador: sus flechas, Arriba / Abajo en el campo, Intro o la salida del campo tras teclear (Escape lo abandona). `ad_value` es el nuevo valor, limitado al rango del contador. Escribir `id_value` por código no activa nada. Un valor escrito por código mientras el campo tiene el foco se muestra de inmediato — salvo si el usuario está tecleando: gana lo tecleado; salir del campo sin teclear no lanza nada
`ue_color_changed (string as_keys, long al_color)`	El usuario elige un color (paleta o selector), o hace clic en la parte principal de un selector de color para volver a aplicar su color actual; `al_color` es el color PowerBuilder. Escribir `il_color` por código no activa nada
`ue_gallery_selection_changed (string as_from_keys, string as_keys)`	Un mosaico de galería ha sido retenido — por el usuario o por `of_select_gallery_item` (una orden de su código también lo lanza). Mismos argumentos que `ue_gallery_selection_changing`: la pregunta y su resultado se leen igual, y `as_from_keys` es el mosaico abandonado
`ue_gallery_selection_changing (string as_from_keys, string as_keys)` → boolean	Cancelable, se plantea antes de que se retenga el mosaico. Lanzado solo cuando `ib_veto_gallery = true`. `as_from_keys` es el mosaico actual. También se plantea para `of_select_gallery_item`. Devuelva `false` para conservarlo (un estilo que el documento aún no puede adoptar): `of_select_gallery_item` devuelve entonces `-4`
`ue_launcher (string as_keys)`	El usuario hace clic en la flecha de iniciador de un grupo (también desde el panel de un grupo replegado): `as_keys` es la dirección del grupo `pestaña/grupo` — abra su ventana de opciones
`ue_selection_changed (string as_keys)`	Otra pestaña pasa al frente: un clic, la rueda sobre la cinta, una tecla de acceso rápido, o `of_select_tab` (una orden de su código también lo lanza). `as_keys` es la clave de la pestaña — vacía cuando no queda ninguna, después de que la pestaña activa se haya ocultado o retirado
`ue_app_button ( )`	Se hace clic en el botón de aplicación
`ue_app_menu_selected (string as_keys)`	El usuario elige una entrada del menú de aplicación: `as_keys` es su dirección (`saveas/as_pdf`). Una entrada atenuada u oculta no se elige
`ue_item_rclicked (string as_keys, long al_x, long al_y)`	El usuario hace clic derecho en un item: `as_keys` es la dirección del control (`pestaña/grupo/control`), del grupo (`pestaña/grupo`) o de la pestaña, o la clave sola de un botón de la barra de acceso rápido — como las da `ue_clicked`; `al_x`, `al_y`: el punto del clic en píxeles de pantalla (tecla Menú o Mayús+F10: la esquina inferior izquierda del item), donde un `contextmenu` de la biblioteca se abre tal cual. Un solo evento por clic derecho: `ue_rclicked` no se lanza con él. Un control atenuado no lanza nada. Abra ahí su propio menú: Agregar a la barra de acceso rápido, una ayuda sobre el comando
`ue_rclicked ( )`	El usuario hace clic derecho en la cinta fuera de todo item: el extremo vacío de la fila de pestañas, una banda sin nada
`ue_minimized (boolean ab_minimized)`	La cinta se repliega o se despliega: el chevrón al final de la fila de pestañas, un doble clic en una pestaña, o `ib_minimized` asignado por su código (una orden también lo activa); `ue_size_changed` indica la nueva altura en todos los casos
`ue_size_changed (long al_height, boolean ab_minimized)`	La altura de la cinta de opciones ha cambiado por sí sola: replegada, desplegada, una pestaña contextual mostrada, una ventana más estrecha que pierde una fila. A diferencia de `ue_auto_height` — que solo habla cuando el componente se dimensiona a sí mismo — este se dispara con la altura automática activada o no: es información pura, para recolocar lo que hay debajo
`ue_keytips (boolean ab_on, integer ai_level)`	Los keytips aparecen (`true`) o desaparecen (`false`). `ai_level` indica en qué punto está la navegación: `1` = las pestañas están letradas, `2` = lo están los comandos de la pestaña actual, `0` = ya no hay ningún keytip
`ue_auto_height (long al_height)`	La cinta de opciones anuncia su altura ideal y acaba de ajustarse a ella — siempre activo: la altura de una cinta de opciones es intrínseca
`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 #

Una cinta de opciones completa, del menú de aplicación a los grupos #

// event open : se agrupa toda la construccion en una unica representacion

// Congelar el dibujo y nombrar el boton de aplicacion
uo_ribbon.of_set_redraw(/*on*/ false)
uo_ribbon.is_app_button = "Archivo"

// Menu de aplicacion, con una cascada bajo "Guardar como"
uo_ribbon.of_add_app_menu_item(/*keys*/ "new", /*label*/ "Nuevo", /*image*/ "mono:img\new.svg")
uo_ribbon.of_add_app_menu_item(/*keys*/ "open", /*label*/ "Abrir...", /*image*/ "mono:img\open.svg")
uo_ribbon.of_add_app_menu_item(/*keys*/ "save_as", /*label*/ "Guardar como", /*image*/ "mono:img\saveas.svg")
uo_ribbon.of_add_app_menu_item(/*keys*/ "save_as/as_pdf", /*label*/ "Documento PDF", /*image*/ "")
uo_ribbon.of_add_app_menu_item(/*keys*/ "save_as/as_csv", /*label*/ "Archivo CSV", /*image*/ "")
uo_ribbon.of_add_app_menu_separator(/*keys*/ "sep1")
uo_ribbon.of_add_app_menu_item(/*keys*/ "quit", /*label*/ "Salir", /*image*/ "mono:img\exit.svg")

// Barra de acceso rapido, encima de las pestanas
uo_ribbon.of_add_qat(/*key*/ "qat_save", /*image*/ "mono:img\save.svg", /*tooltip*/ "Guardar")
uo_ribbon.of_add_qat(/*key*/ "qat_undo", /*image*/ "mono:img\undo.svg", /*tooltip*/ "Deshacer")

// Pestana Inicio
uo_ribbon.of_add_tab(/*key*/ "home", /*title*/ "Inicio")
uo_ribbon.of_tab(/*key*/ "home").is_keytip = "I"

// Un grupo: un boton dividido con su menu y luego dos botones pequenos
uo_ribbon.of_add_group(/*keys*/ "home/clipboard", /*title*/ "Portapapeles")
uo_ribbon.of_add_big_split(/*keys*/ "home/clipboard/paste", /*label*/ "Pegar", /*image*/ "mono:img\paste.svg")
uo_ribbon.of_add_menu_item(/*keys*/ "home/clipboard/paste/paste_text", /*label*/ "Pegar sin formato", /*image*/ "")
uo_ribbon.of_add_menu_item(/*keys*/ "home/clipboard/paste/paste_link", /*label*/ "Pegar como vínculo", /*image*/ "")
uo_ribbon.of_add_button(/*keys*/ "home/clipboard/cut", /*label*/ "Cortar", /*image*/ "mono:img\cut.svg")
uo_ribbon.of_add_button(/*keys*/ "home/clipboard/copy", /*label*/ "Copiar", /*image*/ "mono:img\copy.svg")
uo_ribbon.of_group(/*keys*/ "home/clipboard").ib_launcher = true       // flecha de opciones abajo a la derecha

// Dibujar todo a la vez y luego mostrar la pestana
uo_ribbon.of_set_redraw(/*on*/ true)
uo_ribbon.of_select_tab(/*key*/ "home")

Un único encaminamiento de los clics #

// event ue_clicked de uo_ribbon : (string as_keys)
// La direccion completa llega con el evento : basta un unico enrutador.
// Dos grupos pueden reutilizar la misma clave : la direccion los distingue.
choose case as_keys
    case "home/clipboard/cut" ; of_cut()
    case "home/clipboard/copy" ; of_copy()
    case "home/clipboard/paste" ; of_paste()
    case "home/font/bold" ; of_toggle_bold()
end choose

Gobernar el estado de los controles según los permisos #

// Siempre a traves de la ruta : pestana > grupo > control
uo_ribbon.of_item(/*keys*/ "home/clipboard/paste").ib_enabled = of_clipboard_has_data()
uo_ribbon.of_item(/*keys*/ "home/tools/brush").ib_checked = true
uo_ribbon.of_tab(/*key*/ "admin").ib_visible = gb_administrator

// Atenuar una entrada DENTRO de un menu desplegable (nivel 4)
uo_ribbon.of_menu_item(/*keys*/ "home/clipboard/paste/paste_link").ib_enabled = false

Conmutadores excluyentes y entradas de opción #

// Los tres conmutadores de alineacion del grupo Parrafo se excluyen
uo_ribbon.of_add_group(/*keys*/ "home/para", /*title*/ "Párrafo")
uo_ribbon.of_add_toggle(/*keys*/ "home/para/left", /*label*/ "Izquierda", /*image*/ "mono:img\align-left.svg")
uo_ribbon.of_add_toggle(/*keys*/ "home/para/center", /*label*/ "Centro", /*image*/ "mono:img\align-center.svg")
uo_ribbon.of_add_toggle(/*keys*/ "home/para/right", /*label*/ "Derecha", /*image*/ "mono:img\align-right.svg")
uo_ribbon.of_item(/*keys*/ "home/para/left").is_group = "align"
uo_ribbon.of_item(/*keys*/ "home/para/center").is_group = "align"
uo_ribbon.of_item(/*keys*/ "home/para/right").is_group = "align"

// El texto empieza alineado a la izquierda : los demas se sueltan solos, en silencio
uo_ribbon.of_item(/*keys*/ "home/para/left").ib_checked = true

// Dos entradas de opcion en el menu del boton Pegar : una a la vez
uo_ribbon.of_menu_item(/*keys*/ "home/clipboard/paste/paste_text").is_group = "paste_mode"
uo_ribbon.of_menu_item(/*keys*/ "home/clipboard/paste/paste_link").is_group = "paste_mode"

Un menú propio con un clic derecho #

// event ue_item_rclicked de uo_ribbon : (string as_keys, long al_x, long al_y)
// Local variables
m_ribbon_context lm_menu

// El comando pulsado se guarda para los Clicked del menu (una variable de instancia)
is_rclicked_keys = as_keys

// Su menu, en el puntero : Agregar a la barra de acceso rapido, Ayuda
lm_menu = create m_ribbon_context
lm_menu.m_main.PopMenu(parent.PointerX(), parent.PointerY())
destroy lm_menu

Pestañas contextuales con banda #

El principio de Office: pestañas que solo aparecen cuando la selección las justifica, coronadas por una banda con título y color.

// event open : se prepara el grupo contextual, oculto de forma predeterminada

// Sin color, la banda sigue el acento del tema ; RGB(...) para imponerlo
uo_ribbon.of_add_contextual_group(/*key*/ "img", /*title*/ "Herramientas de imagen", &
                                           /*color*/ RGB(/*red*/ 224, /*green*/ 32, /*blue*/ 96))
uo_ribbon.of_add_contextual_tab(/*key*/ "format", /*title*/ "Formato", /*group_key*/ "img")
uo_ribbon.of_add_group(/*keys*/ "format/adjust", /*title*/ "Ajustar")
uo_ribbon.of_add_big_button(/*keys*/ "format/adjust/crop", /*label*/ "Recortar", /*image*/ "mono:img\crop.svg")
uo_ribbon.of_add_button(/*keys*/ "format/adjust/rotate", /*label*/ "Girar", /*image*/ "mono:img\rotate.svg")

// Al seleccionar una imagen : se revela la pestana y se activa
uo_ribbon.of_tab(/*key*/ "format").ib_visible = true
uo_ribbon.of_select_tab(/*key*/ "format")

// Al deseleccionar : se oculta, la banda desaparece con ella
uo_ribbon.of_tab(/*key*/ "format").ib_visible = false

Cuadro combinado, control de número, selector de color y galería #


// Un nuevo grupo en la pestana
uo_ribbon.of_add_group(/*keys*/ "home/font", /*title*/ "Fuente")

// Cuadro combinado editable : se llena a traves de su handle
uo_ribbon.of_add_combo(/*keys*/ "home/font/font_name", /*width_px*/ 140, /*editable*/ true)
uo_ribbon.of_add_combo_item(/*keys*/ "home/font/font_name", /*label*/ "Segoe UI")
uo_ribbon.of_add_combo_item(/*keys*/ "home/font/font_name", /*label*/ "Arial")
uo_ribbon.of_add_combo_item(/*keys*/ "home/font/font_name", /*label*/ "Calibri")
uo_ribbon.of_item(/*keys*/ "home/font/font_name").is_text = "Segoe UI"

// Control de numero : minimo, maximo, paso, valor inicial
uo_ribbon.of_add_spinner(/*keys*/ "home/font/size", /*width_px*/ 70, /*min*/ 6, /*max*/ 96, &
                          /*step*/ 1, /*value*/ 11)

// Selector de color en modo paleta completa (con Aceptar / Cancelar)
uo_ribbon.of_add_colorpicker(/*keys*/ "home/font/color", /*label*/ "Color", &
                              /*image*/ "mono:img\font-color.svg", &
                              /*color*/ RGB(/*red*/ 0, /*green*/ 0, /*blue*/ 0), &
                              /*mode*/ u_pbt_ribbon.COLORMODE_OPEN)

// Galeria de estilos : mosaicos ilustrados desplazables
uo_ribbon.of_add_gallery(/*keys*/ "home/font/styles", /*width_px*/ 220, &
                                     /*tile_w*/ 64, /*tile_h*/ 48)
uo_ribbon.of_add_gallery_item(/*keys*/ "home/font/styles/st_normal", /*image*/ "img\style-normal.png", /*label*/ "Normal")
uo_ribbon.of_add_gallery_item(/*keys*/ "home/font/styles/st_title",  /*image*/ "img\style-titre.png",  /*label*/ "Título")
uo_ribbon.of_add_gallery_item(/*keys*/ "home/font/styles/st_note",   /*image*/ "img\style-note.png",   /*label*/ "Nota")
uo_ribbon.of_add_gallery_item(/*keys*/ "home/font/styles/st_code",   /*image*/ "img\style-code.png",   /*label*/ "Código")

// La banda plegada muestra 4 miniaturas a la vez ; las demas siguen siendo
// accesibles mediante las flechas, o en la cuadricula desplegada.
uo_ribbon.of_item(/*keys*/ "home/font/styles").ii_visible_items = 4

// El estilo seleccionado al inicio
uo_ribbon.of_select_gallery_item(/*keys*/ "home/font/styles/st_normal")

// event ue_value_changed de uo_ribbon : (string as_keys, double ad_value)
// Local variables
n_pbt_utils lnv_utils   // autoinstantiate : nada que crear, nada que destruir

// El ultimo nivel de la direccion nombra el control que se movio
if lnv_utils.of_leaf(/*keys*/ as_keys) = "size" then of_apply_size(ad_value)

El rango y el paso de un control de número se cambian después mediante id_min, id_max e id_step de su handle: el valor se devuelve de inmediato al nuevo rango, sin activar ue_value_changed. Su imagen, como la de cualquier control, se cambia con is_image.

// El tamano maximo depende de la fuente elegida : 96, luego 400 en pasos de 2
uo_ribbon.of_item(/*keys*/ "home/font/size").id_max = 400
uo_ribbon.of_item(/*keys*/ "home/font/size").id_step = 2

// event ue_color_changed de uo_ribbon : (string as_keys, long al_color)
// Local variables
n_pbt_utils lnv_utils   // autoinstantiate : nada que crear, nada que destruir

// El ultimo nivel de la direccion nombra el selector de color que cambio
if lnv_utils.of_leaf(/*keys*/ as_keys) = "color" then of_apply_color(al_color)

Rechazar la elección de una miniatura de galería #

// La pregunta solo se plantea a peticion: esta linea la activa, y
// ue_gallery_selection_changing decide entonces cada mosaico.
uo_ribbon.ib_veto_gallery = true

// event ue_gallery_selection_changing de uo_ribbon :
//   (string as_from_keys, string as_keys)
// Local variables
n_pbt_utils lnv_utils   // autoinstantiate : nada que crear, nada que destruir

// Devolver FALSE conserva la miniatura actual (as_from_keys).
if lnv_utils.of_leaf(/*keys*/ as_keys) = "st_code" and not of_document_supports_code() then
    MessageBox("Estilo", "Este documento no puede adoptar el estilo Código.")
    return false
end if
return true

El iniciador del cuadro de diálogo #

// La pequena flecha en la parte inferior derecha del grupo
uo_ribbon.of_group(/*keys*/ "home/font").ib_launcher = true

// event ue_launcher de uo_ribbon : (string as_keys)
// Local variables
n_pbt_utils lnv_utils   // autoinstantiate : nada que crear, nada que destruir

// La ruta identifica el grupo : se abre la ventana de opciones correspondiente.
choose case lnv_utils.of_leaf(/*keys*/ as_keys)
    case "font"        ; open(w_font_options)
    case "clipboard" ; open(w_paste_options)
end choose

Keytips: gobernar la cinta de opciones con el teclado #

// Alt muestra las letras ; Alt luego I luego C activa "copy"
uo_ribbon.of_tab(/*key*/ "home").is_keytip = "I"
uo_ribbon.of_item(/*keys*/ "home/clipboard/copy").is_keytip = "C"
uo_ribbon.of_item(/*keys*/ "home/clipboard/cut").is_keytip = "X"

Una pulsación de Alt esté donde esté el foco dentro de la ventana cede el mando a la cinta de opciones: toma el foco del teclado y muestra sus letras. No tiene nada que programar, basta con que haya al menos un keytip declarado. Esc, un segundo Alt o la elección de un comando devuelven el foco al control que el usuario había abandonado. Una tecla puede tener varias letras ("FP", como en Office): el usuario las teclea una tras otra, las insignias que ya no empiezan por lo tecleado se apartan, y Retroceso las devuelve. Un control de un grupo replegado conserva su tecla: abre el panel del grupo. Esc sube un nivel, como en Office: de los comandos de una pestaña a las pestañas, y luego fuera. Los botones de la barra de acceso rápido reciben su letra con las pestañas (of_qat_item(clave).is_keytip).

ue_keytips le avisa en cada cambio de estado y le facilita el nivel actual:

// event ue_keytips de uo_ribbon : (boolean ab_on, integer ai_level)
// El teclado gobierna la cinta: borrar la ayuda de la barra de estado, que habla
// del raton, y restablecerla cuando las letras desaparezcan.
if ab_on then
    uo_statusbar.of_item(/*keys*/ "main").is_text = "Escriba una letra (nivel " + String(ai_level) + ")"
else
    uo_statusbar.of_item(/*keys*/ "main").is_text = ""
end if

Tooltips enriquecidos en un control #

// Local variables
n_pbt_ribbon_item lnv_item

// El super tooltip del boton Pegar: un titulo, un texto, una imagen
lnv_item = uo_ribbon.of_item(/*keys*/ "home/clipboard/paste")
lnv_item.is_super_tooltip_title = "Pegar (Ctrl+V)"
lnv_item.is_super_tooltip_text  = "Inserta el contenido del portapapeles." &
                                + "[br][br][size-=15]Use la flecha para pegar sin formato.[/size-=15]"
lnv_item.is_super_tooltip_image = "img\paste.png"

Estas cuatro propiedades son exactamente las mismas que en cualquier otro item de la biblioteca. Para un tooltip de una sola línea basta is_tooltip.

Altura automática #

La cinta de opciones se dimensiona sola: no hay nada que activar. Le avisa en cada cambio de altura (repliegue, pestaña contextual, cambio de tema) para que usted recoloque lo que hay debajo.

// event ue_auto_height de uo_ribbon : (long al_height)
// La cinta de opciones ya se ha redimensionado : se recoloca lo que hay debajo.
uo_content.y      = uo_ribbon.y + uo_ribbon.height
uo_content.height = this.height - uo_content.y

Replegar la cinta de opciones para ganar espacio #

// Start with the ribbon folded: only the tab headers show
uo_ribbon.ib_minimized = true

// event ue_minimized de uo_ribbon : (boolean ab_minimized)
// Se memoriza la preferencia del usuario para la proxima apertura.
of_save_preference("ribbon_collapsed", ab_minimized)

Partir de una cinta de opciones vacía #

// of_reset vacia pestanas, grupos, controles, barra de acceso rapido y menu
uo_ribbon.of_reset()
uo_ribbon.of_add_tab(/*key*/ "home", /*title*/ "Inicio")

Desde un menú PowerBuilder existente #

Una aplicación PowerBuilder ya ha descrito sus comandos una vez: en su menú. Etiquetas, atajos, imágenes, separadores, submenús, informaciones sobre herramientas — está todo. n_pbt_menu2ribbon vuelve a leer ese menú mediante RTTI y escribe el PowerScript que construye la cinta correspondiente.

// Una sola vez, a mano : el generador ESCRIBE codigo, no se ejecuta en
// produccion. Pegue su resultado en el open de su ventana.
// Local variables
n_pbt_menu2ribbon lnv_gen
string ls_code

// Generar el codigo a partir del menu
lnv_gen = create n_pbt_menu2ribbon
ls_code = lnv_gen.of_generate(/*menu*/ m_principal, /*ribbon_var*/ "uo_ribbon")
destroy lnv_gen

// Copiarlo, listo para pegar
ClipBoard(ls_code)

La conversión es determinista: sin IA, sin llamadas de red, nada que salga del equipo. Cada clave generada es el ClassName del elemento de menú (m_fichier, m_ouvrir): la dirección que la cinta devuelve (m_fichier/g1/m_ouvrir) lleva por tanto de vuelta al elemento, y el enrutador escrito al final del código dispara su Clicked desde ue_clicked, ue_toggled y ue_menu_selected - su código existente se ejecuta tal cual. Los submenús se retoman a cualquier profundidad, un elemento oculto se descarta, uno atenuado sigue atenuado, uno marcado se convierte en un conmutador o en una entrada marcable que empieza marcada.

El código producido es un punto de partida que hay que revisar, no un entregable: un menú es una lista, una cinta es una maquetación. Agrupe, elija sus botones grandes, quite lo que no merece estar siempre a la vista. El ejemplo 9 de la página de la cinta en la aplicación de demostración muestra un resultado completo.

Buenas prácticas #

Encuadre toda la construcción entre of_set_redraw(false) y of_set_redraw(true): una cinta de opciones completa se dibuja así de una sola vez, sin parpadeos.
Cada adición devuelve un código: 0, o -5 para una dirección errónea, un padre de la naturaleza equivocada o una clave ya ocupada. Compruébelo donde un error de construcción le importe; para gobernar un control después, of_item(dirección) devuelve su handle.
Llame a of_preload_icons al arrancar: sin ello, la primera visualización de una pestaña nunca abierta muestra un breve retardo antes de sus iconos.
Un identificador solo tiene que ser único dentro de su grupo. Aprovéchelo para dar a sus controles nombres sencillos (copy, paste) en lugar de recurrir a prefijos.
Reserve las pestañas contextuales para los comandos que no tienen ningún sentido fuera de contexto: una pestaña permanente atenuada es más descansada que una pestaña que aparece y desaparece.
La pregunta antes de un mosaico está inactiva de forma predeterminada: actívela con ib_veto_gallery = true solo si ue_gallery_selection_changing debe poder rechazar, porque cada pregunta cuesta una ida y vuelta hasta PowerBuilder.
Un solo iniciador de cuadro de diálogo por grupo, y solo si el grupo tiene realmente opciones avanzadas que ofrecer.
Para reconstruir una cinta de opciones entera, prefiera of_clear() (o of_reset()) a una serie de of_remove_tab: un solo comando, y todos los handles entregados se liberan de una vez.
Para una barra de comandos más ligera, sin pestañas ni grupos, vea toolbar; para una navegación lateral, listbar.

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

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.