statusbar — u_pbt_statusbar #

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

Barre d'état à panneaux : texte riche, icônes, largeurs fixes ou automatiques, alignement à gauche ou à droite, panneaux cliquables, mini-barre de progression et états colorés.

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

En bref #

Démarrage rapide #

// event open de la fenetre
// of_add_panel(cle, texte, icone, alignement, largeur)
// la cle retrouve le panneau plus tard ; largeur 0 = ajustee au texte, -1 = prend la place libre
uo_status.of_add_panel(/*key*/ "state", /*text*/ "Ready",          /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ -1)
uo_status.of_add_panel(/*key*/ "pos",   /*text*/ "Line 12, Col 4", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 0)
uo_status.of_add_panel(/*key*/ "clock", /*text*/ "12:00",          /*icon_file*/ "", /*align*/ uo_status.ALIGN_END,   /*width*/ 140)

// Mettre un panneau a jour a tout moment, par son identifiant
uo_status.of_panel(/*key*/ "state").is_text = "Enregistrement en cours..."

Le modèle : des panneaux à clé #

La barre est une suite de panneaux, ajoutés dans l'ordre. Un panneau reçoit un identifiant à la création : c'est par lui qu'on le retrouve ensuite pour changer son texte, son icône ou son état.

L'identifiant est une clé d'adressage, pas un interrupteur d'interactivité :

• Identifiant renseigné : le panneau est retrouvable — on change son contenu, on lui pose une info-bulle. Il reste inerte : une barre d'état affiche avant tout, et un panneau comme Ligne 12, Col 4 ne doit pas avoir l'air pressable. Il reçoit pourtant le clic droit (ue_panel_rclicked) : un menu contextuel « Copier » n'est pas une activation.
• Identifiant vide : le panneau est purement décoratif. Il n'est ni retrouvable, ni cliquable, et aucune info-bulle ne peut lui être attachée. Donnez un identifiant à tous vos panneaux : ça ne coûte rien et ça garde la porte ouverte. Il compte pourtant dans of_count et dans les positions, et of_keys_at rend une clé vide pour lui.
• Pour rendre un panneau cliquable, demandez-le : of_panel(/*key*/ "id").ib_clickable = true. Un panneau doté d'une liste déroulante (of_add_menu_item) l'est d'office.

// Le panneau affiche un nouveau texte
uo_status.of_panel(/*key*/ "state").is_text = "3 enregistrements modifies"

Voir Socle commun · Les items.

Propriétés #

Méthodes #

Les arguments de of_add_panel #

Sur un panneau — n_pbt_statusbar_panel #

Sur une entrée de liste — n_pbt_statusbar_menu_item #

Obtenue par of_menu_item(/*keys*/ "enc/utf8") : l'adresse a deux niveaux, le panneau puis l'entrée. La liste est un menu natif : une propriété changée pendant qu'il est ouvert se voit à l'ouverture suivante.

Les propriétés que toute poignée d'item hérite — is_tooltip, is_super_tooltip_title, is_super_tooltip_text, is_super_tooltip_image, il_accent, il_back_color, il_text_color, il_back_color_hover, il_text_color_hover — sont sans effet sur une entrée : la liste est un menu natif, qui ne montre ni infobulle ni couleur d'une entrée. Elles sont ignorées et se relisent vides (-1 pour une couleur). Une position dans une liste compte des entrées : un séparateur n'en est pas une, et of_count("enc"), of_keys_at("enc", n), of_has("enc/utf8") parcourent les entrées d'un panneau. Une clé qui commence par __ est réservée au composant.

// The menu of the encoding panel, entry by entry
uo_status.of_add_menu_item(/*keys*/ "enc/utf8", /*label*/ "UTF-8")
uo_status.of_add_menu_item(/*keys*/ "enc/ansi", /*label*/ "ANSI")
uo_status.of_menu_item(/*keys*/ "enc/utf8").ib_checked = true     // the current value
uo_status.of_menu_item(/*keys*/ "enc/ansi").ib_enabled = false    // not available here

Constantes d'état #

Comme pour toute propriété à valeurs prédéfinies, utilisez la constante plutôt que la chaîne :

// The panel takes the colors of a warning
uo_status.of_panel(/*key*/ "state").is_state = n_pbt_statusbar_panel.STATE_WARNING

Événements #

Au clavier #

La barre est un seul arrêt de tabulation : seuls les panneaux faits pour être cliqués y entrent, et les flèches les parcourent.

Un panneau qui se contente d'afficher n'est pas un contrôle : il n'est ni focalisable ni annoncé comme tel. Un panneau cliquable mais désactivé reste, lui, annoncé comme indisponible plutôt que de passer pour du texte. Une barre de progression annonce sa valeur, et une progression indéterminée n'en annonce aucune — cette absence est le sens du mot. Un panneau cliquable grisé montre toujours son infobulle — celle qui dit pourquoi il est grisé — et un panneau à liste dit si sa liste est ouverte.

Un lecteur d'écran entend les messages de of_flash_panel sans que le focus bouge : c'est le rôle d'une barre d'état (une région vivante polie). Les autres changements — un nouveau texte, un nouvel état — ne sont lus qu'avec ib_announce = true, sans quoi une horloge à la seconde parlerait toute la journée.

Le focus survit à la reconstruction de la barre : un panneau ajouté, retiré, masqué ou grisé la reconstruit, et le focus revient sur le même panneau (sur le suivant quand il ne peut plus le prendre). Un texte, un état ou une progression changent sur place, sans rien reconstruire — une horloge à la seconde ne vole jamais le focus.

Exemples #

Largeurs fixes et largeurs automatiques #

// Largeur 0 : le panneau prend exactement la place de son texte
uo_status.of_add_panel(/*key*/ "", /*text*/ "Panneau ajuste au contenu", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 0)

// Largeur fixe en pixels : utile quand le texte change souvent,
// pour que les panneaux voisins ne bougent pas a chaque mise a jour
uo_status.of_add_panel(/*key*/ "pos", /*text*/ "Ligne 1, Col 1", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 150)

// Un panneau pousse a l'extremite opposee
uo_status.of_add_panel(/*key*/ "clock", /*text*/ "12:00", /*icon_file*/ "", /*align*/ uo_status.ALIGN_END, /*width*/ 140)

Icônes et panneaux cliquables #

// Une cle rend le panneau adressable ; ib_clickable le rend cliquable
uo_status.of_add_panel(/*key*/ "save", /*text*/ "Enregistre", /*icon_file*/ "mono:img\save.svg", /*align*/ uo_status.ALIGN_START, /*width*/ 0)
uo_status.of_add_sep()   // trait de separation entre deux groupes de panneaux
uo_status.of_add_panel(/*key*/ "conn", /*text*/ "Connecte",   /*icon_file*/ "mono:img\plug.svg", /*align*/ uo_status.ALIGN_START, /*width*/ 0)
uo_status.of_add_panel(/*key*/ "user", /*text*/ "Alex Martin",  /*icon_file*/ "mono:img\user.svg", /*align*/ uo_status.ALIGN_END, /*width*/ 160)

// Seuls ces deux-la repondent au clic (ue_panel_clicked)
uo_status.of_panel(/*key*/ "conn").ib_clickable = true
uo_status.of_panel(/*key*/ "user").ib_clickable = true

// event ue_panel_clicked de uo_status
choose case as_key
    case "conn" ; open(w_connection_settings)
    case "user" ; open(w_profile)
end choose

Texte riche dans un panneau #

Les panneaux acceptent le balisage riche : styles, couleurs et petites images directement dans le texte.

// Un accueil a gauche
uo_status.of_add_panel(/*key*/ "", /*text*/ "Bienvenue [b]dans[/b] [accent]PBToolboxAI[/accent]", &
                       /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 0)

// L'etat de la connexion a droite
uo_status.of_add_panel(/*key*/ "", /*text*/ "[green]En ligne[/green] [picture=mono:img\plug.svg,14,14]", &
                       /*icon_file*/ "", /*align*/ uo_status.ALIGN_END, /*width*/ 0)

// Variables locales
long ll_changed

// Le texte riche vaut aussi pour les mises a jour
ll_changed = dw_list.ModifiedCount()
uo_status.of_panel(/*key*/ "state").is_text = "[b]" + String(ll_changed) + "[/b] records changed"

Suivre un traitement long #

// Local variables
n_pbt_statusbar_panel lnv_import

// Le panneau d'import, puis son handle pour le suivre
uo_status.of_add_panel(/*key*/ "import", /*text*/ "Import", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ 220)
lnv_import = uo_status.of_panel(/*key*/ "import")

// Variables locales
long ll_percent

// Dans la boucle de traitement : la mini-barre suit l'avancement
for ll_percent = 0 to 100 step 25
    lnv_import.ii_progress = ll_percent
    lnv_import.is_text     = "Import " + String(ll_percent) + " %"
next

// A la fin : masquer la mini-barre et signaler le resultat
lnv_import.ii_progress = -1                       // valeur negative = barre masquee
lnv_import.is_text     = "Import termine"
lnv_import.is_state    = lnv_import.STATE_SUCCESS

Signaler une alerte discrète #

// Local variables
n_pbt_statusbar_panel lnv_panel

// Le panneau de la connexion
lnv_panel = uo_status.of_panel(/*key*/ "conn")

// Hors ligne : le panneau signale une erreur ; connecte : il redevient normal
if not ib_connected then
    lnv_panel.is_text  = "Hors ligne"
    lnv_panel.is_state = lnv_panel.STATE_ERROR
else
    lnv_panel.is_text  = "Connecte"
    lnv_panel.is_state = lnv_panel.STATE_NONE   // retour a l'apparence normale
end if

Adapter la barre au contexte #

// Masquer un panneau sans le supprimer : il retrouvera sa place plus tard
uo_status.of_panel(/*key*/ "user").ib_visible = ib_user_signed_in

// Le griser quand l'action correspondante n'a pas de sens
uo_status.of_panel(/*key*/ "save").ib_enabled = ib_document_open

// Reorganiser : placer le panneau d'etat en tete (positions comptees a partir de 1)
uo_status.of_move_panel(/*key*/ "state", /*index*/ 1)

// Retirer un panneau devenu inutile
uo_status.of_remove_panel(/*key*/ "import")

La poignée de redimensionnement #

// Tirer la poignee de coin redimensionne la fenetre qui porte la barre (masquee quand elle est maximisee)
uo_status.ib_show_resize_grip = true

Un panneau qui prend la place libre #

Comme le panneau « Prêt » de toute barre d'état Windows : il grandit avec la fenêtre, pousse les panneaux de fin au bout, et c'est son texte qui s'élide le premier quand la place manque.

// Une largeur de -1 : le panneau prend toute la place libre
uo_status.of_add_panel(/*key*/ "state", /*text*/ "Ready", /*icon_file*/ "", /*align*/ uo_status.ALIGN_START, /*width*/ -1)
uo_status.of_add_panel(/*key*/ "clock", /*text*/ "12:00", /*icon_file*/ "", /*align*/ uo_status.ALIGN_END, /*width*/ 140)

// La meme chose sur un panneau qui existe deja
uo_status.of_panel(/*key*/ "state").ib_spring = true

Placer la barre au bas de la fenêtre #

of_dock_bottom la pose le long du bord bas de ce qui la porte, sur toute la largeur : un appel dans l'événement resize suffit. Dans un cadre MDI, les feuilles se partagent ce qui reste au-dessus.

// event resize de la fenetre : la barre suit le bord bas
uo_status.of_dock_bottom()

// event resize d'un cadre MDI : la barre en bas, les feuilles au-dessus
uo_status.of_dock_bottom()
mdi_1.Resize(WorkSpaceWidth(), WorkSpaceHeight() - uo_status.Height)

Reprendre la MicroHelp #

Dans un cadre MDI à MicroHelp, PowerBuilder écrit l'aide de l'élément de menu sous le pointeur, et SetMicroHelp écrit la vôtre. La barre reprend ce rôle : nommez une fois le panneau qui affiche l'aide (is_help_panel), puis écrivez is_help là où vous appeliez SetMicroHelp. L'aide s'affiche par-dessus le texte du panneau, et "" le lui rend.

// Une fois : le panneau qui affiche l'aide (le premier, en general)
uo_status.is_help_panel = "state"

// La ou vous appeliez SetMicroHelp : l'aide passe par-dessus Ready
uo_status.is_help = "Saving the order..."

// "" rend au panneau son propre texte
uo_status.is_help = ""

// event ue_item_hover d'une menubar (uo_menu) : l'aide de l'entree sous le pointeur
uo_status.is_help = this.of_item(/*keys*/ as_keys).is_tooltip

// event getfocus d'un champ (sle_name) : son Tag est son aide
uo_status.is_help = sle_name.Tag

Bonnes pratiques #

• Donnez une largeur fixe aux panneaux dont le texte change souvent (position du curseur, compteurs) : les panneaux voisins cesseront de sauter à chaque rafraîchissement.
• Faites du premier panneau un ressort (ib_spring, ou une largeur de -1) : il prend la place libre, et c'est son texte qui s'élide le premier.
• Un panneau est inerte par défaut : demandez le clic par ib_clickable, et laissez sans réaction les panneaux qui ne font qu'afficher.
• Réservez la fin de barre (ALIGN_END) aux informations stables (heure, utilisateur, connexion) et le début (ALIGN_START) au contexte courant ; en lecture de droite à gauche, les deux côtés s'inversent d'eux-mêmes.
• Employez is_state plutôt que des couleurs dans le texte : l'état suit le thème clair comme sombre.
• Pensez à repasser is_state à STATE_NONE et ii_progress à une valeur négative dès que l'alerte ou le traitement est terminé.
• Une barre d'état n'est pas un journal : au-delà de cinq ou six panneaux, préférez une notification toaster.
• Si la progression mérite mieux qu'une mini-barre de panneau, passez à la progressbar.

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.

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