menubar — `u_pbt_menubar` #

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

Barre de menus d'application : menus, sous-menus, entrées cochables, séparateurs, icônes et raccourcis — le tout dessiné par la bibliothèque, sans menu Windows.

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

En bref #

Userobject	`u_pbt_menubar`
Classe d'items	`n_pbt_menubar_item` (une entrée)
Sert à	Donner à votre fenêtre la barre de menus de l'application, thémée comme le reste
Principe	Vous déclarez les menus, puis leurs entrées ; chaque entrée se retrouve par son adresse `menu/id`

Démarrage rapide #

// event open de la fenetre
uo_menus.of_add_menu(/*key*/ "file", /*text*/ "Fichier")
uo_menus.of_add_item(/*keys*/ "file/open", /*text*/ "Ouvrir")
uo_menus.of_add_item(/*keys*/ "file/save", /*text*/ "Enregistrer")

// event ue_item_selected : (string as_keys)
choose case as_keys
	case "open"; of_ouvrir()
	case "save"; of_enregistrer()
end choose

Le modèle : trois niveaux, une clé par niveau #

Une barre de menus a trois niveaux, et chacun se désigne par sa clé :

Niveau	Posé par	Clé
Le menu de la barre	`of_add_menu`	son `id`
L'entrée d'un menu	`of_add_item`	l'adresse `menu/id`
La sous-entrée d'une entrée	`of_add_item`	l'adresse `menu/entree/sous-entree` — trois niveaux

Un identifiant d'entrée n'est unique que dans son menu : c'est pourquoi of_item en demande deux. Deux menus peuvent donc avoir chacun leur entrée "open" sans se gêner.

Un séparateur n'a pas de clé : of_add_separator pose un trait à l'endroit où vous l'appelez, et il n'y a rien à en relire ensuite.

Propriétés #

Propriété	Type	Défaut	Rôle
`is_theme_style`	string	`fluent`	Style visuel du composant (constantes `THEME_STYLE_*`)
`is_theme_mode`	string	`light`	Variante claire ou sombre (constantes `THEME_MODE_*`)
`il_theme_accent`	long	`-1`	Couleur d'accent de ce composant (`-1` = accent du thème)
`is_tooltip`	string	`""`	Info-bulle simple affichée au survol du composant
`is_super_tooltip_title`	string	`""`	Titre de l'info-bulle enrichie (prend le pas sur `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Texte de l'info-bulle enrichie (balisage riche accepté)
`is_super_tooltip_image`	string	`""`	Image de l'info-bulle enrichie

Propriétés d'une entrée — `n_pbt_menubar_item` #

Obtenues par of_item(menu/id) :

Propriété	Type	Défaut	Rôle
`is_text`	string	—	Change le libellé de l'entrée, à chaud
`ib_enabled`	boolean	`true`	Entrée active ; une entrée grisée ne réagit plus au clic
`ib_visible`	boolean	`true`	Entrée retirée de la liste sans être supprimée — sous-menu et raccourci endormis avec elle ; elle garde sa clé et revient telle quelle
`is_shortcut`	string	`""`	L'accélérateur affiché à droite de l'entrée (`Ctrl+S`) — et armé : la combinaison lève `ue_item_selected` pour cette entrée, où que soit le focus. Un menu est l'endroit où l'on apprend les raccourcis d'une application ; une touche affichée qui ne fait rien apprend le contraire. La chaîne vide retire les deux
`ib_checked`	boolean	`false`	Coche affichée devant l'entrée — pour une option qui s'active et se désactive
`is_tooltip`	string	`""`	Info-bulle de cette entrée
`is_super_tooltip_title`	string	`""`	Titre de son info-bulle enrichie
`is_super_tooltip_text`	string	`""`	Texte de son info-bulle enrichie (balisage riche accepté)
`is_super_tooltip_image`	string	`""`	Image de son info-bulle enrichie

Méthodes #

Méthode	Rôle
`of_add_menu (string as_key, string as_text)`	Ajoute un menu à la barre. Renvoie `0` une fois appliqué, `-2` si le composant n'est pas créé
`of_add_item (string as_keys, string as_text)`	Ajoute une entrée dans un menu. Renvoie `0` une fois appliqué, `-5` sur un argument invalide (clé vide, adresse fausse), `-2` si le composant n'est pas créé
`of_add_item (string as_keys, string as_text, string as_image, boolean ab_checked)`	Même chose, avec l'icône, la coche et l'état initial. Renvoie `0` une fois appliqué, `-5` sur un argument invalide (clé vide, adresse fausse), `-2` si le composant n'est pas créé
`of_add_separator (string as_keys)`	Pose un trait de séparation à la suite du menu. Renvoie `0` une fois appliqué, `-2` si le composant n'est pas créé
`of_item (string as_keys)` → `n_pbt_menubar_item`	Handle d'une entrée, pour poser ses propriétés. `as_key` accepte les deux écritures : l'identifiant nu de la feuille, et le chemin complet clés jointes par `/` — `of_item("file", "export/pdf")`. C'est le chemin que rend `ue_item_selected` : ses deux arguments se redonnent tels quels ici. Un identifiant nu n'est unique que dans son sous-menu — deux sous-menus Export peuvent chacun avoir leur `pdf`, et seul le chemin les distingue
`of_menu (string as_key)` → `n_pbt_menubar_menu`	Handle d'un menu de premier niveau, pour le renommer ou l'éteindre. `of_add_menu` ne pouvait le faire qu'à la création : griser Admin à la déconnexion demandait de reconstruire toute la barre ; `ib_visible` le retire de la barre, entrées et raccourcis endormis avec lui
`of_remove_item (string as_keys)` → `long`	Retire une entrée ; les autres restent. `as_key` accepte les deux écritures d'`of_item` : le chemin complet (`export/pdf`) ou l'identifiant nu. Sans elle il n'y avait qu'`of_clear`, qui vide tout — le menu dynamique le plus courant, une liste de fichiers récents, imposait de raser la barre entière à chaque document ouvert. Renvoie `0` une fois appliqué, `-5` sur un argument invalide (clé vide, adresse fausse), `-2` si le composant n'est pas créé
`of_remove_menu (string as_key)` → `long`	Retire un menu de premier niveau, ses entrées avec lui. La barre est redessinée et sa hauteur ré-annoncée. Renvoie `0` une fois appliqué, `-2` si le composant n'est pas créé
`of_clear ( )`	Vide la barre — menus et entrées. Renvoie `0` une fois appliqué, `-2` si le composant n'est pas créé
`of_reset ( )`	Vide la barre et remet toutes les propriétés à leur défaut. Renvoie `0` une fois appliqué, `-2` si le composant n'est pas créé
`of_set_redraw (boolean)`	Regroupe une rafale de modifications en un seul rendu. Renvoie `0` une fois appliqué, `-2` si le composant n'est pas créé
`of_save_as_png (string)` · `of_save_as_jpg (string)`	Exporte le rendu en image. Renvoie `0` une fois l'image écrite, `-4` si l'écriture échoue, `-2` si le composant n'est pas créé

Événements #

Événement	Déclenché quand
`ue_menu_opening (string as_key)`	Levé à l'instant où un menu de premier niveau est cliqué, avant que son déroulant soit construit. C'est le moment d'activer, griser ou remplir ses entrées juste à temps — sans lui, il fallait tenir toute la barre en cohérence avec l'état de l'application en permanence, ou afficher des entrées qui mentent
`ue_item_selected (string as_keys)`	L'utilisateur a choisi une entrée. `as_key` est un chemin dès que l'entrée est imbriquée — `export/pdf`, pas `pdf` : la feuille seule ne dit pas de quel sous-menu elle sort, et deux sous-menus peuvent chacun avoir la leur. Une entrée de premier niveau garde son identifiant nu. Ce même texte se redonne tel quel à `of_item`
`ue_auto_height (long al_height)`	La barre annonce la hauteur qu'il lui faut — repositionnez ce qui se trouve dessous
`ue_ready ( )`	Le composant a fini de charger ; tout ce qui a été envoyé avant a été rejoué
`ue_runtime_missing ( )`	Le runtime WebView2 est absent : le composant reste vide
`ue_bg_color (long al_color)`	Le composant a calculé sa couleur de fond de thème ; l'userobject l'a déjà adoptée (`backcolor`)

La hauteur ne se pose pas, elle s'annonce. Une barre de menus ne défile pas : une hauteur figée ne peut produire que du vide sous la barre ou des menus tronqués. Elle s'ajuste donc toujours, et ue_auto_height vous dit de combien.

Au clavier #

Touche	Effet
Alt	Donne le focus à la barre, comme dans n'importe quelle application Windows
Flèches	Parcourent les menus et leurs entrées ; la droite ouvre une sous-entrée, la gauche remonte
Entrée ou Espace	Choisit l'entrée focalisée (`ue_item_selected`)
Échap	Referme le menu ouvert, puis rend le focus

Exemples #

Une barre de menus complète #

uo_menus.of_set_redraw(false)

// Le menu Fichier, avec une icone sur Ouvrir et un trait avant Quitter
uo_menus.of_add_menu(/*key*/ "file", /*text*/ "F")
uo_menus.of_add_item(/*keys*/ "file/open", /*text*/ "O", /*image*/ "mono:img\packimages.dll:svg/samples/folder-open", /*checked*/ false)
uo_menus.of_add_separator(/*keys*/ "file")
uo_menus.of_add_item(/*keys*/ "file/quit", /*text*/ "Q")

// Un sous-menu : Exporter, puis ses deux formats
uo_menus.of_add_item(/*keys*/ "file/export", /*text*/ "E")
uo_menus.of_add_item(/*keys*/ "file/export/csv", /*text*/ "CSV")
uo_menus.of_add_item(/*keys*/ "file/export/pdf", /*text*/ "PDF")

// Le menu Affichage : une option qui se coche
uo_menus.of_add_menu(/*key*/ "view", /*text*/ "V")
uo_menus.of_add_item(/*keys*/ "view/grid", /*text*/ "G", /*image*/ "", /*checked*/ true)

uo_menus.of_set_redraw(true)

Cocher, décocher, griser #

// L'utilisateur a bascule l'affichage de la grille
uo_menus.of_item(/*keys*/ "view/grid").ib_checked = not uo_menus.of_item(/*keys*/ "view/grid").ib_checked

// Une entree qui n'a plus de sens se grise, elle ne disparait pas :
// l'utilisateur doit pouvoir voir qu'elle existe
uo_menus.of_item(/*keys*/ "file/save").ib_enabled = false

Reconstruire la barre #

// Changer d'espace de travail : on vide et on repose
// of_set_redraw evite de repeindre a chaque ligne
uo_menus.of_set_redraw(false)
uo_menus.of_clear()
uo_menus.of_add_menu(/*key*/ "tools", /*text*/ "T")
uo_menus.of_set_redraw(true)

Bonnes pratiques #

Donnez à chaque entrée un identifiant métier stable ("save") : c'est lui que vous recevez dans ue_item_selected, pas un libellé qui change avec la langue.
Grisez plutôt que de retirer : une entrée absente laisse l'utilisateur chercher, une entrée grisée lui dit qu'elle existe et qu'il lui manque quelque chose.
Encadrez la construction par of_set_redraw(false) / of_set_redraw(true) : une barre complète, c'est vite trente appels.
Repositionnez ce qui est sous la barre dans ue_auto_height — la hauteur dépend du thème et de la taille de police, elle n'est pas la même partout.
Pour les libellés, passez par of_set_translation si votre application est multilingue : voir le chapitre langue.

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.

Membres	Rôle	Détaillé dans
`of_count` · `of_keys_at` · `of_has`	Parcourir ce que le composant contient	3.2 Les items
`of_reset`	Remettre le composant à zéro	3.6 Remettre un composant à zéro : `of_reset()`
`of_register_shortcut` · `of_clear_shortcuts`	Raccourcis clavier du composant	3.5 Les raccourcis clavier
`of_is_created` · `of_is_ready` · `of_get_last_error`	S'il est né, s'il est prêt, ce qui a échoué	3.7 Diagnostic
`of_save_as_png` · `of_save_as_jpg`	Exporter le rendu en image	3.8 Exporter le rendu en image
`of_set_redraw`	Grouper les modifications en un seul repaint	3.10 Bonnes pratiques
`of_preload_icons`	Icônes affichées sans délai	Affichage instantané : `of_icon`
`of_set_translation`	Traduire un libellé du composant	5.2 Adapter un libellé : `of_set_translation`
`of_focus_webview`	Donner le focus au composant	6.4 Clavier et focus
`of_print` · `of_print_to_pdf`	Imprimer, ou écrire un PDF	6.9 Imprimer

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.