# statictext — `u_pbt_statictext` #

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

> Bloc de texte riche : balisage, alignements, liens et actions cliquables, allure d'en-tête, mode défilant (marquee) et zone de dépôt de fichiers.

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

## En bref #

Userobject | `u_pbt_statictext`
Classe d'items | — (composant sans items)
Sert à | Remplacer un `statictext` PowerBuilder par un bloc de texte formaté, cliquable, capable de servir d'en-tête, de bandeau défilant ou de zone de dépôt
Options opt-in | `ib_auto_height`, `ib_track_mouse`, `ib_allow_drop`, `ib_selectable`, `ib_hover_effect`

## Démarrage rapide #

    // event open de la fenetre
    uo_texte.is_text = "Bienvenue sur [b][accent]PBToolboxAI[/accent][/b][br]" &
                       + "Consultez la [hyperlink=https://pbtoolboxai.net]documentation[/hyperlink]."
    uo_texte.is_align = uo_texte.ALIGN_CENTER
    uo_texte.is_valign = uo_texte.VALIGN_CENTER

Le texte accepte le balisage riche : c'est ce composant qui en tire le meilleur parti, puisqu'il est le seul à rendre les zones `[hyperlink=…]` et `[action=…]` réellement cliquables.

## Constantes #

Constante | Valeur | Pour
--- | --- | ---
`ALIGN_START` · `ALIGN_CENTER` · `ALIGN_END` · `ALIGN_JUSTIFY` | `"start"` `"center"` `"end"` `"justify"` | `is_align`
`VALIGN_TOP` · `VALIGN_CENTER` · `VALIGN_BOTTOM` | `"top"` `"center"` `"bottom"` | `is_valign`

`start` et `end` sont logiques : ils suivent le sens d'écriture (Langue et RTL). Les valeurs physiques `left` et `right` restent acceptées comme alias.

## Propriétés #

### Texte et mise en forme #

Propriété | Type | Défaut | Rôle
--- | --- | --- | ---
`is_text` | string | `""` | Le texte affiché, avec le balisage riche : `[b]`, `[i]`, `[u]`, couleurs, `[picture=…]`, `[hyperlink=…]`, `[action=…]`
`is_align` | string | `"start"` | Alignement horizontal : `ALIGN_START`, `ALIGN_CENTER`, `ALIGN_END`, `ALIGN_JUSTIFY`
`is_valign` | string | `"top"` | Alignement vertical dans le contrôle : `VALIGN_TOP`, `VALIGN_CENTER`, `VALIGN_BOTTOM`
`ib_wrap` | boolean | `true` | Retour à la ligne automatique. `false` force une ligne unique
`ib_ellipsis` | boolean | `false` | Avec `ib_wrap = false`, tronque le débordement par des points de suspension au lieu de le couper net
`ib_ellipsis_tooltip` | boolean | `false` | Opt-in : quand le texte ne tient pas dans la boîte, l'afficher en entier dans une info-bulle (balisage compris). Ne remplace jamais une info-bulle que vous avez posée avec `is_tooltip` ou `is_super_tooltip_*` : la vôtre gagne
`is_font_family` | string | `""` | Police par défaut du bloc (vide = police du thème)
`ii_font_size` | integer | `0` | Taille par défaut en points (`0` = taille du thème)
`il_text_color` | long | `-1` | Couleur de texte `RGB()` (`-1` = couleur du thème). Les balises `[color]` restent prioritaires sur leur portion
`ii_line_spacing` | integer | `0` | Interligne en pourcentage (`150` = 1,5 ligne ; `0` = défaut)
`ib_enabled` | boolean | `true` | Bloc actif ou grisé (liens et actions inertes quand il est grisé)
`ib_selectable` | boolean | `false` | Opt-in : autorise l'utilisateur à sélectionner et copier le texte (coupé par défaut, comme un libellé)

### Allure de bloc (look « en-tête ») #

Propriété | Type | Défaut | Rôle
--- | --- | --- | ---
`il_back_color` | long | `-1` | Fond du bloc `RGB()` (`-1` = fond du thème)
`il_border_color` | long | `-1` | Couleur de la bordure (`-1` = pas de bordure)
`ii_border_width` | integer | `0` | Épaisseur de la bordure en pixels (`0` = pas de bordure)
`ii_corner_radius` | integer | `0` | Rayon d'arrondi des angles, en pixels
`ii_padding` | integer | `0` | Marge intérieure en pixels (`0` = valeur du thème)
`ib_hover_effect` | boolean | `false` | Opt-in : léger assombrissement au survol, pour un libellé-bouton

### Mode défilant (marquee) #

Propriété | Type | Défaut | Rôle
--- | --- | --- | ---
`ib_marquee` | boolean | `false` | Transforme le bloc en bandeau défilant horizontalement
`ii_marquee_speed` | integer | `60` | Vitesse de défilement, en pixels par seconde
`is_marquee_direction` | string | `MARQUEE_START` | Sens du défilement : `MARQUEE_START` (vers le début de lecture) ou `MARQUEE_END`. Alias physiques `"left"` / `"right"` acceptés
`ib_marquee_overflow_only` | boolean | `false` | Opt-in : ne défiler que si le texte est trop large pour la boîte. Un bandeau qui fait défiler un texte déjà lisible n'est que du bruit visuel. Désactivé par défaut, pour que `ib_marquee = true` continue de vouloir dire ça défile
`ib_marquee_pause_on_hover` | boolean | `false` | Opt-in : arrête le défilement tant que le pointeur est sur le bloc, pour qu'un texte long soit lisible. La position de boucle est conservée : rien ne saute quand le pointeur s'en va

### Interactions optionnelles #

Propriété | Type | Défaut | Rôle
--- | --- | --- | ---
`ib_allow_drop` | boolean | `false` | Opt-in : accepte le dépôt de fichiers depuis l'Explorateur Windows ; les chemins complets arrivent par `ue_drop_files`
`ib_track_mouse` | boolean | `false` | Opt-in : active `ue_mouse_enter` / `ue_mouse_leave`
`ib_auto_height` | boolean | `false` | Opt-in : le bloc mesure sa hauteur idéale et redimensionne l'userobject ; voir Socle commun
`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

## Méthodes #

Méthode | Rôle
--- | ---
`of_reset ( )` | Remet toutes les propriétés à leur défaut et vide le texte
`of_set_redraw (boolean)` | Regroupe une rafale de modifications en un seul rendu
`of_save_as_png (string)` · `of_save_as_jpg (string)` | Exporte le rendu en image
`of_scroll_to_end ( )` | Descend au bas du texte. Pour un journal, dont la ligne la plus récente est à la fin : sans cela elle passe sous la ligne de flottaison dès que le texte dépasse la hauteur visible

## Événements #

Événement | Déclenché quand
--- | ---
`ue_clicked ( )` | Clic gauche sur le bloc — pas déclenché sur une zone `[action]` ou `[hyperlink]` (aucun doublon)
`ue_hyperlink (string as_url)` | Une zone `[hyperlink=url]` a été cliquée. Le navigateur s'ouvre tout seul : l'event vous est remis en plus, pour tracer le clic ou en faire davantage
`ue_action (string as_id)` | Une zone `[action=id]` a été cliquée : à vous d'y brancher votre code
`ue_drop_files (string as_files[])` | Des fichiers ont été déposés depuis Windows : chemins complets, une entrée par fichier. Nécessite `ib_allow_drop = true`
`ue_drag_enter ( )` | Un glissement de fichiers entre sur le composant (`ib_allow_drop`)
`ue_drag_leave ( )` | Le glissement de fichiers quitte le composant
`ue_auto_height (long al_height)` | Le bloc a calculé sa hauteur idéale — nécessite `ib_auto_height = true`
`ue_rclicked ( )` | Clic droit sur le bloc
`ue_double_clicked ( )` | Double-clic sur le bloc, comme le `StaticText` natif de PowerBuilder. Les clics simples qui le précèdent sont émis aussi, dans le même ordre. Pas déclenché sur une zone `[action]` ou `[hyperlink]`, qui ont leur propre canal
`ue_text_overflow (boolean ab_truncated)` | Le texte a cessé de tenir dans la boîte — ou y tient de nouveau. Émis uniquement sur changement, jamais en rafale : un bloc en retour à la ligne compte comme coupé quand il est rogné en bas, un bloc sur une ligne quand il est coupé sur le côté. À traiter pour élargir une colonne, proposer un bouton voir plus, ou simplement activer `ib_ellipsis_tooltip`
`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_cycle ( )` | Mode défilant uniquement : le texte vient de terminer un passage complet
`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 #

### Un en-tête de section #

Fond plein, texte blanc centré et hauteur ajustée au contenu : le bloc se lit comme une vraie barre de titre.

    uo_entete.of_set_redraw(false)

    uo_entete.is_text  = "[b]Tableau de bord des ventes"
    uo_entete.is_align = uo_entete.ALIGN_CENTER

    // Fond plein et texte blanc lisible
    uo_entete.il_back_color = RGB(/*rouge*/ 60, /*vert*/ 110, /*bleu*/ 190)
    uo_entete.il_text_color = RGB(/*rouge*/ 255, /*vert*/ 255, /*bleu*/ 255)
    uo_entete.ii_padding = 14

    // Le bloc se colle a son contenu : il se lit comme une barre de titre
    uo_entete.ib_auto_height = true

    uo_entete.of_set_redraw(true)

    // event ue_auto_height de uo_entete
    of_repositionner_sous_entete(al_height)   // decale le contenu sous l'en-tete

### Texte riche avec lien et action #

    uo_texte.is_text = "Votre licence expire le [b]31/12[/b]. " &
                       + "[hyperlink=https://pbtoolboxai.net]En savoir plus[/hyperlink] " &
                       + "ou [action=renew]la renouveler maintenant[/action]."

    // event ue_action de uo_texte : (string as_id)
    choose case as_id
        case "renew" ; of_ouvrir_renouvellement()
    end choose

`ue_hyperlink` est réservé aux URL (le navigateur s'ouvre tout seul) ; `[action=id]` est le bon choix quand le clic doit rester dans votre application. La variante `[invisibleaction=id]` déclenche le même `ue_action` sans l'apparence d'un lien.

### Un bloc repliable #

    uo_recap.is_text = "[b]Commande 2026-0148[/b][br]" &
                       + "[foldarea:[b]Livraison[/b]]Expedie le 12/07, sous 48 heures.[/foldarea]" &
                       + "[foldarea-closed:[i]Mentions legales[/i]]Retour accepte sous 14 jours.[/foldarea]"

    uo_recap.ib_auto_height = true   // le bloc se retracte quand une section est repliee

Un `[foldarea:Titre]` ajoute un en-tête cliquable au-dessus de son contenu : le lecteur replie la section d'un clic, et le marqueur passe de `−` à `+`. `[foldarea-closed:Titre]` produit le même bloc, replié dès l'affichage. Les blocs s'imbriquent, et le repli ne remonte aucun event : c'est une affaire de lecture, pas de code. Si `ib_auto_height` est actif, la hauteur est renotifiée à chaque repli. Le titre est du texte à balises : `[foldarea:[b][accent]Commande 2026-0148[/accent][/b]]` met le sien en gras et à la couleur d'accent.

### Un bandeau défilant #

    uo_bandeau.is_text = "[b]Information[/b] -- fermeture exceptionnelle du service le vendredi 12."

    // Mode defilant, facon fil d'actualite
    uo_bandeau.ib_marquee = true
    uo_bandeau.ii_marquee_speed = 90        // pixels par seconde
    uo_bandeau.is_marquee_direction = uo_bandeau.MARQUEE_START

Le défilement boucle sans temps mort. Pour l'arrêter, repassez `ib_marquee` à `false` : le texte reprend sa mise en page normale.

À chaque passage complet du texte, l'événement `ue_cycle` est déclenché — pratique pour faire tourner plusieurs messages :

    // Dans ue_cycle du bandeau : passer au message suivant
    ii_message = Mod(ii_message, UpperBound(is_messages)) + 1
    uo_bandeau.is_text = is_messages[ii_message]

### Une zone de dépôt de fichiers #

    // Accepter les fichiers glisses depuis l'Explorateur Windows
    uo_zone.ib_allow_drop = true

    uo_zone.is_text = "[size=32][accent][b]Deposez vos fichiers ici[/b][/accent][/size][br][br]" &
                      + "Glissez un ou plusieurs fichiers depuis l'Explorateur Windows."
    uo_zone.is_align  = uo_zone.ALIGN_CENTER
    uo_zone.is_valign = uo_zone.VALIGN_CENTER

    // event ue_drop_files de uo_zone : (string as_files[])
    integer li

    for li = 1 to UpperBound(as_files)
        of_importer(as_files[li])       // as_files[li] = chemin COMPLET du fichier
    next

    // event ue_drag_enter de uo_zone : signaler la cible pendant le survol
    uo_zone.il_border_color = RGB(/*rouge*/ 21, /*vert*/ 101, /*bleu*/ 192)
    uo_zone.ii_border_width = 2

Les chemins reçus sont complets : vous pouvez les passer directement à `FileOpen` ou à votre routine d'import.

### Un libellé qui se comporte comme un bouton #

    uo_lien.is_text = "Tout selectionner"
    uo_lien.il_text_color = RGB(/*rouge*/ 21, /*vert*/ 101, /*bleu*/ 192)
    uo_lien.ii_padding = 8
    uo_lien.ii_corner_radius = 6
    uo_lien.ib_hover_effect = true       // reagit au survol comme un bouton

    // event ue_clicked de uo_lien
    of_tout_selectionner()

## Bonnes pratiques #

- Un texte sans balise n'a aucun surcoût : n'hésitez pas à remplacer systématiquement vos `statictext` PowerBuilder, même pour du texte brut.
- Préférez `is_align = uo.ALIGN_START` à `"left"` : votre écran restera correct si l'application passe en écriture de droite à gauche.
- `ib_selectable` reste coupé par défaut, comme un libellé. Ne l'activez que là où la copie a du sens (numéro de dossier, message d'erreur technique).
- Pour un en-tête, combinez `il_back_color` + `ii_padding` + `ib_auto_height` : le bloc se dimensionne seul quand le texte change de longueur.
- N'activez `ib_track_mouse` que si vous scriptez réellement `ue_mouse_enter` / `ue_mouse_leave`.
- Appelez `of_reset()` avant de réutiliser un bloc pour un autre contenu : sans cela, un fond, une bordure ou le mode défilant précédents restent en place.

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