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 #

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 handle del elemento padre.

// Leer o gobernar un control : siempre la ruta completa
uo_ruban.of_tab("accueil").of_group("presse_papier").of_item("coller").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
n_pbt_ribbon_tab   lnv_onglet
n_pbt_ribbon_group lnv_groupe

lnv_onglet = uo_ruban.of_add_tab("accueil", "Inicio")

lnv_groupe = lnv_onglet.of_add_group("presse_papier", "Portapapeles")
lnv_groupe.of_add_big_button("coller", "Pegar", "mono:img\paste.svg")
lnv_groupe.of_add_button("couper", "Cortar", "mono:img\cut.svg")
lnv_groupe.of_add_button("copier", "Copiar", "mono:img\copy.svg")

uo_ruban.of_select_tab("accueil")

// event ue_clicked de uo_ruban : (string as_tab, string as_group, string as_id)
choose case as_id
    case "coller" ; of_coller()
    case "couper" ; of_couper()
    case "copier" ; of_copier()
end choose

Propiedades #

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(id), se modifican en caliente.

Propiedades de un grupo — n_pbt_ribbon_group #

Obtenidas mediante of_tab(id).of_group(id).

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_tab(id).of_group(id).of_item(id). Se aplican a todos los tipos de controles; las propiedades que no vienen al caso para un tipo dado simplemente se ignoran.

Propiedades de una entrada de menú — n_pbt_ribbon_menu_item #

Obtenidas mediante of_tab(id).of_group(id).of_item(id).of_menu_item(id).

Los doce tipos de controles #

Todos se añaden sobre el handle de un grupo y devuelven el handle del control creado — por lo tanto, puede encadenar acto seguido el llenado de un menú o de una lista.

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 #

Llenar los menús y las listas #

Todos estos métodos se invocan sobre el handle de un control.

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

Pestañas contextuales #

Comunes #

Eventos #

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

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
n_pbt_ribbon_tab   lnv_onglet
n_pbt_ribbon_group lnv_groupe
n_pbt_ribbon_item  lnv_item

uo_ruban.of_set_redraw(false)
uo_ruban.is_app_button = "Archivo"

// Menu de aplicacion, con una cascada bajo "Guardar como"
uo_ruban.of_add_app_menu_item(/*id*/ "nouveau", /*etiqueta*/ "Nuevo", /*imagen*/ "mono:img\new.svg")
uo_ruban.of_add_app_menu_item("ouvrir", "Abrir...", "mono:img\open.svg")
uo_ruban.of_add_app_menu_item("enr_sous", "Guardar como", "mono:img\saveas.svg")
uo_ruban.of_add_app_menu_item(/*parent*/ "enr_sous", /*id*/ "sous_pdf", "Documento PDF", "")
uo_ruban.of_add_app_menu_item(/*parent*/ "enr_sous", /*id*/ "sous_csv", "Archivo CSV", "")
uo_ruban.of_add_app_menu_separator("sep1")
uo_ruban.of_add_app_menu_item("quitter", "Salir", "mono:img\exit.svg")

// Barra de acceso rapido, encima de las pestanas
uo_ruban.of_add_qat(/*id*/ "qat_enr", /*imagen*/ "mono:img\save.svg", /*tooltip*/ "Guardar")
uo_ruban.of_add_qat("qat_annuler", "mono:img\undo.svg", "Deshacer")

// Pestana Inicio
lnv_onglet = uo_ruban.of_add_tab("accueil", "Inicio")
lnv_onglet.is_keytip = "I"

lnv_groupe = lnv_onglet.of_add_group("presse_papier", "Portapapeles")
lnv_item = lnv_groupe.of_add_big_split("coller", "Pegar", "mono:img\paste.svg")
lnv_item.of_add_menu_item("coller_texte", "Pegar sin formato", "")
lnv_item.of_add_menu_item("coller_lien", "Pegar como vínculo", "")
lnv_groupe.of_add_button("couper", "Cortar", "mono:img\cut.svg")
lnv_groupe.of_add_button("copier", "Copiar", "mono:img\copy.svg")
lnv_groupe.ib_launcher = true       // flecha de opciones abajo a la derecha

uo_ruban.of_set_redraw(true)
uo_ruban.of_select_tab("accueil")

Un único encaminamiento de los clics #

// event ue_clicked de uo_ruban : (string as_tab, string as_group, string as_id)
// La ruta completa llega con el evento : basta un solo encaminamiento,
// y dos grupos pueden reutilizar el mismo identificador sin estorbarse.
choose case as_group + "/" + as_id
    case "presse_papier/couper" ; of_couper()
    case "presse_papier/copier" ; of_copier()
    case "presse_papier/coller" ; of_coller()
    case "police/gras"          ; of_basculer_gras()
end choose

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

// Siempre a traves de la ruta : pestana > grupo > control
uo_ruban.of_tab("accueil").of_group("presse_papier").of_item("coller").ib_enabled = of_presse_papier_non_vide()
uo_ruban.of_tab("accueil").of_group("outils").of_item("pinceau").ib_checked = true
uo_ruban.of_tab("admin").ib_visible = gb_administrateur

// Atenuar una entrada DENTRO de un menu desplegable (nivel 4)
uo_ruban.of_tab("accueil").of_group("presse_papier").of_item("coller") &
        .of_menu_item("coller_lien").ib_enabled = false

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
n_pbt_ribbon_ctx_group lnv_ctx
n_pbt_ribbon_tab       lnv_onglet
n_pbt_ribbon_group     lnv_groupe

// Sin color, la banda sigue el acento del tema ; RGB(...) para imponerlo
lnv_ctx = uo_ruban.of_add_contextual_group(/*id*/ "img", /*titulo*/ "Herramientas de imagen", &
                                           /*color*/ RGB(224, 32, 96))
lnv_onglet = lnv_ctx.of_add_tab("format", "Formato")
lnv_groupe = lnv_onglet.of_add_group("ajuster", "Ajustar")
lnv_groupe.of_add_big_button("rogner", "Recortar", "mono:img\crop.svg")
lnv_groupe.of_add_button("pivoter", "Girar", "mono:img\rotate.svg")

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

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

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

n_pbt_ribbon_group lnv_groupe
n_pbt_ribbon_item  lnv_item

lnv_groupe = uo_ruban.of_tab("accueil").of_add_group("police", "Fuente")

// Cuadro combinado editable : se llena a traves de su handle
lnv_item = lnv_groupe.of_add_combo(/*id*/ "nom_police", /*ancho_px*/ 140, /*editable*/ true)
lnv_item.of_add_combo_item("Segoe UI")
lnv_item.of_add_combo_item("Arial")
lnv_item.of_add_combo_item("Calibri")
lnv_item.is_text = "Segoe UI"

// Control de numero : minimo, maximo, paso, valor inicial
lnv_groupe.of_add_spinner(/*id*/ "taille", /*ancho_px*/ 70, /*minimo*/ 6, /*maximo*/ 96, &
                          /*paso*/ 1, /*valor*/ 11)

// Selector de color en modo paleta completa (con Aceptar / Cancelar)
lnv_groupe.of_add_colorpicker(/*id*/ "couleur", /*etiqueta*/ "Color", &
                              /*imagen*/ "mono:img\font-color.svg", &
                              /*color*/ RGB(0, 0, 0), &
                              /*modo*/ lnv_groupe.COLORMODE_OPEN)

// Galeria de estilos : mosaicos ilustrados desplazables
lnv_item = lnv_groupe.of_add_gallery(/*id*/ "styles", /*ancho_px*/ 220, &
                                     /*ancho_mosaico*/ 64, /*alto_mosaico*/ 48)
lnv_item.of_add_gallery_item("st_normal", "img\style-normal.png", "Normal")
lnv_item.of_add_gallery_item("st_titre",  "img\style-titre.png",  "Título")
lnv_item.of_add_gallery_item("st_note",   "img\style-note.png",   "Nota")
lnv_item.of_add_gallery_item("st_code",   "img\style-code.png",   "Código")

// La banda plegada muestra 4 miniaturas a la vez ; las demas siguen siendo
// accesibles mediante las flechas, o en la cuadricula desplegada.
lnv_item.ii_visible_items = 4

lnv_item.of_select_item("st_normal")

// event ue_value_changed de uo_ruban : (string as_tab, string as_group, string as_id, double ad_value)
if as_id = "taille" then of_appliquer_taille(ad_value)

// event ue_color_changed de uo_ruban : (string as_tab, string as_group, string as_id, long al_color)
if as_id = "couleur" then of_appliquer_couleur(al_color)

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

// La pregunta se plantea de forma PREDETERMINADA: nada que activar. Esta linea
// hace lo contrario, la suprime cuando arbitrar no sirve.
uo_ruban.ib_veto_gallery = false

// event ue_gallery_selection_changing de uo_ruban :
//   (string as_tab, string as_group, string as_id, string as_from_item, string as_item)
// Devolver FALSE conserva la miniatura actual (as_from_item).
if as_item = "st_code" and not of_document_supporte_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_ruban.of_tab("accueil").of_group("police").ib_launcher = true

// event ue_launcher de uo_ruban : (string as_tab, string as_group)
// La ruta identifica el grupo : se abre la ventana de opciones correspondiente.
choose case as_group
    case "police"        ; open(w_options_police)
    case "presse_papier" ; open(w_options_collage)
end choose

Keytips: gobernar la cinta de opciones con el teclado #

// Alt muestra las letras ; Alt luego I luego C activa "copier"
uo_ruban.of_tab("accueil").is_keytip = "I"
uo_ruban.of_tab("accueil").of_group("presse_papier").of_item("copier").is_keytip = "C"
uo_ruban.of_tab("accueil").of_group("presse_papier").of_item("couper").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.

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

// event ue_keytips de uo_ruban : (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_statut.of_item("main").is_text = "Escriba una letra (nivel " + String(ai_level) + ")"
else
    uo_statut.of_item("main").is_text = ""
end if

Tooltips enriquecidos en un control #

n_pbt_ribbon_item lnv_item

lnv_item = uo_ruban.of_tab("accueil").of_group("presse_papier").of_item("coller")
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_ruban : (long al_height)
// La cinta de opciones ya se ha redimensionado : se recoloca lo que hay debajo.
uo_contenu.y      = uo_ruban.y + uo_ruban.height
uo_contenu.height = this.height - uo_contenu.y

Replegar la cinta de opciones para ganar espacio #

uo_ruban.ib_minimized = true

// event ue_minimized de uo_ruban : (boolean ab_minimized)
// Se memoriza la preferencia del usuario para la proxima apertura.
of_enregistrer_preference("ruban_replie", ab_minimized)

Partir de una cinta de opciones vacía #

// of_reset vacia pestanas, grupos, controles, barra de acceso rapido y menu
uo_ruban.of_reset()
uo_ruban.of_add_tab("accueil", "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.
n_pbt_menu2ribbon lnv_gen
string ls_code

lnv_gen = create n_pbt_menu2ribbon
ls_code = lnv_gen.of_generate(/*menu*/ m_principal, /*variable*/ "uo_ruban")
destroy lnv_gen

ClipBoard(ls_code)

La conversión es determinista: sin IA, sin llamadas de red, nada que salga del equipo. Y los identificadores generados conservan la ruta del menú (m_principal.m_fichier.m_ouvrir), de modo que el choose case de sus acciones existentes funciona tal cual desde ue_clicked.

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.
• Conserve los handles devueltos (n_pbt_ribbon_tab, n_pbt_ribbon_group, n_pbt_ribbon_item) en variables locales durante el tiempo de la construcción: el código queda corto y legible. Para gobernar un control más tarde, vuelva a pasar simplemente por la ruta.
• 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 (copier, coller) 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 se plantea de forma predeterminada: un ue_gallery_selection_changing dejado vacío autoriza siempre la elección, no tiene nada que hacer. Desactívela con ib_veto_gallery = false si arbitrar no le sirve, 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: sin ello, reutilizar un identificador de pestaña falla.
• Para una barra de comandos más ligera, sin pestañas ni grupos, vea toolbar; para una navegación lateral, listbar.

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