toolbar — `u_pbt_toolbar` #

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

Barre d'outils plate : plusieurs barres réparties sur des bandes, boutons, bascules, menus déroulants, champs de saisie, débordement automatique et déplacement à la poignée.

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

En bref #

Userobject	`u_pbt_toolbar`
Classes d'items	`n_pbt_toolbar_bar` (barre) → `n_pbt_toolbar_item` (outil) → `n_pbt_toolbar_menu_item` (entrée de menu)
Sert à	Remplacer une barre d'outils classique par une barre moderne, thémée, à plusieurs rangées réorganisables
Hauteur	Intrinsèque : la barre se cale toujours sur ses rangées, rien à activer — voir Hauteur automatique

Démarrage rapide #

// event open de la fenetre

// MAIN_BAR est la barre par defaut, toujours presente : l adresse part d elle
uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/save", /*text*/ "", /*image*/ "mono:img\save.svg", /*tooltip*/ "Enregistrer")
uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/find", /*text*/ "", /*image*/ "mono:img\find.svg", /*tooltip*/ "Rechercher")
uo_toolbar.of_add_separator(/*keys*/ uo_toolbar.MAIN_BAR)
uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/help", /*text*/ "Aide",  /*image*/ "", /*tooltip*/ "A propos")

// event ue_clicked de uo_toolbar : (string as_keys)
choose case as_keys
    case "main/save" ; of_save()
    case "main/find" ; of_find()
    case "main/help" ; of_help()
end choose

Le modèle : barres, bandes, outils #

Une barre d'outils contient une ou plusieurs barres. Chaque barre est posée sur une bande (une rangée) et occupe une position dans cette rangée : deux barres sur la même bande se partagent la rangée, deux barres sur des bandes différentes s'empilent — exactement comme les barres d'outils Office classiques.

Les outils (boutons, bascules, menus, champs) appartiennent à une barre. Leur identifiant n'est unique qu'à l'intérieur de leur barre : l'accès passe donc toujours par le chemin complet.

// Gray out a tool, or one entry of its menu
uo_toolbar.of_item(/*keys*/ "main/save").ib_enabled = false
uo_toolbar.of_menu_item(/*keys*/ "main/export/pdf").ib_enabled = false

Tout se fait depuis le composant, par adresses : un outil s'ajoute à la sienne (of_add_button("main/save", …)), une entrée de menu à la sienne ("main/export/pdf", un niveau de plus par cascade), et chaque niveau a son getter — of_bar, of_item, of_menu_item. Voir Socle commun · Les items pour le principe général.

Listes déroulantes #

Une liste déroulante (of_add_combo) est un champ et sa flèche, comme la combo du ruban. Non modifiable, l'utilisateur choisit dans la liste (un clic sur le champ, Entrée, F4 ou Alt+Bas l'ouvrent) ; modifiable, il peut aussi taper une valeur à lui. Chaque choix revient dans ue_combo_changed ; repliée dans le chevron d'une barre trop étroite, la liste reste vivante.

// A font the user only chooses, a size he may also type
uo_toolbar.of_add_combo(/*keys*/ "main/font", /*width*/ 130, /*editable*/ false, /*tooltip*/ "Font")
uo_toolbar.of_add_combo_item(/*keys*/ "main/font", /*label*/ "Segoe UI")
uo_toolbar.of_add_combo_item(/*keys*/ "main/font", /*label*/ "Arial")
uo_toolbar.of_item(/*keys*/ "main/font").is_text = "Segoe UI"
uo_toolbar.of_add_combo(/*keys*/ "main/size", /*width*/ 60, /*editable*/ true, /*tooltip*/ "Size")
uo_toolbar.of_add_combo_item(/*keys*/ "main/size", /*label*/ "10")
uo_toolbar.of_add_combo_item(/*keys*/ "main/size", /*label*/ "12")

// ue_combo_changed (string as_keys, string as_text) of uo_toolbar
st_status.Text = as_keys + " = " + as_text

Propriétés #

Propriété	Type	Défaut	Rôle
`is_theme_style`	string	`""`	Style visuel du composant (constantes `THEME_STYLE_*`) ; vide = celui de l'application, suivi à chaque changement
`is_theme_mode`	string	`""`	Variante claire ou sombre (constantes `THEME_MODE_*`) ; vide = celle de l'application, suivie à chaque changement
`il_theme_accent`	long	`-1`	Couleur d'accent de ce composant (`-1` = l'accent de l'application, ou celui 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
`ib_reorderable`	boolean	`false`	Permet à l'utilisateur de réorganiser les barres à la souris : les poignées de déplacement apparaissent et une barre peut être glissée vers une autre bande. Désactivé par défaut — une barre d'outils démontée par accident, c'est un appel au support. Votre code, lui, les réorganise dans tous les cas (`of_set_layout`, `of_add_bar`) : l'autorisation porte sur l'utilisateur, jamais sur l'application

Constante #

Constante	Valeur	Rôle
`MAIN_BAR`	`"main"`	Identifiant de la barre par défaut, que l'on adresse sans l'avoir créée : elle naît à son premier outil. Pour la placer, ajoutez-la d'abord — `of_add_bar(MAIN_BAR, 1, 1)`

Méthodes #

Méthode	Rôle
`of_bar (string as_key)` → `n_pbt_toolbar_bar`	Rend le handle d'une barre (créé au premier accès) : `ii_band`, `ii_index`, `ib_visible`
`of_add_button (string as_keys, string as_text, string as_image, string as_tooltip)` → `long`	Bouton d'action à son adresse, `"main/save"` : la barre, puis son propre identifiant. Le clic déclenche `ue_clicked`. Renvoie `0` une fois ajouté, `-5` si l'adresse est refusée (pas `barre/outil`, barre jamais ajoutée — `main` excepté —, adresse déjà prise), `-2` si le composant n'est pas créé
`of_item (string as_keys)` → `n_pbt_toolbar_item`	Rend le handle d'un outil, par son adresse `barre/outil`. Une adresse d'une autre profondeur ne désigne aucun outil : une barre, c'est `of_bar`, une entrée de menu, `of_menu_item`
`of_menu_item (string as_keys)` → `n_pbt_toolbar_menu_item`	Rend le handle d'une entrée de menu déroulant, par son adresse `barre/deroulant/entree` — un niveau de plus par cascade. Deux cascades peuvent avoir chacune leur `pdf` : l'adresse en désigne une, jamais les deux
`of_add_bar (string as_key)` → `long`	Ajoute une barre, sur une bande à elle après les autres. Renvoie `0` une fois ajoutée, `-5` si la clé est refusée (vide, avec `/` ou `	`, commençant par` __`, ou déjà prise),` -2 `si le composant n'est pas créé. La barre par défaut` main `naît à son premier outil : pour la placer, ajoutez-la avant tout outil (`of_add_bar(MAIN_BAR, 1, 1)`) ; ensuite elle est prise (`-5`) et se déplace par` of_bar(MAIN_BAR)`
`of_add_bar (string as_key, integer ai_band, integer ai_index)` → `long`	Ajoute une barre à une bande et à une position précises (les deux comptées à partir de 1) ; la barre qui tenait ce rang passe d'un cran à droite. Mêmes codes que ci-dessus
`of_remove_bar (string as_key)` → `long`	Retire une barre et ses outils, avec leurs handles et leurs raccourcis. Les autres gardent leur état vivant, et les bandes se resserrent derrière celle qui part. Ce n'est pas la masquer (`ib_visible` sur son handle) : masquer la garde dans le modèle, prête à revenir exactement où elle était ; retirer l'oublie. Renvoie `0` une fois retirée, `-5` pour une barre qui n'existe pas, `-2` si le composant n'est pas créé
`of_get_layout ()` → `string`	Relit la disposition courante en JSON : quelle barre sur quelle bande, à quel rang, et visible ou non. Bandes et rangs comptés à partir de 1, comme `ii_band` / `ii_index` : à stocker telle quelle, puis à rendre par `of_set_layout` — un aller-retour rend la même chaîne
`of_set_layout (string as_layout_json)` → `long`	Restaure une disposition lue par `of_get_layout` ou reçue par `ue_layout_changed`, rendue telle quelle. Une barre qu'elle ne nomme pas reste où elle est. `ue_layout_changed` est levé, comme pour tout changement de disposition. Renvoie `0` une fois appliqué, `-5` sur une chaîne vide, `-2` si le composant n'est pas créé. Un texte qui n'est pas du JSON rend aussi `-5`
`of_clear ( )` → `long`	Supprime toutes les barres, tous les outils et tous les menus, avec les handles distribués et les raccourcis des outils et des entrées ; chaque adresse peut être ajoutée de nouveau. Renvoie `0` une fois appliqué, `-2` si le composant n'est pas créé
`of_reset ( )`	Vide le contenu et remet les propriétés à leur défaut. Renvoie `0` une fois appliqué, `-2` si le composant n'est pas créé
`of_add_toggle (string as_keys, string as_text, string as_image, string as_tooltip)` → `long`	Bascule à deux états ; le clic déclenche `ue_toggled`. Renvoie `0` une fois ajouté, `-5` si l'adresse est refusée (pas `barre/outil`, barre jamais ajoutée — `main` excepté —, adresse déjà prise), `-2` si le composant n'est pas créé
`of_add_dropdown (string as_keys, string as_text, string as_image, string as_tooltip)` → `long`	Bouton à menu déroulant, rempli par `of_add_menu_item` ; un choix déclenche `ue_menu_selected`. Renvoie `0` une fois ajouté, `-5` si l'adresse est refusée (pas `barre/outil`, barre jamais ajoutée — `main` excepté —, adresse déjà prise), `-2` si le composant n'est pas créé. Un déroulant dont aucune entrée n'est visible se dessine grisé
`of_add_split_button (string as_keys, string as_text, string as_image, string as_tooltip)` → `long`	Bouton partagé : sa partie principale est un bouton (`ue_clicked`), sa flèche ouvre un menu rempli par `of_add_menu_item` comme celui d'un déroulant (`ue_menu_selected`). Son raccourci déclenche la partie principale ; replié dans le chevron, il ouvre une liste dont la première ligne est sa propre action. Renvoie `0` une fois ajouté, `-5` si l'adresse est refusée (pas `barre/outil`, barre jamais ajoutée — `main` excepté —, adresse déjà prise), `-2` si le composant n'est pas créé
`of_add_label (string as_keys, string as_text)` → `long`	Libellé informatif, non cliquable. Renvoie `0` une fois ajouté, `-5` si l'adresse est refusée (pas `barre/outil`, barre jamais ajoutée — `main` excepté —, adresse déjà prise), `-2` si le composant n'est pas créé
`of_add_textbox (string as_keys, string as_text, integer ai_width, string as_tooltip)` → `long`	Champ de saisie ; Entrée ou perte du focus déclenche `ue_text_changed`, Échap rend le texte validé. `ai_width` en pixels. Renvoie `0` une fois ajouté, `-5` si l'adresse est refusée (pas `barre/outil`, barre jamais ajoutée — `main` excepté —, adresse déjà prise), `-2` si le composant n'est pas créé
`of_add_combo (string as_keys, integer ai_width, boolean ab_editable, string as_tooltip)` → `long`	Liste déroulante (combo) : un champ et sa flèche, la combo du ruban. `ab_editable = false`, l'utilisateur choisit seulement dans la liste ; `true`, il peut aussi taper sa propre valeur, validée par Entrée ou la perte du focus. La liste se remplit par `of_add_combo_item`, un choix déclenche `ue_combo_changed`, `is_text` pose et relit la valeur. `ai_width` en pixels (0 = largeur par défaut). Repliée dans le chevron, elle reste une liste vivante. Renvoie `0` une fois ajoutée, `-5` si l'adresse est refusée (pas `barre/outil`, barre jamais ajoutée — `main` excepté —, adresse déjà prise), `-2` si le composant n'est pas créé
`of_add_combo_item (string as_keys, string as_label)` → `long`	Ajoute un choix à la liste d'une liste déroulante : `as_keys` nomme la liste (`"main/zoom"`). Un choix a pour clé son libellé, son adresse est donc `"main/zoom/150%"` (`of_remove_combo_item`, `of_has`) ; `of_count` et `of_keys_at` sur la liste parcourent ses choix. En démonstration, la liste affiche 6 choix. Renvoie `0` une fois ajouté, `-5` si `as_keys` n'est pas une liste déroulante, ou si le libellé est vide, contient `/` ou `	`, ou figure déjà dans la liste,` -2` si le composant n'est pas créé
`of_add_datepicker (string as_keys, string as_date, string as_tooltip)` → `long`	Sélecteur de date ; un choix déclenche `ue_date_changed`, `is_date` lit et pose la date. Dates au format `"aaaa-mm-jj"`. Renvoie `0` une fois ajouté, `-5` si l'adresse est refusée (pas `barre/outil`, barre jamais ajoutée — `main` excepté —, adresse déjà prise), `-2` si le composant n'est pas créé
`of_add_separator (string as_keys)` → `long`	Trait vertical de séparation dans une barre (`as_keys` la nomme). Un séparateur n'a ni clé ni rang. Renvoie `0` une fois ajouté, `-5` pour une barre jamais ajoutée (`main` excepté), `-2` si le composant n'est pas créé. Un séparateur que des outils masqués laisseraient en tête, en queue ou doublé n'est pas dessiné
`of_insert_button (string as_keys, string as_text, string as_image, string as_tooltip, integer ai_index)` → `long`	Bouton ajouté à la position choisie (premier = 1) plutôt qu'à la fin. Renvoie `0` une fois ajouté, `-5` si l'adresse est refusée (pas `barre/outil`, barre jamais ajoutée — `main` excepté —, adresse déjà prise), `-2` si le composant n'est pas créé
`of_move_item (string as_keys, integer ai_index)` → `long`	Déplace un outil à une autre position dans sa barre (premier = 1 ; le rang compte les outils, un séparateur n'en tient aucun). Il garde son type, son menu et son état vivant : l'outil change de place, il n'est pas reconstruit. Renvoie `0` une fois appliqué, `-5` si aucun outil ne vit à cette adresse, `-2` si le composant n'est pas créé
`of_remove_item (string as_keys)` → `long`	Retire un outil (`"main/save"`) ou une entrée de menu (`"main/export/pdf"`, sa cascade avec elle), avec ses handles et son raccourci. Tout le reste demeure, état vivant compris. Pour faire aller et venir un outil, `ib_visible` sur son handle le garde dans le modèle. Renvoie `0` une fois retiré, `-5` si rien ne vit à cette adresse, `-2` si le composant n'est pas créé
`of_remove_combo_item (string as_keys)` → `long`	Retire un choix d'une liste déroulante, nommé par son adresse `"main/zoom/150%"` ; la valeur affichée reste. `of_remove_item` fait de même. Renvoie `0` une fois retiré, `-5` si cette liste n'a pas ce choix, `-2` si le composant n'est pas créé
`of_add_menu_item (string as_keys, string as_label, string as_image)` → `long`	Entrée du menu d'un bouton déroulant, à son adresse `barre/deroulant/entree` ; chaque niveau de plus la range en cascade sous l'entrée précédente, à toute profondeur. Un libellé vide affiche la clé. Renvoie `0` une fois ajoutée, `-5` si l'adresse est refusée (niveau vide ou avec `	`, déroulant ou entrée parente jamais ajoutés, adresse déjà prise),` -2 `si le composant n'est pas créé. Vaut aussi pour le menu d'un bouton partagé (`of_add_split_button`)
`of_add_menu_separator (string as_keys)` → `long`	Trait de séparation à la fin du menu d'un déroulant (`"main/export"`), ou de la cascade d'une entrée (`"main/export/img"`). Renvoie `0` une fois ajouté, `-5` si l'adresse ne nomme ni l'un ni l'autre, `-2` si le composant n'est pas créé. Vaut aussi pour le menu d'un bouton partagé (`of_add_split_button`)
`of_clear_menu (string as_keys)` → `long`	Vide le menu d'un déroulant (`"main/recent"`) et garde le bouton : la façon de reconstruire une liste de fichiers récents. Les handles et raccourcis de ses entrées partent avec elles. Renvoie `0` une fois appliqué, `-5` si l'adresse ne nomme aucun déroulant, `-2` si le composant n'est pas créé. Vaut aussi pour le menu d'un bouton partagé (`of_add_split_button`)
`of_clear_combo (string as_keys)` → `long`	Vide la liste d'une liste déroulante (`"main/zoom"`) ; la valeur affichée reste. Pour reconstruire une liste qui suit le document. Renvoie `0` une fois appliqué, `-5` si `as_keys` n'est pas une liste déroulante, `-2` si le composant n'est pas créé
`of_register_shortcut (string as_chord, string as_keys)` → `long`	Sur une toolbar, le raccourci prend l'adresse de ce qu'il déclenche : un outil (`barre/outil` — comme `is_shortcut` sur son handle) ou une entrée de menu (`barre/deroulant/entree`). Il répond où que soit le focus dans la fenêtre et s'affiche dans l'info-bulle ou à droite de l'entrée ; `""` le retire. Une barre d'outils n'a rien à déclencher pour elle-même : la forme à un argument rend `-5`. Renvoie `0` une fois appliqué, `-5` si l'adresse ne nomme aucun outil ni aucune entrée, ou nomme un libellé, `-2` si le composant n'est pas créé
`of_clear_shortcuts ( )` → `long`	Retire tous les raccourcis de la barre d'outils — ceux de ses outils et de ses entrées de menu : ils ne répondent plus, ne s'affichent plus, et `is_shortcut` relit `""`. Renvoie `0` une fois appliqué, `-2` si le composant n'est pas créé

Sur une barre — `n_pbt_toolbar_bar` #

Membre	Type	Défaut	Rôle
`ii_band`	integer	`1`	Bande (rangée) qui porte la barre ; `1` = première rangée
`ii_index`	integer	`1`	Position de la barre dans sa bande ; `1` = la première
`ib_visible`	boolean	`true`	Montre ou masque une barre. Une barre masquée garde sa bande, son rang et ses items : la réafficher la remet exactement où elle était, sans rien reconstruire — c'est la différence avec `of_clear`, qui les perdrait

Sur un outil — `n_pbt_toolbar_item` #

Membre	Type	Défaut	Rôle
`ib_visible`	boolean	`true`	Montre ou masque un item. Il garde son rang dans la barre : le réafficher le remet exactement où il était, pas à la fin. À ne pas confondre avec `ib_enabled`, qui le laisse en place, grisé — masquez ce qui ne s'applique pas, grisez ce qui est momentanément indisponible
`ib_enabled`	boolean	`true`	Outil actif ou grisé
`ib_checked`	boolean	`false`	État d'une bascule (sans effet sur les autres types)
`is_text`	string	`""`	Libellé, balisage riche accepté
`is_shortcut`	string	`""`	Raccourci clavier (`"Ctrl+S"`), affiché dans l'info-bulle et actif ; relu tel qu'écrit. Un outil masqué, grisé ou au-delà du plafond de démonstration n'y répond pas. Il lui faut Ctrl ou Alt (Maj s'y ajoute), ou c'est F1 à F24 : une touche seule — une lettre, Suppr, Entrée — c'est de la saisie, jamais un raccourci. Un bouton ou une bascule se déclenche ; un champ de saisie reçoit le curseur, son texte sélectionné ; un sélecteur de date ouvre son calendrier ; un libellé n'en prend aucun
`is_date`	string	`""`	Date d'un sélecteur de date, `"aaaa-mm-jj"` (`""` vide le champ). Relit la date affichée — celle que l'utilisateur a choisie comme celle posée ici. Une date mal formée est ignorée ; les autres types d'outil n'ont pas de date et relisent `""`
`is_image`	string	`""`	Icône de l'outil (mêmes formes qu'à l'ajout : chemin, `mono:`, `tint:`…) ; `""` la retire. Une bascule Lecture qui passe en Pause, un bouton qui passe en icône d'erreur — sans retirer ni rajouter l'outil
`is_group`	string	`""`	Groupe d'une bascule : les bascules d'une même barre qui partagent un groupe sont exclusives, comme les boutons d'alignement d'un éditeur — en presser une relâche les autres, presser celle déjà enfoncée la laisse enfoncée. Seule la bascule pressée lève `ue_toggled`. `ib_checked = true` posé par votre code relâche aussi les autres, sans event. `""` (défaut) : hors groupe
`ib_editable`	boolean	`false`	Une liste déroulante (`of_add_combo`) : `true`, l'utilisateur peut taper sa propre valeur en plus des choix de la liste ; `false`, il choisit seulement. Tout autre outil lit `false` et l'ignore

Sur une entrée de menu — `n_pbt_toolbar_menu_item` #

Membre	Type	Défaut	Rôle
`ib_enabled`	boolean	`true`	Grisée, l'entrée reste dans le menu et ne peut plus être choisie — ni à la souris, ni au clavier, ni par son raccourci
`ib_visible`	boolean	`true`	Masquée, l'entrée quitte le menu (sa cascade avec elle) ; elle garde sa place et son état, et revient où elle était
`ib_checked`	boolean	`false`	Une coche devant l'entrée. C'est l'application qui la décide : choisir l'entrée ne la bascule pas
`is_text`	string	`""`	Libellé de l'entrée, balisage riche accepté ; relit la clé si l'entrée a été ajoutée sans libellé
`is_shortcut`	string	`""`	Raccourci affiché à droite de l'entrée et actif : il la choisit où que soit le focus et lève `ue_menu_selected` comme un clic — pas si l'entrée, un niveau au-dessus ou son déroulant est grisé ou masqué. Relu tel qu'écrit ; `""` le retire. Même règle que pour un outil : Ctrl ou Alt, ou F1 à F24
`is_image`	string	`""`	Icône de l'entrée, affichée à la prochaine ouverture du menu ; `""` la retire

Les images acceptent toutes les formes reconnues par la bibliothèque : chemin, mono:, tint:, ressource de DLL. Une entrée de menu prend les cinq couleurs d'item (il_back_color, il_text_color, leurs variantes de survol, il_accent), dessinées dans le menu ; elle n'affiche pas d'info-bulle — un menu natif n'en a pas.

Événements #

Événement	Déclenché quand
`ue_clicked (string as_keys)`	Un bouton — ou la partie principale d'un bouton partagé — est déclenché : par un clic, par son raccourci, ou depuis le panneau du chevron quand il est replié. `as_keys` est son adresse, `"main/save"`
`ue_toggled (string as_keys, boolean ab_checked)`	Une bascule change d'état ; `ab_checked` porte le nouvel état. Levé par un geste de l'utilisateur seulement : poser `ib_checked` ne le lève pas. Dans un groupe (`is_group`), seule la bascule pressée le lève
`ue_menu_selected (string as_keys)`	Une entrée de menu déroulant est choisie — à la souris, au clavier ou par son raccourci, dans la barre comme dans le panneau du chevron. `as_keys` est son adresse complète, `"main/export/img/png"`. Vaut pour le menu d'un bouton partagé comme pour celui d'un déroulant ; l'entrée elle-même est le dernier niveau de l'adresse
`ue_text_changed (string as_keys, string as_text)`	Un champ de saisie est validé (Entrée ou perte du focus) ; Entrée s'arrête au champ et n'actionne pas le bouton par défaut de la fenêtre. Échap rend au champ son texte sans le lever, et poser `is_text` ne le lève pas
`ue_date_changed (string as_keys, string as_date)`	Une date est choisie (`"aaaa-mm-jj"`). Levé par un choix de l'utilisateur dans le calendrier seulement ; poser `is_date` ne le lève pas
`ue_combo_changed (string as_keys, string as_text)`	L'utilisateur a choisi une valeur dans la liste d'une liste déroulante, ou en a tapé une dans une liste modifiable et l'a validée (Entrée, ou en quittant le champ) — dans la barre ou dans le panneau du chevron. `as_text` est la valeur, `as_keys` = `barre/outil`. Une valeur tapée ne le lève que si elle a changé ; Échap rend la valeur sans le lever ; `is_text` posé par votre code ne lève rien. L'event du ruban : même nom, même sens
`ue_bar_reordered (string as_key, integer ai_band, integer ai_index)`	L'utilisateur a fait glisser une barre par sa poignée vers une autre bande ou un autre rang (demande `ib_reorderable`). Dit quelle barre a bougé et où elle atterrit, là où `ue_layout_changed` porte l'arrangement entier. Bande et rang partent de 1, comme `ii_band` et `ii_index`
`ue_layout_changed (string as_layout_json)`	L'arrangement a changé — l'utilisateur a fait glisser une barre à la poignée, ou votre propre code en a déplacé ou masqué une, ou a remis une disposition par `of_set_layout`. Porte la disposition entière, pas seulement ce qui a bougé , bandes et rangs comptés à partir de 1 : à stocker telle quelle et à rendre à `of_set_layout`. Un ajout de barre qui en pousse une autre le lève aussi ; rien n'est levé quand rien n'a bougé (réafficher une barre déjà visible)
`ue_item_rclicked (string as_keys)`	Clic droit sur un outil (un outil grisé ne dit rien) ; `as_keys` est son adresse. Ouvrez-y votre propre menu contextuel. Un clic droit hors de tout outil lève `ue_rclicked` à la place — jamais les deux
`ue_rclicked ( )`	Clic droit sur la barre hors de tout outil (un clic droit sur un outil lève `ue_item_rclicked` seul)
`ue_mouse_enter ( )`	La souris entre dans la barre
`ue_mouse_leave ( )`	La souris quitte la barre
`ue_auto_height (long al_height)`	La hauteur idéale a changé et la barre s'y est ajustée — toujours actif : le nombre de rangées dicte la hauteur
`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`)

Exemples #

Bascules pré-cochées et outil grisé #

// Deux bascules, un separateur, un bouton
uo_toolbar.of_add_toggle(/*keys*/ uo_toolbar.MAIN_BAR + "/bold",   /*text*/ "", /*image*/ "mono:img\bold.svg",   /*tooltip*/ "Gras")
uo_toolbar.of_add_toggle(/*keys*/ uo_toolbar.MAIN_BAR + "/italic", /*text*/ "", /*image*/ "mono:img\italic.svg", /*tooltip*/ "Italique")
uo_toolbar.of_add_separator(/*keys*/ uo_toolbar.MAIN_BAR)
uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/undo",   /*text*/ "", /*image*/ "mono:img\undo.svg",   /*tooltip*/ "Annuler")

// Chaque outil se pilote par son handle, obtenu depuis SA barre
uo_toolbar.of_item(/*keys*/ uo_toolbar.MAIN_BAR + "/bold").ib_checked = true    // bascule pre-cochee
uo_toolbar.of_item(/*keys*/ uo_toolbar.MAIN_BAR + "/undo").ib_enabled = false   // rien a annuler pour l'instant

// event ue_toggled de uo_toolbar
if as_keys = "main/bold" then of_apply_bold(ab_checked)

// Le menu se remplit depuis le composant : trois niveaux, barre/deroulant/entree
uo_toolbar.of_add_dropdown(/*keys*/ uo_toolbar.MAIN_BAR + "/export", /*text*/ "Exporter", &
                                   /*image*/ "mono:img\save.svg", /*tooltip*/ "Exporter le dossier")
uo_toolbar.of_add_menu_item(/*keys*/ uo_toolbar.MAIN_BAR + "/export/exp_pdf", /*label*/ "PDF",  /*image*/ "")
uo_toolbar.of_add_menu_item(/*keys*/ uo_toolbar.MAIN_BAR + "/export/exp_csv", /*label*/ "CSV",  /*image*/ "")
uo_toolbar.of_add_menu_separator(/*keys*/ uo_toolbar.MAIN_BAR + "/export")

// Sous-menu : un QUATRIEME niveau, l entree sous laquelle il se niche
uo_toolbar.of_add_menu_item(/*keys*/ uo_toolbar.MAIN_BAR + "/export/exp_img", /*label*/ "Image...", /*image*/ "")
uo_toolbar.of_add_menu_item(/*keys*/ uo_toolbar.MAIN_BAR + "/export/exp_img/exp_png", /*label*/ "PNG", /*image*/ "")
uo_toolbar.of_add_menu_item(/*keys*/ uo_toolbar.MAIN_BAR + "/export/exp_img/exp_jpg", /*label*/ "JPEG", /*image*/ "")

// Une entree se pilote par SA poignee, a son adresse
uo_toolbar.of_menu_item(/*keys*/ uo_toolbar.MAIN_BAR + "/export/exp_csv").ib_enabled = false

// event ue_menu_selected de uo_toolbar : (as_keys)
n_pbt_utils lnv_utils   // autoinstantiate : rien a creer, rien a detruire
string ls_ids[]

// Une entree du menu Export : sa feuille dit le format
if lnv_utils.of_split_path(/*keys*/ as_keys, /*out*/ ls_ids) >= 3 then
	if ls_ids[2] = "export" then of_export(ls_ids[UpperBound(ls_ids)])
end if

Champ de recherche et sélecteur de date #

// Un bouton avec son raccourci, puis un separateur
uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/save", /*text*/ "", /*image*/ "mono:img\save.svg", /*tooltip*/ "Enregistrer")
uo_toolbar.of_item(/*keys*/ uo_toolbar.MAIN_BAR + "/save").is_shortcut = "Ctrl+S"    // raccourci actif et affiche
uo_toolbar.of_add_separator(/*keys*/ uo_toolbar.MAIN_BAR)

// 160 px de large ; la saisie remonte a la validation
uo_toolbar.of_add_textbox(/*keys*/ uo_toolbar.MAIN_BAR + "/search", /*text*/ "", /*width*/ 160, /*tooltip*/ "Rechercher (Entree pour valider)")

// Une etiquette devant un selecteur de date
uo_toolbar.of_add_label(/*keys*/ uo_toolbar.MAIN_BAR + "/lbl_due", /*text*/ "Echeance :")
uo_toolbar.of_add_datepicker(/*keys*/ uo_toolbar.MAIN_BAR + "/due", /*date*/ "2026-07-11", /*tooltip*/ "Date d'echeance")

// event ue_text_changed de uo_toolbar
if as_keys = "main/search" then of_filter(as_text)

// event ue_date_changed de uo_toolbar : as_date au format "aaaa-mm-jj"
if as_keys = "main/due" then id_due_date = Date(as_date)

Deux barres et disposition mémorisée #

Avec ib_reorderable = true, l'utilisateur peut saisir une barre par sa poignée (à gauche de la barre) et la déplacer sur une autre bande ou à une autre position. Conservez la disposition à la fermeture, restituez-la à l'ouverture.

// Sans cette ligne, aucune poignee : l utilisateur ne peut rien deplacer
uo_toolbar.ib_reorderable = true

// La barre principale et ses deux boutons
uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/new",  /*text*/ "Nouveau", /*image*/ "", /*tooltip*/ "")
uo_toolbar.of_add_button(/*keys*/ uo_toolbar.MAIN_BAR + "/open", /*text*/ "Ouvrir",  /*image*/ "", /*tooltip*/ "")

// Seconde barre, posee sur la bande 2 (deuxieme rangee), en premiere position
uo_toolbar.of_add_bar(/*key*/ "format", /*band*/ 2, /*index*/ 1)
uo_toolbar.of_add_toggle(/*keys*/ "format/bold", /*text*/ "G", /*image*/ "", /*tooltip*/ "Gras")

// On peut aussi replacer une barre a tout moment par ses proprietes
uo_toolbar.of_bar(/*key*/ "format").ii_band  = 1
uo_toolbar.of_bar(/*key*/ "format").ii_index = 2    // deuxieme barre de la premiere rangee

// event ue_layout_changed de uo_toolbar : conserver la disposition choisie
is_layout = as_layout_json

// A l'ouverture suivante : restituer ce que l'utilisateur avait arrange
if is_layout <> "" then uo_toolbar.of_set_layout(/*layout_json*/ is_layout)

Bouton partagé et bascules exclusives #

// Coller : la partie principale colle tout de suite, la fleche propose les autres facons
uo_toolbar.of_add_split_button(/*keys*/ "edit/paste", /*text*/ "", /*image*/ "mono:img\paste.svg", /*tooltip*/ "Paste")
uo_toolbar.of_add_menu_item(/*keys*/ "edit/paste/plain", /*label*/ "Plain text", /*image*/ "")
uo_toolbar.of_add_menu_item(/*keys*/ "edit/paste/special", /*label*/ "Paste special...", /*image*/ "")

// Les bascules d alignement partagent un groupe : une seule enfoncee a la fois
uo_toolbar.of_add_toggle(/*keys*/ "edit/left", /*text*/ "", /*image*/ "mono:img\left.svg", /*tooltip*/ "Left")
uo_toolbar.of_add_toggle(/*keys*/ "edit/center", /*text*/ "", /*image*/ "mono:img\center.svg", /*tooltip*/ "Center")
uo_toolbar.of_add_toggle(/*keys*/ "edit/right", /*text*/ "", /*image*/ "mono:img\right.svg", /*tooltip*/ "Right")
uo_toolbar.of_item(/*keys*/ "edit/left").is_group = "align"
uo_toolbar.of_item(/*keys*/ "edit/center").is_group = "align"
uo_toolbar.of_item(/*keys*/ "edit/right").is_group = "align"
uo_toolbar.of_item(/*keys*/ "edit/left").ib_checked = true

// event ue_clicked de uo_toolbar : la partie principale du bouton partage
if as_keys = "edit/paste" then of_paste()

// event ue_toggled de uo_toolbar : seule la bascule enfoncee le leve
if ab_checked and Left(as_keys, 5) = "edit/" then of_align(Mid(as_keys, 6))

Débordement : « Plus d'outils » #

Quand la largeur ne suffit plus, les outils qui ne tiennent pas sont repliés dans un menu Plus d'outils signalé par un chevron en fin de barre. C'est automatique, il n'y a rien à programmer : les outils repliés restent cliquables et déclenchent les mêmes events. Un champ replié — zone de saisie ou sélecteur de date — reste un vrai champ : on y tape, on y choisit une date, et l'event part comme si l'outil était resté dans la barre.

Hauteur automatique #

Rien à activer : le nombre de rangées (of_set_layout) dicte la hauteur, la barre s'y ajuste seule et vous prévient.

// event ue_auto_height de uo_toolbar
uo_content.y      = uo_toolbar.y + al_height
uo_content.height = parent.workspaceheight() - uo_content.y

Voir Socle commun.

Bonnes pratiques #

Servez-vous de MAIN_BAR tant qu'une seule barre suffit : elle naît à son premier outil, inutile de l'ajouter. Pour la placer ailleurs qu'après les autres barres, ajoutez-la avant tout outil — of_add_bar(MAIN_BAR, 1, 1) ; une fois née, of_add_bar(MAIN_BAR) rend -5 et elle se déplace par of_bar(MAIN_BAR).ii_band.
Sur une toolbar, of_register_shortcut prend l'adresse de l'outil ou de l'entrée qu'il déclenche. Un raccourci demande Ctrl ou Alt, ou une touche F1 à F24 : une touche seule reste à la saisie.
Rangez toujours un outil par son chemin — of_item("main/save") — et non par son seul identifiant : c'est ce qui rend les identifiants réutilisables d'une barre à l'autre.
Groupez les outils apparentés avec of_add_separator("main") plutôt que par des barres supplémentaires.
Sur les boutons à icône seule, renseignez toujours l'info-bulle : c'est le seul libellé dont dispose l'utilisateur.
Si vous laissez l'utilisateur réorganiser les barres, mémorisez ue_layout_changed et rejouez of_set_layout à l'ouverture, sinon l'effort est perdu à chaque lancement.
Appelez of_reset() avant de reconstruire entièrement la barre d'outils pour un autre contexte.
Quand les commandes deviennent trop nombreuses pour une barre, passez au ribbon, organisé par onglets et groupes.

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
`of_set_property` · `of_get_property` · `of_component_name`	Piloter une propriété par son nom	3.1 Le moteur de propriétés

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.