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)
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_enregistrer()
    case "main/find" ; of_rechercher()
    case "main/help" ; of_aide()
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.

uo_toolbar.of_bar("main").of_item("save").ib_enabled = false

Les ajouts vivent eux aussi sur le handle du parent : on ajoute un outil à une barre, pas à la barre d'outils. Voir Socle commun · Les items pour le principe général.

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
`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, toujours disponible sans avoir à la créer

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)
`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 appliqué, `-5` sur un argument invalide (clé vide, adresse fausse), `-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
`of_add_bar (string as_key)` → `long`	Ajoute une barre et renvoie `0` (`-5` sur un argument invalide, `-2` si le composant n'est pas créé)
`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 0). Renvoie `0` une fois appliqué, `-2` si le composant n'est pas créé
`of_remove_bar (string as_key)`	Retire une barre et ses outils. 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 appliqué, `-5` sur un argument invalide (clé vide, adresse fausse), `-2` si le composant n'est pas créé
`of_get_layout ()`	Relit la disposition courante en JSON : quelle barre sur quelle bande, à quel rang, et visible ou non. À stocker, puis à rendre par `of_set_layout`
`of_set_layout (string as_layout_json)`	Restaure une disposition de barres précédemment reçue par `ue_layout_changed`. Renvoie `0` une fois appliqué, `-5` sur un argument invalide (clé vide, adresse fausse), `-2` si le composant n'est pas créé
`of_clear ( )`	Supprime toutes les barres et tous les outils. 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 appliqué, `-5` sur un argument invalide (clé vide, adresse fausse), `-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 ; un choix déclenche `ue_menu_selected`. Renvoie `0` une fois appliqué, `-5` sur un argument invalide (clé vide, adresse fausse), `-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 appliqué, `-5` sur un argument invalide (clé vide, adresse fausse), `-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`. `ai_width` en pixels. Renvoie `0` une fois appliqué, `-5` sur un argument invalide (clé vide, adresse fausse), `-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`. Dates au format `"aaaa-mm-jj"`. 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)`	Trait vertical de séparation. Renvoie `0` une fois appliqué, `-5` sur un argument invalide (clé vide, adresse fausse), `-2` si le composant n'est pas créé
`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 = 0) plutôt qu'à la fin. Renvoie `0` une fois appliqué, `-5` sur un argument invalide (clé vide, adresse fausse), `-2` si le composant n'est pas créé
`of_move_item (string as_keys, integer ai_index)`	Déplace un outil à une autre position dans cette barre (premier = 0). Il garde son type, son menu et son état vivant : l'outil change de place, il n'est pas reconstruit. Vaut pour tous les types, donc les `of_add_` sans `of_insert_` insèrent en ajoutant puis en déplaçant. Renvoie `0` une fois appliqué, `-5` sur un argument invalide (clé vide, adresse fausse), `-2` si le composant n'est pas créé
`of_remove_item (string as_keys)`	Retire un outil de cette barre. La barre reste, et tout le reste avec elle, état vivant compris — seul l'outil nommé s'en va. Pour le faire aller et venir, `ib_visible` sur son handle le garde dans le modèle. Renvoie `0` une fois appliqué, `-5` sur un argument invalide (clé vide, adresse fausse), `-2` si le composant n'est pas créé
`of_add_menu_item (string as_keys, string as_label, string as_image)`	Entrée du menu d'un bouton déroulant ; entrée en cascade, rangée sous une entrée existante. Renvoie `0` une fois appliqué, `-5` sur un argument invalide (clé vide, adresse fausse), `-2` si le composant n'est pas créé
`of_add_menu_separator (string as_keys)`	Trait de séparation dans le menu. Renvoie `0` une fois appliqué, `-5` sur un argument invalide (clé vide, adresse fausse), `-2` si le composant n'est pas créé

Sur une barre — `n_pbt_toolbar_bar` #

Membre	Type	Défaut	Rôle
`ii_band`	integer	`0`	Bande (rangée) qui porte la barre ; `0` = première rangée
`ii_index`	integer	`0`	Position de la barre dans sa bande
`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

Les images acceptent toutes les formes reconnues par la bibliothèque : chemin, mono:, tint:, ressource de DLL.

Événements #

Événement	Déclenché quand
`ue_clicked (string as_keys)`	Un bouton est cliqué (ou déclenché par son raccourci)
`ue_toggled (string as_keys, boolean ab_checked)`	Une bascule change d'état ; `ab_checked` porte le nouvel état
`ue_menu_selected (string as_keys)`	Une entrée de menu déroulant est choisie
`ue_text_changed (string as_keys, string as_text)`	Un champ de saisie est validé (Entrée ou perte du focus)
`ue_date_changed (string as_keys, string as_date)`	Une date est choisie (`"aaaa-mm-jj"`)
`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
`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. Porte la disposition entière, pas seulement ce qui a bougé
`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é #



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_key = "bold" then of_appliquer_gras(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*/ "")

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

if lnv_utils.of_split_path(as_keys, ls_ids) = 3 then
	if ls_ids[2] = "export" then of_exporter(ls_ids[3])
end if

Champ de recherche et sélecteur de date #



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)")

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_key = "search" then of_filtrer(as_text)

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

Deux barres et disposition mémorisée #

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.



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 1 (deuxieme rangee), en premiere position

uo_toolbar.of_add_toggle(/*keys*/ /*bar*/ "format", /*band*/ 1, /*index*/ 0 + "/bold", /*text*/ "G", /*image*/ "", /*tooltip*/ "Gras")

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

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

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

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_contenu.y      = uo_toolbar.y + al_height
uo_contenu.height = parent.workspaceheight() - uo_contenu.y

Voir Socle commun.

Bonnes pratiques #

Servez-vous de MAIN_BAR tant qu'une seule barre suffit : elle existe déjà, inutile de l'ajouter.
Rangez toujours un outil par son chemin — of_bar(...).of_item(...) — 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() 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

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.