treeview — u_pbt_treeview #

← Riferimento dei componenti · Sommario della guida

treeview mostra dati ad albero: nodi che ne contengono altri, aperti e chiusi dal loro chevron, con un'immagine, un badge, una casella a tre stati e una selezione singola o multipla. Appena gli si aggiunge una colonna, diventa una lista ad albero (TreeList): la prima colonna porta l'albero, le altre mostrano i campi di ogni nodo, ordinabili con un clic sulla loro intestazione. Un ramo può promettere figli che legge solo all'apertura; l'utente rinomina un nodo (F2) e lo trascina altrove, e la vostra applicazione può rifiutare prima; una ricerca tiene solo ciò che corrisponde. L'albero si riempie a mano o da un DataStore gerarchico (una riga nomina il suo padre), e può riscrivervi ciò che l'utente cambia.

▶ Vederlo dal vivo — Applicazione dimostrativa, riquadro Tree view: l'anteprima, il codice che lo produce e questa pagina, affiancati.

In breve #

Avvio rapido #

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

Un indirizzo per nodo #

Un nodo è designato dal suo indirizzo: le chiavi dei suoi livelli unite da /. "europe" è in cima, "europe/france" dentro "europe" — il padre si aggiunge prima. Una chiave è unica sotto il suo padre: "europe/paris" e "usa/paris" sono due nodi. Un indirizzo già preso, un padre sconosciuto, un livello vuoto, una chiave che contiene | o comincia con __: l'aggiunta restituisce -5 e of_get_last_error dice perché. of_insert_node mette un nodo tra i suoi fratelli (posizione contata a partire da 1), of_move_node lo sposta con il suo sottoalbero sotto un altro padre ("" = in cima): il suo indirizzo cambia, e gli handle presi al vecchio indirizzo sono liberati subito (un handle preso poi al nuovo resta valido). Per percorrere l'albero: of_count() e of_keys_at(n) per il primo livello, of_count(indirizzo) e of_keys_at(indirizzo, n) per i figli di un nodo — che restituisce l'indirizzo completo, riutilizzabile così com'è.

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

Aprire, selezionare, spuntare #

Un nodo si apre dal suo chevron, un doppio clic, la tastiera o il vostro codice (ib_expanded del suo handle, of_expand_all, of_collapse_all, of_expand_to_level, of_scroll_to_node, ciò che apre of_select_node; of_clear_children chiude): ognuno solleva ue_node_toggled, poi ue_layout_changed. La selezione segue is_selection_mode: un nodo (SELECT_SINGLE, il predefinito), più nodi con Ctrl e Maiusc come in Esplora risorse (SELECT_MULTIPLE), o nessuno (SELECT_NONE: la tastiera sposta solo un focus). of_select_node seleziona un nodo da solo, apre ciò che lo contiene e lo porta a schermo — un albero apre per selezionare, come il TreeView di Windows, ma giudica prima: un nodo nascosto o contenuto in un nascosto, oltre il limite demo o escluso dalla ricerca è rifiutato (-5, of_get_last_error dice perché) e nulla si apre. ue_selection_changed riceve gli indirizzi selezionati in un array JSON — che l'abbia cambiata un clic, la tastiera o il vostro codice, o che un nodo selezionato abbia lasciato lo schermo (ramo chiuso, nodo rimosso o nascosto, nodo celato dalla ricerca). Chiudere un ramo vi riporta il focus. Con ib_checkboxes, ogni nodo ha una casella; con ib_check_cascade (il predefinito), una spunta dell'utente su un padre spunta il suo sottoalbero tranne un nodo disattivato e il suo sottoalbero, che restano come sono (il padre è allora misto); una spunta del vostro codice spunta tutto. Durante una ricerca, la cascata prende tutto il sottoalbero, nodi celati compresi. Sotto la cascata, un padre è lo stato dei figli che l'albero può disegnare (né nascosti né, in modalità demo, oltre il limite): spuntato quando lo sono tutti, misto quando lo è una parte. Una spunta messa dall'utente solleva ue_node_checked; una spunta messa dal vostro codice (ib_checked, of_check_all) è un valore, muto come SetItem. I figli ricevuti sotto una foglia spuntata prendono la sua spunta — tutti, tutta la risposta a ue_children_needed — finché una spunta (gesto o codice) o un nodo spostato dentro non vi mette fine. Una spunta dell'utente non tocca mai un nodo oltre il limite demo, né, con ib_write_back, un nodo nascosto. of_select_nodes(as_keys_json) seleziona più nodi in una volta in SELECT_MULTIPLE — il corrispettivo di of_selected_keys — con una sola domanda ai veti e un solo ue_selection_changed; il focus va all'ultimo indirizzo nominato.

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

Chiedere prima: selezione e apertura #

Una schermata master-detail non deve lasciare una scheda non salvata. Con ib_veto_selection, ue_selection_changing riceve la selezione attuale e quella richiesta (array JSON di indirizzi) prima di ogni scelta: un clic, Ctrl o Maiusc + clic, la tastiera, F3, of_select_node, of_clear_selection, of_search_next o of_search_prev. Restituite FALSE per rifiutare: nulla si muove, nemmeno il focus della tastiera, e il metodo restituisce -4; ue_node_clicked è sollevato comunque, il clic è avvenuto. Ciò che esce dalla selezione per conseguenza — un ramo chiuso, un nodo rimosso, nascosto o celato dalla ricerca — non è chiesto. Allo stesso modo, ib_veto_toggle pone ue_node_toggling prima di ogni apertura o chiusura, da un gesto o dal codice: un ib_expanded rifiutato non invia nulla (of_get_last_error lo dice), of_expand_all, of_collapse_all e of_expand_to_level applicano gli altri nodi e restituiscono -4, of_select_node e of_scroll_to_node restituiscono -4 senza aprire nulla. of_select_node chiede prima le aperture (ue_node_toggling), poi la selezione: un'applicazione non agisce mai su una selezione accettata per un'apertura poi rifiutata. Ciò che esce dalla selezione per conseguenza non si rifiuta: perché un ramo chiuso non lasci una scheda non salvata, abbinate ib_veto_selection a ib_veto_toggle e rifiutate la chiusura del ramo che la contiene. ib_single_expand lascia un solo ramo aperto sotto ogni padre: aprire un nodo chiude i suoi fratelli aperti, senza chiedere; impostarlo non chiude nulla sul momento.

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

Rami caricati su richiesta #

Un albero grande — un disco, un catalogo, una tabella di migliaia di righe — non deve essere letto tutto in una volta. ib_has_children = true su un nodo è una promessa: il suo chevron si mostra anche se non contiene nulla. Quando si apre — un clic, la tastiera, il vostro codice, o of_select_node che apre ciò che contiene un nodo —, viene sollevato ue_children_needed: i vostri of_add_node fatti durante l'evento ci sono quando il ramo si apre, dopo il ritorno della riga che l'ha aperto (ib_expanded = true non li aspetta). La promessa vale fino a questa risposta, anche se nel frattempo vi è stato aggiunto o rilasciato un nodo; se non aggiungete nulla, è ritirata (lo chevron sparisce). Rimettere ib_has_children = true la fa richiedere alla prossima apertura. Un'apertura fatta durante l'evento solleva un solo ue_node_toggled. of_expand_all apre solo i rami che hanno già dei figli: un ramo la cui promessa non ha avuto risposta resta chiuso, nessuna domanda è posta in massa. Per una tabella, inutile chiamare of_add_node riga per riga: of_from_datastore(ads, as_parent_keys) fa delle righe di un DataStore i figli del nodo, in un solo messaggio — lo schema ItemPopulate → Retrieve del TreeView di PowerBuilder. ROLE_PARENT vi nomina una riga dello stesso lotto (vuoto o sconosciuto: direttamente sotto il nodo); lo stesso DataStore ridato sotto lo stesso nodo sostituisce il suo lotto, un altro DataStore aggiunge il proprio. of_row di un nodo di un lotto restituisce la sua riga nel suo DataStore, e ib_write_back scrive lì. of_clear_children rimuove i figli di un nodo e lo fa promettere di nuovo: la sua prossima apertura richiede di nuovo (l'«aggiorna» di una cartella). Date a ogni lotto il suo DataStore (creato all'apertura del suo ramo, mantenuto finché i suoi nodi sono mostrati): un DataStore ricaricato per un altro nodo — Reset, Retrieve, poi of_from_datastore sotto un altro nodo — porta le sue righe al nuovo lotto, e PowerBuilder ridà gli stessi RowID dopo un Reset. I nodi del lotto precedente mantengono allora ciò che mostrano ma non hanno più una riga: of_row restituisce 0, uno spostamento dal codice restituisce -5 ("loaded again"), un testo rinominato o una spunta è rifiutato e ue_write_back_failed dice perché, e il caricamento che l'ha causato li conta (stale=N) in of_get_last_error. Lo stesso DataStore ridato sotto lo stesso nodo sostituisce il suo lotto; per aggiornare un lotto da un altro oggetto DataStore, chiamate prima of_clear_children, altrimenti si aggiunge accanto al primo. Una colonna chiamata has_children (ROLE_HAS_CHILDREN) fa promettere a una riga i propri figli, senza ciclo. as_parent_keys vuoto è rifiutato (-5): la cima dell'albero è 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

Rinominare e spostare #

Con ib_editable, l'utente rinomina un nodo: F2, o un clic sul nodo già selezionato (dopo un breve ritardo, come in Esplora risorse). Invio (o lasciare il campo) tiene il testo, Esc lo ripristina, un testo svuotato è rifiutato (la modifica si annulla); ue_node_edited riceve il testo digitato e quello vecchio — un testo digitato è testo, mai markup. Un comando del vostro codice durante la modifica conserva il campo e ciò che vi è digitato; se la riga modificata lascia lo schermo senza un gesto dell'utente (codice, scorrimento), la modifica è annullata. Con ib_drag_drop, trascina un nodo: sul quarto alto di una riga va prima di essa, sul quarto basso dopo — come primo figlio se è un ramo aperto —, al centro dentro; un ramo chiuso sotto il puntatore si apre dopo un istante, l'albero scorre vicino ai suoi bordi, Esc annulla, un nodo non va mai nel proprio sottoalbero né dove la sua chiave è presa, e nulla si rilascia sulla riga di un nodo disattivato. Un trascinamento il cui pulsante rilasciato l'albero non vede — la finestra perde il focus (Alt+Tab, una finestra di messaggio) — è annullato: nulla si sposta. Sotto un ordinamento, o con ib_parents_first, un rilascio va solo dentro. ue_node_moved riceve il nuovo indirizzo, il vecchio e il posto sotto il nuovo padre; un nodo rilasciato dove già si trova non chiede, non scrive e non solleva nulla. Con ib_veto_changes, ue_node_editing e ue_node_moving sono posti prima — ue_node_moving con il posto finale, quello che dirà ue_node_moved: restituite FALSE per rifiutare — nulla cambia, e of_move_node restituisce -4. Si trascina un nodo alla volta, anche in selezione multipla.

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

Anche il vostro codice apre un nome in modifica: of_edit_node(as_keys) — l'EditLabel di un TreeView PowerBuilder, per una «Nuova cartella» che si apre pronta a essere nominata. Il nodo viene prima selezionato (ciò che lo contiene si apre), poi il campo si apre; la fine spetta all'utente, come sopra. Un blocco ferma l'utente, mai il vostro codice: funziona con ib_editable = false, su un nodo di sola lettura o disattivato. of_cancel_edit() chiude il campo e ripristina il testo, come Esc.

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

Blocchi, Canc e copia #

Tre blocchi per nodo fermano l'utente, mai il vostro codice: ib_read_only (né rinominato né trascinato, resta una destinazione), ib_drop_target = false (nulla viene rilasciato dentro di esso, né un nodo né un file — prima o dopo di esso resta permesso) e ib_show_checkbox = false (nessuna casella: il nodo non conta per il padre, non è in of_checked_keys, e la cascata lo attraversa verso i figli). Canc solleva ue_delete_requested con i nodi selezionati (in SELECT_NONE, quello del focus; senza selezione altrimenti non si solleva nulla), tranne quelli disattivati e in sola lettura: l'albero non rimuove nulla, la vostra applicazione chiama of_remove_node per ciò che elimina. Ctrl+C (o Ctrl+Ins) solleva ue_copy con i nodi selezionati (in SELECT_NONE, quello del focus) in testo separato da tabulazioni, un numero grezzo (un punto, né raggruppamento né simbolo): il testo dopo tante tabulazioni quanta la sua profondità, poi le colonne di una lista ad albero allineate, prima una riga d'intestazione; l'albero prova anche gli appunti del browser, che possono essere rifiutati alla pagina — ClipBoard(as_tsv) per essere sicuri.

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

File rilasciati da Esplora risorse #

Con ib_allow_drop, l'albero accetta file trascinati da Esplora risorse di Windows su un nodo: il nodo sotto il cursore si illumina durante il trascinamento, ue_drop_files riceve il suo indirizzo e i percorsi completi. as_keys è vuoto per un rilascio accanto ai nodi, su un nodo disattivato o su un nodo il cui ib_drop_target vale false. ue_drag_enter e ue_drag_leave dicono che un trascinamento di file è entrato, poi è uscito senza rilasciare nulla.

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

Colonne, ordinamento e disposizione #

of_add_column fa dell'albero una lista ad albero: la prima colonna porta l'albero (il suo titolo è is_tree_title), ogni colonna aggiunta mostra il campo della stessa chiave di ogni nodo — posto con of_set_field, o una colonna del DataStore. L'handle di una colonna (of_column) regola il suo titolo, la sua larghezza (0 = automatica), il suo allineamento, il suo formato (una maschera numerica come "#,##0.00" con i separatori della lingua di visualizzazione, o token di data per un valore "yyyy-mm-dd", quelli del datagrid), la sua visibilità e il suo posto. Un clic su un'intestazione ordina i fratelli di ogni livello — crescente, decrescente, poi l'ordine di aggiunta — e solleva ue_sort_changed; of_sort fa lo stesso dal codice. L'ordinamento cambia solo l'ordine mostrato: of_keys_at e le posizioni mantengono l'ordine di aggiunta. L'utente allarga una colonna dal bordo della sua intestazione e la sposta trascinando l'intestazione. Ciò che ha sistemato — larghezze, ordine, visibilità, ordinamento, nodi aperti — si legge con of_get_layout e si restituisce con of_set_layout; ue_layout_changed porta la disposizione intera dopo ogni gesto che la cambia, e quando il vostro codice scrive la larghezza, il posto o la visibilità di una colonna (ii_width, ii_index, ib_visible) e la disposizione cambia. Valori uguali mantengono l'ordine del modello, e l'ordinamento è rifatto quando la lingua di visualizzazione cambia. Rimuovere la colonna ordinata (of_remove_column, of_clear_columns) solleva ue_sort_changed con la chiave successiva dell'ordinamento — SORT_NONE quando era la sola —, poi ue_layout_changed. I cinque colori dell'handle di una colonna (il_accent, il_back_color, il_text_color, il_back_color_hover, il_text_color_hover) colorano la sua intestazione. Appena ci sono colonne, la colonna dell'albero resta bloccata nello scorrimento orizzontale. L'ordinamento può riguardare più chiavi: of_sort(as_sort) legge la sintassi del SetSort di un DataWindow («type A, text D», «text» essendo il testo dei nodi), of_sort(as_column, as_dir) accetta anche un campo che nessuna colonna mostra, e ue_sort_changed riceve l'ordinamento intero come terzo argomento. ib_parents_first mette a ogni livello i nodi che hanno (o promettono) figli prima delle foglie — le cartelle prima dei file — qualunque sia l'ordinamento. Una colonna non può prendere la chiave text, che indica il testo dei nodi (-5): of_sort("text", as_dir) ordina per esso, e of_sort accetta più spazi tra una colonna e la sua direzione, come 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")

Esportare l'albero con la sua gerarchia: of_export_csv(as_path) scrive un CSV (UTF-8, punto e virgola) in cui il testo di un nodo sta nella cella del suo livello — una cella più a destra per livello —, le colonne di una lista ad albero dopo il livello più profondo, prima una riga d'intestazione; of_export_xlsx(as_path) scrive una cartella di lavoro Excel in cui il testo è rientrato del suo livello e ogni ramo raggruppato sotto il suo genitore, ripiegabile in Excel, i numeri restando numeri. is_export_scope dice quali nodi: EXPORT_ALL (il predefinito) tutti i nodi, rami chiusi compresi, EXPORT_SHOWN le righe sullo schermo. L'albero costruisce il file, la DLL lo scrive, ue_csv_saved / ue_xlsx_saved confermano; rifiutato in modalità demo.

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

Totali per ramo #

Una colonna di una lista ad albero può mostrare, su ogni ramo, il totale di ciò che contiene: is_summary sul suo handle vale SUMMARY_SUM, SUMMARY_AVG, SUMMARY_MIN, SUMMARY_MAX o SUMMARY_COUNT (i valori non vuoti). Il calcolo scende fino alle foglie — una media è quella delle foglie, mai una media di medie — e il totale si scrive in grassetto, con is_format — un conteggio sempre come numero semplice. Un ramo che ha un valore proprio lo tiene e lo fa risalire, tranne con ib_summary_over_value sulla colonna. Contano solo i nodi che l'albero può disegnare (mai uno nascosto); con ib_summary_filtered, sul componente, solo ciò che la ricerca mostra. of_get_field restituisce il totale grezzo (un numero con il punto), un ordinamento su questa colonna usa i totali, e i totali seguono ogni aggiunta, rimozione o trascinamento. SUMMARY_MIN e SUMMARY_MAX confrontano anche date (yyyy-mm-dd, yyyy-mm-dd hh:mm:ss, hh:mm:ss), e una somma di interi resta esatta oltre 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")

Cercare #

is_filter mostra solo i nodi il cui testo contiene la ricerca (maiuscole ignorate), con i nodi che li contengono, aperti, e il testo trovato evidenziato. "" mostra tutto. Ciò che contiene una corrispondenza si mostra aperto senza cambiare ib_expanded, e gli chevron sono inerti durante la ricerca. Con ib_toolbar, una barra sopra l'albero porta un campo di ricerca (che scrive is_filter: una lettura lo restituisce subito), e i pulsanti Espandi tutto e Comprimi tutto. Esc nel campo svuota la ricerca, Freccia giù passa all'albero, Invio e F3 vanno alla corrispondenza successiva (Maiusc: alla precedente) e il campo tiene la tastiera. Un nodo selezionato che la ricerca nasconde esce dalla selezione, e ue_selection_changed lo dice; il nodo che lo contiene non è selezionato al suo posto. of_select_node e of_scroll_to_node rifiutano un nodo che la ricerca esclude (-5). Per andare da una corrispondenza all'altra, of_search_next e of_search_prev selezionano la successiva o la precedente dopo il nodo del focus, in cerchio (F3 e Maiusc+F3 da tastiera), e of_match_count dice quante la ricerca ne ha trovate. of_find_node(as_field, as_value, as_after_keys) trova senza filtrare: l'indirizzo del primo nodo il cui campo ("" = il suo testo) vale esattamente il valore, nell'ordine che l'albero mostra, rami chiusi compresi; ridate l'indirizzo trovato per il successivo. In SELECT_NONE, of_search_next e of_search_prev vi spostano il focus, come F3. of_find_node parte dopo il posto di as_after_keys nell'ordine mostrato — anche un nodo nascosto; uno sconosciuto restituisce "" e of_get_last_error lo dice. of_find_nodes(as_field, as_value) restituisce tutte le corrispondenze in una volta, come array JSON nell'ordine mostrato.

La ricerca ignora gli accenti per impostazione predefinita, come l'ordinamento: «montreal» trova «Montréal», e la I con il punto del turco conta come una I («izmir» trova «İzmir»); ib_filter_accents = true li fa contare. In selezione multipla, Ctrl+A seleziona tutti i nodi mostrati (una sola domanda con 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"))

Da un DataStore #

of_from_datastore fa un nodo di ogni riga di una tabella gerarchica: la colonna ROLE_KEY dà la sua chiave (senza di essa, il RowID della riga), la colonna ROLE_PARENT nomina la chiave del nodo che lo contiene (vuota, sconosciuta, o un ciclo: in cima) — con una colonna ROLE_KEY, un valore di padre nomina una chiave, mai un RowID. Gli altri ruoli: il testo (ROLE_TEXT, mostrato come testo, mai come markup), l'immagine, la spunta, il badge e l'apertura al caricamento. Una colonna gioca un ruolo quando si chiama come lui (key, parent, text…) o quando of_map lo dice. Ogni colonna è un campo (of_get_field) — le colonne della lista non sono create per voi: of_add_column con il nome della colonna. Date e numeri sono letti qualunque siano le impostazioni regionali, in una sola forma: una data yyyy-mm-dd, una data-ora yyyy-mm-dd hh:mm:ss, un numero con il punto e senza zeri inutili (1234,50 diventa 1234.5) — una colonna decimale si formatta e si ordina come un numero. Due righe con la stessa chiave: la seconda prende "chiave~RowID". Ciò che il caricamento ha dovuto correggere (righe il cui padre manca, cicli spezzati, chiavi doppie, chiavi impossibili) è detto da of_get_last_error, il ritorno resta 0. of_reload_row rilegge una riga cambiata dal vostro codice e aggiorna il suo nodo sul posto; una riga la cui chiave o il cui padre è cambiato sposta il suo nodo. Il nodo di una riga rimosso da of_remove_node resta fuori fino al prossimo of_from_datastore; of_reload_row della sua riga lo riporta. Con ib_write_back, un testo rinominato è scritto nella colonna ROLE_TEXT e un nodo che cambia padre lo scrive nella colonna ROLE_PARENT (NULL in cima, qualunque sia il suo tipo; uno spostamento tra gli stessi fratelli non scrive nulla), prima dell'evento; un nodo di riga non va allora né sotto un nodo aggiunto a mano, né sotto una riga senza valore di chiave — la sua colonna padre non saprebbe dirlo. Un valore che il DataStore rifiuta, o un DataStore distrutto dopo il caricamento (no DataStore is bound), rimette a posto il nodo e solleva ue_write_back_failed. Senza ib_write_back, un trascinamento sposta solo il nodo: la sua riga mantiene ciò che dice il DataStore, e la rilettura successiva delle righe (of_map, is_group_by, of_reload_row, un nuovo caricamento) rimette il nodo dove dice la sua riga — il suo vecchio handle è liberato. L'Update resta vostro. L'handle di un nodo legge il numero della sua riga (of_row). of_from_datastore legge anche le righe di un DataWindow o di un DataWindowChild — quello che l'utente vede accanto: l'albero scrive allora in quello. Con ib_write_back, una spunta dell'utente si scrive anche nella colonna ROLE_CHECKED di ogni riga che ha cambiato — cascata compresa, e i rami sopra il cui stato passa a spuntato o non spuntato (un ramo che diventa misto mantiene il suo valore) —, scritta come la colonna la scrive già (1/0, Y/N, T/F, O/N, -1/0…; una colonna che mostra solo il suo no scrive il sì abituale: Y per N, 1 per 0 — O e -1 solo se la colonna ne contiene già uno); una colonna i cui valori non sono né un sì né un no è rifiutata, con il suo motivo. Ogni valore è giudicato prima e la scrittura è tutto o niente: un rifiuto rende le spunte del gesto e solleva ue_write_back_failed. of_row_keys restituisce l'indirizzo del nodo di una riga del DataStore principale: rimuovete il nodo prima di un DeleteRow. Ogni scrittura di ritorno è tutto o niente — ogni valore giudicato prima che uno sia scritto; una data-ora mantiene la sua ora, una colonna time si scrive, si legge e si raggruppa in hh:mm:ss. Uno spostamento scritto da of_move_node è giudicato di nuovo dopo ue_node_moving, e ciò che era scritto è rimesso se il nodo non si muove. Con ib_write_back, un nodo di riga il cui DataStore non ha una colonna ROLE_TEXT non si rinomina. Un nuovo caricamento libera solo gli handle di ciò che sostituisce: l'handle di un nodo aggiunto a mano, un handle inerte o preso a un indirizzo non ancora creato restano validi; of_from_datastore da una DataWindow verifica che i suoi dati si possano condividere (-5 con il motivo). Ciò che una rilettura delle righe ha dovuto correggere si conta in of_get_last_error — compresi i nodi aggiunti a mano risaliti in cima perché il loro gruppo non c'è più (lifted=N) e i lotti partiti con il loro nodo (lots=N); of_map e is_group_by lo dicono per tutte le fonti.

// 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 ruolo si risolve per DataStore: la colonna che of_map(ads, as_role, as_column) ha dato a questo DataStore, altrimenti quella di of_map(as_role, as_column) quando questo DataStore la ha, altrimenti la colonna che porta il nome del ruolo. Un lotto di dipendenti sotto un albero di reparti non ha quindi bisogno di nessuna colonna dei reparti. Una tabella le cui radici portano 0 nella colonna padre (una colonna NOT NULL) lo dice con is_root_parent_value = "0" ("0|-1" per due valori): quelle righe stanno in cima senza contare come orfane, e un nodo spostato in cima con ib_write_back scrive 0 invece di NULL. Le colonne ROLE_STATE_IMAGE e ROLE_OVERLAY_IMAGE danno l'immagine di stato e l'immagine sovrapposta di un nodo, lette come 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 albero raggruppato per colonne #

Lo stile TreeView di un DataWindow, senza DataWindow: is_group_by = "region|country|city" fa delle righe di of_from_datastore le foglie di gruppi costruiti sui valori di quelle colonne, un livello per colonna (ROLE_PARENT non ha alcun ruolo, ROLE_KEY nomina le foglie). La chiave di un gruppo è il suo valore (/, | e % scritti %2F, %7C, %25), il suo testo il valore scritto con il formato della colonna della stessa chiave, «(vuoto)» per un valore vuoto; l'handle di un nodo di gruppo legge of_group_column() e of_group_value(). Posto dopo un caricamento, raggruppa di nuovo; of_reload_row mette una riga il cui valore è cambiato nel suo nuovo gruppo. of_set_level_image dà un'immagine a tutti i nodi di un livello, of_expand_to_level apre l'albero fino a un livello, e is_summary dà i totali di ogni gruppo. Con ib_write_back, una foglia rilasciata sotto un gruppo dell'ultimo livello scrive tutte le sue colonne di gruppo prima dell'evento; altrove, e per un nodo di gruppo, lo spostamento è rifiutato. Il testo di un gruppo segue un formato impostato dopo il caricamento, l'arrivo della sua colonna e la lingua di visualizzazione; un valore che comincia con __ si scrive %5F_ nella chiave; of_group_value di una data-ora vale yyyy-mm-dd hh:mm:ss, di un'ora hh:mm:ss. Senza ib_write_back, una foglia trascinata sotto un altro gruppo torna nel suo al raggruppamento successivo, poiché la sua riga non è cambiata; un nodo aggiunto a mano sotto un gruppo che scompare risale in cima.

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

Proprietà #

Proprietà di un nodo — n_pbt_treeview_node #

Il suo handle, tramite of_node(indirizzo). Una lettura chiede all'albero cosa sia il nodo ora. Il suo of_count() conta i suoi figli, il suo of_keys_at(n) restituisce l'indirizzo del suo n-esimo figlio (a partire da 1), il suo of_has(chiave) dice se ha quel figlio, il suo of_key() restituisce la sua chiave.

Proprietà di una colonna — n_pbt_treeview_column #

Il suo handle, tramite of_column(chiave). Un valore scritto dal vostro codice è muto, come SetItem — tranne la sua disposizione: ii_width, ii_index e ib_visible scritti dal vostro codice sollevano ue_layout_changed quando la disposizione cambia, come un gesto. Una lettura restituisce ciò che l'utente può aver cambiato (larghezza, posto).

Costanti #

Vivono su u_pbt_treeview: u_pbt_treeview.CHECK_MIXED.

Metodi #

Eventi #

Tastiera e mouse #

• Clic su un nodo: è selezionato (ue_node_clicked); sul suo chevron: si apre o si chiude; sulla sua casella: è spuntato; doppio clic: ue_node_opened, e un ramo si apre o si chiude; clic destro: ue_node_rclicked. In SELECT_MULTIPLE, Ctrl + clic aggiunge o toglie un nodo, Maiusc + clic prende l'intervallo dall'ultimo.
• Su / Giù: il nodo precedente, il successivo; Inizio / Fine: il primo, l'ultimo; Pag su / Pag giù: di uno schermo. I nodi disattivati sono saltati.
• Destra apre il nodo, poi scende al suo primo figlio; Sinistra lo chiude, poi risale al suo padre — invertite in un'applicazione da destra a sinistra. * del tastierino numerico apre tutto il sottoalbero; + / - del tastierino numerico aprono e chiudono — quelli della tastiera principale si digitano, per raggiungere «+1.2» o «-Debiti».
• Spazio spunta il nodo (con ib_checkboxes), altrimenti lo seleziona; Invio: ue_node_opened; F2: rinominare (con ib_editable); tasto Menu o Maiusc + F10: ue_node_rclicked.
• In SELECT_MULTIPLE, Maiusc + frecce estendono la selezione, Ctrl + frecce spostano solo il focus, Ctrl + Spazio aggiunge o toglie il nodo del focus, Ctrl + A seleziona tutti i nodi mostrati (una sola domanda con ib_veto_selection).
• Le prime lettere di un testo selezionano il nodo mostrato che comincia con esse, come una freccia (in SELECT_NONE, vi portano solo il focus).
• Canc: ue_delete_requested (l'albero non rimuove nulla); Ctrl+C o Ctrl+Ins: ue_copy; F3 / Maiusc+F3: la corrispondenza successiva / precedente della ricerca (in SELECT_NONE, il focus vi va), dall'albero o dal campo di ricerca, dove Invio fa lo stesso. Canc e Ctrl+C agiscono sul nodo del focus solo in SELECT_NONE.
• L'intestazione di una lista ad albero è una fermata del tasto Tab: Sinistra / Destra vanno da un'intestazione all'altra (invertite in un'applicazione da destra a sinistra), Inizio / Fine alla prima e all'ultima, Invio o Spazio ordina, Ctrl + Sinistra / Destra restringe o allarga la colonna di 10 pixel, Ctrl + Maiusc + Sinistra / Destra la sposta, Giù passa alle righe.
• Trascinare un nodo (con ib_drag_drop): un fantasma segue il puntatore, una barra mostra dove cadrà prima o dopo, una cornice quando cade dentro; Esc annulla. Trascinare il bordo di un'intestazione allarga la colonna, trascinare l'intestazione la sposta — un fantasma e una barra d'inserimento mostrano dove, Esc annulla —, cliccare l'intestazione ordina. Un trascinamento il cui pulsante rilasciato l'albero non vede — la finestra perde il focus (Alt+Tab, una finestra di messaggio) — è annullato: nulla si sposta, una larghezza ritorna.
• L'albero è una fermata del tasto Tab (più l'intestazione di una lista ad albero, il campo e i pulsanti della barra degli strumenti); un anello tratteggiato del colore del testo segna il nodo che ha il focus. Un albero disattivato non prende il focus.

Esempi #

Diritti da spuntare #

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

Ritrovare la disposizione al prossimo avvio #

// 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 su un nodo #

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

Buone pratiche #

• Chiavi stabili: un identificativo, non un'etichetta — il testo si rinomina, la chiave resta. of_keys_at restituisce indirizzi completi, da passare così come sono a of_node. Una disposizione conservata da un avvio all'altro (of_get_layout) richiede una colonna ROLE_KEY: senza di essa, le chiavi delle righe sono i loro RowID, che un nuovo Retrieve dà ad altre righe.
• Rami su richiesta appena l'albero è grande o costoso da leggere: ib_has_children e ue_children_needed leggono solo ciò che l'utente apre.
• Un DataStore per lotto: ricaricato per un altro nodo, un DataStore porta via le sue righe — e PowerBuilder i suoi RowID — dal lotto precedente, i cui nodi non hanno allora più una riga.
• Molti nodi: solo le righe visibili sono disegnate — diecimila nodi scorrono come venti. Aggiungerli è un'altra cosa: ogni of_add_node è un messaggio all'albero, circa 0,7 ms (2.000 nodi ≈ 1,3 s misurati, 10.000 ≈ 7 s attesi); un albero grande si carica con of_from_datastore, in un solo messaggio, o si legge su richiesta, un lotto per ramo (of_from_datastore(ads, as_parent_keys)).
• Le colonne di un DataStore sono identificativi quanto valori: scegliete quelle che mostrate con of_add_column, nulla è creato per voi.
• Una spunta è un valore: posta dal vostro codice, non solleva nulla; leggete of_checked_keys quando l'utente conferma.
• of_get_last_error dice perché l'ultima chiamata è stata rifiutata; è svuotato da ogni metodo che agisce e da ogni proprietà scritta, e da of_find_node / of_find_nodes, che dicono tramite lui perché non hanno trovato nulla.
• Un ordine dato durante un'attesa (codice PowerBuilder che gira mentre l'albero attende la sua pagina, un timer per esempio) non è verificato in anticipo: la pagina decide da sola, e un'aggiunta o uno spostamento che rifiuta restituisce comunque 0.
• Durante un'attesa (un evento del componente in corso di risposta), un ordine del vostro codice non è giudicato in anticipo: ib_expanded e of_move_node passano il veto senza porre la domanda, e of_get_last_error lo dice. Date i vostri ordini fuori dall'evento quando il veto conta.
• of_set_layout rimette uno stato — tipicamente all'avvio — senza porre le domande di ib_veto_selection né di ib_veto_toggle: è l'eccezione alla regola secondo cui un ordine del codice pone la domanda.
• Modalità demo: senza chiave, l'albero disegna i primi 8 nodi di ogni livello e 200 nodi in tutto l'albero (i primi aggiunti), nell'ordine del modello — prima dell'ordinamento, della ricerca e dell'occultamento: un nodo nascosto conta, una ricerca o un ordinamento non mostrano mai il nono, lotti e gruppi compresi, e un totale non conta mai ciò che il limite nasconde; gli altri restano in memoria, né mostrati né selezionabili (vedere la modalità demo).

Ereditato dalla base comune #

Questi membri esistono su tutti i componenti visivi — non sono propri di questo. Sono descritti una sola volta, nei capitoli trasversali; questa tabella dice solo dove leggerli.

Due aiuti non sono ereditati: of_icon e of_escape_markup vivono su n_pbt_utils. Ne dichiari uno — n_pbt_utils lnv_utils, niente da creare — e li chiami su di esso.

← Riferimento dei componenti · Sommario della guida