treeview — u_pbt_treeview #

← Referencia de componentes · Índice de la guía

treeview muestra datos en árbol: nodos que contienen otros, abiertos y cerrados por su chevron, con una imagen, una insignia, una casilla de tres estados y una selección simple o múltiple. En cuanto se le añade una columna, se convierte en una lista en árbol (TreeList): la primera columna lleva el árbol, las demás muestran los campos de cada nodo, ordenables con un clic en su encabezado. Una rama puede prometer hijos que solo lee al abrirse; el usuario renombra un nodo (F2) y lo arrastra a otro sitio, y su aplicación puede rechazarlo antes; una búsqueda solo deja lo que coincide. El árbol se llena a mano o desde un DataStore jerárquico (una fila nombra a su padre), y puede reescribir en él lo que el usuario cambia.

▶ Verlo en vivo — Aplicación de demostración, mosaico Tree view: la vista previa, el código que lo genera y esta página, uno al lado del otro.

De un vistazo #

Inicio rápido #

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

Una dirección por nodo #

Un nodo se designa por su dirección: las claves de sus niveles unidas por /. "europe" está arriba, "europe/france" dentro de "europe" — el padre se añade primero. Una clave es única bajo su padre: "europe/paris" y "usa/paris" son dos nodos. Una dirección ya ocupada, un padre desconocido, un nivel vacío, una clave que contiene | o empieza por __: la adición devuelve -5 y of_get_last_error dice por qué. of_insert_node coloca un nodo entre sus hermanos (posición contada desde 1), of_move_node lo mueve con su subárbol bajo otro padre ("" = arriba): su dirección cambia, y los handles tomados en la antigua dirección se liberan en el acto (un handle tomado después en la nueva sigue siendo válido). Para recorrer el árbol: of_count() y of_keys_at(n) para el primer nivel, of_count(dirección) y of_keys_at(dirección, n) para los hijos de un nodo — que devuelve la dirección completa, reutilizable tal cual.

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

Abrir, seleccionar, marcar #

Un nodo se abre con su chevron, un doble clic, el teclado o su código (ib_expanded de su handle, of_expand_all, of_collapse_all, of_expand_to_level, of_scroll_to_node, lo que abre of_select_node; of_clear_children cierra): cada uno lanza ue_node_toggled, luego ue_layout_changed. La selección sigue is_selection_mode: un nodo (SELECT_SINGLE, el predeterminado), varios con Ctrl y Mayús como en el Explorador (SELECT_MULTIPLE), o ninguno (SELECT_NONE: el teclado solo mueve un foco). of_select_node selecciona un nodo solo, abre lo que lo contiene y lo trae a la pantalla — un árbol abre para seleccionar, como el TreeView de Windows, pero juzga primero: un nodo oculto o contenido en uno oculto, más allá del límite demo o descartado por la búsqueda se rechaza (-5, of_get_last_error dice por qué) y nada se abre. ue_selection_changed recibe las direcciones seleccionadas en un array JSON — tanto si la cambió un clic, el teclado o su código, como si un nodo seleccionado salió de la pantalla (rama cerrada, nodo quitado u oculto, nodo escondido por la búsqueda). Cerrar una rama devuelve el foco a ella. Con ib_checkboxes, cada nodo tiene una casilla; con ib_check_cascade (el predeterminado), una marca del usuario en un padre marca su subárbol salvo un nodo desactivado y su subárbol, que se quedan como están (el padre queda entonces mixto); una marca de su código lo marca todo. Durante una búsqueda, la cascada toma todo el subárbol, nodos escondidos incluidos. Bajo la cascada, un padre es el estado de los hijos que el árbol puede dibujar (ni ocultos ni, en modo demo, más allá del límite): marcado cuando todos lo están, mixto cuando una parte lo está. Una marca puesta por el usuario lanza ue_node_checked; una marca puesta por su código (ib_checked, of_check_all) es un valor, mudo como SetItem. Los hijos recibidos bajo una hoja marcada toman su marca — todos, toda la respuesta a ue_children_needed — hasta que una marca (gesto o código) o un nodo movido dentro le pone fin. Una marca del usuario nunca toca un nodo más allá del límite demo, ni, con ib_write_back, un nodo oculto. of_select_nodes(as_keys_json) selecciona varios nodos a la vez en SELECT_MULTIPLE — el par de of_selected_keys — con una sola pregunta a los vetos y un solo ue_selection_changed; el foco va a la última dirección nombrada.

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

Preguntar antes: selección y apertura #

Una pantalla maestro-detalle no debe abandonar una ficha sin guardar. Con ib_veto_selection, ue_selection_changing recibe la selección actual y la pedida (arrays JSON de direcciones) antes de cualquier elección: un clic, Ctrl o Mayús + clic, el teclado, F3, of_select_node, of_clear_selection, of_search_next u of_search_prev. Devuelva FALSE para rechazar: nada se mueve, ni siquiera el foco del teclado, y el método devuelve -4; ue_node_clicked se lanza de todos modos, el clic tuvo lugar. Lo que sale de la selección como consecuencia — una rama cerrada, un nodo quitado, oculto o escondido por la búsqueda — no se pregunta. Del mismo modo, ib_veto_toggle plantea ue_node_toggling antes de cada apertura o cierre, por un gesto o por el código: un ib_expanded rechazado no envía nada (of_get_last_error lo dice), of_expand_all, of_collapse_all y of_expand_to_level aplican los demás nodos y devuelven -4, of_select_node y of_scroll_to_node devuelven -4 sin abrir nada. of_select_node pregunta primero las aperturas (ue_node_toggling), luego la selección: una aplicación nunca actúa sobre una selección aceptada para una apertura rechazada después. Lo que sale de la selección como consecuencia no se rechaza: para que una rama cerrada no abandone una ficha sin guardar, combine ib_veto_selection con ib_veto_toggle y rechace el cierre de la rama que la contiene. ib_single_expand deja una sola rama abierta bajo cada padre: abrir un nodo cierra sus hermanas abiertas, sin preguntar; ponerlo no cierra nada en el 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

Ramas cargadas a petición #

Un árbol grande — un disco, un catálogo, una tabla de miles de filas — no tiene por qué leerse de una vez. ib_has_children = true en un nodo es una promesa: su chevron se muestra aunque no contiene nada. Cuando se abre — un clic, el teclado, su código, o of_select_node abriendo lo que contiene un nodo —, se lanza ue_children_needed: sus of_add_node hechos durante el evento están ahí cuando la rama se abre, después del retorno de la línea que la abrió (ib_expanded = true no los espera). La promesa vale hasta esa respuesta, aunque entretanto se haya añadido o soltado un nodo en ella; no añada nada, y se retira (el chevron desaparece). Volver a poner ib_has_children = true hace que la próxima apertura vuelva a preguntar. Una apertura hecha durante el evento lanza un solo ue_node_toggled. of_expand_all solo abre las ramas que ya tienen hijos: una rama cuya promesa no ha tenido respuesta se queda cerrada, no se hace ninguna pregunta en masa. Para una tabla, no hace falta llamar a of_add_node fila por fila: of_from_datastore(ads, as_parent_keys) hace de las filas de un DataStore los hijos del nodo, en un solo mensaje — el patrón ItemPopulate → Retrieve del TreeView de PowerBuilder. ROLE_PARENT nombra allí una fila del mismo lote (vacío o desconocido: directamente bajo el nodo); el mismo DataStore dado de nuevo bajo el mismo nodo sustituye su lote, otro DataStore añade el suyo. of_row de un nodo de un lote devuelve su fila en su DataStore, e ib_write_back escribe allí. of_clear_children quita los hijos de un nodo y le hace prometer de nuevo: su próxima apertura vuelve a preguntar (el «actualizar» de una carpeta). Dé a cada lote su propio DataStore (creado al abrirse su rama, conservado mientras se muestran sus nodos): un DataStore recargado para otro nodo — Reset, Retrieve, luego of_from_datastore bajo otro nodo — se lleva sus filas al nuevo lote, y PowerBuilder vuelve a dar los mismos RowID tras un Reset. Los nodos del lote anterior conservan entonces lo que muestran pero ya no tienen fila: of_row devuelve 0, un movimiento por código devuelve -5 ("loaded again"), un texto renombrado o una marca se rechaza y ue_write_back_failed dice por qué, y la carga que lo causó los cuenta (stale=N) en of_get_last_error. El mismo DataStore dado de nuevo bajo el mismo nodo sustituye su lote; para refrescar un lote desde otro objeto DataStore, llame primero a of_clear_children, si no se añade junto al primero. Una columna llamada has_children (ROLE_HAS_CHILDREN) hace que una fila prometa sus propios hijos, sin bucle. as_parent_keys vacío se rechaza (-5): la cima del árbol es 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

Renombrar y mover #

Con ib_editable, el usuario renombra un nodo: F2, o un clic en el nodo ya seleccionado (tras un breve retraso, como el Explorador). Intro (o salir del campo) guarda el texto, Esc lo devuelve, un texto vaciado se rechaza (la edición se cancela); ue_node_edited recibe el texto tecleado y el antiguo — un texto tecleado es texto, nunca etiquetas. Una orden de su código durante la edición conserva el campo y lo tecleado en él; si la fila editada sale de la pantalla sin un gesto del usuario (código, desplazamiento), la edición se cancela. Con ib_drag_drop, arrastra un nodo: sobre el cuarto superior de una fila va antes de ella, sobre el cuarto inferior después — como primer hijo si es una rama abierta —, en el centro dentro; una rama cerrada bajo el puntero se abre tras un momento, el árbol se desplaza cerca de sus bordes, Esc cancela, un nodo nunca va a su propio subárbol ni adonde su clave está ocupada, y nada se suelta sobre la fila de un nodo desactivado. Un arrastre cuyo botón soltado el árbol no ve — la ventana pierde el foco (Alt+Tab, un cuadro de mensaje) — se cancela: nada se mueve. Bajo una ordenación, o con ib_parents_first, una soltada solo va dentro. ue_node_moved recibe la nueva dirección, la antigua y el lugar bajo el nuevo padre; un nodo soltado donde ya está no pregunta, no escribe ni lanza nada. Con ib_veto_changes, ue_node_editing y ue_node_moving se plantean antes — ue_node_moving con el lugar final, el que dirá ue_node_moved: devuelva FALSE para rechazar — nada cambia, y of_move_node devuelve -4. Se arrastra un nodo a la vez, incluso en selección múltiple.

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

Su código también abre un nombre en edición: of_edit_node(as_keys) — el EditLabel de un TreeView de PowerBuilder, para una «Nueva carpeta» que se abre lista para nombrarla. Primero se selecciona el nodo (lo que lo contiene se abre), después se abre el campo; el final es del usuario, como arriba. Un bloqueo detiene al usuario, nunca a su código: funciona con ib_editable = false, en un nodo de solo lectura o atenuado. of_cancel_edit() cierra el campo y devuelve el texto, como 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")

Bloqueos, Supr y copia #

Tres bloqueos por nodo detienen al usuario, nunca a su código: ib_read_only (ni renombrado ni arrastrado, sigue siendo un destino), ib_drop_target = false (nada se suelta dentro de él, ni un nodo ni un archivo — antes o después de él sigue permitido) e ib_show_checkbox = false (sin casilla: el nodo no cuenta para su padre, no está en of_checked_keys, y la cascada lo atraviesa hacia sus hijos). Supr lanza ue_delete_requested con los nodos seleccionados (en SELECT_NONE, el del foco; sin selección, si no, no se lanza nada), salvo los desactivados y de solo lectura: el árbol no quita nada, su aplicación llama a of_remove_node para lo que borra. Ctrl+C (o Ctrl+Insert) lanza ue_copy con los nodos seleccionados (en SELECT_NONE, el del foco) en texto tabulado, un número bruto (un punto, sin agrupación ni símbolo): el texto tras tantas tabulaciones como su profundidad, luego las columnas de una lista en árbol alineadas, primero una línea de encabezado; el árbol intenta también el portapapeles del navegador, que se le puede negar a la página — ClipBoard(as_tsv) para estar seguro.

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

Archivos soltados desde el Explorador #

Con ib_allow_drop, el árbol acepta archivos arrastrados desde el Explorador de Windows sobre un nodo: el nodo bajo el cursor se ilumina durante el arrastre, ue_drop_files recibe su dirección y las rutas completas. as_keys está vacío para una soltada junto a los nodos, sobre un nodo desactivado o sobre un nodo cuyo ib_drop_target vale false. ue_drag_enter y ue_drag_leave dicen que un arrastre de archivos entró y luego salió sin soltar nada.

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

Columnas, ordenación y disposición #

of_add_column convierte el árbol en una lista en árbol: la primera columna lleva el árbol (su título es is_tree_title), cada columna añadida muestra el campo de la misma clave de cada nodo — puesto con of_set_field, o una columna del DataStore. El handle de una columna (of_column) ajusta su título, su ancho (0 = automático), su alineación, su formato (una máscara numérica como "#,##0.00" con los separadores del idioma de visualización, o tokens de fecha para un valor "yyyy-mm-dd", los del datagrid), su visibilidad y su lugar. Un clic en un encabezado ordena los hermanos de cada nivel — ascendente, descendente, luego el orden de adición — y lanza ue_sort_changed; of_sort hace lo mismo desde el código. La ordenación solo cambia el orden mostrado: of_keys_at y las posiciones conservan el orden de adición. El usuario ensancha una columna por el borde de su encabezado y la mueve arrastrando el encabezado. Lo que ha dispuesto — anchos, orden, visibilidad, ordenación, nodos abiertos — se lee con of_get_layout y se devuelve con of_set_layout; ue_layout_changed lleva la disposición entera tras cada gesto que la cambia, y cuando su código escribe el ancho, el lugar o la visibilidad de una columna (ii_width, ii_index, ib_visible) y la disposición cambia. Los valores iguales conservan el orden del modelo, y la ordenación se rehace cuando cambia el idioma de visualización. Quitar la columna ordenada (of_remove_column, of_clear_columns) lanza ue_sort_changed con la clave siguiente de la ordenación — SORT_NONE cuando era la única —, luego ue_layout_changed. Los cinco colores del handle de una columna (il_accent, il_back_color, il_text_color, il_back_color_hover, il_text_color_hover) colorean su encabezado. En cuanto hay columnas, la columna del árbol queda fija al desplazarse en horizontal. La ordenación puede tener varias claves: of_sort(as_sort) lee la sintaxis del SetSort de un DataWindow («type A, text D», siendo «text» el texto de los nodos), of_sort(as_column, as_dir) acepta también un campo que ninguna columna muestra, y ue_sort_changed recibe la ordenación entera como tercer argumento. ib_parents_first pone en cada nivel los nodos que tienen (o prometen) hijos antes de las hojas — las carpetas antes de los archivos — sea cual sea la ordenación. Una columna no puede tomar la clave text, que nombra el texto de los nodos (-5): of_sort("text", as_dir) ordena por él, y of_sort acepta varios espacios entre una columna y su sentido, como 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")

Exportar el árbol con su jerarquía: of_export_csv(as_path) escribe un CSV (UTF-8, punto y coma) en el que el texto de un nodo está en la celda de su nivel — una celda más a la derecha por nivel —, las columnas de una lista en árbol después del nivel más profundo, primero una línea de encabezado; of_export_xlsx(as_path) escribe un libro de Excel en el que el texto está sangrado según su nivel y cada rama agrupada bajo su padre, plegable en Excel, y los números siguen siendo números. is_export_scope dice qué nodos: EXPORT_ALL (el predeterminado) todos los nodos, ramas cerradas incluidas, EXPORT_SHOWN las filas en pantalla. El árbol construye el archivo, la DLL lo escribe, ue_csv_saved / ue_xlsx_saved lo confirman; rechazado en modo 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")

Totales por rama #

Una columna de una lista en árbol puede mostrar, en cada rama, el total de lo que contiene: is_summary en su handle vale SUMMARY_SUM, SUMMARY_AVG, SUMMARY_MIN, SUMMARY_MAX o SUMMARY_COUNT (los valores no vacíos). El cálculo baja hasta las hojas — una media es la de las hojas, nunca una media de medias — y el total se escribe en negrita, por is_format — un recuento siempre como número simple. Una rama que tiene su propio valor lo conserva y lo hace subir, salvo con ib_summary_over_value en la columna. Solo cuentan los nodos que el árbol puede dibujar (nunca uno oculto); con ib_summary_filtered, en el componente, solo lo que la búsqueda muestra. of_get_field devuelve el total bruto (un número con punto), una ordenación por esta columna usa los totales, y los totales siguen cada adición, retirada o arrastre. SUMMARY_MIN y SUMMARY_MAX comparan también fechas (yyyy-mm-dd, yyyy-mm-dd hh:mm:ss, hh:mm:ss), y una suma de enteros sigue exacta más allá 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")

Buscar #

is_filter solo muestra los nodos cuyo texto contiene la búsqueda (mayúsculas ignoradas), con los nodos que los contienen, abiertos, y el texto encontrado resaltado. "" muestra todo. Lo que contiene una coincidencia se muestra abierto sin cambiar ib_expanded, y los chevrons quedan inertes mientras dura la búsqueda. Con ib_toolbar, una barra encima del árbol lleva un campo de búsqueda (que escribe is_filter: una lectura lo devuelve al instante), y los botones Expandir todo y Contraer todo. Esc en el campo vacía la búsqueda, Flecha abajo pasa al árbol, Intro y F3 van a la coincidencia siguiente (Mayús: a la anterior) y el campo conserva el teclado. Un nodo seleccionado que la búsqueda esconde sale de la selección, y ue_selection_changed lo dice; el nodo que lo contiene no se selecciona en su lugar. of_select_node y of_scroll_to_node rechazan un nodo que la búsqueda descarta (-5). Para ir de coincidencia en coincidencia, of_search_next y of_search_prev seleccionan la siguiente o la anterior tras el nodo del foco, en bucle (F3 y Mayús+F3 con el teclado), y of_match_count dice cuántas encontró la búsqueda. of_find_node(as_field, as_value, as_after_keys) encuentra sin filtrar: la dirección del primer nodo cuyo campo ("" = su texto) vale exactamente el valor, en el orden que muestra el árbol, ramas cerradas incluidas; vuelva a dar la dirección encontrada para la siguiente. En SELECT_NONE, of_search_next y of_search_prev mueven allí el foco, como F3. of_find_node parte tras el lugar de as_after_keys en el orden mostrado — también un nodo oculto; uno desconocido devuelve "" y of_get_last_error lo dice. of_find_nodes(as_field, as_value) devuelve todas las coincidencias de una vez, como array JSON en el orden mostrado.

La búsqueda ignora los acentos por defecto, como la ordenación: «montreal» encuentra «Montréal», y la I con punto del turco cuenta como una I («izmir» encuentra «İzmir»); ib_filter_accents = true los hace contar. En selección múltiple, Ctrl+A selecciona todos los nodos mostrados (una sola pregunta 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"))

Desde un DataStore #

of_from_datastore hace un nodo de cada fila de una tabla jerárquica: la columna ROLE_KEY da su clave (sin ella, el RowID de la fila), la columna ROLE_PARENT nombra la clave del nodo que lo contiene (vacía, desconocida, o un bucle: arriba) — con una columna ROLE_KEY, un valor de padre nombra una clave, nunca un RowID. Los demás roles: el texto (ROLE_TEXT, mostrado como texto, nunca como etiquetas), la imagen, la marca, la insignia y la apertura al cargar. Una columna desempeña un rol cuando se llama como él (key, parent, text…) o cuando of_map lo dice. Cada columna es un campo (of_get_field) — las columnas de la lista no se crean automáticamente: of_add_column con el nombre de la columna. Fechas y números se leen sea cual sea la configuración regional, en una sola forma: una fecha yyyy-mm-dd, una fecha-hora yyyy-mm-dd hh:mm:ss, un número con punto y sin ceros inútiles (1234,50 pasa a 1234.5) — una columna decimal se formatea y se ordena como un número. Dos filas con la misma clave: la segunda toma "clave~RowID". Lo que la carga tuvo que corregir (filas cuyo padre no está, bucles rotos, claves duplicadas, claves imposibles) lo dice of_get_last_error, y el retorno sigue siendo 0. of_reload_row vuelve a leer una fila cambiada por su código y actualiza su nodo en el sitio; una fila cuya clave o padre cambió mueve su nodo. El nodo de una fila quitado por of_remove_node sigue fuera hasta el próximo of_from_datastore; of_reload_row de su fila lo trae de vuelta. Con ib_write_back, un texto renombrado se escribe en la columna ROLE_TEXT y un nodo que cambia de padre lo escribe en la columna ROLE_PARENT (NULL arriba, sea cual sea su tipo; un movimiento entre los mismos hermanos no escribe nada), antes del evento; un nodo de fila no va entonces ni bajo un nodo añadido a mano ni bajo una fila sin valor de clave — su columna padre no sabría decirlo. Un valor que el DataStore rechaza, o un DataStore destruido desde la carga (no DataStore is bound), devuelve el nodo a su sitio y lanza ue_write_back_failed. Sin ib_write_back, un arrastre solo mueve el nodo: su fila conserva lo que dice el DataStore, y la siguiente relectura de las filas (of_map, is_group_by, of_reload_row, una nueva carga) devuelve el nodo a donde dice su fila — su antiguo handle se libera. El Update sigue siendo suyo. El handle de un nodo lee el número de su fila (of_row). of_from_datastore lee también las filas de un DataWindow o de un DataWindowChild — el que el usuario ve al lado: el árbol escribe entonces en ese. Con ib_write_back, una marca del usuario se escribe también en la columna ROLE_CHECKED de cada fila que cambió — cascada incluida, y las ramas de encima cuyo estado pasa a marcado o desmarcado (una rama que queda mixta conserva su valor) —, escrita como la columna ya la escribe (1/0, Y/N, T/F, O/N, -1/0…; una columna que solo muestra su no escribe el sí habitual: Y para N, 1 para 0 — O y -1 solo si la columna ya contiene uno); una columna cuyos valores no son ni un sí ni un no se rechaza, con su motivo. Cada valor se juzga primero y la escritura es todo o nada: un rechazo devuelve las marcas del gesto y lanza ue_write_back_failed. of_row_keys devuelve la dirección del nodo de una fila del DataStore principal: quite el nodo antes de un DeleteRow. Toda escritura de vuelta es todo o nada — cada valor se juzga antes de escribir uno; una fecha-hora conserva su hora, una columna time se escribe, se lee y se agrupa en hh:mm:ss. Un movimiento escrito por of_move_node se juzga de nuevo tras ue_node_moving, y lo escrito se repone si el nodo no se mueve. Con ib_write_back, un nodo de fila cuyo DataStore no tiene columna ROLE_TEXT no se renombra. Una nueva carga solo libera los handles de lo que sustituye: el handle de un nodo añadido a mano, un handle inerte o uno tomado en una dirección aún no creada siguen válidos; of_from_datastore desde una DataWindow comprueba que sus datos se pueden compartir (-5 con el motivo). Lo que una relectura de las filas tuvo que corregir se cuenta en of_get_last_error — incluidos los nodos añadidos a mano subidos arriba porque su grupo ya no existe (lifted=N) y los lotes que se fueron con su nodo (lots=N); of_map e is_group_by lo dicen para todas las fuentes.

// 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 rol se resuelve por DataStore: la columna que of_map(ads, as_role, as_column) dio a este DataStore, si no la de of_map(as_role, as_column) cuando este DataStore la tiene, si no la columna que lleva el nombre del rol. Un lote de empleados bajo un árbol de departamentos no necesita así ninguna columna de los departamentos. Una tabla cuyas raíces llevan 0 en su columna padre (una columna NOT NULL) lo dice con is_root_parent_value = "0" ("0|-1" para dos valores): esas filas están arriba sin contar como huérfanas, y un nodo movido arriba con ib_write_back escribe 0 en lugar de NULL. Las columnas ROLE_STATE_IMAGE y ROLE_OVERLAY_IMAGE dan la imagen de estado y la imagen superpuesta de un nodo, leídas como 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 árbol agrupado por columnas #

El estilo TreeView de un DataWindow, sin DataWindow: is_group_by = "region|country|city" hace de las filas de of_from_datastore las hojas de grupos construidos sobre los valores de esas columnas, un nivel por columna (ROLE_PARENT no desempeña ningún papel, ROLE_KEY nombra las hojas). La clave de un grupo es su valor (/, | y % escritos %2F, %7C, %25), su texto el valor escrito con el formato de la columna de la misma clave, «(vacío)» para un valor vacío; el handle de un nodo de grupo lee of_group_column() y of_group_value(). Puesto tras una carga, reagrupa; of_reload_row coloca una fila cuyo valor cambió en su nuevo grupo. of_set_level_image da una imagen a todos los nodos de un nivel, of_expand_to_level abre el árbol hasta un nivel, e is_summary da los totales de cada grupo. Con ib_write_back, una hoja soltada bajo un grupo del último nivel escribe todas sus columnas de grupo antes del evento; en otro lugar, y para un nodo de grupo, el movimiento se rechaza. El texto de un grupo sigue un formato puesto tras la carga, la llegada de su columna y el idioma de visualización; un valor que empieza por __ se escribe %5F_ en la clave; of_group_value de una fecha-hora vale yyyy-mm-dd hh:mm:ss, de una hora hh:mm:ss. Sin ib_write_back, una hoja arrastrada bajo otro grupo vuelve al suyo en la siguiente agrupación, ya que su fila no cambió; un nodo añadido a mano bajo un grupo que desaparece sube arriba.

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

Propiedades #

Propiedades de un nodo — n_pbt_treeview_node #

Su handle, mediante of_node(dirección). Una lectura pregunta al árbol qué es el nodo ahora. Su of_count() cuenta sus hijos, su of_keys_at(n) devuelve la dirección de su n-ésimo hijo (desde 1), su of_has(clave) dice si tiene ese hijo, su of_key() devuelve su clave.

Propiedades de una columna — n_pbt_treeview_column #

Su handle, mediante of_column(clave). Un valor escrito por su código es mudo, como SetItem — salvo su disposición: ii_width, ii_index e ib_visible escritos por su código lanzan ue_layout_changed cuando la disposición cambia, como un gesto. Una lectura devuelve lo que el usuario haya podido cambiar (ancho, lugar).

Constantes #

Están en u_pbt_treeview: u_pbt_treeview.CHECK_MIXED.

Métodos #

Eventos #

Teclado y ratón #

• Clic en un nodo: queda seleccionado (ue_node_clicked); en su chevron: se abre o se cierra; en su casilla: queda marcado; doble clic: ue_node_opened, y una rama se abre o se cierra; clic derecho: ue_node_rclicked. En SELECT_MULTIPLE, Ctrl + clic añade o quita un nodo, Mayús + clic toma el rango desde el último.
• Arriba / Abajo: el nodo anterior, el siguiente; Inicio / Fin: el primero, el último; Re Pág / Av Pág: de una pantalla. Los nodos desactivados se saltan.
• Derecha abre el nodo, luego baja a su primer hijo; Izquierda lo cierra, luego sube a su padre — invertidas en una aplicación de derecha a izquierda. * del teclado numérico abre todo el subárbol; + / - del teclado numérico abren y cierran — los del teclado principal se teclean, para llegar a «+1.2» o «-Débitos».
• Espacio marca el nodo (con ib_checkboxes), si no lo selecciona; Intro: ue_node_opened; F2: renombrar (con ib_editable); tecla Menú o Mayús + F10: ue_node_rclicked.
• En SELECT_MULTIPLE, Mayús + flechas amplían la selección, Ctrl + flechas solo mueven el foco, Ctrl + Espacio añade o quita el nodo del foco, Ctrl + A selecciona todos los nodos mostrados (una sola pregunta con ib_veto_selection).
• Las primeras letras de un texto seleccionan el nodo mostrado que empieza por ellas, como una flecha (en SELECT_NONE, solo llevan el foco a él).
• Supr: ue_delete_requested (el árbol no quita nada); Ctrl+C o Ctrl+Insert: ue_copy; F3 / Mayús+F3: la coincidencia siguiente / anterior de la búsqueda (en SELECT_NONE, el foco va allí), desde el árbol o desde el campo de búsqueda, donde Intro hace lo mismo. Supr y Ctrl+C actúan sobre el nodo del foco solo en SELECT_NONE.
• El encabezado de una lista en árbol es una parada de la tecla Tab: Izquierda / Derecha van de encabezado en encabezado (invertidas en una aplicación de derecha a izquierda), Inicio / Fin al primero y al último, Intro o Espacio ordena, Ctrl + Izquierda / Derecha estrecha o ensancha la columna 10 píxeles, Ctrl + Mayús + Izquierda / Derecha la mueve, Abajo pasa a las filas.
• Arrastrar un nodo (con ib_drag_drop): un fantasma sigue al puntero, una barra muestra dónde caerá antes o después, un marco cuando cae dentro; Esc cancela. Arrastrar el borde de un encabezado ensancha la columna, arrastrar el encabezado la mueve — un fantasma y una barra de inserción muestran dónde, Esc cancela —, hacer clic en el encabezado ordena. Un arrastre cuyo botón soltado el árbol no ve — la ventana pierde el foco (Alt+Tab, un cuadro de mensaje) — se cancela: nada se mueve, un ancho vuelve.
• El árbol es una parada de la tecla Tab (más el encabezado de una lista en árbol, el campo y los botones de la barra de herramientas); un anillo punteado del color del texto marca el nodo que tiene el foco. Un árbol desactivado no toma el foco.

Ejemplos #

Permisos que marcar #

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

Recuperar la disposición en el próximo inicio #

// 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 menú sobre 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

Buenas prácticas #

• Claves estables: un identificador, no una etiqueta — el texto se renombra, la clave se queda. of_keys_at devuelve direcciones completas, para pasar tal cual a of_node. Una disposición guardada de un inicio a otro (of_get_layout) exige una columna ROLE_KEY: sin ella, las claves de las filas son sus RowID, que un nuevo Retrieve da a otras filas.
• Ramas a petición en cuanto el árbol es grande o costoso de leer: ib_has_children y ue_children_needed solo leen lo que el usuario abre.
• Un DataStore por lote: recargado para otro nodo, un DataStore se lleva sus filas — y PowerBuilder sus RowID — del lote anterior, cuyos nodos ya no tienen fila.
• Muchos nodos: solo se dibujan las filas visibles — diez mil nodos se desplazan como veinte. Añadirlos es otra cosa: cada of_add_node es un mensaje al árbol, unos 0,7 ms (2.000 nodos ≈ 1,3 s medidos, 10.000 ≈ 7 s esperados); un árbol grande se carga con of_from_datastore, en un solo mensaje, o se lee a petición, un lote por rama (of_from_datastore(ads, as_parent_keys)).
• Las columnas de un DataStore son identificadores tanto como valores: elija las que muestra con of_add_column, nada se crea solo.
• Una marca es un valor: puesta por su código, no lanza nada; lea of_checked_keys cuando el usuario confirme.
• of_get_last_error dice por qué se rechazó la última llamada; lo vacía todo método que actúa y toda propiedad escrita, y of_find_node / of_find_nodes, que dicen por él por qué no encontraron nada.
• Una orden dada durante una espera (código PowerBuilder que se ejecuta mientras el árbol espera a su página, un temporizador por ejemplo) no se comprueba de antemano: la página decide sola, y una adición o un movimiento que rechaza devuelve igualmente 0.
• Durante una espera (un evento del componente que se está respondiendo), una orden de su código no se juzga de antemano: ib_expanded y of_move_node pasan el veto sin plantear la pregunta, y of_get_last_error lo dice. Dé sus órdenes fuera del evento cuando el veto cuenta.
• of_set_layout restituye un estado — normalmente al inicio — sin plantear las preguntas de ib_veto_selection ni de ib_veto_toggle: es la excepción a la regla de que una orden del código plantea la pregunta.
• Modo demo: sin clave, el árbol dibuja los 8 primeros nodos de cada nivel y 200 nodos en todo el árbol (los primeros añadidos), en el orden del modelo — antes de la ordenación, la búsqueda y la ocultación: un nodo oculto cuenta, una búsqueda o una ordenación nunca muestran el noveno, lotes y grupos incluidos, y un total nunca cuenta lo que el límite oculta; los demás se quedan en memoria, ni mostrados ni seleccionables (véase el modo demo).

Heredado de la base común #

Estos miembros existen en todos los componentes visuales — no son propios de este. Se detallan una sola vez, en los capítulos transversales; esta tabla solo dice dónde leerlos.

Dos ayudas no se heredan: of_icon y of_escape_markup viven en n_pbt_utils. Declare uno — n_pbt_utils lnv_utils, nada que crear — y llámelas sobre él.

← Referencia de componentes · Índice de la guía