4D v12 permite especificar e usar list box hierárquicos. Um list box hierárquico é um list box no qual o conteúdo da primeira coluna aparece em forma hierárquica. Este tipo de representação se adapta à apresentação de informação que inclui valores repetidos ou valores que dependem hierarquicamente (país, região ou cidade, etc.).

Apenas os list box de tipo array podem ser hierárquicos
Os list box hierárquicos constituem um modo particular de representar dados, mas não modificam a estrutura dos dados (arrays). Os list box hierárquicos se manejam da mesma maneira como os list box regulares.

Para especificar um list box hierárquico, há três possibilidades diferentes:

• Configurar manualmente elementos hierárquicos utilizando a lista de propriedades no editor de formulários.
• Gerar visualmente  a hierarquia utilizando o menu emergente de gestão dos list box, no editor de formulários.
• Utilize os comandos LISTBOX SET HIERARCHY e LISTBOX GET HIERARCHY, descritos no manual Linguagem de 4D.

Esta seção explica como criar list box hierárquicos no editor de formulários de 4D e os fundamentos de seu funcionamento durante a execução. Para obter mais informação sobre a gestão programada dos list box hierárquicos (seleções, rupturas, utilização dos eventos formulário On Expand e On Collapse, etc...).

Pode ativar e configurar o modo hierárquico no tema "Hierarquia" da lista de propriedades. Para obter mais informação, consulte Propriedades específicas dos list Box.

Ao clicar na área de colunas de um list box, o menu contextual do editor de formulários contém os comandos Criar hierarquia e Cancelar hierarquia.

Quando selecionar ao menos uma coluna, além da primeira, de um objeto list box (do tipo array) no editor de formulários, o comando Criar hierarquia está disponível no menu contextual:

Ao escolher esse comando, as seguintes ações são realizadas.

• A opção "List box hierárquico" está selecionada para o objeto na Lista das propriedades.
• As variáveis das colunas são usadas para definir a hierarquia. Elas substituem as variáveis já especificadas.
• As colunas selecionadas já não aparecem na list box (exceto pelo título da primeira).

Exemplo: dado um list box cujas primeiras colunas contém País, Região, Cidade e População. Quando País, Região E Cidade estão selecionados (veja a imagem acima), se você escolher Criar hierarquia no menu contextual, uma hierarquia de três níveis é criada na primeira coluna, as colunas 2 e 3 são elimina das e a coluna  População se converte na segunda:

Quando a primeira coluna está selecionada e foi definida como hierárquica, pode utilizar o comando Cancelar hierarquia. Ao escolher esse comando, são efetuadas as seguintes ações:

• A opção List box hierárquico são desmarcadas para o objeto,
• Os níveis hierárquicos de 2 a X são eliminados e são transformados em colunas agregadas ao list box.

Quando se abre pela primeira vez um formulário que contém um list box hierárquico, por padrão, todas as linhas se expandem.

Uma linha de ruptura e um "nodo" hierárquico são agreagadas automaticamente ao list box quando os valores se repetem nos arrays. Por exemplo, imagine um list box que contém quatro arrays especificando as cidades, cada cidade é caracterizada pelo seu país, sua região, seu nome e seu número de habitantes:

Se esse list box é mostrado em forma hierárquica (os primeiros três arrays incluídos na hierarquia), se obtêm:

Os arrays não são ordenados antes da construção da hierarquia. Se, por exemplo, um array contém os dados AAABBAACC, a hierarquia obtida será:
    >    A
    >    B
    >    A
    >    C

Para expandir ou contrair um "nodo" hierárquico, clique nele. Se pressionar Alt+clique (Windows) ou Opção+clique (Mac OS) no nodo, todos seus sub elementos se expandem ou contrairão também. Estas operações também  podem ser realizadas por programação utilizando os comandos LISTBOX EXPAND e LISTBOX COLLAPSE.

Quando os valores de tipo data ou hora são incluídos em um list box hierárquico, são mostrados em um formato padrão:

• As datas são mostradas no formato sistema curto (por exemplo, para 30 de maio de 2009, "05/30/09" no sistema americano e "30/05/09" no sistema europeu).
• As horas também são mostradas no formato sistema curto ("12:15:30" ou "12:15" em função dos parâmetros do sistema).

Em um list box em modo hierárquico, uma ordenação padrão (efetuada clicando no título de uma coluna do list box) sempre se constrói da seguinte forma:

Em primeiro lugar, todos os níveis da coluna hierárquica (primeira coluna) são ordenados automaticamente em ordem ascendente.

• A ordenação é realizada em ordem ascendente ou descendente (segundo a ação do usuário) nos valores da coluna na que se clicou.
• Todas as colunas se sincronizam.   
• Durante as ordenações posteriores das colunas não hierárquicas do list box, só o último nível da primeira coluna é ordenado. É possível modificar a ordenação desta coluna clicando em seu título.

Dando como ejemplo o list box a seguir, no qual não é definida nenhuma ordenação específica:

Se clicar em "População" para ordenar as populações de forma ascendente (ou alternativamente descendente), os dados aparecem assim:

Como para todos os list box, pode desativar o mecanismo de ordenação padrão desmarcando a propriedade "Ordenável" para o list box e manejando a ordenação por programação.

Um list box hierárquico mostra um número variável de linhas na tela de acordo com o estado exibido/contraído dos nós hierárquicos. Isto não significa contudo que o número de linhas dos arrays vai variar. Somente é modificada a visualização, não os dados.

É importante entender este principio porque a gestão programada de list box hierárquicos se baseia sempre nos dados dos arrays, não nos dados mostrados. Particularmente, as quebras de linhas adicionadas automaticamente não são tidas em conta nos arrays de opções de visualização (consulte a seção Management of break rows).

Vejamos, por exemplo, os seguintes arrays:

Se estes arrays estão representados hierárquicamente, a linhea "Quimper" não será mostrada na segunda linha, senão na quarta, por causa das duas quebras de linha adicionadas:

Independentemente de como os dados são mostrados no list box (hierárquicamente ou não), se quiser mudar a linha que contém "Quimper" a negrito, deverá utilizar a instrução Style{2} = bold. Somente será tida em conta a posição da linha nos arrays.

Este principio é aplicado para os arrays internos que podem ser utilizados para gerenciar:

• cores
• cores de fundo
• estilos
• linhas ocultas
• seleções

Por exemplo, se você quiser selecionar a linha que contém Rennes, deverá passar:

Representação não-hierárquica:

Representação hierárquica:

Nota: se uma ou mais linhas são ocultas porque seus pais estão contraídos, não são mais selecionados. Somente as linhas que são visíveis (seja diretamente ou por deslocamento) podem ser selecionados. Em outras palavras, as linhas não podem estar ao mesmo tempo ocultas e selecionadas.

Da mesma maneira que com as seleções, o comando LISTBOX GET CELL POSITION retorna os mesmos valores para um list box hierárquico e um list box não hierárquico. Isto significa que nos dois exemplos a seguir,  LISTBOX GET CELL POSITION  retornará a mesma posição: (3;2).

Representação não-hierárquica:

Representação hierárquica:

Quando todas as linhas de uma sub-hierarquia estão ocultas, a quebra de linha é oculta automaticamente. No exemplo anterior, se as linhas 1 à 3 estão ocultas, a quebra de linha "Brittany" não será exibida.

Se o usuário selecionar uma quebra de linha, LISTBOX GET CELL POSITION retorna a primeira ocorrência da linha no array correspondente. No seguinte caso: 

... LISTBOX GET CELL POSITION retorna (2;4). Para selecionar uma quebra de linha por programação, deverá utilizar o comando LISTBOX SELECT BREAK.

As quebras de linha não são tidas em conta nos arrays internos utilizados para gerenciar a aparência gráfica dos list box (estilos e cores). Contudo é possível modificar essas características para as quebras de linha vía os comandos de gestão gráfica para objetos (tema "Propriedades dos objetos"). Somente deverá executar os comandos apropriados nos arrays que constituem a hierarquia. 

Por exemplo a seguinte list box (os nomes dos arrays associados são especificados entre parênteses): 

Representação não-hierárquica: 

Representação hierárquica:

No modo hierárquico, os níveis de quebra não são tidos em conta pelos arrays de modificação de estilo chamados tStyle e tColors. Para modificar a cor ou o estilo dos níveis de quebra, deveráe executar as seguintes instruções:

Nota: Neste contexto, somente a sintaxe que utiliza a variável array pode funcionar com os comandos de propriedade do objeto porque os arrays não têm objeto associado.

Resultado:

Pode otimizar a visualização e a gestão dos list box hierárquicos utilizando os eventos formulário On Expand e On Collapse.

Um list box hierárquico é construido a partir dos conteúdos de seus arrays pelo qual só podem ser mostrados quando todos os arrays são carregados na memória. Isto faz difícil a geração de list box hierárquicos de grande tamanho baseados em arrays gerados a partir dos dados (vía o comando SELECTION TO ARRAY), não somente pela velocidade de visualização, mas também pelo uso da memória.

O uso dos eventos formulario On Expand e On Collapse permite superar estas limitações: por exemplo, agora pode ser mostrado somente uma parte da hierarquia e carregar/descarregar os arrays enquanto estiver rodando, em função das ações do usuário.

No contexto destes eventos, o comando LISTBOX GET CELL POSITION devolve a célula onde o usuário clicou para expandir o contrair uma linha.

Neste caso, deve preencher e esvaziar os arrays por código. Os principios a ser aplicados são:

 - Durante a visualização do list box, só o primeiro array deve ser preenchido. Contudo, você deve criar um segundo array com valores vazios para que o list box mostre os botões expandir/contrair:

 - Quando um usuário clica num botão de expandir, pode processar o evento On Expand. O comando LISTBOX GET CELL POSITION devolve a célula em questão e permite criar a hierarquia apropriada: preenche-se o primeiro array com os valores repetidos e o segundo com os valores enviados a partir do comando SELECTION TO ARRAY e inserir no list box tantas linhas quanto seja necessário utilizando o comando LISTBOX INSERT ROWS.

 - Quando um usuário clica num botão de contração, pode processar o evento On Collapse. O comando LISTBOX GET CELL POSITION retorna a célula em questão: elimina do list box tantas linhas quanto seja necessário utilizando o comando LISTBOX DELETE ROWS.