treeview — u_pbt_treeview #

← Component reference · Guide contents

treeview shows data as a tree: nodes that hold others, opened and closed by their chevron, with a picture, a badge, a three-state check box and a single or multiple selection. As soon as it is given a column, it becomes a tree list (TreeList): the first column carries the tree, the others show the fields of each node, sorted by a click on their header. A branch can promise children it reads only when it opens; the user renames a node (F2) and drags it elsewhere, your application being able to refuse first; a search keeps only what matches. The tree is filled by hand or from a hierarchical DataStore (a row names its parent), and can write back into it what the user changes.

▶ See it live — Demo application, Tree view tile: the preview, the code behind it and this page, side by side.

At a glance #

Quick start #

// 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)

One address per node #

A node is named by its address: the keys of its levels joined with /. "europe" is at the top, "europe/france" inside "europe" — the parent is added first. A key is unique under its parent: "europe/paris" and "usa/paris" are two nodes. An address already taken, an unknown parent, an empty level, a key that holds | or starts with __: the add returns -5 and of_get_last_error says why. of_insert_node puts a node among its siblings (a position counted from 1), of_move_node moves it with its subtree under another parent ("" = the top): its address changes, and the handles taken at the old address are freed at once (a handle taken afterwards at the new one stays valid). To walk the tree: of_count() and of_keys_at(n) for the top level, of_count(address) and of_keys_at(address, n) for the children of a node — which returns the whole address, reusable as it is.

// 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

Opening, selecting, checking #

A node opens by its chevron, a double click, the keyboard or your code (ib_expanded of its handle, of_expand_all, of_collapse_all, of_expand_to_level, of_scroll_to_node, what of_select_node opens; of_clear_children closes): each one raises ue_node_toggled, then ue_layout_changed. The selection follows is_selection_mode: one node (SELECT_SINGLE, the default), several with Ctrl and Shift as in the Explorer (SELECT_MULTIPLE), or none (SELECT_NONE: the keyboard only moves a focus). of_select_node selects a node alone, opens what holds it and brings it on screen — a tree opens to select, like the TreeView of Windows, but it judges first: a node hidden or held by a hidden one, beyond the demo cap or left out by the search is refused (-5, of_get_last_error says why) and nothing opens. ue_selection_changed receives the selected addresses as a JSON array — whether a click, the keyboard or your code changed it, or a selected node left the screen (a branch closed, a node removed or hidden, a node the search hides). Closing a branch brings the focus back onto it. With ib_checkboxes, each node has a box; with ib_check_cascade (the default), a check of the user on a parent checks its subtree except a greyed node and its subtree, which stay as they are (the parent then shows mixed); a check of your code checks everything. During a search, the cascade takes the whole subtree, hidden nodes included. Under the cascade, a parent is the state of the children the tree can draw (neither hidden nor, in demo mode, beyond the cap): checked when they all are, mixed when some are. A check set by the user raises ue_node_checked; a check set by your code (ib_checked, of_check_all) is a value, silent like SetItem. The children received under a checked leaf take its check — all of them, the whole answer to ue_children_needed — until a check (user or code) or a node moved inside ends it. A check of the user never touches a node beyond the demo cap, nor, with ib_write_back, a hidden one. of_select_nodes(as_keys_json) selects several nodes at once in SELECT_MULTIPLE — the pendant of of_selected_keys — with one question to the vetoes and one ue_selection_changed; the focus goes to the last address named.

// 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

Asking first: selection and opening #

A master-detail screen must not leave an unsaved record. With ib_veto_selection, ue_selection_changing receives the selection now and the one asked (JSON arrays of addresses) before any choice: a click, Ctrl or Shift + click, the keyboard, F3, of_select_node, of_clear_selection, of_search_next or of_search_prev. Return FALSE to refuse: nothing moves, not even the keyboard focus, and the method returns -4; ue_node_clicked is raised anyway, the click took place. What leaves the selection as a consequence — a branch closed, a node removed, hidden or hidden by the search — is not asked. In the same way, ib_veto_toggle asks ue_node_toggling before each opening or closing, by a gesture or by the code: a refused ib_expanded sends nothing (of_get_last_error says it), of_expand_all, of_collapse_all and of_expand_to_level apply the other nodes and return -4, of_select_node and of_scroll_to_node return -4 without opening anything. of_select_node asks the openings first (ue_node_toggling), then the selection: an application never acts on a selection accepted for an opening it then refused. What leaves the selection as a consequence cannot be refused: to keep a closing branch from leaving an unsaved record, pair ib_veto_selection with ib_veto_toggle and refuse closing the branch that holds it. ib_single_expand leaves one open branch under each parent: opening a node closes its open siblings, without asking; setting it closes nothing at once.

// 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

Branches loaded on demand #

A large tree — a disk, a catalogue, a table of thousands of rows — need not be read at once. ib_has_children = true on a node is a promise: its chevron shows although it holds nothing. When it opens — a click, the keyboard, your code, or of_select_node opening what holds a node — ue_children_needed is raised: your of_add_node made during the event are there when the branch opens, after the line that opened it has returned (ib_expanded = true does not wait for them). The promise holds until that answer, even if a node was added or dropped inside meanwhile; add nothing, and it is withdrawn (the chevron goes). Set ib_has_children = true again and the next opening asks again. An opening made during the event raises one ue_node_toggled only. of_expand_all only opens the branches that already have children: a branch whose promise has not been answered stays closed, no question is asked in bulk. For a table, there is no need to call of_add_node row by row: of_from_datastore(ads, as_parent_keys) makes the rows of a DataStore the children of the node, in one message — the ItemPopulate → Retrieve pattern of the PowerBuilder TreeView. ROLE_PARENT there names a row of the same lot (empty or unknown: right under the node); the same DataStore given again under the same node replaces its lot, another DataStore adds its own. of_row of a node of a lot returns its row in its DataStore, and ib_write_back writes there. of_clear_children removes the children of a node and makes it promise again: its next opening asks again (the "refresh" of a folder). Give each lot its own DataStore (created when its branch opens, kept while its nodes are shown): a DataStore loaded again for another node — Reset, Retrieve, then of_from_datastore under another node — takes its rows to the new lot, and PowerBuilder gives the same RowIDs again after a Reset. The nodes of the earlier lot then keep what they show but have no row any more: of_row returns 0, a move by the code returns -5 ("loaded again"), a renamed text or a check is refused and ue_write_back_failed says why, and the load that caused it counts them (stale=N) in of_get_last_error. The same DataStore given again under the same node replaces its lot; to refresh a lot from another DataStore object, call of_clear_children first, or it is added beside the first one. A column named has_children (ROLE_HAS_CHILDREN) makes a row promise its own children, with no loop. as_parent_keys empty is refused (-5): the top of the tree is 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

Renaming and moving #

With ib_editable, the user renames a node: F2, or a click on the node already selected (after a short delay, like the Explorer). Enter (or leaving the field) keeps the text, Escape gives it back, an emptied text is refused (the edit is cancelled); ue_node_edited receives the text typed and the old one — a typed text is text, never markup. A command of your code during the edit keeps the field and what is typed in it; if the row being edited leaves the screen without a gesture of the user (code, scrolling), the edit is cancelled. With ib_drag_drop, they drag a node: on the top quarter of a row it goes before it, on the bottom quarter after it — as the first child when it is an open branch —, in the middle inside it; a closed branch held under the pointer opens after a moment, the tree scrolls near its edges, Escape cancels, a node never goes into its own subtree nor where its key is taken, and nothing is dropped on the row of a greyed node. A drag whose released button the tree cannot see — the window loses the focus (Alt+Tab, a message box) — is cancelled: nothing moves. Under a sort, or with ib_parents_first, a drop only goes inside. ue_node_moved receives the new address, the old one and the place under the new parent; a node dropped where it already is asks, writes and raises nothing. With ib_veto_changes, ue_node_editing and ue_node_moving are asked before — ue_node_moving with the final place, the one ue_node_moved will say: return FALSE to refuse — nothing changes, and of_move_node returns -4. One node is dragged at a time, even in a multiple selection.

// 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

Your code opens a name for editing too: of_edit_node(as_keys) — the EditLabel of a PowerBuilder TreeView, for a “New folder” that opens ready to be named. The node is selected first (what holds it opens), then the field opens; the end is the user's, as above. A lock stops the user, never your code: it works with ib_editable = false, on a read-only or a greyed node. of_cancel_edit() closes the field and gives the text back, like Escape.

// 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")

Locks, Delete and copy #

Three locks per node stop the user, never your code: ib_read_only (neither renamed nor dragged, it stays a target), ib_drop_target = false (nothing is dropped into it, neither a node nor a file — before or after it stays allowed) and ib_show_checkbox = false (no box: the node does not count for its parent, is not in of_checked_keys, and the cascade passes through it to its children). Delete raises ue_delete_requested with the selected nodes (in SELECT_NONE, the focused one; nothing selected otherwise: nothing is raised), except greyed and read-only ones: the tree removes nothing, your application calls of_remove_node for what it deletes. Ctrl+C (or Ctrl+Insert) raises ue_copy with the selected nodes (in SELECT_NONE, the focused one) as tab-separated text, a number raw (a dot, no grouping nor symbol): the text after as many tabs as its depth, then the columns of a tree list aligned, a header line first; the tree also tries the clipboard of the browser, which the page may be refused — ClipBoard(as_tsv) to be certain.

// 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)

Files dropped from the Explorer #

With ib_allow_drop, the tree accepts files dragged from the Windows Explorer onto a node: the node under the cursor lights up during the drag, ue_drop_files receives its address and the full paths. as_keys is empty for a drop beside the nodes, on a greyed node or on a node whose ib_drop_target is false. ue_drag_enter and ue_drag_leave tell that a drag of files came in, then left without dropping.

// 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"))

Columns, sort and layout #

of_add_column makes the tree a tree list: the first column carries the tree (its title is is_tree_title), each column added shows the field of the same key of each node — set by of_set_field, or a column of the DataStore. The handle of a column (of_column) sets its title, its width (0 = automatic), its alignment, its format (a numeric mask such as "#,##0.00" with the separators of the display language, or date tokens for a "yyyy-mm-dd" value, those of the datagrid), its visibility and its place. A click on a header sorts the siblings of every level — ascending, descending, then the order of addition — and raises ue_sort_changed; of_sort does the same from the code. The sort only changes the order shown: of_keys_at and the positions keep the order of addition. The user widens a column by the edge of its header and moves it by dragging the header. What they arranged — widths, order, visibility, sort, open nodes — is read by of_get_layout and given back by of_set_layout; ue_layout_changed carries the whole layout after every gesture that changes it, and when your code writes the width, the place or the visibility of a column (ii_width, ii_index, ib_visible) and the layout changes. Equal values keep the order of the model, and the sort is made again when the display language changes. Removing the sorted column (of_remove_column, of_clear_columns) raises ue_sort_changed with the next key of the sort — SORT_NONE when it was the only one —, then ue_layout_changed. The five colours of the handle of a column (il_accent, il_back_color, il_text_color, il_back_color_hover, il_text_color_hover) colour its header. As soon as there are columns, the tree column stays frozen when the list scrolls sideways. The sort can bear on several keys: of_sort(as_sort) reads the syntax of a DataWindow's SetSort ("type A, text D", "text" being the text of the nodes), of_sort(as_column, as_dir) also takes a field no column shows, and ue_sort_changed receives the whole sort as its third argument. ib_parents_first puts at every level the nodes that have (or promise) children before the leaves — the folders before the files — whatever the sort. A column cannot take the key text, which names the text of the nodes (-5): of_sort("text", as_dir) sorts by it, and of_sort accepts several blanks between a column and its direction, as SetSort does.

// 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")

Exporting the tree with its hierarchy: of_export_csv(as_path) writes a CSV (UTF-8, semicolon) where the text of a node stands in the cell of its level — one cell to the right per level —, the columns of a tree list after the deepest level, a header line first; of_export_xlsx(as_path) writes an Excel workbook where the text is indented by its level and every branch grouped under its parent, foldable in Excel, numbers staying numbers. is_export_scope says which nodes: EXPORT_ALL (the default) every node, closed branches included, EXPORT_SHOWN the rows on the screen. The tree builds the file, the DLL writes it, ue_csv_saved / ue_xlsx_saved confirm; refused in demo mode.

// 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")

Branch totals #

A column of a tree list can show, on every branch, the total of what it holds: is_summary on its handle is SUMMARY_SUM, SUMMARY_AVG, SUMMARY_MIN, SUMMARY_MAX or SUMMARY_COUNT (the values that are not empty). The computation goes down to the leaves — an average is that of the leaves, never an average of averages — and the total is written in bold, by is_format — a count always as a plain number. A branch that has its own value keeps it and brings it up, except with ib_summary_over_value on the column. Only the nodes the tree can draw count (never a hidden one); with ib_summary_filtered, on the component, only what the search shows. of_get_field returns the raw total (a number with a dot), a sort on this column uses the totals, and the totals follow every add, removal or drag. SUMMARY_MIN and SUMMARY_MAX also compare dates (yyyy-mm-dd, yyyy-mm-dd hh:mm:ss, hh:mm:ss), and a sum of whole numbers stays exact beyond 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")

Searching #

is_filter only shows the nodes whose text holds the search (case ignored), with the nodes that hold them, open, and the text found highlighted. "" shows everything. What holds a match shows open without changing ib_expanded, and the chevrons are inert while the search lasts. With ib_toolbar, a bar above the tree carries a search field (which writes is_filter: a read gives it at once), and the Expand all and Collapse all buttons. Escape in the field empties the search, Down arrow goes to the tree, Enter and F3 go to the next match (Shift: the previous one) while the field keeps the keyboard. A selected node the search hides leaves the selection, and ue_selection_changed says it; the node that holds it is not selected in its place. of_select_node and of_scroll_to_node refuse a node the search leaves out (-5). To go from match to match, of_search_next and of_search_prev select the next or the previous one after the node with the focus, round the list (F3 and Shift+F3 from the keyboard), and of_match_count says how many the search found. of_find_node(as_field, as_value, as_after_keys) finds without filtering: the address of the first node whose field ("" = its text) holds exactly the value, in the order the tree shows, closed branches included; give the address found back for the next one. In SELECT_NONE, of_search_next and of_search_prev move the focus there, as F3 does. of_find_node starts after the place of as_after_keys in the order shown — a hidden node too; an unknown one returns "" and of_get_last_error says it. of_find_nodes(as_field, as_value) gives every match at once, as a JSON array in the order shown.

The search ignores accents by default, like the sort: “montreal” finds “Montréal”, and the dotted capital I of Turkish counts as an I (“izmir” finds “İzmir”); ib_filter_accents = true makes them count. In multiple selection, Ctrl+A selects every node shown (one question with 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"))

From a DataStore #

of_from_datastore makes one node of each row of a hierarchical table: the ROLE_KEY column gives its key (without it, the RowID of the row), the ROLE_PARENT column names the key of the node that holds it (empty, unknown, or a loop: at the top) — with a ROLE_KEY column, a parent value names a key, never a RowID. The other roles: the text (ROLE_TEXT, shown as text, never as markup), the picture, the check, the badge and whether it starts open. A column plays a role when it is named like it (key, parent, text…) or when of_map says so. Every column is a field (of_get_field) — the columns of the list are not created for you: of_add_column with the column name. Dates and numbers are read whatever the regional settings, in one form: a date yyyy-mm-dd, a date-time yyyy-mm-dd hh:mm:ss, a number with a dot and no useless zero (1234,50 becomes 1234.5) — a decimal column is formatted and sorted as a number. Two rows with one key: the second takes "key~RowID". What the load had to put right (rows whose parent is not there, loops broken, keys taken twice, keys that cannot be one) is said by of_get_last_error, the return staying 0. of_reload_row reads one row changed by your code again and updates its node in place; a row whose key or parent changed moves its node. The node of a row removed by of_remove_node stays out until the next of_from_datastore; of_reload_row of its row brings it back. With ib_write_back, a renamed text is written into the ROLE_TEXT column and a node that changes parent writes it into the ROLE_PARENT column (NULL at the top, whatever its type; a move among the same siblings writes nothing), before the event; a node of a row then goes neither under a node added by hand nor under a row without a key value — its parent column could not say it. A value the DataStore refuses, or a DataStore destroyed since the load (no DataStore is bound), puts the node back and raises ue_write_back_failed. Without ib_write_back, a drag only moves the node: its row keeps what the DataStore says, and the next reading of the rows (of_map, is_group_by, of_reload_row, a new load) puts the node back where its row says — its old handle is freed. The Update stays yours. The handle of a node reads the number of its row (of_row). of_from_datastore also reads the rows of a DataWindow or a DataWindowChild — the one the user sees beside it: the tree then writes into that one. With ib_write_back, a check of the user is also written into the ROLE_CHECKED column of every row it changed — the cascade included, and the branches above whose state turns checked or unchecked (a branch that becomes mixed keeps its value) —, spelled the way the column already writes it (1/0, Y/N, T/F, O/N, -1/0…; a column that shows only its no writes the usual yes: Y for N, 1 for 0 — O and -1 only when the column already holds one); a column holding values that are neither a yes nor a no is refused, with its reason. Every value is judged first and the write is all or nothing: a refusal gives the checks of the gesture back and raises ue_write_back_failed. of_row_keys returns the address of the node of a row of the main DataStore: remove the node before a DeleteRow. Every write-back is all or nothing — each value judged before one is written; a date and time keeps its time, a time column is written, read and grouped as hh:mm:ss. A move written by of_move_node is judged again after ue_node_moving, and what was written goes back if the node does not move. With ib_write_back, a node of a row whose DataStore has no ROLE_TEXT column cannot be renamed. A new load frees only the handles of what it replaces: the handle of a node added by hand, an inert handle or one taken at an address not created yet stay valid; of_from_datastore from a DataWindow checks that its data can be shared (-5 with the reason). What a reading of the rows had to put right is counted in of_get_last_error — including the nodes added by hand lifted to the top because their group is gone (lifted=N) and the lots that left with their node (lots=N); of_map and is_group_by report it for every source.

// 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;

A role resolves per DataStore: the column of_map(ads, as_role, as_column) gave this DataStore, else that of of_map(as_role, as_column) when this DataStore has it, else the column named like the role. A lot of employees under a tree of departments thus needs none of the columns of the departments. A table whose roots carry 0 in their parent column (a NOT NULL column) says so by is_root_parent_value = "0" ("0|-1" for two values): those rows stand at the top without counting as orphans, and a node moved to the top with ib_write_back writes 0 instead of NULL. The ROLE_STATE_IMAGE and ROLE_OVERLAY_IMAGE columns give the state picture and the overlay picture of a node, read like 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)

A tree grouped by columns #

The TreeView style of a DataWindow, without a DataWindow: is_group_by = "region|country|city" makes the rows of of_from_datastore the leaves of groups built on the values of those columns, one level per column (ROLE_PARENT plays no part, ROLE_KEY names the leaves). The key of a group is its value (/, | and % written %2F, %7C, %25), its text the value written with the format of the column of the same key, "(empty)" for an empty value; the handle of a group node reads of_group_column() and of_group_value(). Set after a load, it groups again; of_reload_row puts a row whose value changed into its new group. of_set_level_image gives a picture to every node of a level, of_expand_to_level opens the tree down to a level, and is_summary gives the totals of each group. With ib_write_back, a leaf dropped under a group of the last level writes all its group columns before the event; elsewhere, and for a group node, the move is refused. The text of a group follows a format set after the load, the arrival of its column and the display language; a value starting with __ is written %5F_ in the key; of_group_value of a date and time is yyyy-mm-dd hh:mm:ss, of a time hh:mm:ss. Without ib_write_back, a leaf dragged under another group goes back to its own at the next grouping, since its row did not change; a node added by hand under a group that disappears goes up to the top.

// 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)

Properties #

Properties of a node — n_pbt_treeview_node #

Its handle, through of_node(address). A read asks the tree what the node is now. Its of_count() counts its children, its of_keys_at(n) returns the address of its n-th child (counted from 1), its of_has(key) says whether it has that child, its of_key() returns its key.

Properties of a column — n_pbt_treeview_column #

Its handle, through of_column(key). A value written by your code is silent, like SetItem — except its layout: ii_width, ii_index and ib_visible written by your code raise ue_layout_changed when the layout changes, as a gesture does. A read returns what the user may have changed (width, place).

Constants #

They live on u_pbt_treeview: u_pbt_treeview.CHECK_MIXED.

Methods #

Events #

Keyboard and mouse #

• Click on a node: it is selected (ue_node_clicked); on its chevron: it opens or closes; on its box: it is checked; double click: ue_node_opened, and a branch opens or closes; right click: ue_node_rclicked. In SELECT_MULTIPLE, Ctrl + click adds or takes away a node, Shift + click takes the range from the last one.
• Up / Down: the previous node, the next one; Home / End: the first, the last; Page Up / Page Down: by a screen. Greyed nodes are skipped.
• Right opens the node, then goes down to its first child; Left closes it, then goes up to its parent — inverted in a right-to-left application. * of the numeric keypad opens the whole subtree; + / - of the numeric keypad open and close — those of the main keyboard are typed, to reach “+1.2” or “-Debits”.
• Space checks the node (with ib_checkboxes), otherwise selects it; Enter: ue_node_opened; F2: rename (with ib_editable); context-menu key or Shift + F10: ue_node_rclicked.
• In SELECT_MULTIPLE, Shift + arrows extend the selection, Ctrl + arrows only move the focus, Ctrl + Space adds or takes away the node with the focus, Ctrl + A selects every node shown (one question with ib_veto_selection).
• The first letters of a text select the node shown that starts with them, as an arrow does (in SELECT_NONE, they only bring the focus to it).
• Delete: ue_delete_requested (the tree removes nothing); Ctrl+C or Ctrl+Insert: ue_copy; F3 / Shift+F3: the next / previous match of the search (in SELECT_NONE, the focus goes there), from the tree or from the search field, where Enter does the same. Delete and Ctrl+C act on the node with the focus in SELECT_NONE only.
• The header of a tree list is one stop of the Tab key: Left / Right go from header to header (inverted in a right-to-left application), Home / End to the first and the last, Enter or Space sorts, Ctrl + Left / Right narrows or widens the column by 10 pixels, Ctrl + Shift + Left / Right moves it, Down goes to the rows.
• Drag a node (with ib_drag_drop): a ghost follows the pointer, a bar shows where it will fall before or after, a frame when it falls inside; Escape cancels. Drag the edge of a header to widen the column, drag the header to move it — a ghost and an insertion bar show where, Escape cancels —, click the header to sort. A drag whose released button the tree cannot see — the window loses the focus (Alt+Tab, a message box) — is cancelled: nothing moves, a width comes back.
• The tree is one stop of the Tab key (plus the header of a tree list, the field and the buttons of the toolbar); a dotted ring in the colour of the text marks the node with the focus. A greyed tree takes no focus.

Examples #

Rights to check #

// 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

Finding the layout again at the next start #

// 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)

A menu on a node #

// 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

Good practice #

• Stable keys: an id, not a label — the text is renamed, the key stays. of_keys_at returns whole addresses, to give as they are to of_node. A layout kept from one run to the next (of_get_layout) needs a ROLE_KEY column: without it, the keys of the rows are their RowIDs, which a new Retrieve gives to other rows.
• Branches on demand as soon as the tree is large or costly to read: ib_has_children and ue_children_needed read only what the user opens.
• One DataStore per lot: loaded again for another node, a DataStore takes its rows — and PowerBuilder its RowIDs — away from the earlier lot, whose nodes then have no row any more.
• Many nodes: only the visible rows are drawn — ten thousand nodes scroll like twenty. Adding them is another matter: each of_add_node is a message to the tree, about 0.7 ms (2,000 nodes ≈ 1.3 s measured, 10,000 ≈ 7 s expected); a large tree is loaded by of_from_datastore, in one message, or read on demand, one lot per branch (of_from_datastore(ads, as_parent_keys)).
• The columns of a DataStore are ids as much as values: choose those you show with of_add_column, nothing is created for you.
• A check is a value: set by your code, it raises nothing; read of_checked_keys when the user confirms.
• of_get_last_error says why the last call was refused; it is emptied by every method that acts and every property written, and by of_find_node / of_find_nodes, which say through it why they found nothing.
• An order given during a wait (PowerBuilder code running while the tree waits for its page, a timer for instance) is not checked beforehand: the page decides alone, and an add or a move it refuses still returns 0.
• During a wait (an event of the component being answered), an order of your code is not judged beforehand: ib_expanded and of_move_node pass the veto without asking the question, and of_get_last_error says it. Give your orders outside the event when the veto matters.
• of_set_layout puts back a state — typically at the start — without asking the questions of ib_veto_selection and ib_veto_toggle: it is the exception to the rule that an order of the code asks the question.
• Demo mode: without a key, the tree draws the first 8 nodes of each level and 200 nodes in the whole tree (the first ones added), in the order of the model — before the sort, the search and the hiding: a hidden node counts, a search or a sort never shows the ninth, lots and groups included, and a total never counts what the cap hides; the others stay in memory, neither shown nor selectable (see demo mode).

Inherited from the common base #

These members exist on every visual component — they are not specific to this one. They are detailed once, in the transverse chapters; this table only says where to read them.

Two helpers are not inherited: of_icon and of_escape_markup live on n_pbt_utils. Declare one — n_pbt_utils lnv_utils, nothing to create — and call them on it.

← Component reference · Guide contents