treeview — u_pbt_treeview #

← Referência dos componentes · Índice do guia

treeview mostra dados em árvore: nós que contêm outros, abertos e fechados pelo seu chevron, com uma imagem, um emblema, uma caixa de três estados e uma seleção simples ou múltipla. Assim que lhe é acrescentada uma coluna, torna-se uma lista em árvore (TreeList): a primeira coluna tem a árvore, as outras mostram os campos de cada nó, ordenáveis com um clique no seu cabeçalho. Um ramo pode prometer filhos que só lê ao abrir; o utilizador renomeia um nó (F2) e arrasta-o para outro lado, podendo a sua aplicação recusar antes; uma pesquisa só deixa o que corresponde. A árvore preenche-se à mão ou a partir de um DataStore hierárquico (uma linha nomeia o seu pai), e pode reescrever nele o que o utilizador muda.

▶ Ver ao vivo — Aplicação de demonstração, mosaico Tree view: a pré-visualização, o código que o produz e esta página, lado a lado.

Em resumo #

Início 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)

Um endereço por nó #

Um nó é designado pelo seu endereço: as chaves dos seus níveis juntas por /. "europe" está no topo, "europe/france" dentro de "europe" — o pai é acrescentado primeiro. Uma chave é única sob o seu pai: "europe/paris" e "usa/paris" são dois nós. Um endereço já ocupado, um pai desconhecido, um nível vazio, uma chave que contém | ou começa por __: o acréscimo devolve -5 e of_get_last_error diz porquê. of_insert_node coloca um nó entre os seus irmãos (posição contada a partir de 1), of_move_node desloca-o com a sua subárvore para outro pai ("" = o topo): o seu endereço muda, e os handles obtidos no endereço antigo são libertados de imediato (um handle obtido depois no novo continua válido). Para percorrer a árvore: of_count() e of_keys_at(n) para o primeiro nível, of_count(endereço) e of_keys_at(endereço, n) para os filhos de um nó — que devolve o endereço completo, reutilizável tal como está.

// 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, selecionar, marcar #

Um nó abre-se pelo seu chevron, um duplo clique, o teclado ou o seu código (ib_expanded do seu handle, of_expand_all, of_collapse_all, of_expand_to_level, of_scroll_to_node, o que of_select_node abre; of_clear_children fecha): cada um levanta ue_node_toggled, depois ue_layout_changed. A seleção segue is_selection_mode: um nó (SELECT_SINGLE, o predefinido), vários com Ctrl e Shift como no Explorador (SELECT_MULTIPLE), ou nenhum (SELECT_NONE: o teclado só move um foco). of_select_node seleciona um nó sozinho, abre o que o contém e trá-lo para o ecrã — uma árvore abre para selecionar, como o TreeView do Windows, mas julga primeiro: um nó escondido ou contido num escondido, além do limite de demonstração ou afastado pela pesquisa é recusado (-5, of_get_last_error diz porquê) e nada se abre. ue_selection_changed recebe os endereços selecionados num array JSON — quer a tenha mudado um clique, o teclado ou o seu código, quer um nó selecionado tenha saído do ecrã (ramo fechado, nó retirado ou escondido, nó ocultado pela pesquisa). Fechar um ramo traz o foco de volta para ele. Com ib_checkboxes, cada nó tem uma caixa; com ib_check_cascade (o predefinido), uma marca do utilizador num pai marca a sua subárvore exceto um nó desativado e a sua subárvore, que ficam como estão (o pai fica então misto); uma marca do seu código marca tudo. Durante uma pesquisa, a cascata abrange toda a subárvore, nós ocultados incluídos. Sob a cascata, um pai é o estado dos filhos que a árvore pode desenhar (nem escondidos nem, em modo de demonstração, além do limite): marcado quando todos o estão, misto quando uma parte o está. Uma marca posta pelo utilizador levanta ue_node_checked; uma marca posta pelo seu código (ib_checked, of_check_all) é um valor, mudo como SetItem. Os filhos recebidos sob uma folha marcada recebem a sua marca — todos, toda a resposta a ue_children_needed — até que uma marca (gesto ou código) ou um nó deslocado para dentro lhe ponha fim. Uma marca do utilizador nunca toca num nó além do limite de demonstração, nem, com ib_write_back, num nó escondido. of_select_nodes(as_keys_json) seleciona vários nós de uma vez em SELECT_MULTIPLE — o par de of_selected_keys — com uma só pergunta aos vetos e um só ue_selection_changed; o foco vai para o último endereço nomeado.

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

Perguntar primeiro: seleção e abertura #

Um ecrã mestre-detalhe não deve sair de uma ficha por gravar. Com ib_veto_selection, ue_selection_changing recebe a seleção atual e a pedida (arrays JSON de endereços) antes de qualquer escolha: um clique, Ctrl ou Shift + clique, o teclado, F3, of_select_node, of_clear_selection, of_search_next ou of_search_prev. Devolva FALSE para recusar: nada se move, nem sequer o foco do teclado, e o método devolve -4; ue_node_clicked é levantado na mesma, o clique aconteceu. O que sai da seleção por consequência — um ramo fechado, um nó retirado, escondido ou ocultado pela pesquisa — não é perguntado. Da mesma forma, ib_veto_toggle pergunta ue_node_toggling antes de cada abertura ou fecho, por um gesto ou pelo código: um ib_expanded recusado não envia nada (of_get_last_error di-lo), of_expand_all, of_collapse_all e of_expand_to_level aplicam os outros nós e devolvem -4, of_select_node e of_scroll_to_node devolvem -4 sem abrir nada. of_select_node pergunta primeiro as aberturas (ue_node_toggling), depois a seleção: uma aplicação nunca age sobre uma seleção aceite para uma abertura depois recusada. O que sai da seleção por consequência não se recusa: para que um ramo fechado não saia de uma ficha por gravar, junte ib_veto_selection a ib_veto_toggle e recuse o fecho do ramo que a contém. ib_single_expand deixa um só ramo aberto sob cada pai: abrir um nó fecha os seus irmãos abertos, sem perguntar; defini-lo não fecha nada no 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

Ramos carregados a pedido #

Uma árvore grande — um disco, um catálogo, uma tabela de milhares de linhas — não tem de ser lida de uma vez. ib_has_children = true num nó é uma promessa: o seu chevron aparece embora não contenha nada. Quando se abre — um clique, o teclado, o seu código, ou of_select_node a abrir o que contém um nó —, ue_children_needed é levantado: os seus of_add_node feitos durante o evento estão lá quando o ramo se abre, depois do retorno da linha que o abriu (ib_expanded = true não espera por eles). A promessa vale até essa resposta, mesmo que entretanto um nó tenha sido acrescentado ou largado lá dentro; não acrescente nada, e ela é retirada (o chevron desaparece). Voltar a pôr ib_has_children = true faz a próxima abertura voltar a perguntar. Uma abertura feita durante o evento levanta um só ue_node_toggled. of_expand_all só abre os ramos que já têm filhos: um ramo cuja promessa não teve resposta fica fechado, nenhuma pergunta é feita em massa. Para uma tabela, não é preciso chamar of_add_node linha a linha: of_from_datastore(ads, as_parent_keys) faz das linhas de um DataStore os filhos do nó, numa só mensagem — o padrão ItemPopulate → Retrieve do TreeView do PowerBuilder. ROLE_PARENT nomeia aí uma linha do mesmo lote (vazio ou desconhecido: diretamente sob o nó); o mesmo DataStore dado de novo sob o mesmo nó substitui o seu lote, outro DataStore acrescenta o seu. of_row de um nó de um lote devolve a sua linha no seu DataStore, e ib_write_back escreve lá. of_clear_children retira os filhos de um nó e fá-lo prometer de novo: a sua próxima abertura volta a perguntar (o «atualizar» de uma pasta). Dê a cada lote o seu próprio DataStore (criado quando o seu ramo abre, guardado enquanto os seus nós são mostrados): um DataStore recarregado para outro nó — Reset, Retrieve, depois of_from_datastore sob outro nó — leva as suas linhas para o novo lote, e o PowerBuilder volta a dar os mesmos RowID depois de um Reset. Os nós do lote anterior guardam então o que mostram mas já não têm linha: of_row devolve 0, uma deslocação pelo código devolve -5 ("loaded again"), um texto renomeado ou uma marca é recusado e ue_write_back_failed diz porquê, e o carregamento que o causou conta-os (stale=N) em of_get_last_error. O mesmo DataStore dado de novo sob o mesmo nó substitui o seu lote; para refrescar um lote a partir de outro objeto DataStore, chame primeiro of_clear_children, senão acrescenta-se ao lado do primeiro. Uma coluna chamada has_children (ROLE_HAS_CHILDREN) faz uma linha prometer os seus próprios filhos, sem ciclo. as_parent_keys vazio é recusado (-5): o topo da árvore é 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

Renomear e deslocar #

Com ib_editable, o utilizador renomeia um nó: F2, ou um clique no nó já selecionado (após um breve atraso, como o Explorador). Enter (ou sair do campo) guarda o texto, Esc devolve-o, um texto esvaziado é recusado (a edição é cancelada); ue_node_edited recebe o texto escrito e o antigo — um texto escrito é texto, nunca etiquetas. Uma ordem do seu código durante a edição mantém o campo e o que nele está escrito; se a linha editada sair do ecrã sem um gesto do utilizador (código, deslocamento), a edição é cancelada. Com ib_drag_drop, arrasta um nó: sobre o quarto superior de uma linha vai antes dela, sobre o quarto inferior depois — como primeiro filho se for um ramo aberto —, ao meio dentro; um ramo fechado sob o ponteiro abre-se ao fim de um momento, a árvore desloca-se perto dos seus bordos, Esc cancela, um nó nunca vai para a sua própria subárvore nem para onde a sua chave está ocupada, e nada se larga sobre a linha de um nó desativado. Um arrastar cujo botão solto a árvore não vê — a janela perde o foco (Alt+Tab, uma caixa de mensagem) — é cancelado: nada se move. Sob uma ordenação, ou com ib_parents_first, uma largada só vai dentro. ue_node_moved recebe o novo endereço, o antigo e o lugar sob o novo pai; um nó largado onde já está não pergunta, não escreve nem levanta nada. Com ib_veto_changes, ue_node_editing e ue_node_moving são perguntados antes — ue_node_moving com o lugar final, o que ue_node_moved dirá: devolva FALSE para recusar — nada muda, e of_move_node devolve -4. Arrasta-se um nó de cada vez, mesmo em seleção múltipla.

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

O seu código também abre um nome em edição: of_edit_node(as_keys) — o EditLabel de um TreeView PowerBuilder, para uma «Nova pasta» que se abre pronta a ser nomeada. O nó é primeiro selecionado (o que o contém abre-se), depois o campo abre-se; o fim pertence ao utilizador, como acima. Um bloqueio para o utilizador, nunca o seu código: funciona com ib_editable = false, num nó só de leitura ou desativado. of_cancel_edit() fecha o campo e devolve o 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")

Bloqueios, Delete e cópia #

Três bloqueios por nó travam o utilizador, nunca o seu código: ib_read_only (nem renomeado nem arrastado, continua a ser um destino), ib_drop_target = false (nada é largado dentro dele, nem um nó nem um ficheiro — antes ou depois dele continua permitido) e ib_show_checkbox = false (sem caixa: o nó não conta para o pai, não está em of_checked_keys, e a cascata atravessa-o para os seus filhos). Delete levanta ue_delete_requested com os nós selecionados (em SELECT_NONE, o do foco; sem seleção, caso contrário, nada é levantado), exceto os desativados e só de leitura: a árvore não retira nada, a sua aplicação chama of_remove_node para o que apaga. Ctrl+C (ou Ctrl+Insert) levanta ue_copy com os nós selecionados (em SELECT_NONE, o do foco) em texto separado por tabulações, um número bruto (um ponto, sem agrupamento nem símbolo): o texto depois de tantas tabulações quanto a sua profundidade, depois as colunas de uma lista em árvore alinhadas, primeiro uma linha de cabeçalho; a árvore tenta também a área de transferência do navegador, que pode ser recusada à página — ClipBoard(as_tsv) para ter a certeza.

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

Ficheiros largados a partir do Explorador #

Com ib_allow_drop, a árvore aceita ficheiros arrastados a partir do Explorador do Windows sobre um nó: o nó sob o cursor acende-se durante o arrastar, ue_drop_files recebe o seu endereço e os caminhos completos. as_keys fica vazio para uma largada ao lado dos nós, sobre um nó desativado ou sobre um nó cujo ib_drop_target vale false. ue_drag_enter e ue_drag_leave dizem que um arrastar de ficheiros entrou e depois saiu sem largar 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"))

Colunas, ordenação e disposição #

of_add_column faz da árvore uma lista em árvore: a primeira coluna tem a árvore (o seu título é is_tree_title), cada coluna acrescentada mostra o campo com a mesma chave de cada nó — definido por of_set_field, ou uma coluna do DataStore. O handle de uma coluna (of_column) regula o seu título, a sua largura (0 = automática), o seu alinhamento, o seu formato (uma máscara numérica como "#,##0.00" com os separadores da língua de apresentação, ou tokens de data para um valor "yyyy-mm-dd", os do datagrid), a sua visibilidade e o seu lugar. Um clique num cabeçalho ordena os irmãos de cada nível — crescente, decrescente, depois a ordem de acréscimo — e levanta ue_sort_changed; of_sort faz o mesmo a partir do código. A ordenação só muda a ordem mostrada: of_keys_at e as posições mantêm a ordem de acréscimo. O utilizador alarga uma coluna pelo bordo do seu cabeçalho e desloca-a arrastando o cabeçalho. O que dispôs — larguras, ordem, visibilidade, ordenação, nós abertos — lê-se por of_get_layout e devolve-se por of_set_layout; ue_layout_changed leva a disposição inteira depois de cada gesto que a muda, e quando o seu código escreve a largura, o lugar ou a visibilidade de uma coluna (ii_width, ii_index, ib_visible) e a disposição muda. Valores iguais mantêm a ordem do modelo, e a ordenação é refeita quando a língua de apresentação muda. Retirar a coluna ordenada (of_remove_column, of_clear_columns) levanta ue_sort_changed com a chave seguinte da ordenação — SORT_NONE quando era a única —, depois ue_layout_changed. As cinco cores do handle de uma coluna (il_accent, il_back_color, il_text_color, il_back_color_hover, il_text_color_hover) colorem o seu cabeçalho. Assim que há colunas, a coluna da árvore fica fixa no deslocamento horizontal. A ordenação pode ter várias chaves: of_sort(as_sort) lê a sintaxe do SetSort de um DataWindow («type A, text D», sendo «text» o texto dos nós), of_sort(as_column, as_dir) aceita também um campo que nenhuma coluna mostra, e ue_sort_changed recebe a ordenação inteira como terceiro argumento. ib_parents_first põe em cada nível os nós que têm (ou prometem) filhos antes das folhas — as pastas antes dos ficheiros — seja qual for a ordenação. Uma coluna não pode ter a chave text, que designa o texto dos nós (-5): of_sort("text", as_dir) ordena por ele, e of_sort aceita vários espaços entre uma coluna e o seu 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 a árvore com a sua hierarquia: of_export_csv(as_path) escreve um CSV (UTF-8, ponto e vírgula) em que o texto de um nó fica na célula do seu nível — uma célula mais à direita por nível —, as colunas de uma lista em árvore depois do nível mais profundo, primeiro uma linha de cabeçalho; of_export_xlsx(as_path) escreve um livro Excel em que o texto fica recuado pelo seu nível e cada ramo agrupado sob o seu pai, dobrável no Excel, e os números continuam números. is_export_scope diz quais nós: EXPORT_ALL (o predefinido) todos os nós, ramos fechados incluídos, EXPORT_SHOWN as linhas no ecrã. A árvore constrói o ficheiro, a DLL escreve-o, ue_csv_saved / ue_xlsx_saved confirmam; recusado no modo de demonstração.

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

Totais por ramo #

Uma coluna de uma lista em árvore pode mostrar, em cada ramo, o total do que contém: is_summary no seu handle vale SUMMARY_SUM, SUMMARY_AVG, SUMMARY_MIN, SUMMARY_MAX ou SUMMARY_COUNT (os valores não vazios). O cálculo desce até às folhas — uma média é a das folhas, nunca uma média de médias — e o total escreve-se a negrito, por is_format — uma contagem sempre como número simples. Um ramo que tem um valor próprio guarda-o e fá-lo subir, exceto com ib_summary_over_value na coluna. Só contam os nós que a árvore pode desenhar (nunca um escondido); com ib_summary_filtered, no componente, só o que a pesquisa mostra. of_get_field devolve o total bruto (um número com ponto), uma ordenação por esta coluna usa os totais, e os totais seguem cada adição, remoção ou arrastar. SUMMARY_MIN e SUMMARY_MAX comparam também datas (yyyy-mm-dd, yyyy-mm-dd hh:mm:ss, hh:mm:ss), e uma soma de inteiros continua exata além 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")

Pesquisar #

is_filter só mostra os nós cujo texto contém a pesquisa (maiúsculas ignoradas), com os nós que os contêm, abertos, e o texto encontrado realçado. "" mostra tudo. O que contém uma correspondência aparece aberto sem mudar ib_expanded, e os chevrons ficam inertes enquanto dura a pesquisa. Com ib_toolbar, uma barra por cima da árvore tem um campo de pesquisa (que escreve is_filter: uma leitura devolve-o de imediato), e os botões Expandir tudo e Recolher tudo. Esc no campo esvazia a pesquisa, Seta para baixo passa para a árvore, Enter e F3 vão para a correspondência seguinte (Shift: para a anterior) e o campo mantém o teclado. Um nó selecionado que a pesquisa oculta sai da seleção, e ue_selection_changed di-lo; o nó que o contém não é selecionado no seu lugar. of_select_node e of_scroll_to_node recusam um nó que a pesquisa afasta (-5). Para ir de correspondência em correspondência, of_search_next e of_search_prev selecionam a seguinte ou a anterior depois do nó do foco, em ciclo (F3 e Shift+F3 no teclado), e of_match_count diz quantas a pesquisa encontrou. of_find_node(as_field, as_value, as_after_keys) encontra sem filtrar: o endereço do primeiro nó cujo campo ("" = o seu texto) vale exatamente o valor, pela ordem que a árvore mostra, ramos fechados incluídos; volte a dar o endereço encontrado para o seguinte. Em SELECT_NONE, of_search_next e of_search_prev movem para lá o foco, como F3. of_find_node parte depois do lugar de as_after_keys na ordem mostrada — também um nó escondido; um desconhecido devolve "" e of_get_last_error di-lo. of_find_nodes(as_field, as_value) devolve todas as correspondências de uma vez, como array JSON na ordem mostrada.

A pesquisa ignora os acentos por predefinição, como a ordenação: «montreal» encontra «Montréal», e o I com ponto do turco conta como um I («izmir» encontra «İzmir»); ib_filter_accents = true fá-los contar. Em seleção múltipla, Ctrl+A seleciona todos os nós apresentados (uma única pergunta com 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"))

A partir de um DataStore #

of_from_datastore faz um nó de cada linha de uma tabela hierárquica: a coluna ROLE_KEY dá a sua chave (sem ela, o RowID da linha), a coluna ROLE_PARENT nomeia a chave do nó que o contém (vazia, desconhecida, ou um ciclo: no topo) — com uma coluna ROLE_KEY, um valor de pai nomeia uma chave, nunca um RowID. Os outros papéis: o texto (ROLE_TEXT, mostrado como texto, nunca como etiquetas), a imagem, a marca, o emblema e a abertura ao carregar. Uma coluna desempenha um papel quando se chama como ele (key, parent, text…) ou quando of_map o diz. Cada coluna é um campo (of_get_field) — as colunas da lista não são criadas automaticamente: of_add_column com o nome da coluna. Datas e números são lidos sejam quais forem as definições regionais, numa só forma: uma data yyyy-mm-dd, uma data-hora yyyy-mm-dd hh:mm:ss, um número com ponto e sem zeros inúteis (1234,50 passa a 1234.5) — uma coluna decimal é formatada e ordenada como um número. Duas linhas com a mesma chave: a segunda recebe "chave~RowID". O que o carregamento teve de corrigir (linhas cujo pai não está lá, ciclos quebrados, chaves duplicadas, chaves impossíveis) é dito por of_get_last_error, o retorno continuando 0. of_reload_row relê uma linha mudada pelo seu código e atualiza o seu nó no lugar; uma linha cuja chave ou pai mudou desloca o seu nó. O nó de uma linha retirado por of_remove_node fica fora até ao próximo of_from_datastore; of_reload_row da sua linha trá-lo de volta. Com ib_write_back, um texto renomeado é escrito na coluna ROLE_TEXT e um nó que muda de pai escreve-o na coluna ROLE_PARENT (NULL no topo, seja qual for o seu tipo; uma deslocação entre os mesmos irmãos não escreve nada), antes do evento; um nó de linha não vai então nem para debaixo de um nó acrescentado à mão nem para debaixo de uma linha sem valor de chave — a sua coluna pai não o saberia dizer. Um valor que o DataStore recusa, ou um DataStore destruído desde o carregamento (no DataStore is bound), volta a pôr o nó no lugar e levanta ue_write_back_failed. Sem ib_write_back, um arrastar só desloca o nó: a sua linha guarda o que o DataStore diz, e a releitura seguinte das linhas (of_map, is_group_by, of_reload_row, um novo carregamento) devolve o nó para onde a sua linha diz — o seu antigo handle é libertado. O Update continua a ser seu. O handle de um nó lê o número da sua linha (of_row). of_from_datastore lê também as linhas de um DataWindow ou de um DataWindowChild — o que o utilizador vê ao lado: a árvore escreve então nesse. Com ib_write_back, uma marca do utilizador escreve-se também na coluna ROLE_CHECKED de cada linha que mudou — cascata incluída, e os ramos acima cujo estado passa a marcado ou desmarcado (um ramo que fica misto guarda o seu valor) —, escrita como a coluna já a escreve (1/0, Y/N, T/F, O/N, -1/0…; uma coluna que só mostra o seu não escreve o sim habitual: Y para N, 1 para 0 — O e -1 só se a coluna já contiver um); uma coluna cujos valores não são nem um sim nem um não é recusada, com o seu motivo. Cada valor é julgado primeiro e a escrita é tudo ou nada: uma recusa devolve as marcas do gesto e levanta ue_write_back_failed. of_row_keys devolve o endereço do nó de uma linha do DataStore principal: retire o nó antes de um DeleteRow. Toda a escrita de volta é tudo ou nada — cada valor julgado antes de um ser escrito; uma data-hora guarda a sua hora, uma coluna time escreve-se, lê-se e agrupa-se em hh:mm:ss. Uma deslocação escrita por of_move_node é julgada de novo depois de ue_node_moving, e o que foi escrito é reposto se o nó não se mover. Com ib_write_back, um nó de linha cujo DataStore não tem coluna ROLE_TEXT não se renomeia. Um novo carregamento só liberta os handles do que substitui: o handle de um nó acrescentado à mão, um handle inerte ou um obtido num endereço ainda não criado continuam válidos; of_from_datastore a partir de uma DataWindow verifica que os seus dados se podem partilhar (-5 com o motivo). O que uma releitura das linhas teve de corrigir conta-se em of_get_last_error — incluindo os nós acrescentados à mão subidos ao topo porque o seu grupo já não existe (lifted=N) e os lotes que partiram com o seu nó (lots=N); of_map e is_group_by dizem-no para todas as fontes.

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

Um papel resolve-se por DataStore: a coluna que of_map(ads, as_role, as_column) deu a este DataStore, senão a de of_map(as_role, as_column) quando este DataStore a tem, senão a coluna com o nome do papel. Um lote de empregados sob uma árvore de departamentos não precisa assim de nenhuma coluna dos departamentos. Uma tabela cujas raízes têm 0 na coluna pai (uma coluna NOT NULL) di-lo com is_root_parent_value = "0" ("0|-1" para dois valores): essas linhas ficam no topo sem contar como órfãs, e um nó deslocado para o topo com ib_write_back escreve 0 em vez de NULL. As colunas ROLE_STATE_IMAGE e ROLE_OVERLAY_IMAGE dão a imagem de estado e a imagem sobreposta de um nó, lidas 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)

Uma árvore agrupada por colunas #

O estilo TreeView de um DataWindow, sem DataWindow: is_group_by = "region|country|city" faz das linhas de of_from_datastore as folhas de grupos construídos sobre os valores dessas colunas, um nível por coluna (ROLE_PARENT não tem papel, ROLE_KEY nomeia as folhas). A chave de um grupo é o seu valor (/, | e % escritos %2F, %7C, %25), o seu texto o valor escrito com o formato da coluna com a mesma chave, «(vazio)» para um valor vazio; o handle de um nó de grupo lê of_group_column() e of_group_value(). Definido depois de um carregamento, reagrupa; of_reload_row coloca uma linha cujo valor mudou no seu novo grupo. of_set_level_image dá uma imagem a todos os nós de um nível, of_expand_to_level abre a árvore até um nível, e is_summary dá os totais de cada grupo. Com ib_write_back, uma folha largada sob um grupo do último nível escreve todas as suas colunas de grupo antes do evento; noutro lado, e para um nó de grupo, a deslocação é recusada. O texto de um grupo segue um formato posto depois do carregamento, a chegada da sua coluna e a língua de apresentação; um valor que começa por __ escreve-se %5F_ na chave; of_group_value de uma data-hora vale yyyy-mm-dd hh:mm:ss, de uma hora hh:mm:ss. Sem ib_write_back, uma folha arrastada para outro grupo volta ao seu no agrupamento seguinte, pois a sua linha não mudou; um nó acrescentado à mão sob um grupo que desaparece sobe ao topo.

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

Propriedades #

Propriedades de um nó — n_pbt_treeview_node #

O seu handle, através de of_node(endereço). Uma leitura pergunta à árvore o que o nó é agora. O seu of_count() conta os seus filhos, o seu of_keys_at(n) devolve o endereço do seu n-ésimo filho (a partir de 1), o seu of_has(chave) diz se tem esse filho, o seu of_key() devolve a sua chave.

Propriedades de uma coluna — n_pbt_treeview_column #

O seu handle, através de of_column(chave). Um valor escrito pelo seu código é mudo, como SetItem — exceto a sua disposição: ii_width, ii_index e ib_visible escritos pelo seu código levantam ue_layout_changed quando a disposição muda, como um gesto. Uma leitura devolve o que o utilizador possa ter mudado (largura, lugar).

Constantes #

Estão em u_pbt_treeview: u_pbt_treeview.CHECK_MIXED.

Métodos #

Eventos #

Teclado e rato #

• Clique num nó: fica selecionado (ue_node_clicked); no seu chevron: abre-se ou fecha-se; na sua caixa: fica marcado; duplo clique: ue_node_opened, e um ramo abre-se ou fecha-se; clique direito: ue_node_rclicked. Em SELECT_MULTIPLE, Ctrl + clique acrescenta ou retira um nó, Shift + clique toma o intervalo desde o último.
• Cima / Baixo: o nó anterior, o seguinte; Home / End: o primeiro, o último; Page Up / Page Down: de um ecrã. Os nós desativados são saltados.
• Direita abre o nó, depois desce ao seu primeiro filho; Esquerda fecha-o, depois sobe ao seu pai — invertidas numa aplicação da direita para a esquerda. * do teclado numérico abre toda a subárvore; + / - do teclado numérico abrem e fecham — os do teclado principal escrevem-se, para chegar a «+1.2» ou «-Débitos».
• Espaço marca o nó (com ib_checkboxes), senão seleciona-o; Enter: ue_node_opened; F2: renomear (com ib_editable); tecla Menu ou Shift + F10: ue_node_rclicked.
• Em SELECT_MULTIPLE, Shift + setas alargam a seleção, Ctrl + setas só movem o foco, Ctrl + Espaço acrescenta ou retira o nó do foco, Ctrl + A seleciona todos os nós apresentados (uma única pergunta com ib_veto_selection).
• As primeiras letras de um texto selecionam o nó mostrado que começa por elas, como uma seta (em SELECT_NONE, só levam o foco até ele).
• Delete: ue_delete_requested (a árvore não retira nada); Ctrl+C ou Ctrl+Insert: ue_copy; F3 / Shift+F3: a correspondência seguinte / anterior da pesquisa (em SELECT_NONE, o foco vai para lá), a partir da árvore ou do campo de pesquisa, onde Enter faz o mesmo. Delete e Ctrl+C só agem sobre o nó do foco em SELECT_NONE.
• O cabeçalho de uma lista em árvore é uma paragem da tecla Tab: Esquerda / Direita vão de cabeçalho em cabeçalho (invertidas numa aplicação da direita para a esquerda), Home / End ao primeiro e ao último, Enter ou Espaço ordena, Ctrl + Esquerda / Direita estreita ou alarga a coluna em 10 píxeis, Ctrl + Shift + Esquerda / Direita desloca-a, Baixo passa às linhas.
• Arrastar um nó (com ib_drag_drop): um fantasma segue o ponteiro, uma barra mostra onde cairá antes ou depois, uma moldura quando cai dentro; Esc cancela. Arrastar o bordo de um cabeçalho alarga a coluna, arrastar o cabeçalho desloca-a — um fantasma e uma barra de inserção mostram onde, Esc cancela —, clicar no cabeçalho ordena. Um arrastar cujo botão solto a árvore não vê — a janela perde o foco (Alt+Tab, uma caixa de mensagem) — é cancelado: nada se move, uma largura volta.
• A árvore é uma paragem da tecla Tab (mais o cabeçalho de uma lista em árvore, o campo e os botões da barra de ferramentas); um anel pontilhado da cor do texto marca o nó que tem o foco. Uma árvore desativada não recebe o foco.

Exemplos #

Direitos a 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

Reencontrar a disposição no próximo arranque #

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

Um menu sobre um nó #

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

Boas práticas #

• Chaves estáveis: um identificador, não um rótulo — o texto renomeia-se, a chave fica. of_keys_at devolve endereços completos, a passar tal como estão a of_node. Uma disposição guardada de um arranque para o outro (of_get_layout) exige uma coluna ROLE_KEY: sem ela, as chaves das linhas são os seus RowID, que um novo Retrieve dá a outras linhas.
• Ramos a pedido assim que a árvore é grande ou cara de ler: ib_has_children e ue_children_needed só leem o que o utilizador abre.
• Um DataStore por lote: recarregado para outro nó, um DataStore leva as suas linhas — e o PowerBuilder os seus RowID — para longe do lote anterior, cujos nós deixam de ter linha.
• Muitos nós: só as linhas visíveis são desenhadas — dez mil nós deslocam-se como vinte. Acrescentá-los é outra coisa: cada of_add_node é uma mensagem à árvore, cerca de 0,7 ms (2.000 nós ≈ 1,3 s medidos, 10.000 ≈ 7 s esperados); uma árvore grande carrega-se por of_from_datastore, numa só mensagem, ou lê-se a pedido, um lote por ramo (of_from_datastore(ads, as_parent_keys)).
• As colunas de um DataStore são identificadores tanto como valores: escolha as que mostra com of_add_column, nada é criado sozinho.
• Uma marca é um valor: posta pelo seu código, não levanta nada; leia of_checked_keys quando o utilizador confirmar.
• of_get_last_error diz porque é que a última chamada foi recusada; é esvaziado por todo o método que age e por toda a propriedade escrita, e por of_find_node / of_find_nodes, que dizem por ele porque não encontraram nada.
• Uma ordem dada durante uma espera (código PowerBuilder que corre enquanto a árvore espera pela sua página, um temporizador por exemplo) não é verificada antecipadamente: a página decide sozinha, e uma adição ou deslocação que ela recuse devolve mesmo assim 0.
• Durante uma espera (um evento do componente a ser respondido), uma ordem do seu código não é julgada de antemão: ib_expanded e of_move_node passam o veto sem fazer a pergunta, e of_get_last_error di-lo. Dê as suas ordens fora do evento quando o veto conta.
• of_set_layout repõe um estado — tipicamente no arranque — sem fazer as perguntas de ib_veto_selection nem de ib_veto_toggle: é a exceção à regra que quer que uma ordem do código faça a pergunta.
• Modo de demonstração: sem chave, a árvore desenha os 8 primeiros nós de cada nível e 200 nós em toda a árvore (os primeiros acrescentados), pela ordem do modelo — antes da ordenação, da pesquisa e da ocultação: um nó escondido conta, uma pesquisa ou uma ordenação nunca mostram o nono, lotes e grupos incluídos, e um total nunca conta o que o limite esconde; os outros ficam em memória, nem mostrados nem selecionáveis (ver o modo de demonstração).

Herdado da base comum #

Estes membros existem em todos os componentes visuais — não são próprios deste. São detalhados uma só vez, nos capítulos transversais; esta tabela apenas diz onde os ler.

Duas ajudas não são herdadas: of_icon e of_escape_markup vivem em n_pbt_utils. Declare um — n_pbt_utils lnv_utils, nada a criar — e chame-as nele.

← Referência dos componentes · Índice do guia