Gerenciar Listas Hierárquicas

As listas hierárquicas são objetos de formulário que permitem mostrar os dados como listas com um ou mais níveis que podem ser expandidas ou contraídas.

Nos formulários, as listas hierárquicas podem servir para visualizar ou introduzir dados. Cada elemento da lista pode conter até 2 bilhões de caracteres (tamanho máximo de um campo de texto) e estar associado com um ícone. As listas hierárquicas geralmente são compatíveis com clique, duplo clique e navegação com o teclado como também arrastar e soltar. É possível efetuar uma pesquisa no conteúdo de uma lista (comando Find in list).

As listas hierárquicas podem ser criadas completamente por programação (através dos comandos New list ou Copy list) ou utilizando listas definidas no editor de listas no ambiente Desenho (comando Load list).

Os conteúdos e a aparência das listas hierárquicas são administrados por programação utilizando os comandos do tema "Listas hierárquicas". Algumas características de aparência específicas também podem ser definidas utilizando comandos genéricos do tema [#title id="283"/ (ver a seguir).

Pode associar dinamicamente as referências de listas hierárquicas as listas de seleção de objetos de formulários (fontes, valores obrigatório e valores excluídos) utilizando os comandos [#cmd id="1266"/] ou OBJECT SET LIST BY NAME. Também pode associar as listas de seleção definidas no editor de listas aos objetos de formulários via a Lista de propriedades.

Uma lista hierárquica é tanto um objeto de linguagem existente em memória quanto um objeto de formulário.

O objeto de linguagem é referenciado de maneira única por um identificador interno, de tipo Inteiro longo, desenhado por RefList neste manual. Este identificador é retornado pelos comandos que podem ser utilizados para criar listas: New list, Copy list, Load list, BLOB to list. Existe apenas uma instância em memória do objeto de linguagem e toda modificação que se leve a cabo neste objeto imediatamente repercute em todos os lugares onde se utiliza.

O objeto de formulário não é necessariamente único: pode haver várias representações de uma mesma lista hierárquica em um mesmo formulário ou em formulários diferentes. Como para os outros objetos de formulário, você especifica o objeto na linguagem utilizando a sintaxe (*;"NomLista", etc.).

Você conecta o "objeto de linguagem" lista hierárquica com o "objeto de formulário" através da variável que contém o valor do identificador único RefLista. Por exemplo, se escreve:

... é suficiente associar o nome da variável minhalista ao objeto de formulário Lista hierárquica na lista de propriedades com o objetivo de que administre o objeto de linguagem cujo RefLista é guardada em minhalista

Cada representação da lista tem características próprias como também características em comum com as outras representações. As seguintes características são específicas para cada representação de lista:

• A seleção,
• O estado expandido/contraído de seus elementos,
• A posição do cursor de rolagem,

As outras características (fonte, estilo de fonte, estilo, filtro de entrada, cor, conteúdo da lista, ícones, etc.) são comuns a todas as representações e não podem ser modificadas separadamente.

Portanto, quando utilize comandos baseados na configuração expandida/contraída ou o elemento atual, por exemplo Count list items (quando o parâmetro * final não é passado), é importante poder especificar sem ambigüidade a representação a utilizar.

Deve utilizar o identificador de tipo RefLista com os comandos da linguagem quando deseja especificar a lista hierárquica encontrada na memória.

Se deseja especificar a representação a nível de formulário de um objeto Lista hierárquica, deve utilizar o nome do objeto (tipo cadeia) no comando, através da sintaxe (*;"NomLista", etc.). Esta sintaxe é idêntica à utilizada nos comandos do tema "Propriedades dos objetos". É aceita pela maioria dos comandos do tema "Listas hierárquicas" que atuam sobre as propriedades das listas (por favor consulte a descrição dos comandos deste tema).

Advertência, no caso dos comandos que definem propriedades, a sintaxe baseada no nome do objeto não significa que só o objeto de formulário especificado será modificado pelo comando, mas que a ação do comando estará baseada no estado de este objeto. As características comuns das listas hierárquicas sempre são modificadas em todas as representações.

Por exemplo, se passa a instrução SET LIST ITEM FONT(*;"milista1";*;lafuente), está indicando que deseja modificar a fonte da lista hierárquica associada ao objeto de formulário minhalista1. O comando considera o elemento atual do objeto minhalista1 para definir o elemento a ser modificado, mas esta modificação será considerada em todas as representações da lista em todos os processos.

Como para os outros comandos de gestão de propriedades de objetos, é possível utilizar o caractere “@” no parâmetro ListName. De maneira geral, esta sintaxe é utilizada para designar um conjunto de objetos no formulário. Entretanto, no contexto dos comandos de listas hierárquicas, este princípio não aplica em todos os casos. Esta sintaxe terá dois efeitos diferentes dependendo do tipo de comando:

• Para os comandos que definem as propriedades, esta sintaxe designa todos os objetos cujo nome corresponde (funcionamento padrão). Por exemplo, o parâmetro "LH@" designa todos os objetos de tipo lista hierárquica cujo nome começa com “LH.” Estes comandos são:
  DELETE FROM LIST,
  INSERT IN LIST
  SELECT LIST ITEMS BY POSITION
  SET LIST ITEM
  SET LIST ITEM FONT
  SET LIST ITEM ICON
  SET LIST ITEM PARAMETER
  SET LIST ITEM PROPERTIES
  

• Para os comandos que recuperam propriedades, esta sintaxe designa o primeiro objeto cujo nome corresponde. Estes comandos são:
  
  Count list items
  Find in list
  GET LIST ITEM
  Get list item font
  GET LIST ITEM ICON
  GET LIST ITEM PARAMETER
  GET LIST ITEM PROPERTIES
  List item parent
  List item position
  Selected list items
  

É possível modificar a aparência de uma lista hierárquica em um formulário utilizando vários comandos 4D genéricos. Deve passar a estes comandos seja o nome do objeto da lista hierárquica (utilizando o parâmetro *) ou seu nome de variável (sintaxe padrão).

Nota: no caso das listas hierárquicas, a variável do formulário contém o valor de RefLista. Se executa um comando que modifica um atributo passando-lhe a variável associada à lista hierárquica, não será possível definir a lista objetivo no caso das representações múltiplas. Portanto, só o nome do objeto permite diferenciar individualmente cada representação.

Esta é uma lista de comandos que podem ser utilizadas com as listas hierárquicas. 

OBJECT SET FONT
OBJECT SET FONT STYLE
OBJECT SET FONT SIZE
OBJECT SET COLOR
SET FILTER
OBJECT SET ENTERABLE
OBJECT SET SCROLLBAR
OBJECT SET SCROLL POSITION
OBJECT SET RGB COLORS

Lembre: exceto pelo comando OBJECT SET SCROLL POSITION, estes comandos modificam todas as representações de uma mesma lista, mesmo que apenas especifique uma lista através de seu nome de objeto.

Algumas propriedades das listas hierárquicas (por exemplo, o atributo editável ou cor) podem ser definidas de três maneiras: através da Lista de propriedades no ambiente Desenho, através de um comando do tema “Propriedades dos objetos” ou através de um comando do tema “Listas hierárquicas”.

Quando as três maneiras são utilizadas para definir propriedades de uma lista, é aplicado o seguinte ordem de prioridade:

1. Comandos do tema “Listas hierárquicas”
2. Comandos genéricos de propriedade do objeto
3. Parâmetros da Lista de propriedades

Este principio são aplicadas sem importar a ordem na qual são chamados os comandos. Se modificar uma propriedade do elemento individualmente através de um comando de lista hierárquica, o comando de propriedade do objeto equivalente não terá efeito neste elemento inclusive se é chamada posteriormente. Por exemplo, se modificar a cor de um elemento através do comando SET LIST ITEM PROPERTIES, o comando OBJECT SET COLOR não terá efeito sobre este elemento.

Geralmente pode trabalhar de duas formas com os conteúdos das listas hierárquicas: por posição ou por referência.

• Quando trabalha por posição, 4D se baseia na posição relativa dos elementos na lista mostrada na tela para identificá-los. O resultado será diferente se os elementos hierárquicos estão exibidos ou contraídos. Note que no caso de representações múltiplas, cada objeto de formulário, tem sua própia configuração de elementos contraídos/exibidos.
• Quando trabalha por referência, 4D se baseia no número único refElemento dos elementos da lista. Então cada elemento pode ser especificado individualmente, sem importar sua posição ou visualização na lista hierárquica.

Cada elemento de uma lista hierárquica tem um número de referência (refElemento) de tipo Inteiro longo. Este valor está destinado unicamente a seu próprio uso: 4D simplesmente o mantém.

Advertência: como número de referência pode utilizar todo valor de tipo Inteiro longo, exceto 0. Na verdade, para a maioria dos comandos deste tema, o valor 0 é utilizado para especificar o último elemento adicionado à lista.

Estes são alguns conselhos para utilizar números de referência:

1. Não necessita identificar cada elemento com um número único (nível principiante).

• Primeiro exemplo: você constrói por programação um sistema de abas, por exemplo, um caderno de endereços. Como o sistema retorna o número da aba selecionada, provavelmente necessite mais informação. Neste caso, não se preocupe pelos números de referência dos elementos: passe qualquer valor (exceto 0) no parâmetro refElemento. Note que para um sistema de caderno de endereços, pode pré definir uma lista A, B, ..., Z no ambiente Desenho. Igualmente pode ser criada por programação para eliminar as letras para as quais não há registros.

• Segundo exemplo: trabalhando com um banco, você constrói progressivamente uma lista de palavras chaves. Pode guardar esta lista ao final de cada sessão utilizando os comandos SAVE LIST ou LIST TO BLOB e carregá-las novamente ao início de cada nova sessão utilizando os comandos Load list ou BLOB to list. Pode mostrar esta lista em una palheta flutuante; quando o usuário clicar em uma palavra chave da lista, o elemento escolhido é inserido na área editável selecionada do processo do primeiro plano. Também pode utilizar arrastar e soltar. Em todos os casos, o importante é que você só processa o elemento selecionado (por clique ou arrastar e soltar), porque os comandos Selected list items (no caso de um clique) e DRAG AND DROP PROPERTIES retornam a posição do elemento que você deve processar. Quando utilize este valor de posição, obtém o título do elemento graças ao comando GET LIST ITEM. Aqui também, necessita identificar cada elemento individualmente; pode passar todo valor (exceto 0) no parâmetro refElemento.

2. Deve identificar parcialmente os elementos da lista (nível intermediário).

Utilize o número de referência do elemento para guardar a informação necessária quando trabalhe com o elemento; este ponto se detalha no exemplo do comando APPEND TO LIST. Neste exemplo, utilizamos os números de referência do elemento para guardar os números de registros. Entretanto, devemos poder estabelecer uma distinção entre os elementos que correspondem aos registros [Departamentos] e os que correspondem aos registros [Empregados].

3. Deve identificar individualmente os elementos da lista (nível avançado).

Você programa uma gestão elaborada de listas hierárquicas na qual deve poder identificar individualmente cada elemento em todos os níveis da lista. Uma maneira simples de implementar este funcionamento é manter um contador pessoal. Suponhamos que crie uma lista hlList utilizando o comando New list. Neste momento, você inicializa um contador vhlCounter em 1. Cada vez que você chama APPEND TO LIST ou INSERT IN LIST, é incrementado este contador (vhlCounter:=vhlCounter+1), e você passa o número do contador como número de referência do elemento. O truque consiste em não diminuir o contador quando eliminar elementos — o contador só pode crescer. Desta forma, você garante a unicidade dos números de referência dos elementos. Como estes números são de tipo Inteiro longo, pode adicionar ou inserir mais de dois bilhões de elementos em uma lista que tenha sido reinicializada... (Entretanto se está trabalhando com grandes quantidades de elementos, isto geralmente significa que deve utilizar uma tabela em lugar de uma lista.)

Nota: se utilizar Operadores de bit, igualmente pode utilizar os números de referência dos elementos para armazenar a informação que pode ser alocada em um Inteiro longo, ou seja 2 Inteiros, valores de 4 bytes ou 32 Booleanos.

Na maioria dos casos, quando utiliza listas hierárquicas em interfaces de usuário que só tratam com o elemento selecionado (o qual recebeu um clique ou foi arrastado), não necessitará utilizar os números de referência dos elementos. A utilização dos comandos Selected list items e GET LIST ITEM lhe proporcionam toda a informação necessária para a gestão do elemento selecionado atualmente. Além disso, os comandos tais como INSERT IN LIST e DELETE FROM LIST lhe permitem manipular a lista de maneira “relativa” ao elemento selecionado.

Basicamente, necessita tratar com os números de referência dos elementos quando queira acessar diretamente por programação a qualquer elemento da lista e não necessariamente ao elemento atualmente selecionado.