contextmenu — u_pbt_contextmenu #

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

El menú contextual de Windows, con el tema de la aplicación: una lista en cascada que se abre en el cursor, bajo un control o en un punto de la pantalla — iconos, atajos mostrados, marcas de verificación, entradas de opción, encabezados de sección, listas largas que se desplazan y responden al tecleo.

▶ Verlo en vivo — Aplicación de demostración, mosaico Context menu: la vista previa, el código que lo produce y esta página, lado a lado.

En resumen #

Inicio rápido #

// The menu of a grid : three commands, a separator, a cascade
uo_menu.of_add_item(/*keys*/ "copy", /*text*/ "&Copy")
uo_menu.of_add_item(/*keys*/ "paste", /*text*/ "&Paste")
uo_menu.of_add_item(/*keys*/ "delete", /*text*/ "&Delete")
uo_menu.of_add_separator(/*keys*/ "")
uo_menu.of_add_item(/*keys*/ "export", /*text*/ "&Export")
uo_menu.of_add_item(/*keys*/ "export/pdf", /*text*/ "PDF")
uo_menu.of_add_item(/*keys*/ "export/csv", /*text*/ "CSV")

// It opens from the right-click event of the grid : see Where to call of_show

// event ue_item_selected of uo_menu : (string as_keys)
// as_keys is the ADDRESS of the chosen entry
choose case as_keys
	case "copy"
		of_copy_selection()
	case "export/pdf"
		of_export("pdf")
end choose

Abrir el menú #

El componente en sí es invisible: no ocupa espacio en la ventana. Colóquelo en cualquier sitio, con anchura y altura nulas — solo existe mientras el menú está abierto. Cuatro maneras de abrirlo:

• of_show() — en el cursor, desde el clic derecho del control que recibe el gesto — vea la tabla más abajo.
• of_show_under(control) — bajo un control: el menú cuelga de su borde inferior, alineado con su borde de inicio (su borde derecho en una disposición de derecha a izquierda), y se abre por encima cuando la pantalla se acaba debajo. Lo que necesita un botón Más o … — y el teclado: of_show_under(control, true) resalta la primera entrada activa.
• of_show(x, y) — en un punto de la pantalla, en píxeles. Unas coordenadas negativas son un punto real: una pantalla situada a la izquierda o por encima de la principal.
• of_show_at(control, x, y) — en un punto dentro de un control, en unidades PowerBuilder desde su esquina superior izquierda: el punto que tomaba PopMenu, nada que convertir. of_source() nombra luego ese control en ue_item_selected — un solo menú para varios controles.

// event rbuttondown of a DataWindow : the row under the cursor first
if row > 0 then dw_list.SetRow(/*row*/ row)
uo_menu.of_show()

// event ue_clicked of a "More" button : the menu hangs from it
uo_menu.of_show_under(/*control*/ uo_more)

// event rbuttondown of a DataWindow, another way : the point in the control, in
// PowerBuilder units, as PopMenu took it
uo_menu.of_show_at(/*control*/ dw_list, /*x*/ dw_list.PointerX(), /*y*/ dw_list.PointerY())

Dónde llamar a of_show #

of_show() se abre donde está el cursor, es decir, donde el usuario pulsó: ninguna unidad que convertir. of_show(x, y) espera píxeles de pantalla, nunca las unidades PowerBuilder de un xpos/ypos relativo al control. Para un punto dentro de un control, en unidades PowerBuilder, está of_show_at(control, x, y).

Con el teclado — Mayús+F10 o la tecla Menú — el ratón está en cualquier parte: abra el menú bajo el control que tiene el foco, con of_show_under(control, true). Como en Windows, su primera entrada activa queda resaltada: Intro la elige, las flechas parten de ahí. Con PowerBuilder 10, pbm_contextmenu solo recibe el clic derecho, y Mayús+F10 no llega a un campo de entrada (medido: ni pbm_contextmenu, ni pbm_keydown, ni pbm_syskeydown). La tecla que abre el menú en un control PowerBuilder es pues la tecla Menú (KeyApps!), tomada en un evento de usuario en pbm_keydown — pbm_dwnkey para un DataWindow, cuyo clic derecho pasa por su evento rbuttondown: pbm_contextmenu no llega ahí con un clic en una celda (medido). Mayús+F10 lo siguen recibiendo los propios componentes PBToolboxAI (su ue_rclicked).

// User event ue_contextmenu of an edit field, mapped on pbm_contextmenu :
// the right-click opens the menu at the cursor
uo_menu.of_show()

// The field does not open its own Windows menu as well
return 1

// User event ue_key of the same field, mapped on pbm_keydown : the Menu key
// opens the menu under the field, its first entry highlighted
if key = KeyApps! then
	uo_menu.of_show_under(/*control*/ this, /*keyboard*/ true)
	return 1
end if

// User event ue_key of a DataWindow, mapped on pbm_dwnkey : the Menu key
if key = KeyApps! then
	uo_menu.of_show_under(/*control*/ this, /*keyboard*/ true)
	return 1
end if

Una sola respuesta por apertura: un menú abierto termina con una elección (ue_item_selected) o sin ella (ue_dismissed — un clic fuera, Esc, of_close). Un menú que no tiene nada que mostrar no se abre: ue_dismissed llega enseguida. Mientras el menú está en pantalla la aplicación sigue funcionando: una entrada atenuada, oculta o eliminada entretanto ya no puede elegirse (ue_dismissed en su lugar), y of_remove_item, of_clear u of_reset cierran el menú abierto. ue_dismissed(as_reason) dice por qué: REASON_ESCAPE (Esc), REASON_OUTSIDE (un clic fuera), REASON_FOCUS (otra ventana tomó el foco), REASON_USER (de otra manera, otro menú que toma su lugar), REASON_CODE (of_close, una entrada eliminada o el menú vaciado), REASON_REPLACED (un segundo of_show), REASON_EMPTY (nada que mostrar), REASON_UNAVAILABLE (la entrada elegida ya no estaba disponible).

Un menú cada vez: un segundo of_show sustituye al menú abierto, que responde primero ue_dismissed. Y of_close llamado justo después de of_show cierra el menú antes incluso de que se dibuje — también sigue ue_dismissed.

Con el teclado, las flechas recorren las entradas saltando las atenuadas, → abre una cascada y ← la cierra, Intro elige, Esc sube un nivel y luego cierra. La letra subrayada — la que sigue a & en la etiqueta, && para un ampersand — elige la entrada directamente; si no, teclear las primeras letras de una etiqueta lleva a esa entrada, espacios incluidos («report 2»). Una lista larga (quinientas entradas y más) se desplaza y sigue fluida. Leído de derecha a izquierda, el menú se alinea a la derecha y las cascadas se abren hacia la izquierda.

Cascadas, secciones y marcas #

Una entrada se designa por su dirección: su clave sola en el primer nivel (copy), las claves de sus padres y luego la suya, unidas por /, en una cascada (export/pdf). El padre debe existir; una clave no contiene ni / ni | y no empieza por __. ue_item_selected devuelve esa misma dirección: dos cascadas pueden nombrar igual sus entradas.

Un separador (of_add_separator) y un encabezado de sección (of_add_header) se colocan al final del menú (dirección vacía) o de la cascada de una entrada. Ninguno de los dos es una entrada: nunca elegidos, nunca contados. Un separador nunca se muestra al principio, al final ni duplicado; un encabezado cuyas entradas están todas ocultas desaparece con ellas.

Una marca de verificación (ib_checked) dice que una opción está activa; una entrada de opción (is_group) es una elección entre varias: las entradas de un mismo grupo bajo el mismo padre se excluyen — marcar una, por código o por la elección del usuario, desmarca las demás, y una viñeta redonda sustituye a la marca. El atajo (is_shortcut) se muestra a la derecha de la entrada; solo se muestra: la tecla pertenece al control del que habla el menú (un campo de entrada ya copia con Ctrl+C), y un menú contextual que la armara se la quitaría a todos los controles de la ventana.

Una entrada marcada fuera de un grupo no cambia sola cuando el usuario la elige — como en todo menú de Windows: cámbiela en ue_item_selected. Un comando que destruye se distingue por su tono: is_tone = TONE_DANGER escribe su texto en el rojo del tema, legible en claro como en oscuro. Para que una opción cambie sola al elegirla, ponga ib_auto_check = true: la marca cambia antes de ue_item_selected. Una opción es una casilla de verificación — anunciada «no activada» por un lector de pantalla — en cuanto se ha marcado una vez, o en cuanto ib_checkable = true.

// A section of three exclusive entries in the View cascade
uo_menu.of_add_header(/*keys*/ "view", /*text*/ "Layout")
uo_menu.of_add_item(/*keys*/ "view/list", /*text*/ "&List")
uo_menu.of_add_item(/*keys*/ "view/details", /*text*/ "&Details")
uo_menu.of_item(/*keys*/ "view/list").is_group = "layout"
uo_menu.of_item(/*keys*/ "view/details").is_group = "layout"

// Checking one unchecks the other
uo_menu.of_item(/*keys*/ "view/details").ib_checked = true

// The shortcut SHOWN at the right of an entry
uo_menu.of_item(/*keys*/ "copy").is_shortcut = "Ctrl+C"

// A command that destroys : the red of the theme
uo_menu.of_item(/*keys*/ "delete").is_tone = uo_menu.TONE_DANGER

// event ue_item_selected : a check mark outside a group is switched by you
if as_keys = "wrap" then uo_menu.of_item(/*keys*/ as_keys).ib_checked = not uo_menu.of_item(/*keys*/ as_keys).ib_checked

// ... or by the entry itself, before ue_item_selected
uo_menu.of_item(/*keys*/ "grid").ib_auto_check = true

Reutilizar un menú PowerBuilder #

¿Sus menús emergentes ya están escritos? of_load_menu los convierte en el menú del componente: pase el elemento sobre el que llamaba a PopMenu. Cada elemento se convierte en una entrada, cascadas incluidas, con su texto (& incluido), su estado (Enabled, Checked, Visible), su Shortcut mostrado a la derecha — como el texto tras una tabulación — y su imagen de barra de herramientas cuando es un archivo presente. Su clave es el ClassName del elemento, en cada nivel. Al elegir, el script Clicked del elemento se ejecuta primero, luego ue_item_selected: el código escrito para PopMenu sigue sirviendo. El menú sigue vivo, como con PopMenu: cada apertura vuelve a leer los elementos (Text, Enabled, Checked, Visible, Shortcut). El código que precedía a PopMenu — m_paste.Enabled = (Clipboard() <> "") — y un Clicked que hace this.Checked = not this.Checked se ven por tanto en la apertura siguiente; un elemento atenuado u oculto mientras el menú está abierto no ejecuta su Clicked (ue_dismissed(REASON_UNAVAILABLE)). Mantenga vivo el objeto menú mientras el componente lo use. of_loaded_item devuelve el elemento de una entrada, para leer lo que solo el menú sabe (su MicroHelp) — compruébelo con IsValid, una entrada añadida a mano no tiene. Un script Clicked que lee ParentWindow encuentra en él una ventana válida — medido con PowerBuilder 10, incluso para un menú creado con create y nunca asociado a una ventana —, pero es PowerBuilder quien la elige: nada garantiza que sea la ventana que lleva el menú contextual. Para que un Clicked alcance una ventana concreta, désela al menú en una variable de instancia, asignada antes de of_load_menu, o lleve ese código a ue_item_selected.

// Instance variable of the window : the menu lives as long as it does
// m_popup im_popup

// open event of the window : the items of m_popup.m_edit become the menu
im_popup = create m_popup
uo_menu.of_load_menu(/*menu*/ im_popup.m_edit)

// event rbuttondown of the DataWindow : the code before PopMenu stays,
// of_show replaces PopMenu - the items are read again as it opens
im_popup.m_edit.m_paste.Enabled = (Clipboard() <> "")
uo_menu.of_show()

// event ue_item_hover of uo_menu (ib_track_hover = true) : the MicroHelp
if IsValid(uo_menu.of_loaded_item(/*keys*/ as_keys)) then st_help.text = uo_menu.of_loaded_item(/*keys*/ as_keys).MicroHelp

// A Clicked that must reach ONE given window : the menu keeps that window
// itself. Instance variable of m_popup : window iw_owner
// Clicked of m_edit.m_copy
iw_owner.TriggerEvent("ue_copy")

// open event of the window, before of_load_menu
im_popup.iw_owner = this

Propiedades #

Métodos #

Eventos #

Propiedades de elemento #

Una entrada no muestra ninguna información sobre herramientas: el menú nativo no la tiene. El is_tooltip que hereda el handle se conserva y se relee, pero nunca se muestra — para una ayuda, ib_track_hover y ue_item_hover.

Ejemplos #

Un menú según lo que se ha pulsado #

// event ue_rclicked of the list : the menu is rebuilt for the current row
uo_menu.of_clear()
uo_menu.of_add_item(/*keys*/ "open", /*text*/ "&Open")
uo_menu.of_add_item(/*keys*/ "rename", /*text*/ "Re&name")
uo_menu.of_add_separator(/*keys*/ "")
uo_menu.of_add_item(/*keys*/ "delete", /*text*/ "&Delete")

// A row the user may not change : its commands are greyed
uo_menu.of_item(/*keys*/ "rename").ib_enabled = ib_can_edit
uo_menu.of_item(/*keys*/ "delete").ib_enabled = ib_can_edit

// At the cursor
uo_menu.of_show()

Un botón Más #

// event ue_clicked of the button : the menu hangs from it
uo_menu.of_show_under(/*control*/ uo_more)

Una ayuda en la barra de estado #

// Once, after the menu is built : report the pointed entry
uo_menu.ib_track_hover = true

// event ue_item_hover of uo_menu : (string as_keys), "" when the menu closes
choose case as_keys
	case "delete"
		st_help.text = "Deletes the row, without the clipboard."
	case else
		st_help.text = ""
end choose

Buenas prácticas #

• Abra desde el evento de clic derecho del control (vea la tabla): solo una pulsación elige una entrada, la liberación que sigue no elige nada.
• Un menú corto. Los comandos frecuentes arriba, los destructivos abajo, tras un separador, con TONE_DANGER.
• Atenúe en lugar de ocultar un comando que existe pero no se aplica aquí: el usuario aprende dónde está.
• Muestre los atajos de sus comandos: un menú contextual es donde se aprenden.
• Una cascada, no dos: más allá de un nivel, un cuadro de diálogo se lee mejor.

Versión de demostración #

Sin clave, cada lista del menú — la raíz como cada cascada — muestra sus seis primeras entradas visibles; los separadores y los encabezados no cuentan. La última línea, atenuada, dice cuántas entradas no se muestran — o, sin recorte, lleva la mención «PBToolboxAI — DEMO». El modelo lo guarda todo: una clave muestra el menú entero en la apertura siguiente.

El lanzador no tiene superficie: de los miembros heredados más abajo, of_save_as_png, of_print y of_focus_webview no tienen nada que capturar, imprimir ni recibir. of_register_shortcut sigue siendo útil — un atajo de la ventana que abre el menú con of_show_under.

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.

En este lanzador invisible, of_count y of_keys_at recorren lo que usted ha añadido, ramas ocultas incluidas — no lo que la rueda dibujará. La exportación como imagen, la impresión, of_focus_webview y of_set_redraw no tienen aquí ningún efecto útil: el componente no dibuja nada propio, la rueda vive en su propia ventana.

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.

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