Using object arrays in columns (4D View Pro)

A partir de 4D v15, as colunas de list box podem conter arrays de objetos. Como os arrays de objetos pode conter diferentes tipos de dados, este recurso novo e poderoso permite que você misture diferentes tipos de valores nas linhas de uma única coluna, e exibir vários widgets também. Por exemplo, você pode inserir uma entrada de texto na primeira linha, uma caixa de seleção na segunda, e na terceira uma lista drop-down. Arrays de objetos também oferecem acesso a novos tipos de widgets, como botões ou seletores de cores.

A list box a seguir foi projetada usando um array objeto:

Nota sobre as licenças: a capacidade de utilizar arrays de objetos em list boxes é um primeiro passo para a próxima ferramenta "4D View pro" que vai  substituir progressivamente o plug-in 4D View. Esta funcionalidade exige uma licença 4D View válida. Para mais informação, por favor consulte o Web site de 4D.

Para atribuir um array de objetos para uma coluna de list box, basta definir o nome do array de objetos, seja na lista de propriedades (campo "Nome da variável"), ou utilizando o comando LISTBOX INSERT COLUMN da mesma forma que com toda coluna associada a um array. Na lista de propriedades,  agora você pode selecionar Objeto como "Tipo de variável" para a coluna:

As propriedades padrão relacionadas com coordenadas, tamanho e estilo estão disponíveis para colunas de tipo de objeto. Você pode definir essas propriedades usando a lista de propriedades ou programando os atributos de estilo, cor de fonte, cor de fundo e visibilidade para cada linha de coluna objeto do list box. Este tipo de coluna também pode ser ocultado.

No entanto, o tema Fonte de dados  não está disponível para as colunas do objeto dos list box. Na verdade, o conteúdo de cada célula da coluna é baseada nos atributos presentes no elemento correspondente do array de objetos. Cada elemento do array pode ser definida:

• o tipo de valor (obrigatório): texto, cor, evento, etc.
• o valor em si (opcional): utilizado para a entrada / saída.
  
• a exibição do conteúdo da célula (opcional): botão, lista, etc.
  
• Configurações adicionais (opcional): depende do tipo de valor.

Para definir essas propriedades, você deve definir os atributos apropriados no objeto (os atributos disponíveis listados abaixo). Por exemplo, você pode escrever "Olá mundo!" em uma coluna objeto usando esse código simples:

Nota: O formato de exibição e os filtros de entrada não podem ser definidos para as colunas objeto. Automaticamente dependem do tipo de valor.

Quando uma coluna de list box estiver associada a um array de objetos, a exposição, as entrada e a edição das células baseia-se no atributo valuetype presente em cada elemento do array Os valores valuetype suportados são:

• "Texto": Para valor de texto
• "Real" a um valor numérico que pode incluir separadores como um <espaço>,  <,> ou <.>
• "Integer" para valor inteiro
• "Boolean" para valor True/False
• "Color" para definir uma cor de fundo
• "Event": para exibir um botão com uma etiqueta.

4D utiliza os widgets padrão de acordo com o valor "valuetype" (ie, um "texto" é apresentado como um widget de de entrada de texto, um "boolean", como uma caixa de seleção), mas também estão disponíveis representações alternativas via opções (por exemplo, um real  também pode ser representado como um menu suspenso). A tabela a seguir mostra a exibição padrão, bem como alternativas para cada tipo de valor:

Você não pode definir formatos de exibição ou filtros de entrada para colunas objeto de list box. São definidas automaticamente de acordo com o tipo de valor. Eles estão listados na tabela a seguir:

Cada elemento do objecto matriz objecto é um objecto que pode conter um ou mais atributos que definem o conteúdo de células e exibição de dados (ver o exemplo acima).

O único atributo necessário é "valuetype" e os valores suportados são "text", "real", "inteiro" "boolean", "color" e "evento". A tabela a seguir mostra todos os atributos suportados em arrays de objetos de list box, dependendo do valor "valuetype" (qualquer outro atributo ignorado). Formatos de exibição e exemplos abaixo.

Os valores das células são armazenadas no atributo "value". Esse atributo é usado para entrada e saída. Ele também pode ser utilizado para definir os valores predefinidos quando são usadas listas (ver abaixo).

Exemplo:

Nota: o valor Null é suportado e resulta em uma célula vazia.

Quando "valueType" for "real" ou "inteiro", o objecto também aceita os atributos min e max com os valores apropriados (os valores devem ser do mesmo tipo que o valueType).

Estes atributos podem ser usados para controlar a faixa de valores de entrada. Quando uma célula é validada (quando se perde o foco), se o valor de entrada for menor que o valor min ou maior do que o valor max,  o valor é rejeitado. Neste caso, o valor anterior é realizado e uma mensagem de ajuda exibe uma explicação.

O atributo behavior oferece variações da representação padrão dos valores. Em 4D v15, uma única variação é possível:

Exemplo:

Quando um atributo "choiceList" ou "requiredList" está presente dentro do objeto, a entrada é substituída por uma lista drop-down ou um combo box, dependendo do atributo:

• Se o atributo for "choiceList", a célula é exibida como um cinbo box. Isso significa que o usuário pode selecionar ou inserir um valor.
• Se o atributo for "requiredList", então a célula é exibida como uma lista de rolagem. Isso significa que o usuário pode selecionar apenas um valor da lista.

Nota: os valores de widgets são definidos através de um array. Para atribuir uma lista 4D existente ao widget, você precisa usar os atributos "requiredListReference", "requiredListName", "choiceListReference" ou "choiceListName".

Exemplos:

• Você quer mostrar uma lista drop down com só duas opções: "Open" ou "Closed". "Closed" deve estar pré-selecionada:
  
   ARRAY TEXT($RequiredList;0)
 APPEND TO ARRAY($RequiredList;"Open")
 APPEND TO ARRAY($RequiredList;"Closed")
 C_OBJECT($ob)
 OB SET($ob;"valueType";"text")
 OB SET($ob;"value";"Closed")
 OB SET ARRAY($ob;"requiredList";$RequiredList)
  
  

• Você quer aceitar todo valor inteiro, mas mostrar um combo box para sugerir os valores mais comuns:
  
   ARRAY LONGINT($ChoiceList;0)
 APPEND TO ARRAY($ChoiceList;5)
 APPEND TO ARRAY($ChoiceList;10)
 APPEND TO ARRAY($ChoiceList;20)
 APPEND TO ARRAY($ChoiceList;50)
 APPEND TO ARRAY($ChoiceList;100)
 C_OBJECT($ob)
 OB SET($ob;"valueType";"integer")
 OB SET($ob;"value";10) //10 as default value
 OB SET ARRAY($ob;"choiceList";$ChoiceList)
  
  

Os atributos "requiredListName" e "requiredListReference" permitem que você use em uma célula  de lista box, uma definida em 4D em modo Desenho (na caixa de ferramentas)  ou por programação (usando o comando  New list). A célula é exibida como uma lista drop down. Isso significa que o usuário pode selecionar apenas um valor da lista.

Use "requiredListName" ou "requiredListReference" dependendo da origem da lista: se a lista vir da caixa de ferramentas, passe um nome; caso contrário, se a lista for definida por programação, passe uma referência. Em ambos os casos, um atributo "valor" pode ser utilizado para pré-ajustar um valor no widget.

Neste caso, o atributo "saveAs"  define se o item selecionado deve ser salvo como um "valor" ou como uma "referência".

• Se "saveAs" = "reference", então, será salva como uma referência e o "valuetype" deve ser real ou inteiro.
• Se "saveAs" = "valor", então o valor é salvo. Neste caso, o "valueType" deve ser do mesmo tipo que os valores da lista, "texto" ou "inteiro", em geral; caso contrário 4D tentará converter o valor da lista no  "valuetype" do objeto (veja exemplos abaixo).

Para mais informações sobre a opção "salvar como", ver Guardar como Valor ou Referência no manual de Desenho.

Nota: (".") Se a lista contiver elementos de texto que representem os valores reais, o separador decimal deve ser um ponto ("."), independentemente das configurações locais: "17.6" "1234.456".

Exemplos:

• Você quer mostrar uma lista drop down baseada em uma lista "colors" definida na caixa de ferramentas (contém os valores "blue", "yellow" e "green"), salve a lista como un valor e mostre "blue" como padrão:
  
  
   C_OBJECT($ob)
 OB SET($ob;"valueType";"text")
 OB SET($ob;"saveAs";"value")
 OB SET($ob;"value";"blue")
 OB SET($ob;"requiredListName";"colors")
  
  

• Você quer mostrar uma lista drop down baseada em uma lista definida por programação e salve a lista como uma referência:
  
   <>List:=New list
 APPEND TO LIST(<>List;"Paris";1)
 APPEND TO LIST(<>List;"London";2)
 APPEND TO LIST(<>List;"Berlin";3)
 APPEND TO LIST(<>List;"Madrid";4)
 C_OBJECT($ob)
 OB SET($ob;"valueType";"integer")
 OB SET($ob;"saveAs";"reference")
 OB SET($ob;"value";2) //exibe London como padrão
 OB SET($ob;"requiredListReference";<>List)
  
  

Os atributos "choiceListName" e "choiceListReference" permitem que você use em uma célula de list box, uma lista definitiva en 4D no modo Desenho (na caixa de ferramentas) ou por programação (usando o comando New list). A célula é então apresentada como uma caixa de combinação, o que significa que o usuário pode selecionar ou digitar um valor.

Use "choiceListName" ou "choiceListReference", dependendo da origem da lista, se a lista for proveniente da caixa de ferramentas, um nome é passado; caso contrário, se a lista tiver sido definido por programação, uma referência é passada. Em ambos os casos, um  atributo "valor" pode ser utilizado para pré-ajustar um valor no widget.

Nota: se deseja definir estes valores através de um array simples, é necessário utilizar o atributo "choiceList".

O atributo "saveAs" nao se usa neste caso porque os itens selecionados são salvos automaticamente como um "valor"(ver para más información).

Nota: Se a lista contiver elementos de texto que representam os valores reais, o ponto decimal deve ser um ponto ("."), independentemente dos parâmetros locais, por exemplo: "17.6" ou "1234.456".

Exemplo:

Se deseja mostrar um combo box baseado em uma lista "colors", definida na caixa de ferramentas (que contenha os valores "blue", "yellow" e "green") e mostrar "green" como padrãao:

Você pode usar atributos específicos para adicionar unidades associadas a valores de células (por exemplo: "10 cm", "20 pixels", etc.). Para definir a lista de unidades, você pode usar um dos seguintes atributos:

• "unitsList": um array contendo os elementos x usados ​​na definição das unidades disponíveis (por exemplo, "cm", "polegadas", "km", "milhas", etc.). Utilize este atributo para definir as unidades dentro do objeto.
• "unitsListReference"uma referência a uma lista de 4D que contenha as unidades disponíveis. Utilize este atributo para definir as unidades com uma lista 4D criada com o comando New list.
• "unitsListName": um nome de uma listaD  criada no modo design que contenha as unidades disponíveis. Utilize este atributo para definir as unidades com uma lista 4D criada na caixa de ferramentas.

• "UnitReference": um único valor que contém o índice (de 1 a x) do item selecionado na lista de valores "unitList", "unitsListReference" ou "unitsListName".

Exemplo: queremos definir um valor de entrada numérico seguido de duas unidades possíveis: "linhas" ou "pixels". O valor atual é "2" + "linhas". Nós usamos valores definidos diretamente no objeto (atributo "unitsList"):

Se você deseja adicionar um botão Reticências [...] a uma célula, basta passar o atributo "alternateButton" com o valor True no objeto. O botão é apresentado na célula automaticamente.

Quando os usuários clicam neste botão, um evento On Alternate Click,  é gerado, e você pode operar como você deseja (ver seção "Gestão de Eventos" para obter mais informações).

Nota:  On Alternate Clickk é o novo nome do evento On Arrow Click, rebatizado em 4D v15 para destacar o seu escopo estendido.

Exemplo:

O atributo valueType de valor "color" lhe permite mostrar uma cor ou um texto.

• Se o valor for um número, um retângulo de cor é projetado dentro da célula. Exemplo:
  
   C_OBJECT($ob4)
 OB SET($ob4;"valueType";"color")
 OB SET($ob4;"value";0x00FF0000)
  
      
• Se o valor for um texto, a seguir, é mostrado o texto (por exemplo: "valor", "Automático").

O "evento" valueType mostra um botão simples que gera um evento On Clicked quando o usuário clica. Não se podem passar ou devolver dados ou valores.

Opcionalmente, pode ser passado um atributo "label".

Varios eventos podem ser manejarados nas colunas de list box de tipo array de objetos:

• On Data Change: um evento On Data Change é acionado ao alterar um valor:
  • numa área de entrada de texto
  • numa lista drop-down
  • numa área de combo box
  • num botão de unidade (mudança de valor de x a valor x+1)
  • numa caixa de seleção (muda entre marcado/desmarcado)

• On Clicked: quando o usuário clicar em um botão instalado usando o atributo valueType "event", um  evento On Clicked é gerado. Este evento é lidado pelo programador.

• On Alternative Click: quando o usuário clicar em um botão Reticências (atributo "alternateButton"),  um evento On Alternative Click é gerado. Este evento é tratado pelo programador.

Nota: On Alternative Click é o novo nome do evento On Arrow Click que estava disponível nas versões anteriores de 4D. Este evento foi renomeado em 4D v15 já que seu escopo foi ampliado.