Propriedades específicas dos list Box

Quando se seleciona um objeto List Box do editor de formulários, a lista de propriedades mostra as seguintes propriedades específicas. Note que as propriedades especificas adicionais estão disponíveis quando seleciona uma coluna de list box (ver Propriedades específicas de colunas de list box) ou um título de coluna (ver Propriedades específicas dos títulos de list box).

Este tema inclui a propriedade Fonte de dados que é utilizada para especificar o tipo de list box:

• Selecione a opção Seleção atual se você quiser utilizar expressões, campos ou métodos cujos valores serão avaliados para cada registro da seleção atual de uma tabela.
• Selecione a opção Seleção temporária se você quiser utilizar expressões, campos ou métodos cujos valores serão avaliados para cada registro de uma seleção temporária.
• Selecione a opção arrays se você quiser utilizar elementos do array como linhas do list Box.

A opção arrays é necessária se você quiser recuperar o resultado de uma consulta SQL em um list Box (ver o parágrafo Visualização do resultado de uma petição SQL em um list box).

Este tema aparece somente para os list box de tipo seleção. Contém a propriedade tabela principal para os list Box de tipo seleção atual ou seleção temporária para os list Box de tipo seleção temporária.

• Tabela principal: permite especificar a tabela cuja seleção atual será utilizada. Esta tabela e sua seleção atual serão a referência para os campos associados com as colunas do list Box (referências de campos ou expressões que contém campos). Inclusive se algumas colunas contem campos de outras tabelas, o número de linhas mostradas será definido pela tabela principal.
  O menu associado a esta propriedade mostra todas as tabelas do banco, sem importar se o formulário está relacionado a uma tabela (formulário tabela) ou não (formulário projeto). Por padrão, a propriedade mostra a primeira tabela do banco. Para maiores informações sobre o comportamento desta propriedade, consulte o parágrafo Visualização de campos em list boxes.

• Seleção temporária: permite especificar a seleção temporária a ser utilizada. Você deve introduzir o nome de uma seleção temporária válida. A seleção temporária pode ser processo ou interprocesso. O conteúdo do listbox será baseado nesta seleção. A seleção temporária escolhida deve existir e ser validada no momento da visualização do list Box, caso contrário o list Box será mostrado vazio. Se você deixar vazia a área do nome, o list Box será mostrado vazio.
  Nota As seleções temporárias são listas ordenadas de registros. São utilizadas para conservar em memória a ordem e o registro atual de uma seleção. Para maiores informações, consulte Seleções temporárias no manual de Linguagem de 4D.

Este tema agrupa as propriedades fundamentais do objeto.

• Número de colunas: número de colunas mostradas no list box (1 por padrão). É possível modificar o número de colunas (adicionar, duplicar ou apagar uma coluna) utilizando o menu contextual (clique em uma coluna ou em um título de coluna):
  

• Número de colunas fixas: número de colunas que não podem se mover durante a execução. Este valor indica o número de colunas fixas a partir da primeira coluna do list Box. Para evitar toda movimentação de colunas, este valor deve ser igual ao número total de colunas. Esta propriedade leva em consideração as colunas invisíveis.
  Por padrão, se o modo hierárquico não estiver ativo (Opção List box hierárquico não selecionada) o valor da propriedade é 0, o que significa que todas as colunas podem se mover. Quando o modo hierárquico estiver ativo (list boxes de tipo array unicamente), esta opção sempre é pelo menos 1.

• Array de estilos (list Box de tipo array) / Estilos (list box de tipo seleção): permite aplicar um estilo de caracteres personalizado a cada linha do list Box.
• • Para os list Box de tipo array, você deve introduzir o nome de um array de tipo Inteiro longo. Cada elemento deste array corresponde a uma linha do list Box; o array deve ter o mesmo tamanho que os arrays associados às colunas. Para preencher um array (utilizando um método), utilize as constantes do tema “Texto”. Somando as constantes, você pode combinar estilos. Para aplicar o estilo definido nas propriedades do list Box a uma linha, atribua o valor -255 ao elemento do array correspondente.
    
  • Para os list Box de tipo seleção, você deve introduzir uma expressão ou uma variável (exceto para um array). A expressão ou a variável será avaliada para cada linha mostrada. Você pode utilizar o editor de fórmulas para definir uma expressão. Para fazer isto, clique no botão [...] que aparecer quando você a área é selecionada. Você pode utilizar as constantes do tema “Estilo de caracteres”.
    O exemplo a seguir utiliza um nome de variável entre EstiloEmpresa na área Estilos e no método de formulário, escreva o seguinte código:
    
     EstiloEmpresa:=Choose([Empresas]ID;Bold;Plain;Italic;Underline)

• Array de cores de fonte (list box de tipo array) / Cores de fonte (list box de tipo seleção): permite aplicar uma cor de fonte personalizada para cada fila do list box. Deve-se utilizar os valores de cores RGB. Para maiores informações consulte a descrição do comando SET RGB COLORS no manual de Linguagem de 4D.
• • Para os list boxes de tipo array, deve-se introduzir o nome de um array de tipo Inteiro largo. Cada elemento deste array corresponde a uma linha do list box; o array deve ter o mesmo tamanho que os arrays associados às colunas. É possível utilizar as constantes do tema “SET RGB COLORS”. Para aplicar a cor de fonte definida nas propriedades da list box a uma linha, passe o valor -255 para o elemento do array correspondente.
  • Para os list boxes de tipo seleção, deve-se introduzir uma expressão ou uma variável (exceto para um array). A expressão ou variável será avaliada para cada linha mostrada. É possível utilizar o editor de fórmulas para definir uma expressão. Para o fazer, clique no botão [...] que aparece ao selecionar a área. É possível utilizar as constantes do tema “SET RGB COLORS”.
    O exemplo a seguir utiliza um nome de variável: introduza CorEmpresa na área Cor de fonte e no método de formulário, escreva o seguinte código:
    
     CorEmpresa:=Choose([Empresas]ID;Default background color;Default light shadow color;Default foreground color;Default dark shadow color)

• Array de cores de fundo (list box de tipo array) / Cores de fundo (list box de tipo seleção): permite aplicar uma cor de fundo personalizada para cada linha do list box. Deve-se utilizar os valores de cores RGB. Para maiores informações, consulte a descrição do comando SET RGB COLORS no manual de Linguagem 4D.
• • Para os list boxes de tipo array, deve-se introduzir o nome de um array de tipo inteiro largo. Cada elemento deste array corresponde a uma linha do list box; o array deve ter o mesmo tamanho que os arrays associados às colunas. É possível utilizar as constantes do tema “SET RGB COLORS”. Para aplicar a cor de fundo definida nas propriedades do list box para uma linha, passe o valor -255 para o elemento do array correspondiente.
  • Para os list boxes de tipo seleção, deve-se introduzir uma expressão ou uma variável (exceto para um array). A expressão ou variável será avaliada para cada linha mostrada. É possível utilizar o editor de fórmulas para especificar uma expressão. Para o fazer, clique no botão [...] que aparece quando se seleciona a área. É possível utilizar as constantes do tema “SET RGB COLORS”.

• Array de linhas ocultas (somente list boxes de tipo array): permite ocultar uma ou várias linhas no list box. Deve-se introduzir o nome de um array de tipo Booleano. O array deve ter o mesmo número de elementos que o listbox. Cada elemento do array representa o estado mostrado/oculto da linha correspondente no list box:
• • Para ocultar a linha, passe True,
  • Para mostrar a linha, passe False 

Se não se tem definido um array ou se o array está vazio, todas as linhas do list box são visíveis. Por padrão, as linhas adicionadas são visíveis. 
Ocultar as linhas afeta unicamente a visualização do listbox. As linhas ocultas estão presentes nos arrays e podem ser manipuladas por programação. Os comandos da linguagem, especialmente  Get number of listbox rows ou GET LISTBOX CELL POSITION, não levam em conta o estado oculto/mostrado das linhas. Por exemplo, em um list box de 10 linhas onde 9 linhas estão ocultas, Get number of listbox rows devolve 10.
Desde o ponto de vista do usuário, a presença de linhas ocultas em um list box não é visível. Somente as linhas visíveis são selecionáveis (por exemplo através do comando Select All).

• Modo de seleção: permite definir o modo de seleção das linhas no list box. Há três modos disponíveis:
• • Nenhum: não pode ser selecionada nenhuma linha e não é possível introduzir dados. A seleção e gestão de dados pode ser realizada unicamente por programação. O clique ou o duplo clique na lista não tem nenhum efeito (inclusive se a opção Editável está selecionada para as colunas) porém podem ser gerados os eventos On Clicked e On Double Clicked. Neste modo, o desenvolvedor tem controle total das seleções (utilizando o conjunto ressaltado) e da entrada de dados (utilizando o comando  EDIT ITEM). Não são gerados os eventos de formulário On Selection Change e On Before Data Entry. Por outra lado, o evento  On After Edit pode ser gerado quando os dados são introduzidos pelo usuário por meio do comando  EDIT ITEM.
  • Linha única: uma só linha pode ser selecionada por vez.
  • Multilinhas: várias linhas (adjacentes ou não) utilizando atalhos padrão: Shift+clique para uma seleção contínua e Ctrl+clique (Windows) ou Comando+clique (Mac OS) para uma seleção descontínua.

Este tema reúne todas as propriedades relacionadas com a grade mostrada no list box objeto.

• Linhas horizontais: mostra ou oculta as linhas horizontais do list box (mostradas por padrão).
• Cor de linhas horizontais: define a cor das linhas horizontais no list box (cinza por padrão).
• Linhas verticais: mostra ou oculta as linhas verticais do list box (mostradas por padrão).
• Cor de linhas verticais: define a cor das linhas verticais do list box (cinza por padrão).

Este tema sólo está disponível para os list boxes cuja fonte de dados é Arrays. Suas opções configuram a visualização hierárquica do list box. Lembre que estas propriedades se modificam automaticamente quando se define a hierarquia utilizando o menu emergente do objeto list box (ver Criar e usar list box hierárquicas).

• List box hierárquico: se utiliza para especificar que o list box devem ser mostrado em forma hierárquica. 

• Variável 1 ... 10: estas opções adicionais aparecem quando a opção List box hierárquico está selecionada. Cada vez que se introduz um valor em um campo, se agrega uma nova fila. Podem ser especificadas até 10 variáveis.
  Estas variáveis definem os níveis hierárquicos que se mostrarão na primeira coluna.
  
  A primeira variável sempre corresponde ao nome da variável da primeira coluna do list box (os dois valores são linkados automaticamente). Esta primeira variável é sempre visível e editável. Por exemplo: país.
  A segunda variável é sempre visível e editável, especifica o segundo nível hierárquico. Por exemplo: regiões.
  Começando com o terceiro campo, cada variável depende da qual a precede. Por exemplo: departamentos, cidades, etc. Podem ser especificados um máximo de dez níveis hierárquicos.
  Se elimina um valor, toda a hierarquia se move um nível.
  A última variável nunca é hierárquica, mesmo que vários valores idênticos existam neste nível. Por exemplo, em referência à configuração ilustrada anteriormente, imagine que arr1 contém os valores A A A B B B, arr2 tem os valores 1 1 1 2 2 2 e arr3 os valores X X Y Y Y  Z. Neste caso, A, B, 1 e 2 poderia aparecer em forma contraída, mas não X e Y:
     + A
         + 1
             X
             X
             Y
     + B
         + 2
             Y
             Y
             Z    
  Este princípio não se aplica quando uma só variável se especifica na hierarquia : neste caso, os valores idênticos podem ser agrupados.
  Nota: se especifica uma hierarquia baseada nas primeiras colunas de um list box existente, deve então apagar ou ocultar estas colunas (exceto a primeira), do contrário, aparecerão dois vezes na list box. Se define a hierarquia através do menu emergente do editor (ver Criar e usar list box hierárquicas), as colunas desnecessárias são eliminadas automaticamente do list box.

Este tema reúne todas as propriedades relacionadas com as coordenadas, altura e largura do list box.

A propriedade Altura de filas é específica: permite definir a altura das linhas do list box (em píxels). Esta altura é aplicada igualmente aos títulos. A altura das filas é definida por padrão em função da plataforma e o tamanho da fonte.

Este tema reagrupa as propriedades relativas às cores de fundo das filas bem como com o estilo da borda.

• Cor de fundo: permite definir a cor de fundo do list box. Esta cor se utiliza para todo o objeto com exceção dos títulos (se são mostrados).

• Cor de fundo alternativa: permite definir uma cor de fundo diferente para as linhas ímpares do list box. Utilizar uma cor de fundo alternativa facilita a leitura dos arrays.
• Estilo da borda: permite definir um estilo padrão para a borda do objeto de list box.

Este tema reúne as propriedades relativas ao comportamento dinâmico do list box.

• Método do objeto (Editar...): este botão mostra o método do objeto de list box (observe que cada coluna também pode conter um método de objeto).
• Arrastável e Soltável: ativa as funções arrastar e soltar do list box, permitindo arrastar uma fila do list box para outro list box ou outro objeto 4D e vice-versa. Só as filas do list box podem ser arrastadas e soltas. Não é possível arrastar e soltar as colunas (no entanto, é possível arrastar as colunas para o interior de um mesmo list box).
  A gestão efetiva de arrastar e soltar nos list box é efetuada com a ajuda de mecanismos padrão de 4D (eventos de formulário  On Drop e On Drag Over, comandos DRAG AND DROP PROPERTIES e Drop position). 

• Filas deslocáveis (list box de tipo array unicamente): autoriza o deslocamento de linhas em execução. Esta opção está selecionada por padrão. Esta opção não está disponível para os list boxes de tipo seleção nem para os list box em modo hierárquico (opção List box hierárquico selecionada).

• Ordenável: permite ordenar os dados das colunas ao se clicar no título. Esta opção está selecionada por padrão.

Os arrays de tipo imagem (colunas) não podem ser ordenados utilizando este mecanismo.

Nos list boxes baseados nas seleções de registros, só está disponível a função de ordenação padrão:

• quando a fonte de dados é a Seleção atual,
• com as colunas associadas aos campos (de tipo alfa, numérico, data, hora ou booleano).

Nos outros casos (list boxes baseados nas seleções temporais, colunas associadas com as expressões), a função de ordenação padrão não está disponível.

A ordenação padrão do list box modifica a ordem da seleção atual no banco de dados. No entanto, os registros selecionados e o registro atual não se alteram.
A ordenação padrão sincroniza todas as colunas do list box, incluindo as colunas calculadas.