treeview — u_pbt_treeview #

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

treeview montre des données en arbre : des nœuds qui en contiennent d'autres, ouverts et fermés par leur chevron, avec une image, un badge, une case à cocher à trois états et une sélection simple ou multiple. Dès qu'on lui ajoute une colonne, il devient une liste en arbre (TreeList) : la première colonne porte l'arbre, les autres montrent les champs de chaque nœud, triables d'un clic sur leur en-tête. Une branche peut promettre des enfants qu'elle ne lit qu'à l'ouverture ; l'utilisateur renomme un nœud (F2) et le glisse ailleurs, votre application pouvant refuser avant ; une recherche ne garde que ce qui correspond. L'arbre se remplit à la main ou depuis un DataStore hiérarchique (une ligne nomme son parent), et peut y réécrire ce que l'utilisateur change.

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

En bref #

Démarrage rapide #

// Two levels : a continent, then its countries (the parent is added first)
uo_tree.of_add_node(/*keys*/ "europe", /*text*/ "Europe")
uo_tree.of_add_node(/*keys*/ "europe/france", /*text*/ "France")
uo_tree.of_add_node(/*keys*/ "europe/italy", /*text*/ "Italy")

// Open the continent : its countries show
uo_tree.of_node(/*keys*/ "europe").ib_expanded = true

// event ue_node_opened of uo_tree : (string as_keys)
// A double click or Enter on a node : your own window shows it
OpenWithParm(w_country, as_keys)

Une adresse par nœud #

Un nœud est désigné par son adresse : les clés de ses niveaux jointes par /. "europe" est en haut, "europe/france" dans "europe" — le parent est ajouté d'abord. Une clé est unique sous son parent : "europe/paris" et "usa/paris" sont deux nœuds. Une adresse prise, un parent inconnu, un niveau vide, une clé qui contient | ou commence par __ : l'ajout rend -5 et of_get_last_error dit pourquoi. of_insert_node place un nœud parmi ses frères (position comptée à partir de 1), of_move_node le déplace avec son sous-arbre sous un autre parent ("" = en haut) : son adresse change, et les poignées prises à l'ancienne adresse sont libérées aussitôt (une poignée prise ensuite à la nouvelle reste valable). Pour parcourir l'arbre : of_count() et of_keys_at(n) pour le premier niveau, of_count(adresse) et of_keys_at(adresse, n) pour les enfants d'un nœud — qui rend l'adresse complète, réutilisable telle quelle.

// Local variables
long ll_i

// Paris first among the cities of France, then Italy moved under a new region
uo_tree.of_add_node(/*keys*/ "europe/france/lyon", /*text*/ "Lyon")
uo_tree.of_insert_node(/*keys*/ "europe/france/paris", /*text*/ "Paris", /*image*/ "", /*position*/ 1)
uo_tree.of_add_node(/*keys*/ "south", /*text*/ "Southern Europe")
uo_tree.of_move_node(/*keys*/ "europe/italy", /*to_parent_keys*/ "south", /*position*/ 1)

// The children of France, by their whole address
for ll_i = 1 to uo_tree.of_count(/*keys*/ "europe/france")
    lb_cities.AddItem(uo_tree.of_keys_at(/*keys*/ "europe/france", /*index*/ ll_i))
next

Ouvrir, sélectionner, cocher #

Un nœud s'ouvre par son chevron, un double-clic, le clavier ou votre code (ib_expanded de sa poignée, of_expand_all, of_collapse_all, of_expand_to_level, of_scroll_to_node, ce qu'ouvre of_select_node ; of_clear_children ferme) : chacun lève ue_node_toggled, puis ue_layout_changed. La sélection suit is_selection_mode : un nœud (SELECT_SINGLE, le défaut), plusieurs avec Ctrl et Maj comme dans l'Explorateur (SELECT_MULTIPLE), ou aucun (SELECT_NONE : le clavier ne déplace qu'un focus). of_select_node sélectionne un nœud seul, ouvre ce qui le contient et l'amène à l'écran — un arbre ouvre pour sélectionner, comme le TreeView de Windows, mais il juge d'abord : un nœud masqué ou contenu par un masqué, au-delà du plafond démo ou écarté par la recherche est refusé (-5, of_get_last_error dit pourquoi) et rien ne s'ouvre. ue_selection_changed reçoit les adresses sélectionnées en tableau JSON — qu'un clic, le clavier ou votre code l'ait changée, ou qu'un nœud sélectionné ait quitté l'écran (branche fermée, nœud retiré ou masqué, nœud caché par la recherche). Fermer une branche y ramène le focus. Avec ib_checkboxes, chaque nœud a une case ; avec ib_check_cascade (le défaut), une coche de l'utilisateur sur un parent coche son sous-arbre sauf un nœud grisé et son sous-arbre, qui restent tels quels (le parent est alors mixte) ; une coche de votre code coche tout. Pendant une recherche, la cascade prend tout le sous-arbre, nœuds cachés compris. Sous la cascade, un parent est l'état des enfants que l'arbre peut dessiner (ni masqués ni, en mode démo, au-delà du plafond) : coché quand ils le sont tous, mixte quand une partie l'est. Une coche posée par l'utilisateur lève ue_node_checked ; une coche posée par votre code (ib_checked, of_check_all) est une valeur, muette comme SetItem. Les enfants reçus sous une feuille cochée prennent sa coche — tous, toute la réponse à ue_children_needed — jusqu'à ce qu'une coche (geste ou code) ou un nœud déplacé dedans y mette fin. Une coche de l'utilisateur ne touche jamais un nœud au-delà du plafond démo, ni, avec ib_write_back, un nœud masqué. of_select_nodes(as_keys_json) sélectionne plusieurs nœuds d'un coup en SELECT_MULTIPLE — le pendant d'of_selected_keys — avec une seule question aux vétos et un seul ue_selection_changed ; le focus va à la dernière adresse nommée.

// Local variables
n_pbt_json lnv_json
string ls_keys[]
long ll_i

// A box before each node : checking a parent checks its subtree
uo_tree.ib_checkboxes = true
uo_tree.of_node(/*keys*/ "europe/france").ib_checked = true

// Every checked node, in the order of the tree
lnv_json.of_load(/*json*/ uo_tree.of_checked_keys())
for ll_i = 1 to lnv_json.of_get_array(/*path*/ "", /*values*/ ls_keys)
    lb_chosen.AddItem(ls_keys[ll_i])
next

Demander d'abord : la sélection et l'ouverture #

Un écran maître-détail ne doit pas quitter une fiche non enregistrée. Avec ib_veto_selection, ue_selection_changing reçoit la sélection actuelle et celle demandée (tableaux JSON d'adresses) avant tout choix : un clic, Ctrl ou Maj + clic, le clavier, F3, of_select_node, of_clear_selection, of_search_next ou of_search_prev. Rendez FALSE pour refuser : rien ne bouge, pas même le focus du clavier, et la méthode rend -4 ; ue_node_clicked est levé quand même, le clic a eu lieu. Ce qui sort de la sélection par conséquence — une branche fermée, un nœud retiré, masqué ou caché par la recherche — n'est pas demandé. De même, ib_veto_toggle pose ue_node_toggling avant chaque ouverture ou fermeture, d'un geste ou du code : un ib_expanded refusé n'envoie rien (of_get_last_error le dit), of_expand_all, of_collapse_all et of_expand_to_level appliquent les autres nœuds et rendent -4, of_select_node et of_scroll_to_node rendent -4 sans rien ouvrir. of_select_node demande d'abord les ouvertures (ue_node_toggling), puis la sélection : une application n'agit jamais sur une sélection acceptée pour une ouverture refusée ensuite. Ce qui sort de la sélection par conséquence ne se refuse pas : pour qu'une branche qu'on ferme ne quitte pas une fiche non enregistrée, associez ib_veto_selection à ib_veto_toggle et refusez la fermeture de la branche qui la contient. ib_single_expand ne laisse qu'une branche ouverte sous chaque parent : ouvrir un nœud ferme ses sœurs ouvertes, sans rien demander ; le poser ne ferme rien sur le moment.

// A record shown beside the tree : ask before the selection leaves it, and before
// a branch closes (closing the branch that holds it would leave it)
uo_tree.ib_veto_selection = true
uo_tree.ib_veto_toggle = true

// event ue_selection_changing of uo_tree : (string as_from_keys_json, string as_keys_json)
// Unsaved changes in the detail : the user decides
if dw_detail.ModifiedCount() > 0 then
    if MessageBox("Unsaved changes", "Leave this record without saving?", Question!, YesNo!) = 2 then return false
end if
return true

// event ue_node_toggling of uo_tree : (string as_keys, boolean ab_expanding)
// Closing the branch that holds an unsaved record would leave it : refused
if not ab_expanding and dw_detail.ModifiedCount() > 0 then
    if Pos(uo_tree.of_selected_key() + "/", as_keys + "/") = 1 then return false
end if
return true

Des branches lues à la demande #

Un grand arbre — un disque, un catalogue, une table de milliers de lignes — n'a pas à être lu d'un coup. ib_has_children = true sur un nœud est une promesse : son chevron s'affiche alors qu'il ne contient rien. Quand il s'ouvre — un clic, le clavier, votre code, ou of_select_node qui ouvre ce qui contient un nœud —, ue_children_needed est levé : vos of_add_node faits pendant l'événement sont là quand la branche s'ouvre, après le retour de la ligne qui l'a ouverte (ib_expanded = true ne les attend pas). La promesse tient jusqu'à cette réponse, même si un nœud y a été ajouté ou déposé entre-temps ; n'ajoutez rien, et elle est retirée (le chevron disparaît). Reposer ib_has_children = true la fait redemander à la prochaine ouverture. Une ouverture faite pendant l'événement ne lève qu'un ue_node_toggled. of_expand_all n'ouvre que les branches qui ont déjà des enfants : une branche dont la promesse n'a pas répondu reste fermée, aucune question n'est posée en masse. Pour une table, inutile d'appeler of_add_node ligne par ligne : of_from_datastore(ads, as_parent_keys) fait des lignes d'un DataStore les enfants du nœud, en un seul envoi — le patron ItemPopulate → Retrieve du TreeView de PowerBuilder. ROLE_PARENT y nomme une ligne du même lot (vide ou inconnu : directement sous le nœud) ; le même DataStore redonné sous le même nœud remplace son lot, un autre DataStore ajoute le sien. of_row d'un nœud de lot rend sa ligne dans son DataStore, et ib_write_back y écrit. of_clear_children retire les enfants d'un nœud et lui fait promettre de nouveau : sa prochaine ouverture redemande (le « rafraîchir » d'un dossier). Donnez à chaque lot son propre DataStore (créé à l'ouverture de sa branche, gardé tant que ses nœuds sont montrés) : un DataStore rechargé pour un autre nœud — Reset, Retrieve, puis of_from_datastore sous un autre nœud — emporte ses lignes vers le nouveau lot, et PowerBuilder redonne les mêmes RowID après un Reset. Les nœuds du lot d'avant gardent alors ce qu'ils montrent mais n'ont plus de ligne : of_row rend 0, un déplacement par le code rend -5 (« loaded again »), un texte renommé ou une coche est refusé et ue_write_back_failed dit pourquoi, et le chargement qui l'a causé le compte (stale=N) dans of_get_last_error. Le même DataStore redonné sous le même nœud remplace son lot ; pour rafraîchir un lot depuis un autre objet DataStore, appelez d'abord of_clear_children, sinon il s'ajoute à côté du premier. Une colonne nommée has_children (ROLE_HAS_CHILDREN) fait promettre ses propres enfants à une ligne, sans boucle. as_parent_keys vide est refusé (-5) : le haut de l'arbre, c'est of_from_datastore(ads).

// A folder that promises children : nothing is read before it opens
uo_tree.of_add_node(/*keys*/ "docs", /*text*/ "Documents", /*image*/ "img\packimages.dll:png/folder")
uo_tree.of_node(/*keys*/ "docs").is_expanded_image = "mono:img\packimages.dll:svg/samples/folder-open"
uo_tree.of_node(/*keys*/ "docs").ib_has_children = true

// event ue_children_needed of uo_tree : (string as_keys)
// Local variables
datastore lds_folders
n_pbt_utils lnv_utils

// The folder opens : ITS sub-folders are retrieved into a DataStore of their own and
// added in ONE call - code is their key and name their text (of_map, once), the
// column has_children says whether each one promises its own
lds_folders = create datastore
lds_folders.DataObject = "d_folders"
lds_folders.SetTransObject(SQLCA)

// as_keys is the whole ADDRESS (docs/reports) : the code of the folder is its LAST key
lds_folders.Retrieve(lnv_utils.of_leaf(/*keys*/ as_keys))
uo_tree.of_from_datastore(/*ads*/ lds_folders, /*parent_keys*/ as_keys)

// One DataStore per lot, kept while its nodes are shown : of_row and ib_write_back
// read it ; the window destroys them when it closes
ids_lots[UpperBound(ids_lots) + 1] = lds_folders

Renommer et déplacer #

Avec ib_editable, l'utilisateur renomme un nœud : F2, ou un clic sur le nœud déjà sélectionné (après un court délai, comme l'Explorateur). Entrée (ou quitter le champ) garde le texte, Échap le rend, un texte vidé est refusé (l'édition s'annule) ; ue_node_edited reçoit le texte tapé et l'ancien — un texte tapé est du texte, jamais du balisage. Une commande de votre code pendant l'édition garde le champ et ce qui y est tapé ; si la ligne éditée quitte l'écran sans geste de l'utilisateur (code, défilement), l'édition est annulée. Avec ib_drag_drop, il glisse un nœud : sur le quart haut d'une ligne il va avant elle, sur le quart bas après — en premier enfant si c'est une branche ouverte —, au milieu dedans ; une branche fermée survolée s'ouvre au bout d'un instant, l'arbre défile près de ses bords, Échap annule, un nœud ne va jamais dans son propre sous-arbre ni là où sa clé est prise, et rien ne se dépose sur la ligne d'un nœud grisé. Un glisser dont l'arbre ne voit pas le bouton relâché — la fenêtre perd le focus (Alt+Tab, une boîte de message) — est annulé : rien ne bouge. Sous un tri, ou avec ib_parents_first, un dépôt ne va que dedans. ue_node_moved reçoit la nouvelle adresse, l'ancienne et la place sous le nouveau parent ; un nœud lâché à sa place ne demande, n'écrit ni ne lève rien. Avec ib_veto_changes, ue_node_editing et ue_node_moving sont posés avant — ue_node_moving avec la place finale, celle que dira ue_node_moved : rendez FALSE pour refuser — rien ne change, et of_move_node rend -4. Un seul nœud glisse à la fois, même en sélection multiple.

// Renaming and moving by the user, with a question before each change
uo_tree.ib_editable = true
uo_tree.ib_drag_drop = true
uo_tree.ib_veto_changes = true

// event ue_node_moving of uo_tree : (string as_keys, string as_to_parent_keys, long al_position)
// Nothing goes to the top level : FALSE keeps the node where it is
if as_to_parent_keys = "" then return false
return true

Votre code ouvre lui aussi un nom en édition : of_edit_node(as_keys) — l'EditLabel d'un TreeView PowerBuilder, pour un « Nouveau dossier » qui s'ouvre prêt à être nommé. Le nœud est d'abord sélectionné (ce qui le contient s'ouvre), puis le champ s'ouvre ; la fin appartient à l'utilisateur, comme ci-dessus. Un verrou arrête l'utilisateur, jamais votre code : il marche avec ib_editable = false, sur un nœud en lecture seule ou grisé. of_cancel_edit() ferme le champ et rend le texte, comme Échap.

// A new folder, opened at once in edit mode : the user types its name, then Enter
uo_tree.of_add_node(/*keys*/ "docs/new", /*text*/ "New folder")
uo_tree.of_edit_node(/*keys*/ "docs/new")

Verrous, Suppr et copie #

Trois verrous par nœud arrêtent l'utilisateur, jamais votre code : ib_read_only (ni renommé ni glissé, il reste une cible), ib_drop_target = false (rien n'est déposé dedans, ni un nœud ni un fichier — avant ou après lui reste permis) et ib_show_checkbox = false (pas de case : le nœud ne compte pas pour son parent, n'est pas dans of_checked_keys, et la cascade le traverse vers ses enfants). Suppr lève ue_delete_requested avec les nœuds sélectionnés (en SELECT_NONE, celui du focus ; sans sélection sinon, rien n'est levé), sauf grisés et en lecture seule : l'arbre ne retire rien, votre application appelle of_remove_node pour ce qu'elle supprime. Ctrl+C (ou Ctrl+Inser) lève ue_copy avec les nœuds sélectionnés (en SELECT_NONE, celui du focus) en texte tabulé, un nombre brut (un point, ni groupement ni symbole) : le texte après autant de tabulations que sa profondeur, puis les colonnes d'une liste en arbre alignées, une ligne d'en-tête d'abord ; l'arbre essaie aussi le presse-papiers du navigateur, que la page peut se voir refuser — ClipBoard(as_tsv) pour être sûr.

// The system folder : neither renamed nor dragged, nothing dropped into it, no check box
uo_tree.of_node(/*keys*/ "system").ib_read_only = true
uo_tree.of_node(/*keys*/ "system").ib_drop_target = false
uo_tree.of_node(/*keys*/ "system").ib_show_checkbox = false

// event ue_delete_requested of uo_tree : (string as_keys_json)
// Local variables
n_pbt_json lnv_json
string ls_keys[]
long ll_i

// Delete pressed : the tree removes nothing, your application decides
lnv_json.of_load(/*json*/ as_keys_json)
for ll_i = 1 to lnv_json.of_get_array(/*path*/ "", /*values*/ ls_keys)
    uo_tree.of_remove_node(/*keys*/ ls_keys[ll_i])
next

// event ue_copy of uo_tree : (string as_tsv)
// Ctrl+C : the nodes copied, ready for a spreadsheet
ClipBoard(as_tsv)

Des fichiers déposés depuis l'Explorateur #

Avec ib_allow_drop, l'arbre accepte des fichiers glissés depuis l'Explorateur de Windows sur un nœud : le nœud sous le curseur s'allume pendant le glisser, ue_drop_files reçoit son adresse et les chemins complets. as_keys est vide pour un dépôt à côté des nœuds, sur un nœud grisé ou sur un nœud dont ib_drop_target vaut false. ue_drag_enter et ue_drag_leave disent qu'un glisser de fichiers est entré, puis reparti sans rien déposer.

// Files of the Explorer dropped on a folder of the tree
uo_tree.ib_allow_drop = true

// event ue_drop_files of uo_tree : (string as_keys, string as_files[])
// The folder under the cursor : your application copies the files there
if as_keys <> "" then wf_copy_files(as_files, uo_tree.of_get_field(/*keys*/ as_keys, /*field*/ "path"))

Colonnes, tri et disposition #

of_add_column fait de l'arbre une liste en arbre : la première colonne porte l'arbre (son titre est is_tree_title), chaque colonne ajoutée montre le champ de même clé de chaque nœud — posé par of_set_field, ou une colonne du DataStore. La poignée d'une colonne (of_column) règle son titre, sa largeur (0 = automatique), son alignement, son format (un masque numérique comme "#,##0.00" aux séparateurs de la langue d'affichage, ou des jetons de date pour une valeur "yyyy-mm-dd", ceux du datagrid), sa visibilité et sa place. Un clic sur un en-tête trie les frères de chaque niveau — croissant, décroissant, puis l'ordre d'ajout — et lève ue_sort_changed ; of_sort fait de même par le code. Le tri ne change que l'ordre affiché : of_keys_at et les positions gardent l'ordre d'ajout. L'utilisateur élargit une colonne par le bord de son en-tête et la déplace en glissant l'en-tête. Ce qu'il a arrangé — largeurs, ordre, visibilité, tri, nœuds ouverts — se lit par of_get_layout et se rend par of_set_layout ; ue_layout_changed porte la disposition entière après chaque geste qui la change, et quand votre code écrit la largeur, la place ou la visibilité d'une colonne (ii_width, ii_index, ib_visible) et que la disposition change. Des valeurs égales gardent l'ordre du modèle, et le tri est refait quand la langue d'affichage change. Retirer la colonne triée (of_remove_column, of_clear_columns) lève ue_sort_changed avec la clé suivante du tri — SORT_NONE quand c'était la seule —, puis ue_layout_changed. Les cinq couleurs de la poignée d'une colonne (il_accent, il_back_color, il_text_color, il_back_color_hover, il_text_color_hover) colorent son en-tête. Dès qu'il y a des colonnes, la colonne de l'arbre reste figée au défilement horizontal. Le tri peut porter sur plusieurs clés : of_sort(as_sort) lit la syntaxe du SetSort d'un DataWindow (« type A, text D », « text » étant le texte des nœuds), of_sort(as_column, as_dir) accepte aussi un champ qu'aucune colonne ne montre, et ue_sort_changed reçoit le tri entier en troisième argument. ib_parents_first met à chaque niveau les nœuds qui ont (ou promettent) des enfants avant les feuilles — les dossiers avant les fichiers — quel que soit le tri. Une colonne ne peut pas prendre la clé text, qui nomme le texte des nœuds (-5) : of_sort("text", as_dir) trie par lui, et of_sort accepte plusieurs blancs entre une colonne et son sens, comme SetSort.

// A tree list : the population of each country beside the tree
uo_tree.is_tree_title = "Country"
uo_tree.of_add_column(/*key*/ "population", /*title*/ "Population", /*width*/ 120)
uo_tree.of_column(/*key*/ "population").is_format = "#,##0"
uo_tree.of_column(/*key*/ "population").is_align = u_pbt_treeview.ALIGN_END
uo_tree.of_set_field(/*keys*/ "europe/france", /*field*/ "population", /*value*/ "68000000")

// The largest countries first, inside each continent
uo_tree.of_sort(/*column*/ "population", /*dir*/ u_pbt_treeview.SORT_DESC)

// The folders first, then by type and by name
uo_tree.ib_parents_first = true
uo_tree.of_sort(/*sort*/ "type A, text A")

Exporter l'arbre avec sa hiérarchie : of_export_csv(as_path) écrit un CSV (UTF-8, point-virgule) où le texte d'un nœud se tient dans la cellule de son niveau — une cellule plus à droite par niveau —, les colonnes d'une liste en arbre après le niveau le plus profond, une ligne d'en-tête d'abord ; of_export_xlsx(as_path) écrit un classeur Excel où le texte est en retrait de son niveau et chaque branche groupée sous son parent, repliables dans Excel, les nombres restant des nombres. is_export_scope dit lesquels : EXPORT_ALL (le défaut) tous les nœuds, branches fermées comprises, EXPORT_SHOWN les lignes à l'écran. L'arbre construit le fichier, la DLL l'écrit, ue_csv_saved / ue_xlsx_saved confirment ; refusé en mode démo.

// The tree written to Excel - every node, the closed branches too ; ue_xlsx_saved confirms
uo_tree.is_export_scope = u_pbt_treeview.EXPORT_ALL
uo_tree.of_export_xlsx(/*path*/ "C:\exports\countries.xlsx")

Des totaux par branche #

Une colonne d'une liste en arbre peut montrer, sur chaque branche, le total de ce qu'elle contient : is_summary sur sa poignée vaut SUMMARY_SUM, SUMMARY_AVG, SUMMARY_MIN, SUMMARY_MAX ou SUMMARY_COUNT (les valeurs non vides). Le calcul descend jusqu'aux feuilles — une moyenne est celle des feuilles, jamais une moyenne de moyennes — et le total s'écrit en gras, par is_format — un compte toujours en nombre brut. Une branche qui a sa propre valeur la garde et la fait remonter, sauf avec ib_summary_over_value sur la colonne. Ne comptent que les nœuds que l'arbre peut dessiner (jamais un masqué) ; avec ib_summary_filtered, sur le composant, seulement ce que la recherche montre. of_get_field rend le total brut (un nombre au point), le tri sur cette colonne utilise les totaux, et les totaux suivent chaque ajout, retrait ou glisser. SUMMARY_MIN et SUMMARY_MAX comparent aussi des dates (yyyy-mm-dd, yyyy-mm-dd hh:mm:ss, hh:mm:ss), et une somme d'entiers reste exacte au-delà de 2^53.

// Each continent shows the sum of its countries, in bold
uo_tree.of_column(/*key*/ "population").is_summary = u_pbt_treeview.SUMMARY_SUM

// The total of Europe, read like a field
st_total.text = uo_tree.of_get_field(/*keys*/ "europe", /*field*/ "population")

Rechercher #

is_filter ne montre que les nœuds dont le texte contient la recherche (casse ignorée), avec les nœuds qui les contiennent, ouverts, et le texte trouvé surligné. "" rend tout. Ce qui contient une correspondance s'affiche ouvert sans changer ib_expanded, et les chevrons sont inertes le temps de la recherche. Avec ib_toolbar, une barre au-dessus de l'arbre porte un champ de recherche (qui écrit is_filter : une lecture le rend à l'instant), et les boutons Tout déplier et Tout replier. Échap dans le champ vide la recherche, Flèche bas passe à l'arbre, Entrée et F3 vont à la correspondance suivante (Maj : la précédente) sans que le champ perde le clavier. Un nœud sélectionné que la recherche cache sort de la sélection, et ue_selection_changed le dit ; le nœud qui le contient n'est pas sélectionné à sa place. of_select_node et of_scroll_to_node refusent un nœud que la recherche écarte (-5). Pour aller de correspondance en correspondance, of_search_next et of_search_prev sélectionnent la suivante ou la précédente après le nœud du focus, en boucle (F3 et Maj+F3 au clavier), et of_match_count dit combien la recherche en a trouvé. of_find_node(as_field, as_value, as_after_keys) trouve sans filtrer : l'adresse du premier nœud dont le champ ("" = son texte) vaut exactement la valeur, dans l'ordre que l'arbre montre, branches fermées comprises ; redonnez l'adresse trouvée pour le suivant. En SELECT_NONE, of_search_next et of_search_prev y déplacent le focus, comme F3. of_find_node part après la place d'as_after_keys dans l'ordre affiché — un nœud masqué aussi ; un nœud inconnu rend "" et of_get_last_error le dit. of_find_nodes(as_field, as_value) rend toutes les correspondances d'un coup, en tableau JSON dans l'ordre affiché.

La recherche ignore les accents par défaut, comme le tri : « montreal » trouve « Montréal », et le I pointé du turc compte pour un I (« izmir » trouve « İzmir ») ; ib_filter_accents = true les fait compter. En sélection multiple, Ctrl+A sélectionne tous les nœuds affichés (une seule question avec ib_veto_selection).

// A search field above the tree, and a first search from the code
uo_tree.ib_toolbar = true
uo_tree.is_filter = "par"

// Local variables
string ls_keys

// The first node whose code is FR, selected if there is one
ls_keys = uo_tree.of_find_node(/*field*/ "code", /*value*/ "FR", /*after_keys*/ "")
if ls_keys <> "" then uo_tree.of_select_node(/*keys*/ ls_keys)

// Every node whose status is late, selected at once (a multiple selection)
uo_tree.is_selection_mode = u_pbt_treeview.SELECT_MULTIPLE
uo_tree.of_select_nodes(/*keys_json*/ uo_tree.of_find_nodes(/*field*/ "status", /*value*/ "late"))

Depuis un DataStore #

of_from_datastore fait un nœud de chaque ligne d'une table hiérarchique : la colonne ROLE_KEY donne sa clé (sans elle, le RowID de la ligne), la colonne ROLE_PARENT nomme la clé du nœud qui le contient (vide, inconnue, ou une boucle : en haut) — avec une colonne ROLE_KEY, une valeur de parent nomme une clé, jamais un RowID. Les autres rôles : le texte (ROLE_TEXT, montré comme texte, jamais comme balisage), l'image, la coche, le badge et l'ouverture au chargement. Une colonne joue un rôle quand elle s'appelle comme lui (key, parent, text…) ou quand of_map le dit. Chaque colonne est un champ (of_get_field) — les colonnes de la liste ne sont pas créées pour vous : of_add_column avec le nom de la colonne. Dates et nombres sont lus quels que soient les réglages régionaux, sous une seule forme : une date yyyy-mm-dd, une date-heure yyyy-mm-dd hh:mm:ss, un nombre au point sans zéro inutile (1234,50 devient 1234.5) — une colonne décimale se met en forme et se trie comme un nombre. Deux lignes de même clé : la seconde prend "clé~RowID". Ce que le chargement a dû corriger (lignes dont le parent n'est pas là, boucles cassées, clés en double, clés impossibles) est dit par of_get_last_error, le retour restant 0. of_reload_row relit une ligne changée par votre code et met son nœud à jour en place ; une ligne dont la clé ou le parent a changé déplace son nœud. Le nœud d'une ligne retiré par of_remove_node reste parti jusqu'au prochain of_from_datastore ; of_reload_row de sa ligne le ramène. Avec ib_write_back, un texte renommé est écrit dans la colonne ROLE_TEXT et un nœud qui change de parent l'écrit dans la colonne ROLE_PARENT (NULL en haut, quel que soit son type ; un déplacement parmi les mêmes frères n'écrit rien), avant l'événement ; un nœud de ligne ne va alors ni sous un nœud posé à la main, ni sous une ligne sans valeur de clé — sa colonne parent ne saurait pas le dire. Une valeur que le DataStore refuse, ou un DataStore détruit depuis le chargement (no DataStore is bound), remet le nœud en place et lève ue_write_back_failed. Sans ib_write_back, un glisser ne déplace que le nœud : sa ligne garde ce que dit le DataStore, et la relecture suivante des lignes (of_map, is_group_by, of_reload_row, un nouveau chargement) remet le nœud où sa ligne le dit — son ancienne poignée est libérée. L'Update reste à vous. La poignée d'un nœud lit le numéro de sa ligne (of_row). of_from_datastore lit aussi les lignes d'un DataWindow ou d'un DataWindowChild — celui que l'utilisateur voit à côté : l'arbre écrit alors dans celui-là. Avec ib_write_back, une coche de l'utilisateur s'écrit aussi dans la colonne ROLE_CHECKED de chaque ligne qu'elle a changée — la cascade comprise, et les branches au-dessus dont l'état passe à coché ou décoché (une branche qui devient mixte garde sa valeur) —, épelée comme la colonne l'écrit déjà (1/0, Y/N, T/F, O/N, -1/0… ; une colonne qui ne montre que son non écrit le oui habituel : Y pour N, 1 pour 0 — O et -1 seulement si la colonne en a déjà un) ; une colonne dont les valeurs ne sont ni un oui ni un non est refusée, avec sa raison. Chaque valeur est jugée d'abord et l'écriture est tout ou rien : un refus rend les coches du geste et lève ue_write_back_failed. of_row_keys rend l'adresse du nœud d'une ligne du DataStore principal : retirez le nœud avant un DeleteRow. Tout write-back est tout ou rien — chaque valeur jugée avant qu'une seule ne s'écrive ; une date-heure garde son heure, une colonne time s'écrit, se lit et se groupe en hh:mm:ss. Un déplacement écrit par of_move_node est rejugé après ue_node_moving, et ce qui était écrit est remis si le nœud ne bouge pas. Avec ib_write_back, un nœud de ligne dont le DataStore n'a pas de colonne ROLE_TEXT ne se renomme pas. Un nouveau chargement ne libère que les poignées de ce qu'il remplace : celle d'un nœud posé à la main, une poignée inerte ou prise à une adresse pas encore créée restent valides ; of_from_datastore depuis un DataWindow vérifie que ses données se partagent (-5 avec la raison). Ce qu'une relecture des lignes a dû redresser se compte dans of_get_last_error — y compris les nœuds posés à la main remontés en tête parce que leur groupe n'existe plus (lifted=N) et les lots partis avec leur nœud (lots=N) ; of_map et is_group_by le disent pour toutes les sources.

// The departments : each row names its parent by its id
ids_depts.Retrieve()
uo_tree.of_map(/*role*/ u_pbt_treeview.ROLE_KEY, /*column*/ "dept_id")
uo_tree.of_map(/*role*/ u_pbt_treeview.ROLE_PARENT, /*column*/ "parent_id")
uo_tree.of_map(/*role*/ u_pbt_treeview.ROLE_TEXT, /*column*/ "dept_name")
uo_tree.of_from_datastore(/*ads*/ ids_depts)

// Two columns of the DataStore shown beside the tree
uo_tree.of_add_column(/*key*/ "head_count", /*title*/ "Staff")
uo_tree.of_add_column(/*key*/ "budget", /*title*/ "Budget")
uo_tree.of_column(/*key*/ "budget").is_format = "#,##0"

// A renamed or moved department is written into its row before the event
uo_tree.ib_write_back = true
uo_tree.ib_editable = true
uo_tree.ib_drag_drop = true

// event ue_node_moved of uo_tree : (string as_keys, string as_old_keys, long al_position)
// parent_id is already written in the row : save it
if ids_depts.Update() = 1 then commit using sqlca;

Un rôle se résout par DataStore : la colonne qu'of_map(ads, as_role, as_column) a donnée à ce DataStore, sinon celle d'of_map(as_role, as_column) quand ce DataStore l'a, sinon la colonne qui porte le nom du rôle. Un lot d'employés sous un arbre de départements n'a donc besoin d'aucune colonne des départements. Une table dont les racines portent 0 dans leur colonne parent (une colonne NOT NULL) le dit par is_root_parent_value = "0" ("0|-1" pour deux valeurs) : ces lignes sont en haut sans compter comme orphelines, et un nœud remonté en haut avec ib_write_back écrit 0 au lieu de NULL. Les colonnes ROLE_STATE_IMAGE et ROLE_OVERLAY_IMAGE donnent l'image d'état et l'image superposée d'un nœud, lues comme ROLE_IMAGE.

// event ue_children_needed of uo_tree : (string as_keys)
// Local variables
datastore lds_staff
n_pbt_utils lnv_utils

// The employees of the department that opens, in a DataStore of their own
lds_staff = create datastore
lds_staff.DataObject = "d_staff"
lds_staff.SetTransObject(SQLCA)
lds_staff.Retrieve(lnv_utils.of_leaf(/*keys*/ as_keys))

// THEIR key and THEIR text : the departments keep dept_id and dept_name
uo_tree.of_map(/*ads*/ lds_staff, /*role*/ u_pbt_treeview.ROLE_KEY, /*column*/ "emp_id")
uo_tree.of_map(/*ads*/ lds_staff, /*role*/ u_pbt_treeview.ROLE_TEXT, /*column*/ "emp_name")
uo_tree.of_from_datastore(/*ads*/ lds_staff, /*parent_keys*/ as_keys)

// Kept while its nodes are shown ; the window destroys them when it closes
ids_lots[UpperBound(ids_lots) + 1] = lds_staff

// The roots of the table carry 0 in parent_id (a NOT NULL column) : 0 names the top
uo_tree.is_root_parent_value = "0"
uo_tree.of_from_datastore(/*ads*/ ids_depts)

Un arbre groupé par colonnes #

Le style TreeView d'un DataWindow, sans DataWindow : is_group_by = "region|country|city" fait des lignes de of_from_datastore les feuilles de groupes bâtis sur les valeurs de ces colonnes, un niveau par colonne (ROLE_PARENT n'y joue aucun rôle, ROLE_KEY nomme les feuilles). La clé d'un groupe est sa valeur (/, | et % écrits %2F, %7C, %25), son texte la valeur écrite au format de la colonne de même clé, « (vide) » pour une valeur vide ; la poignée d'un nœud de groupe lit of_group_column() et of_group_value(). Posé après un chargement, il regroupe ; of_reload_row range une ligne dont une valeur a changé dans son nouveau groupe. of_set_level_image donne une image à tous les nœuds d'un niveau, of_expand_to_level ouvre l'arbre jusqu'à un niveau, et is_summary donne les totaux de chaque groupe. Avec ib_write_back, une feuille déposée sous un groupe du dernier niveau écrit toutes ses colonnes de groupe avant l'événement ; ailleurs, et pour un nœud de groupe, le déplacement est refusé. Le texte d'un groupe suit un format posé après le chargement, l'arrivée de sa colonne et la langue d'affichage ; une valeur qui commence par __ s'écrit %5F_ dans la clé ; of_group_value d'une date-heure vaut yyyy-mm-dd hh:mm:ss, d'une heure hh:mm:ss. Sans ib_write_back, une feuille glissée sous un autre groupe retourne dans le sien au regroupement suivant, puisque sa ligne n'a pas changé ; un nœud posé à la main sous un groupe qui disparaît remonte en tête.

// The sales, one row per sale, grouped by region, country and city : the customer is
// the text of each sale
uo_tree.is_group_by = "region|country|city"
uo_tree.of_map(/*role*/ u_pbt_treeview.ROLE_TEXT, /*column*/ "customer")
uo_tree.of_from_datastore(/*ads*/ ids_sales)

// The amount of each sale, and the total of each group
uo_tree.of_add_column(/*key*/ "amount", /*title*/ "Amount")
uo_tree.of_column(/*key*/ "amount").is_format = "#,##0.00"
uo_tree.of_column(/*key*/ "amount").is_summary = u_pbt_treeview.SUMMARY_SUM

// A globe before every region ; only the regions show at first
uo_tree.of_set_level_image(/*level*/ 1, /*image*/ "mono:img\packimages.dll:svg/ribbon/globe", /*expanded_image*/ "")
uo_tree.of_expand_to_level(/*level*/ 1)

Propriétés #

Propriétés d'un nœud — n_pbt_treeview_node #

Sa poignée, par of_node(adresse). Une lecture demande à l'arbre ce qu'est le nœud maintenant. Son of_count() compte ses enfants, son of_keys_at(n) rend l'adresse de son n-ième enfant (à partir de 1), son of_has(clé) dit s'il a cet enfant, son of_key() rend sa clé.

Propriétés d'une colonne — n_pbt_treeview_column #

Sa poignée, par of_column(clé). Une valeur écrite par votre code est muette, comme SetItem — sauf sa disposition : ii_width, ii_index et ib_visible écrits par votre code lèvent ue_layout_changed quand la disposition change, comme un geste. Une lecture rend ce que l'utilisateur a pu changer (largeur, place).

Constantes #

Elles vivent sur u_pbt_treeview : u_pbt_treeview.CHECK_MIXED.

Méthodes #

Événements #

Clavier et souris #

• Clic sur un nœud : il est sélectionné (ue_node_clicked) ; sur son chevron : il s'ouvre ou se ferme ; sur sa case : il est coché ; double-clic : ue_node_opened, et une branche s'ouvre ou se ferme ; clic droit : ue_node_rclicked. En SELECT_MULTIPLE, Ctrl + clic ajoute ou retire un nœud, Maj + clic prend la plage depuis le dernier.
• Haut / Bas : le nœud précédent, le suivant ; Début / Fin : le premier, le dernier ; Page préc. / Page suiv. : d'un écran. Les nœuds grisés sont sautés.
• Droite ouvre le nœud, puis descend à son premier enfant ; Gauche le ferme, puis remonte à son parent — inversées dans une application de droite à gauche. * du pavé numérique ouvre tout le sous-arbre ; + / - du pavé numérique ouvrent et ferment — ceux du clavier principal se tapent, pour atteindre « +1.2 » ou « -Débits ».
• Espace coche le nœud (avec ib_checkboxes), sinon le sélectionne ; Entrée : ue_node_opened ; F2 : renommer (avec ib_editable) ; touche Menu ou Maj + F10 : ue_node_rclicked.
• En SELECT_MULTIPLE, Maj + flèches étendent la sélection, Ctrl + flèches ne déplacent que le focus, Ctrl + Espace ajoute ou retire le nœud du focus, Ctrl + A sélectionne tous les nœuds affichés (une seule question avec ib_veto_selection).
• Les premières lettres d'un texte sélectionnent le nœud affiché qui commence par elles, comme une flèche (en SELECT_NONE, elles n'y amènent que le focus).
• Suppr : ue_delete_requested (l'arbre ne retire rien) ; Ctrl+C ou Ctrl+Inser : ue_copy ; F3 / Maj+F3 : la correspondance suivante / précédente de la recherche (en SELECT_NONE, le focus y va), depuis l'arbre ou depuis le champ de recherche, où Entrée fait de même. Suppr et Ctrl+C n'agissent sur le nœud du focus qu'en SELECT_NONE.
• L'en-tête d'une liste en arbre est un arrêt de la touche Tab : Gauche / Droite vont d'en-tête en en-tête (inversées dans une application de droite à gauche), Début / Fin au premier et au dernier, Entrée ou Espace trie, Ctrl + Gauche / Droite rétrécit ou élargit la colonne de 10 pixels, Ctrl + Maj + Gauche / Droite la déplace, Bas passe aux lignes.
• Glisser un nœud (avec ib_drag_drop) : un fantôme suit le pointeur, une barre montre où il tombera avant ou après, un cadre quand il tombe dedans ; Échap annule. Glisser le bord d'un en-tête élargit la colonne, glisser l'en-tête la déplace — un fantôme et une barre d'insertion montrent où, Échap annule —, cliquer l'en-tête trie. Un glisser dont l'arbre ne voit pas le bouton relâché — la fenêtre perd le focus (Alt+Tab, une boîte de message) — est annulé : rien ne bouge, une largeur revient.
• L'arbre est un arrêt de la touche Tab (plus l'en-tête d'une liste en arbre, le champ et les boutons de la barre d'outils) ; un anneau pointillé de la couleur du texte marque le nœud qui a le focus. Un arbre grisé ne prend pas le focus.

Exemples #

Des droits à cocher #

// The rights of a role : a module, then what it allows
uo_rights.ib_checkboxes = true
uo_rights.of_add_node(/*keys*/ "sales", /*text*/ "Sales")
uo_rights.of_add_node(/*keys*/ "sales/read", /*text*/ "Read orders")
uo_rights.of_add_node(/*keys*/ "sales/write", /*text*/ "Create and change orders")
uo_rights.of_add_node(/*keys*/ "sales/delete", /*text*/ "Delete orders")

// What the role already has ; Sales shows mixed
uo_rights.of_node(/*keys*/ "sales/read").ib_checked = true
uo_rights.of_node(/*keys*/ "sales").ib_expanded = true

// event ue_node_checked of uo_rights : (string as_keys, boolean ab_checked)
// Delete never without write : checking it checks write too
if as_keys = "sales/delete" and ab_checked then this.of_node(/*keys*/ "sales/write").ib_checked = true

Retrouver sa disposition au prochain lancement #

// event ue_layout_changed of uo_tree : (string as_layout_json)
// Widths, order, sort and open nodes, kept for the next start
// (the nodes need STABLE keys : a ROLE_KEY column, never the RowIDs a new Retrieve gives)
SetProfileString("app.ini", "tree", "layout", as_layout_json)

// Local variables
string ls_layout

// After the tree is filled : the layout of the last time, if there is one
ls_layout = ProfileString("app.ini", "tree", "layout", "")
if ls_layout <> "" then uo_tree.of_set_layout(/*layout_json*/ ls_layout)

Un menu sur un nœud #

// The entries of the menu, once : uo_menu is a contextmenu of the window, and
// is_menu_keys a string instance variable that keeps the node right-clicked
uo_menu.of_add_item(/*keys*/ "expand", /*text*/ "Expand")
uo_menu.of_add_item(/*keys*/ "delete", /*text*/ "Delete")

// event ue_node_rclicked of uo_tree : (string as_keys, long al_x, long al_y)
// The node clicked is kept : the selection may have stayed elsewhere (a veto that
// refused it, SELECT_NONE). The menu opens where the user clicked
is_menu_keys = as_keys
uo_menu.of_show(/*x*/ al_x, /*y*/ al_y)

// event ue_item_selected of uo_menu : (string as_keys)
// The entry chosen acts on the node right-clicked
choose case as_keys
    case "expand"
        uo_tree.of_node(/*keys*/ is_menu_keys).ib_expanded = true
    case "delete"
        uo_tree.of_remove_node(/*keys*/ is_menu_keys)
end choose

Bonnes pratiques #

• Des clés stables : un identifiant, pas un libellé — le texte se renomme, la clé reste. of_keys_at rend des adresses complètes, à passer telles quelles à of_node. Une disposition gardée d'un lancement à l'autre (of_get_layout) exige une colonne ROLE_KEY : sans elle, les clés des lignes sont leurs RowID, qu'un nouveau Retrieve donne à d'autres lignes.
• Des branches à la demande dès que l'arbre est grand ou coûteux à lire : ib_has_children et ue_children_needed ne lisent que ce que l'utilisateur ouvre.
• Un DataStore par lot : rechargé pour un autre nœud, un DataStore emporte ses lignes — et PowerBuilder ses RowID — loin du lot d'avant, dont les nœuds n'ont alors plus de ligne.
• Beaucoup de nœuds : seules les lignes visibles sont dessinées — dix mille nœuds défilent comme vingt. Les ajouter est une autre affaire : chaque of_add_node est un message à l'arbre, environ 0,7 ms (2 000 nœuds ≈ 1,3 s mesurées, 10 000 ≈ 7 s attendues) ; un gros arbre se charge par of_from_datastore, en un seul message, ou se lit à la demande, un lot par branche (of_from_datastore(ads, as_parent_keys)).
• Les colonnes d'un DataStore sont des identifiants autant que des valeurs : choisissez celles que vous montrez par of_add_column, rien n'est créé pour vous.
• Une coche est une valeur : posée par votre code, elle ne lève rien ; lisez of_checked_keys quand l'utilisateur valide.
• of_get_last_error dit pourquoi le dernier appel a été refusé ; il est vidé par toute méthode qui agit et toute propriété écrite, et par of_find_node / of_find_nodes, qui disent par lui pourquoi ils n'ont rien trouvé.
• Un ordre donné pendant une attente (du code PowerBuilder qui s'exécute pendant que l'arbre attend sa page, un timer par exemple) n'est pas vérifié d'avance : la page décide seule, et un ajout ou un déplacement qu'elle refuse rend quand même 0.
• Pendant une attente (un événement du composant en cours de réponse), un ordre de votre code n'est pas jugé d'avance : ib_expanded et of_move_node passent le véto sans poser la question, et of_get_last_error le dit. Posez vos ordres hors de l'événement quand le véto compte.
• of_set_layout remet un état — typiquement au démarrage — sans poser les questions de ib_veto_selection ni de ib_veto_toggle : c'est l'exception à la règle qui veut qu'un ordre du code pose la question.
• Mode démonstration : sans clé, l'arbre dessine les 8 premiers nœuds de chaque niveau et 200 nœuds dans tout l'arbre (les premiers ajoutés), dans l'ordre du modèle — avant le tri, la recherche et le masquage : un nœud masqué compte, une recherche ou un tri ne montrent jamais le neuvième, lots et groupes compris, et un total ne compte jamais ce que le plafond cache ; les autres restent en mémoire, sans être affichés ni sélectionnables (voir le mode démo).

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