propertygrid — `u_pbt_propertygrid` #

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

propertygrid est la fenêtre des propriétés d'un EDI, pour vos propres données : des valeurs nommées, rangées dans des catégories qui se replient, chacune avec l'éditeur de son type — texte, nombre, case à cocher, liste de choix, couleur, date, mot de passe. Deux vues (par catégorie, alphabétique), une zone de recherche, un volet d'aide qui décrit la propriété sélectionnée, et un bouton … qui ouvre votre propre boîte de dialogue. L'utilisateur modifie, ue_value_changed vous le dit.

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

En bref #

Userobject	`u_pbt_propertygrid`
Classes d'items	`n_pbt_propertygrid_category` (catégorie) → `n_pbt_propertygrid_property` (propriété)
Sert à	Remplacer un écran de paramètres bricolé à coups de champs et de cases par un inspecteur thémé, typé et cherchable : réglages d'un document, d'un rapport, d'une fiche, d'un objet de l'application
Valeurs	Toujours du texte, une par une (`of_property(adresse).is_value`) ; toutes d'un coup et typées par `of_values`
Options opt-in	`ib_veto_changes`

Démarrage rapide #

// The settings of a report : one value at the top, then a category
uo_grid.of_add_property(/*keys*/ "title", /*label*/ "Title", /*type*/ u_pbt_propertygrid.TYPE_STRING, /*value*/ "Monthly sales")
uo_grid.of_add_category(/*key*/ "page", /*title*/ "Page")
uo_grid.of_add_property(/*keys*/ "page/landscape", /*label*/ "Landscape", /*type*/ u_pbt_propertygrid.TYPE_BOOLEAN, /*value*/ "true")
uo_grid.of_add_property(/*keys*/ "page/margin", /*label*/ "Margin (mm)", /*type*/ u_pbt_propertygrid.TYPE_NUMBER, /*value*/ "12.5")

// The help pane describes the selected property
uo_grid.of_property(/*keys*/ "page/margin").is_description = "Around the printed area, in [b]millimetres[/b]."

// event ue_value_changed of uo_grid : (string as_keys, string as_value)
// The value is already written ; the address says which one
choose case as_keys
    case "title"
        of_set_report_title(as_value)
    case "page/landscape"
        of_set_landscape(as_value = "true")
end choose

Une adresse par propriété #

Une propriété se désigne par son adresse : sa seule clé au premier niveau ("title"), la catégorie puis la propriété jointes par / sous une catégorie ("page/margin"). Une propriété dépliable (TYPE_GROUP) contient à son tour des propriétés, ajoutées à son adresse : "appearance/font/size" dans le groupe font de la catégorie appearance, "margin/left" dans un groupe du haut — et un groupe peut en contenir un autre. Ce qui contient une propriété est donc une catégorie (un seul niveau) ou un groupe. Une catégorie se désigne par sa clé seule. Au premier niveau, une clé ne nomme qu'une chose : une catégorie et une propriété du haut ne peuvent pas la partager. Les events portent la même adresse, celle que vous avez écrite.

// A category by its key, a property by its address
uo_grid.of_category(/*key*/ "page").ib_collapsed = true
uo_grid.of_property(/*keys*/ "page/margin").is_value = "15"

// A property held by a group : the address goes through the group
uo_grid.of_property(/*keys*/ "appearance/font/size").is_value = "11"

Les types de valeur #

Le type se choisit une fois, à of_add_property, et donne l'éditeur de la ligne. La valeur, elle, est toujours du texte — donnée, lue, rendue par les events — écrit de la même manière quelle que soit la langue du poste.

Constante	Éditeur	La valeur, en texte
`TYPE_STRING`	Zone de texte	Le texte tel quel
`TYPE_NUMBER`	Zone de texte qui n'accepte qu'un nombre, lu dans la langue d'affichage : son séparateur décimal ou un point, son groupement des milliers quand il est bien formé (`1,000` vaut mille en anglais, `1.500` mille cinq cents en allemand, `1 234,5` en français) ; une saisie ambiguë (`1,5` en anglais, `1 2`) ou qui n'est pas un nombre est refusée : le texte tapé reste, encadré de rouge, et le volet d'aide dit pourquoi (Échap y renonce). `is_min`, `is_max` et `id_step` bornent la saisie et règlent Haut / Bas	Avec un point : `"12.5"` ; `""` = vide. Gardée chiffre pour chiffre (`"1.50"` reste `"1.50"`) ; un texte qui n'est pas un nombre est refusé
`TYPE_BOOLEAN`	Case à cocher	`"true"` · `"false"`
`TYPE_ENUM`	Liste de choix aux couleurs du thème ; ses options s'ajoutent une par une (`of_add_option`), leur texte en clair, sans balisage	La valeur de l'option choisie, jamais son texte
`TYPE_COLOR`	Pastille de la couleur et sélecteur de couleur ; la cellule affiche `r, v, b`. Au-delà de `16777215`, une couleur système de PowerBuilder (`67108864` Button Face, `553648127` Transparent, `1073741824` Window Background…) s'affiche par son nom, avec une pastille neutre, et le sélecteur s'ouvre sans couleur courante	Le long RGB écrit en texte : `String(RGB(255, 0, 0))` = `"255"`
`TYPE_DATE`	Calendrier ; la cellule affiche la date au format de la langue d'affichage	`"yyyy-mm-dd"` : `String(Today(), "yyyy-mm-dd")`
`TYPE_PASSWORD`	Zone de texte masquée	Le texte en clair, jamais affiché ni trouvé par la recherche (même `{x:raw}` d'un résumé reste masqué)
`TYPE_GROUP`	Aucun : une propriété dépliable (une police, une marge), avec un chevron au début de son libellé ; elle contient les propriétés ajoutées à son adresse et se déplie par `ib_expanded`, son chevron, un double-clic sur son libellé ou le clavier. Fermée quand elle est ajoutée	Aucune à donner (`""`, toute autre est refusée) ; lue, son résumé : celui qu'écrit `is_summary`, sinon les valeurs affichées de ce qu'elle contient, masquées sautées, jointes par `;` (`"Segoe UI; 9; True"`) ; écrite, ignorée

Une valeur que son type ne peut pas tenir est refusée — à of_add_property (-5) comme par is_value ou is_default (l'ancienne reste) — et of_get_last_error dit pourquoi : un nombre qui n'en est pas un, un booléen autre que true / false / 1 / 0, une date qui n'est pas un vrai yyyy-mm-dd, une couleur qui n'est pas un entier à partir de -1, un TYPE_STRING ou un TYPE_PASSWORD sur plusieurs lignes (le champ de la grille tient une ligne). "" (pas de valeur) est toujours accepté. Une valeur de liste qu'aucune option n'offre est acceptée, et montrée telle quelle : une liste peut être chargée après sa valeur. La couleur -1 — celle que donne le thème, la convention de toute la bibliothèque — s'affiche « (par défaut) » ; une couleur système et les true / false d'un résumé s'écrivent dans la langue d'affichage.

Propriétés #

Propriété	Type	Défaut	Rôle
`is_sort`	string	`"categorized"`	La vue : `SORT_CATEGORIZED` (les propriétés du haut, puis chaque catégorie sous un en-tête qui se replie) ou `SORT_ALPHABETICAL` (une seule liste triée par libellé tel qu'il s'affiche, sans son balisage, et sans en-têtes ; un groupe garde ce qu'il contient sous lui). Les deux boutons de la barre d'outils la changent aussi : lue en direct. Passer en alphabétique quand un en-tête est sélectionné vide la sélection
`ib_toolbar`	boolean	`true`	La barre d'outils : les deux vues et la zone de recherche. `false` la masque ; `is_sort` et `is_filter` restent pilotables par le code
`ib_help`	boolean	`true`	Le volet d'aide, en bas : le libellé et la description (`is_description`) de la propriété sélectionnée, le titre d'une catégorie sélectionnée
`ii_label_width`	integer	`40`	Part de la largeur donnée aux libellés, en pour cent, de 15 à 85. L'utilisateur fait glisser la ligne entre libellés et valeurs : lue en direct
`is_filter`	string	`""`	La recherche : ne restent que les propriétés dont le libellé, la clé ou la valeur affichée contient ce texte, sans tenir compte de la casse ; pendant une recherche, chaque catégorie et chaque groupe qui contiennent une réponse s'affichent ouverts, sans perdre leur pli. Le libellé se lit tel qu'il s'affiche, sans son balisage ; ni le titre d'une catégorie ni l'adresse complète ne sont cherchés. Pendant une recherche, un pli de l'utilisateur ne fait rien ; un pli de votre code (`ib_collapsed`, `ib_expanded`, `of_expand_all`, `of_collapse_all`) est enregistré, lève son événement et se voit dès que la recherche se vide ; une ligne sélectionnée que la recherche cache quitte la sélection (`ue_selection_changed` avec une adresse vide). La zone de recherche l'écrit aussi (Échap l'efface) : lue en direct. `""` montre tout
`ib_veto_changes`	boolean	`false`	Opt-in : demander avant d'écrire une valeur de l'utilisateur (déclenche `ue_value_changing`, qui peut refuser : la cellule reprend l'ancienne valeur). Une valeur écrite par votre code ne pose jamais la question
`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

Propriétés d'une catégorie — `n_pbt_propertygrid_category` #

Propriété	Type	Défaut	Rôle
`is_title`	string	`""`	Titre de l'en-tête. Accepte le balisage riche. Vide, l'en-tête montre la clé
`ib_collapsed`	boolean	`false`	`true` replie la catégorie : son en-tête reste, ses propriétés se cachent (une sélection qui y était remonte sur l'en-tête). `ue_category_toggled` suit, comme pour un clic sur l'en-tête. Pendant une recherche, chaque catégorie s'affiche ouverte : un clic sur l'en-tête ne fait rien, et `true` posé par le code est enregistré (l'événement suit, la lecture le rend) et se voit dès que la recherche se vide. Lu en direct
`ib_visible`	boolean	`true`	`false` retire la catégorie, et tout ce qu'elle contient, de la grille ; elle garde sa clé et ses valeurs, que `of_values` rend toujours
`is_tooltip`	string	`""`	Info-bulle simple affichée au survol de l'item
`is_super_tooltip_title`	string	`""`	Titre de l'info-bulle enrichie de l'item (prend le pas sur `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Texte de l'info-bulle enrichie de l'item (balisage riche accepté)
`is_super_tooltip_image`	string	`""`	Image de l'info-bulle enrichie de l'item
`il_accent`	long	`-1`	Accent de l'en-tête de la catégorie : sa sélection le prend (`-1` = celui du composant). Pour la colorer tout entière, `il_back_color` / `il_text_color`
`il_back_color`	long	`-1`	Fond de l'en-tête de la catégorie, en `RGB(r,v,b)` (`-1` = ce que donne le thème)
`il_text_color`	long	`-1`	Couleur du texte de l'en-tête de la catégorie (`-1` = ce que donne le thème)
`il_back_color_hover`	long	`-1`	Fond de l'en-tête de la catégorie sous le pointeur (`-1` = ce que donne le thème)
`il_text_color_hover`	long	`-1`	Couleur du texte de l'en-tête de la catégorie sous le pointeur (`-1` = ce que donne le thème)

Propriétés d'une propriété — `n_pbt_propertygrid_property` #

Propriété	Type	Défaut	Rôle
`is_value`	string	celui d'`of_add_property`	La valeur, en texte (voir Les types de valeur) ; pour une liste, la valeur de l'option. L'écrire ne lève rien, comme `SetItem` ; la lire rend la valeur courante, qui que ce soit qui l'ait écrite. Une valeur que son type ne peut pas tenir (un `TYPE_NUMBER` qui reçoit un texte qui n'est pas un nombre) est refusée : l'ancienne valeur reste, et `of_get_last_error` de la grille dit pourquoi. Sur un groupe (`TYPE_GROUP`), la lecture rend son résumé (voir `is_summary`), et l'écriture est ignorée
`is_label`	string	celui d'`of_add_property`	Le nom affiché dans la colonne de gauche ; accepte le balisage riche. Vide, la ligne montre la clé, telle quelle (jamais lue comme du balisage). La vue alphabétique le trie, et la recherche le lit, tel qu'il s'affiche : sans son balisage
`is_description`	string	`""`	Le texte du volet d'aide pendant que la propriété est sélectionnée ; accepte le balisage riche
`ib_readonly`	boolean	`false`	Montrée, pas modifiable : la valeur s'affiche en gris et aucun éditeur ne s'ouvre, ni au clic, ni au clavier, ni au double-clic. Un groupe en lecture seule rend tout ce qu'il contient en lecture seule. Le bouton … (`ib_ellipsis`) reste actif : lisez `ib_readonly` dans `ue_ellipsis_clicked` pour ouvrir votre boîte en lecture seule
`ib_visible`	boolean	`true`	`false` retire la ligne de la grille ; la propriété garde son adresse et sa valeur (`of_values` la rend toujours). Masquer un groupe masque ce qu'il contient ; masquer la propriété sélectionnée vide la sélection
`ib_ellipsis`	boolean	`false`	Un bouton … en fin de ligne : un clic — ou Ctrl+Entrée sur la ligne sélectionnée — sélectionne la ligne et lève `ue_ellipsis_clicked`, même sur une propriété en lecture seule, pour une boîte de dialogue à vous (un fichier, une police, une liste tirée de la base)
`ib_expanded`	boolean	`false`	Pour une propriété dépliable (`TYPE_GROUP`) : `true` montre ce qu'elle contient, en retrait sous elle ; `false` le cache (une sélection qui y était remonte sur le groupe). `ue_property_toggled` suit, comme pour un clic sur son chevron. Pendant une recherche, un groupe qui contient une réponse s'affiche ouvert : son chevron ne fait rien, et une valeur posée par le code est enregistrée (l'événement suit) et se voit dès que la recherche se vide. Lu en direct ; sans effet sur les autres types
`is_summary`	string	`""`	Pour une propriété dépliable (`TYPE_GROUP`) : comment s'écrit son résumé, un gabarit. `{size}` est la valeur affichée de sa sous-propriété `size`, `{size:raw}` sa valeur telle que gardée (un mot de passe reste masqué), `{?bold}…{/bold}` un morceau gardé seulement quand `bold` est actif (un booléen vrai, une valeur ni vide, ni `false`, ni `0`), `{!bold}…{/bold}` seulement quand il ne l'est pas, `{{ }}` des accolades ; une clé inconnue ne donne rien. `"{name}, {size} pt{?bold}, bold{/bold}"` affiche Segoe UI, 10 pt, bold. Vide (par défaut) : les valeurs affichées, masquées sautées, jointes par `;` . Le résumé est du texte simple ; il suit chaque changement de ce que le groupe contient ; `is_value` du groupe le rend
`is_mask`	string	`""`	Pour un `TYPE_NUMBER` : son masque de saisie, un masque numérique dans la syntaxe de PowerBuilder (EditMask, format DataWindow) : `#` un chiffre facultatif, `0` un chiffre obligatoire, `,` le groupement, `.` le séparateur décimal, `%` le nombre affiché multiplié par 100, des littéraux (`$`, un texte entre guillemets, `\x`) et des sections `positif;négatif` (`"$#,##0;($#,##0)"`). La virgule et le point désignent les séparateurs de la langue d'affichage. Pendant la frappe, le groupement apparaît au fil des chiffres, les décimales sont limitées au masque, les lettres sont refusées, le curseur garde sa place parmi les chiffres et un nombre collé est lu dans la langue d'affichage ; en quittant le champ, le masque complète (`12` devient `12,00`). La valeur garde le nombre tel que le code l'écrit (`"1234.5"`), sans groupement ni symbole. Vide (par défaut) : le champ tape son `is_format` dépouillé de ses littéraux (`$#,##0.00` se tape `#,##0.00`, `#,##0 "px"` se tape `#,##0` ; un `%` reste, c'est une échelle), sinon le nombre tel quel ; sans effet sur les autres types
`is_format`	string	`""`	Pour un `TYPE_NUMBER` : son masque d'affichage, la façon dont la cellule affiche le nombre quand son champ n'a pas le clavier — même syntaxe que `is_mask`, avec ses littéraux : `#,##0 "px"` affiche `575 px`, `$#,##0.00` un prix, `0.0%` un taux (0,125 affiche `12,5%`). Le résumé d'un groupe et la recherche le lisent aussi. Quand le champ prend le clavier, son texte devient celui de `is_mask` (`575`), le curseur gardant sa place parmi les chiffres ; en le quittant, le texte d'affichage revient. La bascule ne change jamais la valeur et ne lève rien : `ue_value_changed` ne rapporte que ce que l'utilisateur a tapé, le nombre nu. Vide (par défaut) : la cellule affiche son `is_mask` ; sans effet sur les autres types
`is_default`	string	`""`	La valeur par défaut, en texte comme `is_value`. Tant que la valeur en diffère, elle s'écrit en gras et le volet d'aide montre le défaut ; l'utilisateur la rétablit par Suppr sur la ligne sélectionnée ou par le bouton Réinitialiser (↺) de la barre d'outils, montré seulement quand une propriété au moins a un défaut — un geste de l'utilisateur : `ue_value_changing` si le veto est actif, puis `ue_value_changed`. Une valeur que son type ne tient pas est refusée. Écrire `""` retire le défaut : plus de gras, plus de défaut au volet d'aide, `""` relu. Sans défaut, Suppr vide la valeur (un booléen reste tel quel)
`is_error`	string	`""`	Une erreur de votre application (`"Ce nom existe déjà"`) : la valeur s'encadre de rouge, le volet d'aide la dit en toutes lettres, une info-bulle aussi, et un lecteur d'écran l'annonce. Elle part quand l'utilisateur modifie la propriété, ou quand vous écrivez `""`. Posée dans `ue_value_changing` avant de refuser, elle explique le refus. Lue, l'erreur que la propriété montre : la vôtre, sinon celle de la grille quand un nombre tapé est refusé (pas un nombre, hors de `is_min` / `is_max`) — le texte tapé reste alors à l'écran pour être corrigé, Échap y renonce
`is_min`	string	`""`	Pour un `TYPE_NUMBER` : la plus petite valeur que l'utilisateur peut donner, en nombre écrit comme le code (`"0"`, `"12.5"`) ; `""` = pas de borne. Un nombre tapé en dessous est refusé, reste à l'écran et le volet d'aide dit pourquoi ; Bas s'y arrête. Votre code peut toujours écrire n'importe quelle valeur. Un texte qui n'est pas un nombre est refusé (`of_get_last_error`), comme une borne qui croise l'autre (`is_min` au-dessus d'`is_max`). Ignorée par les autres types
`is_max`	string	`""`	Pour un `TYPE_NUMBER` : la plus grande valeur que l'utilisateur peut donner ; `""` = pas de borne. Mêmes règles qu'`is_min` ; Haut s'y arrête
`id_step`	double	`1`	Pour un `TYPE_NUMBER` : ce que Haut et Bas ajoutent ou retirent pendant que son champ a le clavier, dans `is_min` / `is_max`. Chaque pas est une valeur de l'utilisateur (`ue_value_changed`, demandée d'abord si le veto est actif). `0` ou moins vaut `1`. Ignoré par les autres types
`of_is_dirty ( )` → `boolean`	—	—	`TRUE` quand la valeur diffère de sa référence (voir `of_is_dirty` de la grille)
`of_type ( )` → `string`	—	—	Le type donné à `of_add_property` (une constante `TYPE_*`). Lecture seule : un type se choisit une fois
`is_tooltip`	string	`""`	Info-bulle simple affichée au survol de l'item
`is_super_tooltip_title`	string	`""`	Titre de l'info-bulle enrichie de l'item (prend le pas sur `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Texte de l'info-bulle enrichie de l'item (balisage riche accepté)
`is_super_tooltip_image`	string	`""`	Image de l'info-bulle enrichie de l'item
`il_accent`	long	`-1`	Accent de la ligne de la propriété : sa sélection et le cadre de son éditeur le prennent (`-1` = celui du composant). Pour la colorer tout entière, `il_back_color` / `il_text_color`
`il_back_color`	long	`-1`	Fond de la ligne de la propriété, en `RGB(r,v,b)` (`-1` = ce que donne le thème)
`il_text_color`	long	`-1`	Couleur du texte de la ligne de la propriété (`-1` = ce que donne le thème)
`il_back_color_hover`	long	`-1`	Fond du libellé de la propriété quand le pointeur est sur sa ligne (`-1` = ce que donne le thème)
`il_text_color_hover`	long	`-1`	Couleur du libellé de la propriété quand le pointeur est sur sa ligne (`-1` = ce que donne le thème)

Méthodes #

Sur le composant #

Méthode	Rôle
`of_add_category (string as_key, string as_title)` → long	Ajoute une catégorie à la fin : un en-tête qui se replie, sous lequel s'ajoutent ensuite les propriétés `"clé/nom"`. Un titre vide montre la clé. Rend `0` une fois ajoutée, `-5` pour une clé vide, qui contient `/` ou `	`, ou déjà prise par une catégorie ou une propriété du haut,` -2` si le composant n'est pas créé
`of_add_property (string as_keys, string as_label, string as_type, string as_value)` → long	Ajoute une propriété à son adresse, à la fin de ce qui la contient : sa catégorie, son groupe (`"appearance/font/size"`, `"margin/left"`) ou les propriétés du haut. `as_type` est une constante `TYPE_*`, `as_value` sa valeur en texte (`""` pour un `TYPE_GROUP`, qui n'en a pas). Rend `0` une fois ajoutée, `-5` pour une adresse déjà prise, un parent qui n'est ni une catégorie ni un groupe (ou pas encore ajouté), un niveau vide (`"layout/"`, `"a//b"`), une clé qui contient `	`, un type inconnu, une valeur` TYPE_NUMBER `qui n'est pas un nombre tel que le code l'écrit (un point pour les décimales, signe et exposant facultatifs,` "" `admis), un booléen, une date ou une couleur qui n'en est pas un, un texte ou un mot de passe sur plusieurs lignes (`of_get_last_error `dit pourquoi) ou une valeur donnée à un` TYPE_GROUP`,` -2` si le composant n'est pas créé
`of_add_option (string as_keys, string as_value, string as_text)` → long	Ajoute une option, à la fin, à la liste d'une propriété `TYPE_ENUM` : `as_value` est ce que la propriété contient (et ce que donne `ue_value_changed`), `as_text` ce que la liste montre, en texte simple sans balisage (`""` montre la valeur). Rend `0` une fois ajoutée, `-5` pour une adresse qui n'est pas une propriété liste, une valeur que cette propriété offre déjà, ou une valeur qui contient `	`ou` / `(`of_keys_at `nomme une option par l'adresse de la propriété suivie de sa valeur : un seul niveau),` -2` si le composant n'est pas créé
`of_remove_option (string as_keys, string as_value)` → long	Retire une option de la liste d'une propriété `TYPE_ENUM`, par sa valeur. La valeur que contient la propriété reste telle quelle, même si c'était cette option. Rend `0` une fois retirée, `-5` pour une adresse qui n'est pas une propriété liste, ou une valeur que sa liste n'offre pas, `-2` si le composant n'est pas créé
`of_clear_options (string as_keys)` → long	Retire toutes les options d'une propriété `TYPE_ENUM`, pour charger une autre liste sans perdre la propriété, son handle, sa sélection ni ses drapeaux. La valeur qu'elle contient reste telle quelle : écrivez la nouvelle dans `is_value`. Rend `0` une fois vidée, `-5` pour une adresse qui n'est pas une propriété liste, `-2` si le composant n'est pas créé
`of_category (string as_key)` → `n_pbt_propertygrid_category`	Handle d'une catégorie, par sa clé (créé au premier accès) : son titre, son pli, sa visibilité et ses couleurs se posent par lui
`of_property (string as_keys)` → `n_pbt_propertygrid_property`	Handle d'une propriété, par son adresse (créé au premier accès) : sa valeur, son libellé, sa description, ses drapeaux et ses couleurs se posent et se lisent par lui. Une adresse que cette grille n'a pas ajoutée (une faute de frappe) rend un handle qui n'est pas gardé : y écrire ne fait rien, et `of_get_last_error` dit pourquoi
`of_remove_property (string as_keys)` → long	Retire une propriété, et son handle avec elle ; un groupe part avec tout ce qu'il contient. Si elle était sélectionnée, `ue_selection_changed` annonce qu'il n'y a plus de sélection. Rend `0` une fois retirée, `-5` pour une adresse que cette grille n'a jamais ajoutée, `-2` si le composant n'est pas créé
`of_remove_category (string as_key)` → long	Retire une catégorie et toutes ses propriétés, avec leurs handles. Si la sélection y était, `ue_selection_changed` annonce qu'il n'y en a plus. Rend `0` une fois retirée, `-5` pour une clé que cette grille n'a jamais ajoutée comme catégorie, `-2` si le composant n'est pas créé
`of_clear ( )` → long	Vide la grille : catégories, propriétés, options et handles. La vue, la barre d'outils, le volet d'aide et la recherche restent tels quels (c'est `of_reset` qui remet chaque propriété du composant). Si une ligne était sélectionnée, `ue_selection_changed` suit avec une adresse vide. Rend `0` une fois vidée, `-2` si le composant n'est pas créé
`of_select_property (string as_keys)` → long	Sélectionne une ligne, comme un clic : une propriété (`"page/margin"`) ou l'en-tête d'une catégorie (`"page"`). Ce qui contient la propriété s'ouvre d'abord : sa catégorie repliée, ses groupes fermés (`ue_category_toggled`, `ue_property_toggled`) — seulement si la ligne sera alors affichée : un appel refusé n'ouvre rien. `ue_selection_changed` suit, comme pour un clic. Rend `0` une fois sélectionnée (ou si elle l'était déjà), `-5` pour une adresse que cette grille n'a jamais ajoutée ou une ligne qui n'est pas affichée (masquée, hors de la recherche, au-delà du plafond de démonstration, un en-tête dans la vue alphabétique), `-2` si le composant n'est pas créé
`of_clear_selection ( )` → long	Ne laisse aucune ligne sélectionnée ; `ue_selection_changed` suit avec une adresse vide. Rien de sélectionné déjà : rien n'est levé. Rend `0` une fois appliqué, `-2` si le composant n'est pas créé
`of_selected_key ( )` → string	Adresse de la ligne sélectionnée, lue en direct, quel que soit celui qui l'a posée : `"page/margin"`, `"page"` pour un en-tête, `""` si aucune. C'est exactement ce que `ue_selection_changed` vous remet
`of_expand_all ( )` → long	Déplie toutes les catégories et ouvre tous les groupes ; `ue_category_toggled` suit pour chaque catégorie qui était repliée, `ue_property_toggled` pour chaque groupe qui était fermé. Rend `0` une fois appliqué, `-2` si le composant n'est pas créé
`of_collapse_all ( )` → long	Replie toutes les catégories et ferme tous les groupes ; `ue_category_toggled` et `ue_property_toggled` suivent pour chacun qui change. Rend `0` une fois appliqué, `-2` si le composant n'est pas créé
`of_dirty_keys (ref string as_keys[])` → long	Remplit `as_keys[]` des adresses des propriétés qui diffèrent de leur référence, dans l'ordre de la vue par catégorie, et rend leur nombre (`0` = rien à enregistrer) ; ce que l'utilisateur tape encore est validé d'abord
`of_is_dirty ( )` → boolean	`TRUE` quand au moins une propriété diffère de sa référence : la valeur avec laquelle elle a été ajoutée, ou ce qu'`of_load` ou `of_reset_update` en ont fait — que l'utilisateur ou votre code l'ait changée. Le même nom que sur le form. À ne pas confondre avec `is_default`, la valeur montrée en gras : celle-ci dit ce qu'il y a à enregistrer. Ce que l'utilisateur tape encore est validé d'abord, comme pour `of_values`
`of_load (string as_json)` → long	Charge des valeurs d'un coup : un objet JSON par adresse, la forme que rend `of_values` — les propriétés du haut, un objet par catégorie et par groupe (`{"name":"Orders","layout":{"width":800}}`) — ou des clés `"layout/width"`. Les valeurs sont écrites en silence (aucun `ue_value_changed`) et deviennent la référence d'`of_is_dirty` ; les erreurs affichées partent. Une propriété que l'objet ne nomme pas garde sa valeur, un nombre est lu chiffre pour chiffre. Une valeur que la grille ne peut pas prendre (aucune propriété à cette adresse, une valeur que son type ne tient pas) est sautée : le reste est écrit, et `of_get_last_error` nomme les adresses sautées. Ce que l'utilisateur tapait est abandonné. Rend `0` une fois appliqué (même avec des valeurs sautées), `-5` pour un texte qui n'est pas un objet JSON, `-2` si le composant n'est pas créé
`of_reset_update ( )` → long	Les valeurs en place deviennent la référence : `of_is_dirty` répond de nouveau `FALSE`. À appeler une fois vos réglages enregistrés, comme `ResetUpdate` d'un DataWindow. Rend `0` une fois appliqué, `-2` si le composant n'est pas créé
`of_revert ( )` → long	Remet chaque propriété à sa valeur de référence, en silence (aucun event, comme une valeur écrite par le code), et retire les erreurs affichées ; ce que l'utilisateur tapait est abandonné (rien n'est levé après) : le bouton Annuler de votre fenêtre de réglages. Rend `0` une fois appliqué, `-2` si le composant n'est pas créé
`of_clear_errors ( )` → long	Retire toutes les erreurs de votre application (`is_error` de chaque propriété). Un nombre tapé que la grille a refusé reste : l'utilisateur doit le corriger. Rend `0` une fois appliqué, `-2` si le composant n'est pas créé
`of_focus_property (string as_keys)` → long	Met le clavier sur une propriété, comme un clic sur sa valeur : ce qui la contient s'ouvre d'abord (`ue_category_toggled`, `ue_property_toggled`), elle est sélectionnée (`ue_selection_changed`) et son éditeur prend le clavier ; un groupe ou une propriété en lecture seule : la grille. Rend `0`, `-5` pour une adresse que cette grille n'a jamais ajoutée ou une ligne qui ne peut pas être affichée (masquée, hors de la recherche, au-delà du plafond de démonstration), `-2` si le composant n'est pas créé
`of_invalid_keys (ref string as_keys[])` → long	Remplit `as_keys[]` des adresses des propriétés en erreur, dans l'ordre de la vue par catégorie, et rend leur nombre (`0` = la grille est valide) ; ce que l'utilisateur tape encore est validé d'abord
`of_is_valid ( )` → boolean	`TRUE` quand aucune propriété affichée ne porte d'erreur : ni la vôtre (`is_error`), ni celle de la grille (un nombre tapé refusé : pas un nombre, hors de `is_min` / `is_max`). Ce que l'utilisateur tape encore est validé d'abord : un texte refusé compte. Le même nom que sur le form
`of_validate ( )` → long	Met le clavier sur la première propriété en erreur — sa catégorie et ses groupes s'ouvrent, elle est sélectionnée et son éditeur prend le clavier : ce qu'appelle votre bouton OK avant d'enregistrer. Ce que l'utilisateur tape encore est validé d'abord. Rend le nombre de propriétés en erreur (`0` = la grille est valide, rien ne bouge), `-2` si le composant n'est pas créé
`of_values ( )` → string	Toutes les valeurs d'un coup, lues en direct — ce que l'utilisateur tape encore est d'abord validé, comme par `AcceptText` (`ue_value_changing` si le veto est actif, puis `ue_value_changed`) —, en un objet JSON : les propriétés du haut, puis chaque catégorie comme un objet à elle, chaque groupe comme un objet dans ce qui le contient — masquées comprises. Typées : un nombre est un nombre, écrit chiffre pour chiffre (un décimal de 21 chiffres reste exact), un booléen un booléen, une couleur son long RGB, le reste du texte. Se lit avec `n_pbt_json`, par la même adresse : `lnv_json.of_get_number("page/margin")`, `lnv_json.of_get_number("appearance/font/size")`
`of_reset ( )` → long	Vide la grille (`of_clear`) puis ramène chaque propriété du composant à sa valeur par défaut : vue par catégorie, barre d'outils et volet d'aide visibles, libellés à 40 %, recherche vide, question désactivée. Rend `0` une fois appliqué, `-2` si le composant n'est pas créé

Sur une catégorie et sur une propriété #

Une catégorie contient des propriétés ; un groupe (TYPE_GROUP) contient ses sous-propriétés ; une propriété liste (TYPE_ENUM) contient ses options, désignées par leur valeur. Les trois méthodes les parcourent.

Méthode	Rôle
`of_count ( )` → long	Nombre de propriétés de la catégorie, masquées comprises ; nombre de sous-propriétés d'un groupe ; nombre d'options d'une propriété liste (`0` pour les autres types)
`of_keys_at (long al_index)` → string	Adresse de la propriété de rang `al_index` (à partir de 1) — `"page/margin"`, `"appearance/font/size"` sur un groupe, réinjectable telle quelle dans `of_property` ; sur une propriété liste, l'adresse suivie de la valeur de l'option. `""` hors bornes
`of_has (string as_key)` → boolean	La catégorie ou le groupe contient-il cette propriété ? La propriété liste offre-t-elle cette valeur ?

Événements #

Événement	Déclenché quand
`ue_value_changed (string as_keys, string as_value)`	L'utilisateur a changé une valeur (saisie validée par Entrée ou en quittant la cellule, case cochée au clic, à Espace ou à Entrée / F2, choix dans une liste, couleur, date, double-clic sur un libellé). `as_keys` est l'adresse de la propriété, `as_value` sa nouvelle valeur en texte ; elle est déjà écrite. Une valeur écrite par votre code (`is_value`) ne lève rien, comme `SetItem` : votre code sait ce qu'il a écrit. Suppr ou le bouton Réinitialiser (retour au défaut) et Haut / Bas dans un nombre sont des gestes de l'utilisateur : ils le lèvent aussi
`ue_value_changing (string as_keys, string as_value)` → boolean	Annulable, posé avant qu'une valeur de l'utilisateur ne soit écrite, et seulement quand `ib_veto_changes = true` (désactivé par défaut). Renvoyer `FALSE` refuse : la cellule reprend l'ancienne valeur, que `of_property(as_keys).is_value` rend encore pendant l'événement. Renvoyez `TRUE` pour accepter. Posez `of_property(as_keys).is_error` avant de refuser : l'utilisateur lit pourquoi
`ue_selection_changed (string as_from_keys, string as_keys)`	La sélection a bougé : un clic, le clavier, ou votre code (`of_select_property`, `of_clear_selection` — un ordre la lève aussi, comme `SelectItem`), ou la ligne sélectionnée est partie : repliée dans sa catégorie ou son groupe (`as_keys` est alors cet en-tête ou ce groupe), retirée, ou plus dessinée — masquée, cachée par la recherche (même par un pli fait pendant elle), au-delà du plafond de démonstration (`as_keys` vaut alors `""`). Une ligne est une propriété (`"page/margin"`) ou l'en-tête d'une catégorie (`"page"`) ; `as_from_keys` est celle qui a été quittée
`ue_category_toggled (string as_key, boolean ab_collapsed)`	Une catégorie s'est repliée (`ab_collapsed = TRUE`) ou dépliée : un clic sur son en-tête, le clavier, son `ib_collapsed` posé par votre code, `of_expand_all`, `of_collapse_all`, ou `of_select_property` sur une propriété qu'elle contient
`ue_property_toggled (string as_keys, boolean ab_expanded)`	Une propriété dépliable (`TYPE_GROUP`) s'est ouverte (`ab_expanded = TRUE`) ou fermée : un clic sur son chevron, un double-clic sur son libellé, le clavier, son `ib_expanded` posé par votre code, `of_expand_all`, `of_collapse_all`, ou `of_select_property` sur ce qu'elle contient. `as_keys` est l'adresse du groupe
`ue_ellipsis_clicked (string as_keys)`	Le bouton … d'une propriété (`ib_ellipsis`) a été cliqué, ou Ctrl+Entrée a été pressé sur sa ligne : ouvrez votre boîte de dialogue, puis écrivez le résultat dans `of_property(as_keys).is_value`. Le bouton reste actif sur une propriété en lecture seule : `of_property(as_keys).ib_readonly` dit s'il faut ouvrir votre boîte en lecture seule
`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`)

Clavier et souris #

Geste	Effet
Flèches haut / bas, Début / Fin, Page préc. / Page suiv.	Déplacent la sélection d'une ligne à l'autre ; Page préc. / Page suiv. avancent d'une hauteur de liste
Flèches gauche / droite	Sur un en-tête, replient ou déplient la catégorie ; sur un groupe, Droite l'ouvre et Gauche le ferme ; Droite sur un en-tête ou un groupe déjà ouvert descend sur sa première ligne ; sur une propriété, Gauche remonte à ce qui la contient, son groupe ou son en-tête (inversées de droite à gauche). Pendant une recherche, plier ou déplier ne fait rien, au clavier comme à la souris
Entrée, F2	Entrent dans l'éditeur de la propriété (ouvrent la liste, le sélecteur de couleur ou le calendrier) ; un booléen bascule ; sur un en-tête ou un groupe, replient ou déplient. Sans rien à faire (aucune ligne, une propriété en lecture seule), la touche est laissée à la fenêtre : son bouton par défaut
Espace	Coche ou décoche un booléen ; sur un en-tête ou un groupe, replie ou déplie
Entrée / Échap dans un éditeur	Valide la saisie / rend l'ancienne valeur ; le clavier revient à la liste. Échap dans un champ non modifié est laissé à la fenêtre : son bouton Annuler
Ctrl+Entrée	Le bouton … de la ligne sélectionnée (`ue_ellipsis_clicked`)
Tab	La liste des propriétés est un seul arrêt de tabulation, quelle que soit sa taille : parmi les éditeurs, seuls ceux de la ligne sélectionnée prennent Tab ; la liste qui a le clavier sans ligne sélectionnée se montre par un contour
Double-clic sur un libellé	Un booléen bascule, une liste passe au choix suivant, un groupe s'ouvre ou se ferme
Suppr	Sur la ligne sélectionnée : rétablit la valeur par défaut (`is_default`) ou, sans défaut, vide la valeur — un texte, un nombre, une date, une couleur, une liste ; un booléen sans défaut reste. Le bouton Réinitialiser (↺) de la barre d'outils rétablit le défaut lui aussi. Un geste de l'utilisateur : `ue_value_changed`
Retour arrière, une touche de caractère	Sur la ligne sélectionnée d'un texte, d'un nombre ou d'un mot de passe : commencent la saisie — Retour arrière ouvre l'éditeur, le texte gardé et le curseur à sa fin (il ne vide plus la valeur) ; une touche de caractère ouvre l'éditeur avec ce caractère, comme dans la fenêtre des propriétés de Visual Studio. Sur une liste, une couleur, une date ou une case : rien
F4, Alt+Bas	Ouvrent la liste, le sélecteur de couleur ou le calendrier de la ligne sélectionnée, depuis la liste comme depuis son bouton, comme une liste déroulante de Windows
Haut / Bas dans un nombre	Ajoutent / retirent `id_step`, dans `is_min` / `is_max` ; chaque pas lève `ue_value_changed`
Séparateur : Gauche / Droite, Début / Fin	La ligne entre libellés et valeurs prend le clavier (Tab) : Gauche / Droite la déplacent de 5 % (inversées de droite à gauche), Début / Fin la mènent aux bouts (`ii_label_width`)
Glisser la ligne entre libellés et valeurs	Change `ii_label_width`
Zone de recherche : Échap / Flèche bas ou Entrée	Efface la recherche / passe dans la liste, sur la première ligne si aucune n'est sélectionnée

Exemples #

Les réglages d'une fenêtre #

// The whole grid in one paint
uo_grid.of_set_redraw(/*on*/ false)

// At the top, without a category : the name of the window
uo_grid.of_add_property(/*keys*/ "name", /*label*/ "Name", /*type*/ u_pbt_propertygrid.TYPE_STRING, /*value*/ "Customers")

// A value given by the application : shown, not editable
uo_grid.of_add_category(/*key*/ "identity", /*title*/ "Identity")
uo_grid.of_add_property(/*keys*/ "identity/id", /*label*/ "Id", /*type*/ u_pbt_propertygrid.TYPE_STRING, /*value*/ "W-0042")
uo_grid.of_property(/*keys*/ "identity/id").ib_readonly = true
uo_grid.of_add_property(/*keys*/ "identity/created", /*label*/ "Created on", /*type*/ u_pbt_propertygrid.TYPE_DATE, /*value*/ String(Today(), "yyyy-mm-dd"))

// A number, a check box and a list of choices
uo_grid.of_add_category(/*key*/ "layout", /*title*/ "Layout")
uo_grid.of_add_property(/*keys*/ "layout/width", /*label*/ "Width", /*type*/ u_pbt_propertygrid.TYPE_NUMBER, /*value*/ "1200")
uo_grid.of_add_property(/*keys*/ "layout/resizable", /*label*/ "Resizable", /*type*/ u_pbt_propertygrid.TYPE_BOOLEAN, /*value*/ "true")
uo_grid.of_add_property(/*keys*/ "layout/state", /*label*/ "Window state", /*type*/ u_pbt_propertygrid.TYPE_ENUM, /*value*/ "normal")
uo_grid.of_add_option(/*keys*/ "layout/state", /*value*/ "normal", /*text*/ "Normal")
uo_grid.of_add_option(/*keys*/ "layout/state", /*value*/ "maximized", /*text*/ "Maximized")

// A colour, as its RGB long written out
uo_grid.of_add_category(/*key*/ "appearance", /*title*/ "Appearance")
uo_grid.of_add_property(/*keys*/ "appearance/back_color", /*label*/ "Back colour", /*type*/ u_pbt_propertygrid.TYPE_COLOR, /*value*/ String(RGB(/*red*/ 240, /*green*/ 244, /*blue*/ 250)))

// One single paint, then the first value to edit
uo_grid.of_set_redraw(/*on*/ true)
uo_grid.of_select_property(/*keys*/ "layout/width")

Un inspecteur qui applique chaque changement #

// event ue_value_changed of uo_grid : (string as_keys, string as_value)
// The address says which setting of the window the user changed
choose case as_keys
    case "name"
        w_customers.title = as_value
    case "layout/width"
        w_customers.width = Long(as_value)
    case "layout/resizable"
        w_customers.resizable = (as_value = "true")
    case "appearance/back_color"
        w_customers.backcolor = Long(as_value)
end choose

Le bouton … : une boîte de dialogue à vous #

// The icon : typed by hand, or chosen through the "..." button
uo_grid.of_add_property(/*keys*/ "appearance/icon", /*label*/ "Icon", /*type*/ u_pbt_propertygrid.TYPE_STRING, /*value*/ "img\customers.png")
uo_grid.of_property(/*keys*/ "appearance/icon").ib_ellipsis = true

// event ue_ellipsis_clicked of uo_grid : (string as_keys)
// Local variables
string ls_path, ls_file
constant unsignedlong OFN_EXPLORER = 2
constant unsignedlong OFN_NOCHANGEDIR = 64

// The application opens its own dialog - in the Explorer style, without moving the current folder of the application - then writes the result (this raises nothing)
if GetFileOpenName("Icon", ls_path, ls_file, "png", "Pictures (*.png),*.png", /*initdir*/ "", OFN_EXPLORER + OFN_NOCHANGEDIR) = 1 then
    uo_grid.of_property(/*keys*/ as_keys).is_value = ls_path
end if

Valider avant d'écrire #

// The question is OFF by default : turn it on to be able to refuse a value
uo_grid.ib_veto_changes = true

// event ue_value_changing of uo_grid : (string as_keys, string as_value)
// FALSE refuses : the cell shows the old value again. is_error, set before, tells
// the user why : the help pane shows it until the value is edited again
choose case as_keys
    case "layout/width"
        if Long(as_value) < 200 or Long(as_value) > 4000 then
            uo_grid.of_property(/*keys*/ as_keys).is_error = "Between 200 and 4000 pixels."
            return false
        end if
    case "name"
        if Trim(as_value) = "" then
            uo_grid.of_property(/*keys*/ as_keys).is_error = "A window needs a name."
            return false
        end if
end choose

// Any other value is accepted
return true

Valeurs par défaut, modifications et Annuler #

Deux notions distinctes, comme dans la fenêtre des propriétés de Visual Studio et dans un DataWindow : la valeur par défaut (is_default) dit ce qui s'écrit en gras et ce que Suppr rétablit ; la référence (of_load, of_reset_update) dit ce qu'il y a à enregistrer (of_is_dirty, of_dirty_keys) et ce qu'Annuler remet (of_revert).

// The defaults of the window : a value that differs is written in bold
uo_grid.of_property(/*keys*/ "layout/width").is_default = "800"
uo_grid.of_property(/*keys*/ "layout/state").is_default = "normal"

// The width the user may type, and what Up / Down add or take
uo_grid.of_property(/*keys*/ "layout/width").is_min = "200"
uo_grid.of_property(/*keys*/ "layout/width").is_max = "4000"
uo_grid.of_property(/*keys*/ "layout/width").id_step = 50

// The saved settings, read back : they become the reference
uo_grid.of_load(/*json*/ is_saved_settings)

// OK : every value right first - otherwise the keyboard goes to the first error
if uo_grid.of_validate() > 0 then return

// Save only what changed (what the user is still typing counts too), then the screen becomes the reference
if uo_grid.of_is_dirty() then
    is_saved_settings = uo_grid.of_values()
    uo_grid.of_reset_update()
end if

// Cancel : every value back to the settings loaded
uo_grid.of_revert()

Une propriété dépliable #

Une police tient en une ligne fermée, qui résume ses valeurs, et s'ouvre sur ses trois propriétés. Sans gabarit le résumé est Segoe UI; 9; False ; is_summary l'écrit à votre façon : Segoe UI, 9 pt, puis , bold tant que Bold est coché.

// A group in the category appearance : the font, closed when it is added
uo_grid.of_add_category(/*key*/ "appearance", /*title*/ "Appearance")
uo_grid.of_add_property(/*keys*/ "appearance/font", /*label*/ "Font", /*type*/ u_pbt_propertygrid.TYPE_GROUP, /*value*/ "")

// What it holds is added at its address
uo_grid.of_add_property(/*keys*/ "appearance/font/name", /*label*/ "Name", /*type*/ u_pbt_propertygrid.TYPE_STRING, /*value*/ "Segoe UI")
uo_grid.of_add_property(/*keys*/ "appearance/font/size", /*label*/ "Size", /*type*/ u_pbt_propertygrid.TYPE_NUMBER, /*value*/ "9")
uo_grid.of_add_property(/*keys*/ "appearance/font/bold", /*label*/ "Bold", /*type*/ u_pbt_propertygrid.TYPE_BOOLEAN, /*value*/ "false")

// Its summary, written your way : "Segoe UI, 9 pt", then ", bold" while Bold is checked
uo_grid.of_property(/*keys*/ "appearance/font").is_summary = "{name}, {size} pt{?bold}, bold{/bold}"

// Open it : its three values show under it
uo_grid.of_property(/*keys*/ "appearance/font").ib_expanded = true

// Local variables
n_pbt_json lnv_json
double ld_size

// The group is an object in the values : the same address reads its size
lnv_json.of_load(/*json*/ uo_grid.of_values())
ld_size = lnv_json.of_get_number(/*path*/ "appearance/font/size")

// event ue_property_toggled of uo_grid : (string as_keys, boolean ab_expanded)
// The group that opened or closed, by its address
if ab_expanded then
    lb_log.AddItem(as_keys + " opened")
else
    lb_log.AddItem(as_keys + " closed")
end if

Lire toutes les valeurs d'un coup #

// Local variables
n_pbt_json lnv_json
string ls_state

// Every value, typed, read along the same addresses as the grid
lnv_json.of_load(/*json*/ uo_grid.of_values())
w_customers.title = lnv_json.of_get_string(/*path*/ "name")
w_customers.width = lnv_json.of_get_number(/*path*/ "layout/width")
w_customers.resizable = lnv_json.of_get_boolean(/*path*/ "layout/resizable")

// One value alone : always text
ls_state = uo_grid.of_property(/*keys*/ "layout/state").is_value

Vues, recherche et largeur des libellés #

// One flat list sorted by label, instead of the categories
uo_grid.is_sort = u_pbt_propertygrid.SORT_ALPHABETICAL

// Keep only what speaks of a colour
uo_grid.is_filter = "colour"

// The labels take half of the width, and the help pane goes away
uo_grid.ii_label_width = 50
uo_grid.ib_help = false

Parcourir une catégorie #

// Local variables
n_pbt_propertygrid_category lnv_layout
string ls_keys
long ll_i

// Each property of the category, by its full address
lnv_layout = uo_grid.of_category(/*key*/ "layout")
for ll_i = 1 to lnv_layout.of_count()
    ls_keys = lnv_layout.of_keys_at(/*index*/ ll_i)
    lb_values.AddItem(ls_keys + " = " + uo_grid.of_property(/*keys*/ ls_keys).is_value)
next

Recharger une liste de choix #

// The states offered depend on the kind of window : the old choices go,
// the property keeps its handle, its flags and its place
uo_grid.of_clear_options(/*keys*/ "layout/state")

// The new choices, then the value to show among them
uo_grid.of_add_option(/*keys*/ "layout/state", /*value*/ "docked", /*text*/ "Docked")
uo_grid.of_add_option(/*keys*/ "layout/state", /*value*/ "floating", /*text*/ "Floating")
uo_grid.of_property(/*keys*/ "layout/state").is_value = "docked"

Bonnes pratiques #

Une valeur est un texte : un nombre s'écrit avec un point ("12.5"), un booléen "true"/"false", une couleur String(RGB(…)), une date "yyyy-mm-dd" — quelle que soit la langue du poste. Pour des valeurs typées, of_values et n_pbt_json.
Le code écrit en silence, l'utilisateur prévient : is_value ne lève rien, ue_value_changed ne parle que des gestes de l'utilisateur. Un seul endroit applique donc les changements, comme dans l'exemple de l'inspecteur.
Décrivez : une phrase dans is_description vaut mieux qu'un libellé à rallonge — le volet d'aide la montre au moment où l'utilisateur en a besoin.
ib_readonly plutôt que ib_visible = false pour une valeur que l'utilisateur doit voir sans pouvoir la changer.
Mode démonstration : sans clé, la grille dessine 8 lignes de propriétés, comptées dans l'ordre de l'écran (vue par catégorie) : un groupe fermé compte pour une ligne, et ses sous-propriétés — que son résumé montre — ne comptent qu'une fois le groupe ouvert ; les en-têtes de catégorie ne comptent pas. Le reste demeure en mémoire et dans of_values, mais ni un résumé ni la recherche n'en lisent la valeur (voir Licence).

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
`is_accessible_name` · `is_accessible_description`	Le nom et la description que dit un lecteur d'écran	3.4 Propriétés et events optionnels

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.