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 LISTBOX INSERT 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.

Nota: os comandos LISTBOX INSERT ROWS e LISTBOX DELETE ROWS 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 #cmd id="1013"/] pode ser utilizado para modificar a tabela associada com a list box por programação.

Neste tipo de list box, cada coluna deve ser associada a uma expressão Os conteúdos de cada linha são então avaliados por elemento de coleção ou por entidade da seleção entidade

Cada elemento da coleção ou cada entidade está disponível como um objeto que pode ser acessado pelo comando This

Uma expressão coluna pode ser um método projeto, uma variável ou qualquer fórmula, acessando cada entidade ou objeto elemento coleção de This. , por exemploThis.<nomePropriedade> (ou This.value no caso de uma coleção de valores escalares). Podem ser usados LISTBOX SET COLUMN FORMULA e LISTBOX INSERT COLUMN FORMULA para modificar as colunas por programação.

Quando a data source for uma coleção, qualquer modificação feita nos valores das list box se reflete na coleção, Por outro lado, se modificações forem feitas na coleção usandoo por exemplo os vários  métodos do tema Coleções, vai precisar notificar explicitamente 4D ao reatribuir a variável coleção para si mesma, de forma que os conteúdos da list box sejam renovados. Por exemplo.

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

• o objeto mesmo,
• as colunas,
• Os cabeçalhos das colunas (pode ser exibida ou ocultada, são exibidas por padrão)
• Os rodapés 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 de 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 que uma célula de list box seja editável 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.

Para preservar consistência de dados para list boxes de tipo de seleção e seleção de entidades, qualquer registro modificado é salvo assim que a célula for validade:

• quando a célula é desativa (usuário digita tab, cliques, etc)
• quando a listbox não tiver mais o foco
• quando o formulário não tiver mais o foco

A sequência típica de eventos gerados durante a entrada de dados ou modificações está abaixo

• o objeto current item  (ver Tema Fonte de dados) contém o valor antes da modificação.
• o objeto This contém o valor modificado.

Nota: Entrada de dados em list boxes do tipo coleção tem um limite quando as expressões avaliadas sejam null. Neste caso, não é possível editar ou remover o valor null na célula.

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.

Nota: a propriedade “Ordenável” afeta apenas a ordenação do usuário padrão; o comandoLISTBOX 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, OBJECT SET FORMAT) 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 Coleção/Seleção de entidades: Seleções são gerenciadas através de propriedades de list box dedicadas: Item atual é um objeto que vai receber a entidade/elemento selecionado.  Itens selecionados é uma coleção de itens selecionados, e  Posição Item atual retorna a posição do elemento ou entidade selecionado. Para saber mais veja Tema Fonte de dados.

• List box de tipo array: o comando LISTBOX SELECT 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 (formulários de projeto e formuários de tabela são suportados). 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 OBJECT SET SCROLL POSITION  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 a constante lk inherited (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 lk 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 lk 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 lk inherited no elemento 4 do array de estilo do list box com o propósito de suprimir o estilo itálica.
• passe a constante lk 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.

Pode estabelecer as propriedades de interface "escondido", "desativado" e "selecionável" para cada linha em uma list box baseada em array.

Estas configurações podem ser gerenciadas usado o Row Control Array, que pode designar usando o comando LISTBOX SET ARRAY ou através da lista de Propriedades:

Um array de controle de linha deve ser do tipo Inteiro Longo e inclui o mesmo número de linhas que as list box. Para saber mais, veja a sessão Propriedades específicas dos list Box.

Cada elemento do array Row Control Array define o estatus da interface de sua linha correspondente no list box. Três propriedades de interfaces estão disponíveis usando constantes no tema de constante "List Box":

Para mudar o estatus da linha, precisa apenas estabelecer as constantes apropriadas ao elemento de array correspondente. Por exemplo, se não quiser que a linha  #10 seja selecionável, pode escrever:

Pode definir diversas propriedades de interface ao mesmo tempo:

Note que estabelecer as propriedades para um elemento sobrepuja qualquer outro valor para este elemento (se não for resetado). Por exemplo:

Quando a opção Hide selection highlight  for marcada (ver  Tema aparência ) , é preciso fazer as seleções de list box visíveis usando opções de interface disponíveis. Já que seleções ainda são totalmente gerenciadas por 4D, isso significa que:

• Para list boxes do tipo array,  deve analisar a variável array Booleana associada com a list box para determirnar que linhas são selecionadas ou não.
• Para list boxes do tipo seleção, precisa verificar se o registro atual (linha) pertence ao conjunto especificado na propriedade Highlight Set da list box.

Pode definir as cores de fundo específicas, cores de fonte e estilos de fonte por programação para personalizar a aparência de linhas selecionadas. Isso pode ser feito usando arrays ou expressões, dependendo do tipo de list box sendo exibida (ver seções abaixo).

Nota:Pode usar a constante lk inherited para mimetizar a aparência atual da list box (por exemplo, cor de fonte, cor de fundo, estilo de fonte, etc). Para saber mais sobre como a constante lk inherited funciona, veja a seção Herança.

Para determinar que linhas foram selecionadas, deve marcar se estão incluídas no conjunto indicado pela proriedade de list box Highlight Set:

Pode então definir a aparência de linhas selecionadas usando uma ou mais das expressões abaixo especificadas na Lista de Propriedades:

• Background Color Expression (Tema Fundo e Borda)
• Font Color Expression (Tema Texto)
• Style Expression (Tema Texto)

Nota: Lembre que expressões são automaticamente reavalidas cada vez que:

• a seleção list box muda.
• a list box obtém ou perde foco.
• a janela de formulário contendo a list box vira, ou deixa de ser, a janela mais à frente..

Quebra de linhas não podem ser ressaltadas quando a opção  Hide selection highlight estiver marcada.

Já que não é possível ter cores diferentes para cabeçalhos no mesmo nível, não há maneira de ressaltar uma quebra de linha específica por programação.

Tem que analisar a variável array Booleana associada com o list box para determinar cujas linhas são selecionadas ou não selecionadas:

Pode então definir a aparência das linhas selecionadas usando um ou mais dos arrays abaixo especificados na Lista de Propriedades:

• Row Background Color Array (Tema Fundo e Borda)
• Row Font Color Array (Tema Texto)
• Row Style Array (Tema Texto)

Nota que list box arrays usados para definir a aparência de linhas selecionadas devem ser recalculados durante o evento de formulário  On Selection Change ; entretanto, pode também modificar esses arrays baseados nos formulários abaixo:

• On Getting Focus (propriedade list box)
• On Losing Focus (propriedade list box)
• On Activate (propriedade formulário)
• On Deactivate (propriedade formulário)

...dependendo se e quando quiser visualmente representar mudanças de foco em seleções.

Se escolheu esconder o ressaltado de sistema e quer exibir seleções de list box com uma cor de fundo verde, como no exemplo:

Para um array tipo list box, precisa adicionar um método de objeto para atualizar a propriedade Row Background Array:

Neste método de objeto pode escrever:

Para um list box de tipo seleção, para produzir o mesmo efeito pode usar um método para atualizar a  Background Color Expression baseado no conjunto especificado na propriedade Highlight Set. Por exemplo:

No método UI_SetColor pode escrever:

É 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 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 LISTBOX GET 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.