button — `u_pbt_button` #

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

Bouton thémé : texte et icône, styles, badge de compteur, raccourci clavier, boutons par défaut et d'annulation.

⚠️ Plusieurs boutons ? Utilisez plutôt buttonbar : une rangée de boutons dans un seul composant, là où N button séparés coûtent N fois plus de mémoire (chaque composant est une vue du moteur). button reste pris en charge pour le code existant.

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

En bref #

Userobject	`u_pbt_button`
Classe d'items	— (composant sans items)
Sert à	Remplacer un `commandbutton` par un bouton moderne, thémé, avec icône et badge
Options opt-in	`ib_track_mouse`

Démarrage rapide #

// event open de la fenetre
uo_button.is_text  = "&Enregistrer"          // & = lettre soulignee : Alt+E le declenche
uo_button.is_style = uo_button.STYLE_PRIMARY // bouton d'action principale
uo_button.is_image = "mono:img\save.svg"     // icone recoloree par le theme
uo_button.is_shortcut = "Ctrl+S"             // raccourci affiche et actif
uo_button.is_tooltip = "Enregistre le dossier en cours"

// event ue_clicked de uo_button
of_save()

Constantes #

Constante	Valeur	Pour
`STYLE_STANDARD` · `STYLE_PRIMARY` · `STYLE_FLAT`	`"standard"` `"primary"` `"flat"`	`is_style`

Propriétés #

Propriété	Type	Défaut	Rôle
`is_text`	string	`""`	Libellé. Accepte le balisage riche et le mnémonique `&` (`&Enregistrer` souligne le E, et Alt+E le déclenche où que soit le focus dans la fenêtre, après les raccourcis explicites et jamais s'il est grisé ; une barre de menus PB qui utilise la même lettre la perd) ; `&&` affiche une esperluette littérale. Un libellé fait d'une seule image (`[picture=…]`) est permis
`is_image`	string	`""`	Icône affichée avant le libellé (formes acceptées : chemin, `mono:`, `tint:`, ressource de DLL)
`ii_image_size`	integer	`0`	Taille de l'icône en pixels (`0` = la taille du thème, 18 pixels)
`is_style`	string	`"standard"`	Apparence : `STYLE_STANDARD`, `STYLE_PRIMARY` (fond d'accent, action principale), `STYLE_FLAT` (sans bordure)
`ib_enabled`	boolean	`true`	Bouton actif ou grisé. Grisé, il ignore souris et clavier, sort de l'ordre de tabulation et rend à la fenêtre Entrée, Échap, son raccourci et son mnémonique
`ib_default`	boolean	`false`	Bouton par défaut : Entrée le déclenche où que soit le focus dans la fenêtre, tant qu'il est actif ; un liseré d'accent le signale. Avec deux boutons par défaut, le plus proche du focus gagne, et à égalité aucun
`ib_cancel`	boolean	`false`	Bouton d'annulation : Échap le déclenche où que soit le focus dans la fenêtre, tant qu'il est actif
`is_shortcut`	string	`""`	Raccourci clavier (`"Ctrl+S"`, `"F5"`, `"Ctrl+Shift+N"`), actif où que soit le focus dans la fenêtre et ajouté à l'info-bulle (« Enregistrer (Ctrl+S) »). Les noms de touches s'écrivent en anglais (`Enter`, `Esc`, `Del`, `PageUp`…) ; un raccourci que la fenêtre ne sait pas déclencher (modificateur ou touche inconnus) est refusé et se relit `""`
`ii_badge`	integer	`0`	Pastille de compteur dans l'angle supérieur de fin (droit, gauche de droite à gauche) ; au-delà de 99 elle affiche `99+` (`0` = aucune)
`il_badge_color`	long	`-1`	Fond de la pastille, en RGB PowerBuilder (`-1` = non posée : la couleur qui vient du thème ; `0` est le noir, comme pour toute autre couleur). La couleur du texte est choisie automatiquement pour que le compteur reste lisible
`ii_badge_size`	integer	`0`	Hauteur de la pastille en pixels (`0` = la taille qui vient du thème). La taille de la police suit toute seule : le compteur reste centré quelle que soit la dimension
`ib_track_mouse`	boolean	`false`	Opt-in : active `ue_mouse_enter` / `ue_mouse_leave`
`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

Méthodes #

Méthode	Rôle
`of_reset ( )`	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_clicked ( )`	Le bouton est cliqué, ou déclenché par Entrée / Échap / son raccourci
`ue_rclicked ( )`	Clic droit sur le bouton
`ue_mouse_enter ( )`	La souris entre — nécessite `ib_track_mouse = true`
`ue_mouse_leave ( )`	La souris sort — nécessite `ib_track_mouse = true`
`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 #

Les trois styles #

// Le bouton principal : il repond a Entree
uo_ok.is_text     = "Valider"
uo_ok.is_style    = uo_ok.STYLE_PRIMARY
uo_ok.ib_default  = true          // touche Entree

// Le bouton d'annulation : il repond a Echap
uo_cancel.is_text   = "Annuler"
uo_cancel.is_style  = uo_cancel.STYLE_STANDARD
uo_cancel.ib_cancel = true       // touche Echap

// Un bouton d'aide discret
uo_help.is_text  = "Aide"
uo_help.is_style = uo_help.STYLE_FLAT   // discret, sans bordure

Icône et badge de notification #

// Une icone plus grande et une pastille de compteur
uo_messages.is_text  = "Messages"
uo_messages.is_image = "mono:img\mail.svg"
uo_messages.ii_image_size = 20
uo_messages.ii_badge = 12             // pastille "12"

// Mettre le compteur a jour : la pastille disparait a 0
uo_messages.ii_badge = ll_unread

// Une pastille rouge pour une alerte, plutot que la couleur du theme.
// La couleur du texte est choisie toute seule pour rester lisible.
uo_messages.il_badge_color = RGB(/*red*/ 200, /*green*/ 30, /*blue*/ 30)

// Revenir a la couleur qui vient du theme
uo_messages.il_badge_color = -1

Libellé enrichi #

// Du texte riche : gras et taille reduite, ou une image dans le texte
uo_button.is_text = "[b]Exporter[/b] [size-=20]· CSV[/size-=20]"
uo_button.is_text = "Statut [picture=mono:img\ok.svg,14,14]"

Bouton d'action principale avec raccourci et aide #

// Geler le dessin pendant les reglages
uo_submit.of_set_redraw(/*on*/ false)

// Texte, style, raccourci, bouton par defaut et infobulle riche
uo_submit.is_text     = "&Valider la commande"
uo_submit.is_style    = uo_submit.STYLE_PRIMARY
uo_submit.is_shortcut = "Ctrl+Enter"
uo_submit.ib_default  = true
uo_submit.is_super_tooltip_title = "Valider"
uo_submit.is_super_tooltip_text  = "Envoie la commande au fournisseur." &
                                    + "[br][br][size-=15]Action irréversible.[/size-=15]"

// Un seul dessin, avec tout
uo_submit.of_set_redraw(/*on*/ true)

Réagir au survol #

// Raise ue_mouse_enter and ue_mouse_leave when the pointer comes and goes
uo_button.ib_track_mouse = true

// event ue_mouse_enter de uo_button
uo_status.of_panel(/*key*/ "main").is_text = "Enregistre le dossier en cours"

Bonnes pratiques #

Un seul bouton primary par écran : c'est l'action attendue.
ib_default et ib_cancel remplacent la gestion manuelle d'Entrée / Échap dans votre fenêtre.
Utilisez mono: pour les icônes monochromes : elles suivront le thème clair comme sombre.
Appelez of_reset() avant de réutiliser un bouton pour une autre action.

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_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.