Lista hierárquica

As listas hierárquicas são objetos de formulário que podem ser utilizados para apresentar dados como listas com um ou mais níveis que podem ser expandidos ou recolhidos.

Quando apropriado, o ícone de expansão/colapso é automaticamente apresentado à esquerda do item. As listas hierárquicas suportam um número ilimitado de subníveis.

Fonte de dados de lista hierárquica

O conteúdo de um objeto formulário lista hierárquica pode ser inicializado de uma das seguintes formas:

• Associar uma lista de opções existente ao objeto. A lista de opções deve ter sido definida no editor de listas no modo Desenho.
• Atribuir diretamente uma referência de lista hierárquica à variável ou expressão associada ao objeto formulário.

Em ambos os casos, você gerencia uma lista hierárquica em tempo de execução através de sua referência ListRef, usando os comandos de lista hierárquica na linguagem 4D.

RefList e nome de objeto

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

O objeto de linguagem é referenciado por um ID interno único do tipo Longint, designado por ListRef na manual da Linguagem 4D. This ID is returned by the commands that can be used to create lists: New list, Copy list, Load list, BLOB to list. Existe apenas uma instância do objeto língua na memória e qualquer modificação efetuada neste objeto é imediatamente transferida para todos os locais onde é utilizado.

O objeto de formulário não é necessariamente único: podem existir várias representações da mesma lista hierárquica na mesma forma ou em formas diferentes. Tal como acontece com outros objetos de formulário, especifica-se o objeto na linguagem utilizando a sintaxe (*; "ListName", etc.).

Você conecta o "objeto de linguagem" lista hierárquica com o "objeto de formulário" lista hierárquica pelo intermediário da variável que contém o valor ListRef. Você conecta o "objeto de linguagem" lista hierárquica com o "objeto de formulário" lista hierárquica pelo intermediário da variável que contém o valor ListRef.

$mylist:=New list

Cada representação da lista tem suas próprias características específicas e compartilha características comuns com todas as outras representações. As características a seguir são específicas de cada representação da lista:

• A selecção,
• O estado expandido/recolhido dos seus itens,
• A posição do cursor de rolagem.

As outras características (fonte, tamanho da fonte, estilo, controle de entrada, cor, conteúdo da lista, ícones, etc.) são comuns a todas as representações e não podem ser modificados separadamente. Consequently, when you use commands based on the expanded/collapsed configuration or the current item, for example Count list items (when the final * parameter is not passed), it is important to be able to specify the representation to be used without any ambiguity.

Você deve usar o ID ListRef com comandos de linguagem quando quiser especificar a lista hierárquica encontrada na memória. Por outro lado, se você quiser especificar a representação de um objeto lista hierárquica no nível do formulário, deverá usar o nome do objeto (tipo string) no comando, por meio da sintaxe padrão (*; "ListName", etc.).

No caso de comandos que definem propriedades, a sintaxe baseada no nome do objeto não significa que somente o objeto de formulário especificado será modificado pelo comando, mas sim que a ação do comando será baseada no estado desse objeto. As características comuns das listas hierárquicas são sempre modificadas em todas as suas representações. Por exemplo, se executa:

SET LIST ITEM FONT(*;"mylist1";*;thefont)

... está a indicar que pretende modificar o tipo de letra do item da lista hierárquica associado ao objeto de formulário mylist1. O comando considerará o item atual do objeto mylist1 para especificar o item a ser modificado, mas essa modificação será transferida para todas as representações da lista em todos os processos.

Suporte da @

As with other object property management commands, it is possible to use the “@” character in the ListName parameter. Regra geral, esta sintaxe é utilizada para designar um conjunto de objetos no formulário. No entanto, no contexto dos comandos de lista hierárquica, isso não se aplica em todos os casos. Essa sintaxe tem dois efeitos diferentes, dependendo do comando:

• Para comandos que definem propriedades, essa sintaxe designa todos os objetos cujo nome corresponde (comportamento padrão). Por exemplo, o parâmetro "LH@" designa todos os objetos do tipo lista hierárquica cujo nome começa com "LH."

  • 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 comandos que recuperam propriedades, essa sintaxe designa o primeiro objeto cujo nome corresponde:

  • 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

Comandos genéricos utilizáveis com listas hierárquicas

É possível modificar a aparência de uma lista hierárquica de objetos usando vários comandos 4D genéricos. Você pode passar para esses comandos o nome do objeto da lista hierárquica (usando o parâmetro *) ou o nome da variável (contendo o valor ListRef):

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

Reminder: Except OBJECT SET SCROLL POSITION, these commands modify all the representations of the same list, even if you only specify a list via its object name.

Prioridade dos comandos de propriedade

Certas propriedades das listas hierárquicas (por exemplo, o atributo Entrável ou a cor) podem ser definidas de diferentes maneiras: nas propriedades do formulário, por um comando do tema "Propriedades dos objetos" ou através de um comando do tema "Listas hierárquicas". Quando todos esses três meios são usados para definir as propriedades da lista, a seguinte ordem de prioridade é aplicada:

1. Comandos do tema "Listas hierárquicas"
2. Comandos genéricos de propriedades de objectos
3. Propriedade formulário

Esse princípio é aplicado independentemente da ordem em que os comandos são chamados. Se uma propriedade de item for modificada individualmente através de um comando de lista hierárquica, o comando de propriedade de objeto equivalente não afetar esse item, mesmo que seja chamado posteriormente. For example, if the color of an item is modified via the SET LIST ITEM PROPERTIES command, the OBJECT SET COLOR command will have no effect on this item.

Gerenciamento dos itens por posição ou referência

Normalmente, você pode trabalhar de duas maneiras com o conteúdo das listas hierárquicas: por posição ou por referência.

• Quando se trabalha por posição, 4D se baseia na posição em relação aos itens da lista exibida na tela para identificá-los. O resultado diferirá conforme o fato de determinados itens hierárquicos serem expandidos ou recolhidos. Observe que, no caso de várias representações, cada objeto de formulário tem sua própria configuração de itens expandidos/colapsados.
• Quando você trabalha por referência, 4D se baseia no número de identificação itemRef dos itens da lista. Assim, cada item pode ser especificado individualmente, independentemente de sua posição ou de sua exibição na lista hierárquica.

Utilização de números de referência dos items (itemRef)

Cada item de uma lista hierárquica tem um número de referência (itemRef) do tipo Longint. Este valor é apenas destinado ao seu próprio uso: 4D simplesmente o mantém.

Aviso: você pode usar qualquer tipo de valor Longint como número de referência, exceto 0. De fato, na maioria dos comandos desse tema, o valor 0 é usado para especificar o último item adicionado à lista.

Seguem-se algumas sugestões para a utilização de números de referência:

1. Não é necessário identificar cada item com um número exclusivo (nível iniciante).

   • Primeiro exemplo: você cria um sistema de guias programando, por exemplo, um catálogo de endereços. Como o sistema retorna o número da guia selecionada, você provavelmente não precisará de mais informações do que isso. Nesse caso, não se preocupe com os números de referência do item: passe qualquer valor (exceto 0) no parâmetro itemRef. Observe que, para um sistema de catálogo de endereços, você pode predefinir uma lista A, B, ..., Z no modo Desenho. Também é possível criá-lo por programação, de modo a eliminar quaisquer letras para as quais não haja registros.
   • Segundo exemplo: ao trabalhar com um banco de dados, você constrói progressivamente uma lista de palavras-chave. You can save this list at the end of each session by using the SAVE LIST or LIST TO BLOB commands and reload it at the beginning of each new session using the Load list or BLOB to list commands. Você pode exibir essa lista em uma paleta flutuante; quando cada usuário clica em uma palavra-chave da lista, o item escolhido é inserido na área de entrada selecionada no processo em primeiro plano. The important thing is that you only process the item selected, because the Selected list items command returns the position of the item that you must process. When using this position value, you obtain the title of the item by means of the GET LIST ITEM command. Aqui, novamente, não é necessário identificar cada item individualmente; você pode passar qualquer valor (exceto 0) no parâmetro itemRef.

2. Você precisa identificar parcialmente os itens da lista (nível intermediário).
   You use the item reference number to store information needed when you must work with the item; this point is detailed in the example of the APPEND TO LIST command. Neste exemplo, usamos os números de referência do item para armazenar os números de registro. No entanto, devemos conseguir estabelecer uma distinção entre os itens que correspondem aos registros do [Departament] e aqueles que correspondem aos registros dos [Employees].

3. Você precisa identificar todos os itens da lista individualmente (nível atacante).
   Você programa um gerenciamento elaborado de listas hierárquicas em que é absolutamente necessário poder identificar cada item individualmente em cada nível da lista. Uma forma simples de o fazer é manter um contador pessoal. Suppose that you create a hlList list using the APPEND TO LIST command. En esta etapa, se inicializa un contador vhlCounter en 1. Each time you call APPEND TO LIST or INSERT IN LIST, you increment this counter (vhlCounter:=vhlCounter+1), and you pass the counter number as the item reference number. O truque consiste em nunca diminuir o contador quando você exclui itens - o contador só pode aumentar. Dessa forma, você garante a exclusividade dos números de referência do item. Como esses números são do tipo Longint, é possível adicionar ou inserir mais de dois bilhões de itens em uma lista que foi reinicializada... (no entanto, se estiver trabalhando com um número tão grande de itens, isso geralmente significa que você deve usar uma tabela em vez de uma lista).

Se você usar operadores bit a bit, também poderá usar números de referência de itens para armazenar informações que podem ser colocadas em um Longint, ou seja, 2 inteiros, valores de 4 bytes ou, mais uma vez, 32 boolianos.

Quando é que são necessários números de referência únicos?

Geralmente, ao usar listas hierárquicas para fins de interface usuário e ao lidar apenas com o item selecionado (aquele sendo clicado ou arrastado), não será necessário usar números de referência de item. Using Selected list items and GET LIST ITEM you have all you need to deal with the currently selected item. In addition, commands such as INSERT IN LIST and DELETE FROM LIST allow you to manipulate the list “relatively” with respect to the selected item.

Basicamente, você precisa lidar com números de referência de itens quando quiser acessar diretamente qualquer item da lista de forma programática e não necessariamente o item selecionado no momento na lista.

Elemento modificável

Pode controlar se os itens da lista hierárquica podem ser modificados pelo usuário, utilizando o atalho Alt+click(Windows) / Option+click (macOS), ou fazendo um clique longo no texto do item.

• Independentemente da fonte de dados da lista hierárquica, você pode controlar todo o objeto com a propriedade Entrável.

• Além disso, se você preencher a lista hierárquica usando uma lista criada no editor de Listas, poderá controlar se um item em uma lista hierárquica é modificável usando a opção Elemento modificável no editor de Listas. Para obter mais informações, consulte Definir as propriedades das listas.

Propriedades compatíveis

Bold - Border Line Style - Bottom - Choice List - Class - Draggable - Droppable - Enterable - Entry Filter - Fill Color - Focusable - Font - Font Color - Font Size - Height - Help Tip - Hide focus rectangle - Horizontal Scroll Bar - Horizontal Sizing - Italic - Left - Multi-selectable - Object Name - Right - Top - Type - Underline - Vertical Scroll Bar - Vertical Sizing - Variable or Expression - Visibility - Width

Supported Events

On After Edit - On Begin Drag Over - On Clicked - On Collapse - On Data Change - On Delete Action - On Double Clicked - On Drag Over - On Drop - On Expand - On Getting focus - On Header - On Load - On Losing focus - On Mouse Enter - On Mouse Leave - On Mouse Move - On Printing Break - On Printing Detail - On Printing Footer - On Selection Change - On Unload - On Validate