tilesbox — `u_pbt_tilesbox` #

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

Panneau de tuiles groupées façon écran d'accueil : quatre tailles de tuile, couleurs, pastilles, tuiles animées, groupes repliables et réorganisation à la souris.

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

En bref #

Userobject	`u_pbt_tilesbox`
Classes d'items	`n_pbt_tilesbox_group` (groupe) → `n_pbt_tilesbox_tile` (tuile)
Sert à	Offrir un écran d'accueil ou un lanceur de fonctions : des tuiles cliquables, lisibles de loin, rangées par thème
Options opt-in	—

Démarrage rapide #

// event open de la fenetre

// Une tuile s ajoute a son ADRESSE : le groupe, puis son propre identifiant
uo_tuiles.of_add_group(/*key*/ "gestion", /*title*/ "Gestion")

uo_tuiles.of_add_tile(/*keys*/ "gestion/clients",   /*label*/ "Clients",   /*icon_file*/ "mono:img\clients.svg",   /*size*/ "medium")
uo_tuiles.of_add_tile(/*keys*/ "gestion/factures",  /*label*/ "Factures",  /*icon_file*/ "mono:img\factures.svg",  /*size*/ "medium")
uo_tuiles.of_add_tile(/*keys*/ "gestion/stock",     /*label*/ "Stock",     /*icon_file*/ "mono:img\stock.svg",     /*size*/ "small")

// event ue_tile_clicked de uo_tuiles : (string as_keys)
choose case as_keys
    case "gestion/clients"  ; open(w_clients)
    case "gestion/factures" ; open(w_factures)
    case "gestion/stock"    ; open(w_stock)
end choose

Le modèle : groupes et tuiles #

Le panneau contient des groupes, chacun avec son titre et son entête repliable. Les tuiles appartiennent à un groupe : leur identifiant n'est unique qu'à l'intérieur de ce groupe. L'accès passe donc toujours par le chemin complet. Les ajouts, eux, vivent sur le composant : un handle ne porte que des propriétés.

// Chemin obligatoire : groupe puis tuile
uo_tuiles.of_tile("gestion/factures").is_badge = "12"

Les events portent eux aussi l'adresse complete (as_keys, le groupe puis la tuile). Voir Socle commun · Les items.

Propriétés #

Propriété	Type	Défaut	Rôle
`ib_reorderable`	boolean	`false`	Autorise l'utilisateur à déplacer les tuiles à la souris (déclenche `ue_tile_moved`)
`is_scroll`	string	`SCROLL_HORIZONTAL`	Sens de défilement : `SCROLL_VERTICAL` (les tuiles passent à la ligne) ou `SCROLL_HORIZONTAL` (colonnes façon écran d'accueil)
`ib_show_group_headers`	boolean	`true`	`false` masque les entêtes de groupe. Utile quand le panneau ne contient qu'un seul groupe : il n'y a rien à nommer et l'entête ne fait que manger de la hauteur. Sans entête il n'y a plus de chevron : les groupes s'affichent toujours dépliés
`ii_anim_duration`	integer	`180`	Durée en millisecondes de l'animation de repli / dépli d'un groupe ; `0` = instantané
`ii_tile_unit`	integer	`0`	Taille de base d une tuile, en pixels : chaque format (petite, moyenne, large, grande) en est un multiple, donc une valeur rend tout le tableau plus dense ou plus aéré. `0` la rend au thème
`ii_badge_size`	integer	`0`	Hauteur des pastilles de tuile en pixels, pour toute la boîte (`0` = la taille qui vient du thème). La taille de la police suit toute seule. La couleur d une pastille appartient à la tuile parce qu elle veut dire quelque chose ; sa taille, non
`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_group (string as_key)` → `n_pbt_tilesbox_group`	Rend le handle d'un groupe (créé au premier accès)
`of_add_group (string as_key, string as_title)` → `long`	Ajoute un groupe et renvoie `0` (`-5` sur un argument invalide, `-2` si le composant n'est pas créé)
`of_add_tile (string as_keys, string as_text, string as_image, string as_size)` → `long`	Ajoute une tuile à son adresse, `"gestion/clients"` : le groupe où elle atterrit, puis son propre identifiant. Renvoie `0` (`-5` sur un argument invalide, `-2` si le composant n'est pas créé) — `-5` si le parent n'est pas un groupe. Une surcharge omet l'icône et la taille
`of_tile (string as_keys)` → `n_pbt_tilesbox_tile`	Rend le handle d'une tuile, par son adresse (créé au premier accès)
`of_add_live_item (string as_keys, string as_text)` → `long`	Ajoute une face au bandeau animé d'une tuile, à son adresse ; à partir de deux faces, la tuile les fait défiler. Renvoie `0` une fois appliqué, `-5` sur un argument invalide (clé vide, adresse fausse), `-2` si le composant n'est pas créé
`of_clear_live_items (string as_keys)` → `long`	Vide le bandeau animé d'une tuile : elle cesse de défiler et retrouve sa face simple. Renvoie `0` une fois appliqué, `-5` sur un argument invalide (clé vide, adresse fausse), `-2` si le composant n'est pas créé
`of_remove_group (string as_key)`	Supprime un groupe et toutes ses tuiles. Renvoie `0` une fois appliqué, `-2` si le composant n'est pas créé
`of_insert_tile (string as_keys, string as_text, integer ai_index)`	Insère une tuile à une position précise dans son groupe (position comptée à partir de 1). Renvoie `0` une fois appliqué, `-5` sur un argument invalide (clé vide, adresse fausse), `-2` si le composant n'est pas créé
`of_insert_tile (string as_keys, string as_text, string as_image, string as_size, integer ai_index)`	Idem, avec l’icône et la taille (`small` / `medium` / `wide` / `large`) : une tuile est une image avec un libellé dessous, et sa taille se voit dans la grille. Renvoie `0` une fois appliqué, `-5` sur un argument invalide (clé vide, adresse fausse), `-2` si le composant n'est pas créé
`of_move_tile (string as_keys, integer ai_index)`	Déplace une tuile existante à une autre position de son groupe, en conservant son état. Renvoie `0` une fois appliqué, `-5` sur un argument invalide (clé vide, adresse fausse), `-2` si le composant n'est pas créé
`of_remove_tile (string as_keys)`	Supprime une seule tuile, le reste du panneau est préservé. Renvoie `0` une fois appliqué, `-5` sur un argument invalide (clé vide, adresse fausse), `-2` si le composant n'est pas créé
`of_clear ( )`	Vide le panneau (groupes et tuiles). Renvoie `0` une fois appliqué, `-2` si le composant n'est pas créé
`of_get_layout ( )`	Relit la disposition courante en JSON : groupes, tuiles, ordre et tailles. À stocker, puis à rendre par `of_set_layout`
`of_set_layout (string as_state_json)`	Restaure une disposition lue avec `of_get_layout` ou 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_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éé

Sur un groupe — `n_pbt_tilesbox_group` #

Membre	Type	Défaut	Rôle
`is_title`	string	`""`	Titre affiché dans l'entête, balisage riche accepté
`ib_collapsed`	boolean	`false`	Groupe replié : ses tuiles sont masquées sous l'entête
`ib_enabled`	boolean	`true`	Groupe entier grisé et inerte
`ib_visible`	boolean	`true`	Groupe masqué, sans être supprimé du modèle

Sur une tuile — `n_pbt_tilesbox_tile` #

Membre	Type	Défaut	Rôle
`is_title`	string	`""`	Texte affiché sur la tuile. Posé par `of_add_tile` ; l'écrire ici le change, le lire dit ce que la tuile affiche en ce moment
`is_image`	string	`""`	Icône de la tuile (chemin disque ou `resources.dll:nom`). Une chaîne vide retire l'icône
`is_size`	string	`SIZE_MEDIUM`	Taille : `SIZE_SMALL`, `SIZE_MEDIUM`, `SIZE_WIDE`, `SIZE_LARGE`
`il_back_color` · `il_text_color`	long	`-1`	Fond et texte propres à la tuile, en `RGB(r,v,b)` (`-1` = ce que donne le thème)
`il_back_color_hover` · `il_text_color_hover`	long	`-1`	Les deux mêmes, mais sous le pointeur
`is_badge`	string	`""`	Pastille affichée dans l'angle de la tuile (un compteur, un état court)
`il_badge_color`	long	`0`	Fond de la pastille, en RGB PowerBuilder (`0` = la couleur qui vient du thème)
`is_live_text`	string	`""`	Texte superposé à la tuile, balisage riche accepté
`ib_enabled`	boolean	`true`	Tuile grisée et non cliquable
`ib_visible`	boolean	`true`	Tuile masquée, sans être retirée de son groupe

Les icônes acceptent toutes les formes reconnues par la bibliothèque : chemin, mono:, tint:, ressource de DLL. Sur une grande tuile, préférez une image nette en haute définition ou un SVG.

Les quatre tailles #

Taille	Encombrement	Usage typique
`small`	1 case	Raccourci secondaire ; le libellé n'est pas affiché, l'info-bulle prend le relais
`medium`	2 × 2 cases	Taille de référence : icône et libellé
`wide`	4 × 2 cases	Tuile allongée, idéale pour un texte animé
`large`	4 × 4 cases	Tuile vedette de l'écran

Événements #

Événement	Déclenché quand
`ue_tile_clicked (string as_keys)`	Une tuile est cliquée
`ue_tile_moved (string as_keys, string as_to_keys, long al_index)`	Une tuile a été déplacée : `as_keys` est l'adresse de départ, `as_to_keys` le groupe d'arrivée, `al_index` la nouvelle position
`ue_group_toggled (string as_key, boolean ab_collapsed)`	Un groupe est replié ou déplié depuis son entête
`ue_tile_context (string as_keys)`	Clic droit sur une tuile
`ue_tile_resized (string as_keys, string as_size)`	La taille d'une tuile a changé ; `as_size` porte la nouvelle taille
`ue_layout_changed (string as_layout_json)`	L'arrangement a changé — l'utilisateur a déplacé ou redimensionné une tuile. Porte la disposition entière, pas seulement ce qui a bougé
`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 #

Tailles mélangées dans un même groupe #


uo_tuiles.of_clear()
uo_tuiles.of_add_group(/*key*/ "accueil", /*title*/ "Accueil")

uo_tuiles.of_add_tile(/*keys*/ "accueil/tableau", /*label*/ "Tableau de bord", /*icon_file*/ "mono:img\chart.svg",  /*size*/ "large")
uo_tuiles.of_add_tile(/*keys*/ "accueil/clients", /*label*/ "Clients",         /*icon_file*/ "mono:img\users.svg",  /*size*/ "medium")
uo_tuiles.of_add_tile(/*keys*/ "accueil/agenda",  /*label*/ "Agenda",          /*icon_file*/ "mono:img\cal.svg",    /*size*/ "wide")
uo_tuiles.of_add_tile(/*keys*/ "accueil/aide",    /*label*/ "Aide",            /*icon_file*/ "mono:img\help.svg",   /*size*/ "small")

Pastille, couleur et tuile animée #

n_pbt_tilesbox_tile lnv_tuile

// Une pastille signale un nombre d'elements en attente
uo_tuiles.of_group("accueil").of_tile("clients").is_badge = String(ll_nouveaux)

// Rouge quand le retard devient critique, couleur du theme sinon (0)
if ll_nouveaux > 50 then
    uo_tuiles.of_group("accueil").of_tile("clients").il_badge_color = RGB(200, 30, 30)
else
    uo_tuiles.of_group("accueil").of_tile("clients").il_badge_color = 0
end if

// Une couleur propre met une tuile en avant : fond, texte, et ce que
// chacun devient sous le pointeur
lnv_tuile = uo_tuiles.of_group("accueil").of_tile("tableau")
lnv_tuile.il_back_color = RGB(0, 103, 192)
lnv_tuile.il_back_color_hover = RGB(0, 80, 150)
lnv_tuile.il_text_color = RGB(255, 255, 255)

// Tuile ANIMEE : chaque face ajoutee defile a son tour sur la tuile
lnv_tuile = uo_tuiles.of_group("accueil").of_tile("agenda")
lnv_tuile.of_clear_live_items()
lnv_tuile.of_add_live_item(/*text*/ "3 rendez-vous aujourd'hui")
lnv_tuile.of_add_live_item(/*text*/ "Reunion equipe a 14h00")
lnv_tuile.of_add_live_item(/*text*/ "2 relances en retard")

Un texte fixe plutôt qu'un défilement #

// is_live_text pose UN texte permanent sur la tuile (balisage riche accepte)
uo_tuiles.of_group("accueil").of_tile("tableau").is_live_text = "[b]48[/b] commandes du jour"

Groupes repliables #


uo_tuiles.of_add_group(/*key*/ "admin", /*title*/ "Administration")
uo_tuiles.of_add_tile(/*keys*/ "admin/users",  /*label*/ "Utilisateurs", /*icon_file*/ "mono:img\users.svg", /*size*/ "medium")
uo_tuiles.of_add_tile(/*keys*/ "admin/params", /*label*/ "Parametres",   /*icon_file*/ "mono:img\gear.svg",  /*size*/ "medium")

// Ce groupe demarre replie : l'utilisateur l'ouvre s'il en a besoin
lnv_admin.ib_collapsed = true

// Un groupe entier peut aussi etre grise selon les droits
lnv_admin.ib_enabled = (is_profil = "ADMIN")

// event ue_group_toggled de uo_tuiles
if as_keys = "admin" and not ab_collapsed then of_tracer("Ouverture du volet administration")

Un panneau à groupe unique, sans entête #

// Un seul groupe n'a rien a nommer : son entete ne fait que manger de la hauteur.
// Sans entete, plus de chevron non plus : les tuiles restent toujours visibles.
uo_tuiles.ib_show_group_headers = false
uo_tuiles.of_add_group(/*key*/ "tout", /*title*/ "")

Déplacer une tuile entre deux groupes #

Avec ib_reorderable = true, l'utilisateur fait glisser une tuile où il veut, y compris d'un groupe vers un autre. L'event ue_tile_moved livre les deux groupes et la nouvelle position.

uo_tuiles.ib_reorderable = true    // faux par defaut : a demander

// event ue_tile_moved de uo_tuiles
// as_keys = d'ou elle vient, as_to_keys = ou elle va, al_index = position
n_pbt_utils lnv_utils   // autoinstantiate : rien a creer, rien a detruire
if as_keys <> as_to_keys then
    of_tracer("Tuile " + lnv_utils.of_leaf(as_keys) + " deplacee de " + lnv_utils.of_parent(as_keys) + " vers " + as_to_keys)
end if
uo_tuiles.of_get_layout()    // demander la disposition pour la conserver

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

// A l'ouverture suivante : restituer l'ecran tel que l'utilisateur l'avait range
if is_disposition <> "" then uo_tuiles.of_set_layout(is_disposition)

Pour figer l'écran, il suffit de couper la réorganisation :

uo_tuiles.ib_reorderable = false

Réorganiser depuis le code #

// Placer la tuile "aide" en tete de son groupe (positions comptees a partir de 1)
uo_tuiles.of_move_tile(/*group*/ "accueil", /*key*/ "aide", /*index*/ 1)

// Inserer une nouvelle tuile en deuxieme position
uo_tuiles.of_insert_tile(/*group*/ "accueil", /*key*/ "devis", /*text*/ "Devis", /*index*/ 2)

// Retirer une tuile sans toucher au reste
uo_tuiles.of_remove_tile(/*group*/ "accueil", /*key*/ "aide")

Réagir au clic droit #

// event ue_tile_context de uo_tuiles : (as_keys)
// Retenir la tuile visee, puis ouvrir votre propre menu contextuel
n_pbt_utils lnv_utils   // autoinstantiate : rien a creer, rien a detruire
// Une seule adresse : la decouper si les deux moities servent.
is_groupe_vise = lnv_utils.of_parent(as_keys)
is_tuile_visee = lnv_utils.of_leaf(as_keys)
of_ouvrir_menu_tuile(PointerX(), PointerY())

Bonnes pratiques #

Une tuile large par écran suffit : c'est le point d'entrée principal, le reste doit rester lisible.
Les tuiles small n'affichent pas leur libellé — renseignez systématiquement l'info-bulle de l'item.
Réservez il_back_color aux tuiles qui doivent trancher : au-delà de deux ou trois couleurs, l'écran perd sa hiérarchie. Et si vous posez un fond clair, posez il_text_color avec — le texte du thème n'est pas garanti lisible dessus.
Préférez of_add_live_item (défilement) à is_live_text (texte fixe) quand vous avez plusieurs informations à faire passer sur la même tuile.
Si vous laissez la réorganisation active, conservez la disposition via of_get_layout / ue_layout_changed et rejouez of_set_layout à l'ouverture.
Utilisez ib_visible et ib_enabled (groupe ou tuile) pour l'adapter aux droits de l'utilisateur, plutôt que de reconstruire le panneau.
Quand l'espace manque pour des tuiles, préférez la navigation latérale compacte du listbar ; pour les actions fréquentes, la toolbar.

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.