contextmenu — u_pbt_contextmenu #

← Référence des composants · Sommaire du guide

Le menu contextuel de Windows, au thème de l'application : une liste en cascade qui s'ouvre au curseur, sous un contrôle ou à un point de l'écran — icônes, raccourcis affichés, coches, entrées radio, en-têtes de section, longues listes qui défilent et répondent à la frappe.

▶ Le voir en vrai — Application de démonstration, tuile Context menu : l'aperçu, le code qui le produit et cette page, côte à côte.

En bref #

Démarrage rapide #

// 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

Ouvrir le menu #

Le composant lui-même est invisible : il ne prend aucune place dans la fenêtre. Posez-le n'importe où, largeur et hauteur nulles — il n'existe que tant que le menu est ouvert. Quatre façons de l'ouvrir :

• of_show() — au curseur, depuis le clic droit du contrôle qui reçoit le geste — voir le tableau ci-dessous.
• of_show_under(contrôle) — sous un contrôle : le menu pend de son bord bas, calé sur son bord de début (son bord droit en lecture de droite à gauche), et s'ouvre au-dessus quand l'écran s'arrête dessous. Ce qu'il faut à un bouton Plus ou … — et au clavier : of_show_under(contrôle, true) désigne la première entrée active.
• of_show(x, y) — à un point de l'écran, en pixels. Des coordonnées négatives sont un vrai point : un écran placé à gauche ou au-dessus du principal.
• of_show_at(contrôle, x, y) — à un point dans un contrôle, en unités PowerBuilder depuis son coin haut gauche : le point que prenait PopMenu, rien à convertir. of_source() nomme ensuite ce contrôle dans ue_item_selected — un seul menu pour plusieurs contrôles.

// 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())

Où appeler of_show #

of_show() s'ouvre où se trouve le curseur, c'est-à-dire là où l'utilisateur a cliqué : aucune unité à convertir. of_show(x, y) attend des pixels de l'écran, jamais les unités PowerBuilder d'un xpos/ypos relatif au contrôle. Pour un point dans un contrôle, en unités PowerBuilder, c'est of_show_at(contrôle, x, y).

Au clavier — Maj+F10 ou la touche Menu — la souris est n'importe où : ouvrez le menu sous le contrôle qui a le focus, par of_show_under(contrôle, true). Comme dans Windows, sa première entrée active est alors désignée : Entrée la choisit, les flèches partent de là. Sous PowerBuilder 10, pbm_contextmenu ne reçoit que le clic droit, et Maj+F10 n'atteint pas un champ de saisie (mesuré : ni pbm_contextmenu, ni pbm_keydown, ni pbm_syskeydown). La touche du clavier qui ouvre le menu sur un contrôle PowerBuilder est donc la touche Menu (KeyApps!), prise dans un événement utilisateur sur pbm_keydown — pbm_dwnkey pour un DataWindow, dont le clic droit passe par son événement rbuttondown : pbm_contextmenu n'y arrive pas pour un clic dans une cellule (mesuré). Maj+F10 reste reçu par les composants PBToolboxAI eux-mêmes (leur 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

Une seule réponse par ouverture : un menu ouvert se termine par un choix (ue_item_selected) ou sans choix (ue_dismissed — un clic dehors, Échap, of_close). Un menu qui n'a rien à montrer ne s'ouvre pas : ue_dismissed arrive tout de suite. Pendant que le menu est à l'écran l'application continue de tourner : une entrée grisée, masquée ou retirée entre-temps ne peut plus être choisie (ue_dismissed à la place), et of_remove_item, of_clear ou of_reset ferment le menu ouvert. ue_dismissed(as_reason) dit pourquoi : REASON_ESCAPE (Échap), REASON_OUTSIDE (un clic dehors), REASON_FOCUS (une autre fenêtre a pris le focus), REASON_USER (une autre façon, un autre menu qui prend la place), REASON_CODE (of_close, une entrée retirée ou le menu vidé), REASON_REPLACED (un second of_show), REASON_EMPTY (rien à montrer), REASON_UNAVAILABLE (l'entrée choisie n'était plus disponible).

Un menu à la fois : un second of_show remplace le menu ouvert, qui répond d'abord ue_dismissed. Et of_close appelé juste après of_show ferme le menu avant même qu'il soit dessiné — ue_dismissed suit aussi.

Au clavier, les flèches parcourent les entrées en sautant les grisées, → ouvre une cascade et ← la referme, Entrée choisit, Échap remonte d'un niveau puis ferme. La lettre soulignée — celle qui suit & dans le libellé, && pour une esperluette — choisit l'entrée directement ; ailleurs, taper les premières lettres d'un libellé va à l'entrée, espaces compris (« report 2 »). Une longue liste (plus de cinq cents entrées comprises) défile et reste fluide. Lu de droite à gauche, le menu s'aligne à droite et les cascades s'ouvrent vers la gauche.

Cascades, sections et marques #

Une entrée se désigne par son adresse : sa clé seule au premier niveau (copy), les clés de ses parents puis la sienne, jointes par /, dans une cascade (export/pdf). Le parent doit exister ; une clé ne contient ni / ni | et ne commence pas par __. ue_item_selected rend cette même adresse : deux cascades peuvent nommer leurs entrées pareil.

Un séparateur (of_add_separator) et un en-tête de section (of_add_header) se posent à la fin du menu (adresse vide) ou de la cascade d'une entrée. Ni l'un ni l'autre n'est une entrée : jamais choisis, jamais comptés. Un séparateur ne s'affiche jamais en tête, en queue ni en double ; un en-tête dont toutes les entrées sont masquées disparaît avec elles.

Une coche (ib_checked) dit qu'une option est active ; une entrée radio (is_group) est un choix parmi plusieurs : les entrées d'un même groupe sous le même parent s'excluent — en cocher une, par le code ou par le choix de l'utilisateur, décoche les autres, et une puce ronde remplace la coche. Le raccourci (is_shortcut) s'affiche à droite de l'entrée ; il est affiché seulement : la touche appartient au contrôle dont parle le menu (un champ de saisie copie déjà sur Ctrl+C), et un menu contextuel qui l'armerait la prendrait à tous les contrôles de la fenêtre.

Une entrée cochée hors groupe ne bascule pas d'elle-même quand l'utilisateur la choisit — comme dans tout menu Windows : basculez-la dans ue_item_selected. Une commande qui détruit se distingue par son ton : is_tone = TONE_DANGER écrit son texte dans le rouge du thème, lisible en clair comme en sombre. Pour qu'une option se bascule d'elle-même au choix, posez ib_auto_check = true : la coche change avant ue_item_selected. Une option est une case à cocher — annoncée « non cochée » par un lecteur d'écran — dès qu'elle a été cochée une fois, ou dès 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

Reprendre un menu PowerBuilder #

Vos menus surgissants sont déjà écrits ? of_load_menu en fait le menu du composant : passez l'élément sur lequel vous appeliez PopMenu. Chaque élément devient une entrée, cascades comprises, avec son texte (& compris), son état (Enabled, Checked, Visible), son Shortcut affiché à droite — comme le texte qui suit une tabulation — et son image de barre d'outils quand c'est un fichier présent. Sa clé est le ClassName de l'élément, à chaque niveau. Au choix, le script Clicked de l'élément s'exécute d'abord, puis ue_item_selected : le code écrit pour PopMenu continue de servir. Le menu reste vivant, comme avec PopMenu : chaque ouverture relit les éléments (Text, Enabled, Checked, Visible, Shortcut). Le code qui précédait PopMenu — m_paste.Enabled = (Clipboard() <> "") — et un Clicked qui fait this.Checked = not this.Checked se voient donc à l'ouverture suivante ; un élément grisé ou masqué pendant que le menu est ouvert ne lance pas son Clicked (ue_dismissed(REASON_UNAVAILABLE)). Gardez l'objet menu vivant tant que le composant s'en sert. of_loaded_item rend l'élément d'une entrée, pour lire ce que seul le menu sait (sa MicroHelp) — testez-le par IsValid, une entrée ajoutée à la main n'en a pas. Un script Clicked qui lit ParentWindow y trouve une fenêtre valide — mesuré sous PowerBuilder 10, même pour un menu créé par create et jamais attaché à une fenêtre — mais c'est PowerBuilder qui la choisit : rien ne garantit que ce soit la fenêtre qui porte le menu contextuel. Pour qu'un Clicked atteigne une fenêtre précise, donnez-la au menu dans une variable d'instance, posée avant of_load_menu, ou déplacez ce code dans 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

Propriétés #

Méthodes #

Événements #

Propriétés d'item #

Une entrée n'affiche aucune info-bulle : le menu natif n'en a pas. L'is_tooltip que la poignée hérite est gardé et se relit, mais il n'est jamais montré — pour une aide, ib_track_hover et ue_item_hover.

Exemples #

Un menu selon ce qui est cliqué #

// 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 bouton Plus #

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

Une aide dans la barre d'état #

// 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

Bonnes pratiques #

• Ouvrez depuis l'événement de clic droit du contrôle (voir le tableau) : seul un appui choisit une entrée, le relâchement qui suit ne choisit rien.
• Un menu court. Les commandes fréquentes en haut, celles qui détruisent en bas, après un séparateur, avec TONE_DANGER.
• Grisez plutôt que masquer une commande qui existe mais ne s'applique pas ici : l'utilisateur apprend où elle est.
• Affichez les raccourcis de vos commandes : un menu contextuel est l'endroit où on les apprend.
• Une cascade, pas deux : au-delà d'un niveau, une boîte de dialogue se lit mieux.

Version de démonstration #

Sans clé, chaque liste du menu — la racine comme chaque cascade — montre ses six premières entrées visibles ; séparateurs et en-têtes ne comptent pas. La dernière ligne, grisée, dit combien d'entrées ne sont pas affichées — ou, sans coupe, porte la mention « PBToolboxAI — DEMO ». Le modèle garde tout : une clé montre le menu entier à l'ouverture suivante.

Le lanceur n'a pas de surface : des membres hérités ci-dessous, of_save_as_png, of_print et of_focus_webview n'ont rien à capturer, à imprimer ni à recevoir. of_register_shortcut reste utile — un raccourci de la fenêtre qui ouvre le menu par of_show_under.

Hérité du socle commun #

Ces membres existent sur tous les composants visuels — ils ne sont pas propres à celui-ci. Ils sont détaillés une seule fois, dans les chapitres transverses ; cette table dit seulement où les lire.

Sur ce lanceur invisible, of_count et of_keys_at parcourent ce que vous avez ajouté, branches masquées comprises — pas ce que la roue dessinera. L'export en image, l'impression, of_focus_webview et of_set_redraw n'y ont pas d'effet utile : le composant ne dessine rien de lui-même, la roue vit dans sa propre fenêtre.

Deux aides ne sont pas héritées : of_icon et of_escape_markup vivent sur n_pbt_utils. Déclarez-en une — n_pbt_utils lnv_utils, rien à créer — et appelez-les dessus.

← Référence des composants · Sommaire du guide