Gestão de objetos List Box

Os comandos de este tema estão dedicados à gestão de objetos de formulário de tipo List box.

Os list boxes são comparáveis com as . Um list box oferece todas as funções das áreas de rolagem agrupadas, principalmente a possibilidade de representar os dados em forma de colunas e de filas selecionáveis. Entretanto, as list box fazem mais que isto, incluindo a possibilidade de introduzir valores, ordenar colunas, definir cores alternos, etc.

É possível configurar completamente um list box no editor de formulários de 4D e igualmente pode controlá-lo por programação. Para mais informação sobre a criação e definição de List boxes no editor de formulários como também sobre seu uso, consulte da documentação 4D.

A programação de objetos de tipo List box é efetuada da mesma forma que para os outros objetos de formulário em lista de 4D. Entretanto, devem ser seguidas as regras específicas, descritas nesta seção.

Uma list box pode conter uma ou mais colunas e pode estar associado a arrays 4D ou a uma seleção de registros. No caso de list boxes de tipo seleção, as colunas são associadas a campos ou expressões.

Não é possível ter ambos tipos de fontes de dados (arrays e seleções) combinados no mesmo list box. A definição da fonte de dados é realizada no momento da criação da list box no editor de formulários, através da Lista de propriedades. Então já não é possível modificá-lo por programação.

Neste tipo de list box, cada coluna está associada a um array 4D de uma dimensão; todos os tipos de array podem ser utilizados, exceto os arrays de ponteiros. O formato de saída de cada coluna pode ser definido no editor de formulários ou utilizando o comando OBJECT SET FORMAT.

Utilizando a linguagem, os valores das colunas (entrada e visualização de dados) são administradas utilizando os comandos de alto nível do tema List box (tais como INSERT LISTBOX ROW o INSERT LISTBOX COLUMN) assim como os comandos de manipulação de arrays.

Por exemplo, para inicializar o conteúdo de uma coluna, pode utilizar a seguinte instrução:

Igualmente pode utilizar uma lista:

Nota: quando um objeto List box contém várias colunas, cada array relacionado deve ter o mesmo tamanho (mesmo número de elementos) que os outros, do contrário só serão mostrados o número de elementos do array menor.

Advertência: quando um list box contém várias colunas de diferentes tamanhos, só é mostrada o número de elementos do array menor (coluna). Deve ter certeza que cada array tenha o mesmo número de elementos que os outros. Igualmente, se uma coluna da list box está vazia (isto ocorre quando o array associado não foi declarado corretamente ou dimensionado utilizando a linguagem), a list box não mostra nada.

Neste tipo de list box, cada coluna pode estar associada com um campo ou uma expressão. O conteúdo de cada fila é avaliado de acordo com uma seleção de registros: a seleção atual de uma tabela ou uma seleção temporal.

Quando a seleção atual é a fonte de dados, todas as modificações realizadas no banco são reportadas automaticamente no list box e vice-versa. A seleção atual é então sempre a mesma em ambas localizações. Note que os comandos LISTBOX INSERT ROW e LISTBOX DELETE ROW não podem ser utilizados com list boxes de tipo seleção.

Pode associar uma coluna de list box a uma expressão. A expressão pode estar baseada em um ou mais campos (por exemplo [Empregados]Sobrenome+" "+[Empregados]Nome) ou simplesmente em uma fórmula (por exemplo String(Milliseconds)). A expressão também pede  um método de projeto, uma variável ou um elemento de array.

O comando LISTBOX SET TABLE SOURCE pode ser utilizado para modificar a tabela associada com a list box por programação.

Um objeto List box está composto de três tipos de elementos separados:

• o objeto mesmo,
• as colunas,
• e os títulos das colunas.

Estes elementos podem ser selecionadas individualmente no editor de formulários. Cada um tem seu próprio nome de objeto e nome de variável e pode ser manejado  separadamente.

Por padrão, as colunas são chamadas Columna1 a X e os títulos Título1 a X no formulário, independentemente dos objetos list box.
Cada tipo de elemento contém características próprias e características compartidas com os outros elementos. Por exemplo, a fonte dos caracteres pode ser atribuída globalmente ao objeto list box ou separadamente às colunas e aos títulos. Por outro lado, as propriedades de entrada só podem ser definidas para as colunas.
Estas regras que aplicam aos comandos do tema “Propriedades dos objetos” podem ser utilizados com os list box. Dependendo de sua funcionalidade, cada comando pode ser utilizada com o list box, as colunas ou títulos de colunas. Para definir o tipo de elemento no qual quer trabalhar, simplesmente passe o nome ou a variável associada a ele.
A seguinte tabela detalha o alcance de cada comando do tema “Propriedades dos objetos” que pode ser utilizada com list boxes:

Notas:

• Todos os comandos do tema “List Box” aplicam unicamente aos objetos List box, a exceção do comando LISTBOX SET COLUMN WIDTH (aplica a objeto, coluna e cabeçalho) e o comando LISTBOX Get column width (aplica a coluna e título unicamente).
• Com list boxes de tipo array, é possível especificar o estilo, cor de fonte, cor de fundo e visibilidade para cada linha separadamente. Isto é administrado através de arrays associados com o list box na lista de propriedades. Pode recuperar os nomes destes arrays por programação utilizando o comando LISTBOX GET ARRAYS.

É possível adiconar um método de objeto ao objeto list box ou a cada coluna da list box. Os métodos de objeto são chamados na seguinte ordem:
1. Método de objeto de cada coluna
2. Método de objeto do list box
O método de objeto da coluna recebe os eventos que ocorrem em seu título.

Quando o comando OBJECT SET VISIBLE é utilizado com um cabeçalho, é utilizado em todos os cabeçalhos del objeto List box, sem importar o título definido no comando. Por exemplo, a instrução OBJECT SET VISIBLE(*;"título3";False) ocultará todos os títulos do objeto List box ao qual pertence titulo3 e não unicamente este cabeçalho.

A função OBJECT Get pointer utilizada com a constante Object with focus ou Object current (antigas funções Focus object e Self) pode ser utilizada no método de objeto de um list box ou de uma coluna de list box.
Devolvem um ponteiro ao list box, a coluna(1) list box ou a variável do cabeçalho em função do tipo de evento de formulário. A seguinte tabela detalha este funcionamento:

(*) Quando o foco se modifica dentro de um list box, se devolve a coluna um ponteiro. Quando o foco se modifica a nivel do formulário, se devolve um ponteiro ao list box. No contexto de um método de objeto de coluna, se devolve um ponteiro a coluna.

(**) Não executado no contexto de um método de objeto de coluna.

(1) Quando se devolve um ponteiro a uma coluna, o objeto ao qual se aponta depende do tipo do list box. Com um array de tipo list box, a função OBJECT Get pointer devolve um ponteiro ao array). O mecanismo de ponteiros de 4D permite conhecer o número do elemento do array modificado. Por exemplo, supondo que o usuário modificou a quinta fila da coluna col2:

No caso de um list box de tipo seleção, a função OBJECT Get pointer devolve:

• Para uma coluna associada a um campo, um ponteiro ao campo associado,
• Para uma coluna associada a uma variável, um ponteiro a variável,
• Para uma coluna associada a uma expressão, o ponteiro Nil.

O comando OBJECT SET SCROLL POSITION (tema “Propriedades dos objetos") pode ser utilizada com um objeto de tipo list box. Esse comando permite deslocar as linhas da list box para mostrar a primeira linha selecionada ou uma linha específica.

O comando EDIT ITEM (tema “Gestão de entrada”) lhe permite passar a modo edição uma célula de um objeto list box.

Quando se aplica a um listbox em modo seleção, o comando REDRAW (tema "Interface do usuário") dispara a atualização dos dados mostrados na list box.

O comando Displayed line number (tema "Seleções") funciona no contexto do evento de formulário On Display Detail para um objeto list box.

Eventos de formulário específicos estão destinados a facilitar a gestão do list box, em particular com o relacionado às operações de arrastar e soltar e ordenar. Para maior informação, consulte a descrição do comando Form event.

O administrar o arrastar e soltar de dados em list boxes é compatível pelos comandos Drop position e DRAG AND DROP PROPERTIES. Estes comandos foram adaptados especialmente para os list boxes.

Tenha cuidado em não confundir arrastar e soltar com mover filas e colunas, realizado pelos comandos LISTBOX MOVED ROW NUMBER e LISTBOX MOVED COLUMN NUMBER.

A list box administra automaticamente a ordenação padrão de colunas em caso de clique no cabeçalho. Uma ordenação padrão é uma ordenação alfanumérica de valores da coluna, de forma alternada ascendente/descendente com cada clique. Todas as colunas sempre se sincronizam automaticamente.
Pode evitar as ordenações de usuário deselecionando a propriedade “Ordenável” do list box.

Automaticamente, o list box maneja automaticamente as ordenações padrão de colunas em caso de clique no cabeçalho. Uma ordenação é uma ordenação alfanumérica dos valores da coluna, alternadamente ascendente/descendente com cada clique sucessivo. Todas as colunas sempre são sincronizadas automaticamente.
Você pode proibir ordenar ao usuário padrão deselecionando a propriedade "Ordenável" para o listbox.

Nota: a propriedade “Ordenável” afeta apenas a ordenação do usuário padrão; o comando LISTBOX SORT COLUMNS não considera esta propriedade.

O valor da variável associada ao título da coluna lhe permite administrar informação adicional: a ordenação atual da coluna (leitura) e a visualização da flecha de ordenação.

• Se a variável vale 0, a coluna não é ordenada e não é mostrada a flecha de ordenação;

• Se a variável vale 1, a coluna é ordenada de forma ascendente e se mostra a flecha de ordenação;

• Se a variável vale 2, a coluna é ordenada de forma descendente e se mostra a flecha de ordenação.

É possível fixar o valor da variável (por exemplo, Titulo2:=2) para “forçar” a visualização da flecha de ordenação. A ordenação da coluna mesma não é modificada neste caso; está nas mãos do desenvolvedor como manejá-la.

A gestão de seleções é realizada de maneira diferente para os list box de tipo array e de tipo seleção.

• List box de tipo seleção: as seleções são administradas por um conjunto chamado "Highlight Set". Este conjunto é definido nas propriedades do list box. É mantido automaticamente por 4D: se o usuário seleciona uma ou mais filas no  list box, o conjunto é atualizado imediatamente. Por outro lado, também é possível utilizar os comandos do tema "Conjuntos" com o propósito de modificar por programação a seleção da list box.

• List box de tipo array: o comando SELECT LISTBOX ROW pode ser utilizado para selecionar por programação uma ou mais filas do list box.

A variável associada ao objeto List box é utilizada para obter, fixar ou armazenar as seleções de filas do objeto.

Esta variável corresponde a um array de booleanos que é criada e mantida automaticamente por 4D. O tamanho deste array é determinado pelo tamanho do list box: contém o mesmo número de elementos que o array mais pequeno associado às colunas.

Cada elemento deste array contém True se a fila correspondente é selecionada e do contrário False. 4D atualiza os conteúdos deste array dependendo das ações do usuário. à inversa, você pode modificar o valor dos elementos deste array para modificar a seleção no list box.

Por outra parte, não é possível inserir ou apagar filas neste array; tampouco é possível digitar filas novamente.

Nota: o comando Count in Array pode ser utilizado para conhecer o número das filas selecionadas.

Por exemplo, este método permite inverter a seleção desta primeira fila do list box (tipo array):

É possível imprimir list boxes a partir de 4D v12. Estão disponíveis dos modos de impressão: modo pré-visualização, o qual pode permitir imprimir um list box como um objeto de formulário e o modo avançado, permite controlar a impressão do objeto list box mesmo dentro do formulário. Note que a aparência "Impressão" está disponível para os objetos list box no editor de formulários.

A impressão de um list box em modo pré-visualização consiste em imprimir diretamente o list box com o formulário que o contenha utilizando os comandos de impressão padrão ou o comando de menu Print. O list box é impresso como está no formulário. Este modo não permite controlar com precisão a impressão do objeto; em particular, não permite imprimir todas as linhas de um list box que contenha mais linhas do que possa mostrar.

Neste modo, a impressão dos list boxes é efetuada por programação, através do comando Print object. Portanto, só os list box presentes nos formulários projeto podem ser impressos em modo avançado. O comando LISTBOX GET PRINT INFORMATION é utilizado para controlar a impressão do objeto. 

Neste modo:

• a altura do objeto list box se reduz automaticamente quando o número de linhas a imprimir é menor que a altura original do objeto (não há linhas "vazias" impressas). Pelo contrário, a altura não aumenta automaticamente  em função do conteúdo do objeto. O tamanho do objeto efetivamente impresso pode ser obtido através do comando LISTBOX GET PRINT INFORMATION.
• O objeto list box é impresso "tal qual", em outras palavras, considerando seus parâmetros de visualização atuais: visibilidade de cabeçalhos e grades, linhas mostradas e ocultas, etc.
  Estes parâmetros também incluem a primeira linha a imprimir: se chama ao comando SCROLL LINES antes de lançar a impressão, a primeira linha impressa no list box será a designada pelo comando. 
• Um mecanismo automático facilita a impressão dos list box que contém mais linhas das que é possível mostrar: chamadas sucessivas a Print object permitem imprimir um novo conjunto de linhas cada vez. O comando LISTBOX GET PRINT INFORMATION permite controlar o estado da impressão.