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 permitem representar os dados em forma de colunas e de filas selecionáveis e propõem muitas funções de interface tais como a possibilidade de introduzir valores, ordenar colunas, mostrar uma hierarquia, definir cores alternadas, 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 o Manual de Desenho 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 LISTBOX INSERT ROWS 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:

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,
• Os títulos das colunas (pode ser exibida ou ocultada, são exibidas por padrão)
• Ao pé das colunas (pode mostrar ou ocultar, esconder, por padrão)

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. Note que por padrão, os mesmos nomes são usados para objetos e suas variáveis associadas, exceto para os pés (por padrão as variáveis estão vazias para os pés, 4D usa as variáveis dinâmicas).
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 os objetos de tipo list boxes:

Nota: 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

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.
Note que a fim de você poder gerenciar a visibilidade desses objetos utilizando o comando OBJECT SET VISIBLE eles devem ter sido exibidos na listbox no nível do editor de formulários (as opções mostrar título e/ou mostrar rodapé devem ser selecionadas para o objeto).

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.

Para uma célula é editável caixa de listagem, tanto das seguintes condições devem ser atendidas:

• A coluna da célula deve ser definida como Editável (caso contrário, as células da coluna não será editável).
• No evento do formulário On Before Data Entry, $0 não retorna -1.
  Quando o cursor atinge a célula, o evento On Before Data Entry é gerado no método de coluna. Se, no contexto deste evento, $0 é definido como -1, a célula é considerada como não editável. Se o evento é gerado após pressionar Tab ou Shift+Tab, o foco vai para a célula seguinte ou anterior. Se não vale $0 no vale -1 (por padrão é $0 es 0), a célula é editável e passa modo de edição.

Imagine por exemplo uma caixa de listagem que contém dois arrays, data e tipo de texto. A data é editável matriz, mas a matriz é em texto editável se a data não passou. 

Este é o método da coluna arrText:

Nota: a partir de 4D v13, o evento On Before Data Entry é retornado antes do On Getting Focus.

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 intermédio de um conjunto chamado por padrão $ListboxSetX (X começa em 0 e se incrementa em função do número de list box no formulário), pode ser modificado se for necessário. 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.

Há vários modos diferentes de configurar as cores de fundo, cores de fonte e estilos de fonte para os list boxes:

• a nível das propriedades do objeto list box,
• a nível das propriedades da coluna,
• utilizando arrays ou métodos para o list box e/ou para cada coluna,
• a nível do texto de cada célula (se texto multi estilo).

Quando uma mesma propriedade se define em mais de um nível, a ordem de prioridade é o seguinte:

Por exemplo, se define um estilo de caracteres nas propriedades do list box e outro utilizando um array de estilo para a coluna, será levado em conta este último.

Dado um list box cujas filas tem uma cor alterno cinza/cinza claro, definido nas propriedades do list box. Um array de cor de fundo também foi definido para o list box com o propósito de mudar a cor das filas nas que pelo menos um valor é negativo por laranja:

A continuação, vamos a colorear os valores negativos de cor laranja escuro. Para isso , se define um array de cor de fundo para cada coluna, por exemplo ample <>_BgndColor_1, <>_BgndColor_2 and <>_BgndColor_3.  Os valores destes arrays serão prioritários sobre os definidos nas propriedades do list box, assim como as do array geral de cor de fundo:

Pode obter o mesmo resultado utilizando os novos comandos LISTBOX SET ROW FONT STYLE e LISTBOX SET ROW COLOR. Tem a vantagem de que lhe permite evitar ter que pré definir os arrays de
estilo/cor das colunas: são criados dinamicamente pelos comandos.

Para cada atributo (estilo, cor e cor de fundo), a herança se aplica quando se utiliza o valor por padrão:

• para os atributos das células: valores de atributos de linhas
• para os atributos das linhas: valores dos atributos das colunas
• para os atributos das colunas: valores dos atributos do listbox

Desta forma, se quiser que um objeto herde o valor do atributo de um nível superior, passe -255 (valor por padrão) ao comando de definição ou diretamente no elemento do array de estilo/cor correspondente.

Dado um listbox que contém um estilo de fonte padrão com cores alternativas: 

Pode realizar as modificações seguintes:

• mudar o fundo da fila 2 a vermelho com a propriedade Array cores de fundo do objeto list box,
• mudar o estilo da fila 4 a itálica pela propriedade Array de estilos do objeto list box,
• dois elementos da coluna 5 são passados a negrito pela propriedade Array de estilos do objeto coluna 5,
• os elementos da fila 2 das colunas 1 e 2 mudam para fundo azul utilizando a propriedade Array cores de fundo dos objetos coluna 1 e 2:

• passe a constante Listbox inherited  nos elementos 2 de os arrays de fundo das colunas 1 e 2: a continuação, herdam a cor de fundo vermelho da linha.
• passe a constante Listbox inherited  nos elementos 3 e 4 dos arrays de estilo da coluna 5: então herdam o estilo padrão, exceto o elemento 4, que muda a itálica como se define no array de estilo do list box
• passe a constante Listbox inherited  no elemento 4 do array de estilo do list box com o propósito de suprimir o estilo itálica.
• passe a constante Listbox inherited  no elemento 2 do array de cores de fundo do list box com o propósito de restaurar a cor alterna original do list box.

É possível por diretamente o resultado de uma petição SQL em um list box de tipo array. Esta função oferece um meio rápido de visualizar o resultado de petições SQL. Só podem ser utilizadas as petições de tipo SELECT. Este mecanismo não pode ser utilizado com uma base SQL externa.

Isso funciona de acordo com os seguintes princípios:

• Crie o list box que receberá os resultados da petição. A fonte de dados do lsit box deve ser Arrays.
• Execute a petição SQL de tipo SELECT e atribua o resultado à variável associada ao list box. É possível utilizar as palavras chaves  Begin SQL/End SQL (ver o manual de Linguagem 4D).
• Quando o conteúdo de um list box provém de uma petição SQL, as colunas não podem ser ordenadas ou modificadas pelo usuário.
• Cada nova execução de uma petição SELECT com o list box a reiniciação das colunas (não é possível preencher o mesmo list box progressivamente utilizando várias petições SELECT).
• Recomenda-se dar ao list box o mesmo número de colunas que as que terá no resultado de petição SQL. Se o número de colunas do list box é inferior ao necessário para a petição  SELECT, as colunas são adicionadas automaticamente. Se o número de colunas do list box é superior ao necessário para a petição SELECT,as colunas desnecessárias são ocultas.

Nota: As colunas adicionadas automaticamente estão relacionadas com as Variáveis Dinâmicas de tipo array. Esses arrays temporários permanecem enquanto o formulário existir. Uma variável temporária é criada do mesmo modo para cada título. Quando se chama o comando GET LISTBOX ARRAYS, o parâmetro arrVarCols contém ponteiros (apontadores) aos arrays temporários e o parâmetro arrVarTitulos contém os ponteiros às variáveis de títulos temporários. Se uma coluna adicionada é, por exemplo, a quinta coluna, seu nome é sql_column5 e seu título é sql_header5.

• Em modo interpretado, os arrays existentes utilizados pelo list box podem ser redigitados automaticamente de acordo com os dados enviados pela petição SQL.