TfrImageComboBox: Uma lista suspensa com imagens e legendas de texto no FastReport VCL

Uma interface visual economiza tempo do usuário: se ao lado do texto de uma opção aparece um ícone compreensível — a bandeira de um país, o logotipo de um sistema de pagamento, um indicador colorido de status — a escolha do item desejado leva segundos, e não tentativas de decifrar linhas secas. É justamente para esses cenários que ao conjunto de componentes FastEditors VCL, que faz parte do FastReport VCL Ultimate foi adicionado um novo controle — o TfrImageComboBox.

TfrImageComboBox — um editor com lista suspensa, em que cada item combina um valor-chave, uma imagem do TImageList e uma legenda textual. Ele não tem um análogo direto na paleta padrão de componentes. O componente suporta alinhamento horizontal das imagens e várias opções de deslocamento do texto na horizontal e na vertical — tanto nos itens da lista quanto no campo do editor.

Neste artigo examinaremos em detalhes as propriedades e os eventos do componente, mostraremos os cenários típicos de seu uso na interface do usuário e daremos um exemplo passo a passo com o qual você pode começar a trabalhar já hoje.

Recursos do componente

O componente ImageComboBox está disponível na IDE na paleta do FastEditors VCL e destina-se à seleção de imagens com legendas textuais em uma lista suspensa e à exibição subsequente delas no campo do editor.

Principais recursos do TfrImageComboBox:

• seleção de um item em uma lista suspensa com imagem e legenda e exibição da opção escolhida no campo do editor;
• uma coleção de itens da lista, em que cada item contém um valor-chave, o índice de imagem do TImageList vinculado e uma legenda para ele;
• alinhamento horizontal das imagens e opções flexíveis de deslocamento do texto na horizontal e na vertical — tanto na lista quanto no campo do editor;
• busca e filtragem da lista suspensa pelas legendas textuais dos itens;
• aparência personalizável separadamente para o campo do editor e separadamente para a lista;
• suporte integrado ao FastGrid: o componente pode funcionar diretamente nas células da tabela.

Vejamos as principais propriedades que distinguem esse componente dos outros editores do conjunto FastEditors VCL.

Propriedades do componente

Propriedades responsáveis pela seleção do item da lista

Value — o valor-chave atual do item selecionado da lista. Você pode gravar aqui um valor do tipo Variant e, se o componente encontrar esse valor na coleção de itens, exibirá automaticamente a imagem e a legenda correspondentes no campo do editor. Se o ImageComboBox é usado dentro da célula de um componente FastGrid, o valor dessa célula é automaticamente atribuído ao Value.

ItemIndex — o índice do item selecionado da lista suspensa. Se o valor de Value não corresponde a nenhum valor-chave dos itens da lista, essa propriedade é igual a -1.

Selected — a propriedade que contém o item selecionado da lista do tipo TfrImageComboBoxItem.

Propriedades responsáveis pelo comportamento da lista suspensa

Properties.AutoDropDown — define a possibilidade de mostrar automaticamente a lista suspensa quando o usuário começa a digitar texto no campo do editor.

Properties.DropDownCount — o número máximo de linhas exibidas na lista suspensa. Se esse valor for igual a 0, o componente tentará exibir quantos itens da lista couberem na tela do monitor.

Properties.ShowDropdownWindow — define se é permitida a exibição da lista suspensa de itens.

Properties.IncrementalFiltering — define se a busca e a filtragem pelas legendas textuais dos itens da lista estão habilitadas.

Propriedades responsáveis pela exibição padrão

Essas propriedades definem o que o componente mostrará se o valor de Value não corresponder a nenhum dos itens da lista:

• Properties.DefaultCaption — define a legenda textual que o componente mostrará por padrão caso o Value não corresponda a nenhum dos itens da lista.
• Properties.DefaultImageIndex — define o índice da imagem no componente TImageList vinculado. O componente mostrará essa imagem por padrão caso o Value não corresponda a nenhum dos itens da lista.

Propriedades responsáveis pela aparência

Properties.Layout — um conjunto de propriedades que controlam o alinhamento do texto e da imagem no campo do editor.

Properties.DropdownItemLayout — um conjunto de propriedades que controlam o alinhamento do texto e da imagem nos itens da lista suspensa.

Properties.DropDownWidth — a largura da lista suspensa. Se for igual a 0, a lista suspensa tem a mesma largura que o próprio componente TfrImageComboBox.

Properties.ImageMargin — a margem que regula a posição da imagem no campo do editor e na lista suspensa.

Properties.ItemHeight — a altura do item da lista. Com o valor 0, a altura é calculada automaticamente. Mas se for preciso desenhar o item da lista manualmente usando o evento Properties.OnCustomDrawItem, é conveniente atribuir a essa propriedade um valor diferente de 0.

Propriedades responsáveis pelos dados

Properties.ItemImages — o componente ImageList que contém as imagens para a coleção de itens da lista suspensa. Se essa propriedade for igual a nil, as imagens não serão exibidas, mas a possibilidade de exibir o texto será mantida.

Properties.Items — a coleção de itens da lista suspensa. Cada item tem as seguintes propriedades:

• Caption — a legenda textual ou a descrição da imagem;
• ImageIndex — o índice da imagem em Properties.ItemImages;
• Tag — uma propriedade adicional de reserva do tipo Integer;
• Value — o valor-chave do tipo Variant que é gravado na propriedade Value do componente quando esse item da lista é selecionado.

Eventos

Properties.OnDropDown — o evento disparado quando a lista de itens aparece.

Properties.OnCloseUp — o evento disparado quando a lista de itens é fechada.

Properties.OnCustomDrawItem — o evento para desenhar os itens da lista manualmente. Por exemplo:

procedure TForm1.frImageComboBox2PropertiesCustomDrawItem(Sender:
  TfrImageComboBoxCustomProperties; ACanvas: TfrCustomCanvas;
  AItemViewInfo: TfrImageComboBoxItemViewInfo; var DefaultDraw: Boolean);
var
  LText: string;
  LTextRect: TRect;
begin
  DefaultDraw := False;
  LText := 'Item ' + Sender.Items[AItemViewInfo.SourceItemIndex].Caption;
  LTextRect := AItemViewInfo.ItemRect;
  ACanvas.FillRect(LTextRect, clWhite);
  ACanvas.DrawFocusRect(LTextRect);
  ACanvas.DrawText(LTextRect, LText);
end;

Essas propriedades permitem configurar o estilo visual de exibição e o comportamento separadamente para o campo do editor e para a lista suspensa:

Na lista suspensa é possível buscar e filtrar as imagens pelo conteúdo das legendas correspondentes: basta começar a digitar texto no campo do editor, e a lista mostrará apenas os itens coincidentes.

Onde aplicar o componente: cenários típicos

O TfrImageComboBox é especialmente útil onde a escolha em uma lista se beneficia de uma imagem visual junto ao texto. Eis os elementos típicos da interface do usuário em que o componente se mostra excelente:

• Seleção de status ou prioridade — «Novo / Em andamento / Fechado», «Baixo / Médio / Alto» com ícones coloridos. Um clássico para rastreadores de tarefas e CRM.
• Seleção de país ou região — bandeira + nome. Conveniente em formulários de endereço, perfis de usuários e configurações de entrega.
• Seleção de moeda — símbolo ou bandeira + código (USD, EUR). Em projetos financeiros e contábeis.
• Seleção de tipo de arquivo ou documento — ícone de Word/Excel/PDF + descrição. Em módulos de fluxo de documentos e upload de anexos.
• Seleção de categoria de produto ou serviço — ícone da categoria + nome. Em catálogos, tabelas de preços e controle de estoque.
• Seleção de forma de pagamento ou entrega — logotipo do sistema de pagamento ou da transportadora + legenda. Na finalização do pedido.
• Seleção de idioma ou localidade — bandeira + idioma. Nas configurações do aplicativo.
• Seleção de papel do usuário — ícone do papel ou das permissões + nome. Em painéis de administração.
• Seleção do estado de equipamento ou sensor — «Normal / Alerta / Falha» com indicadores coloridos. Em sistemas SCADA e de monitoramento.
• Seleção do tipo de comunicação ou contato — ícones de telefone, e-mail, mensageiro. Nos cartões de clientes.

Como começar a usar o componente rapidamente

Para conectar o TfrImageComboBox ao projeto bastam alguns passos:

1. Encontre o TfrImageComboBox na paleta de componentes do FastEditors VCL e coloque-o no formulário. Se você precisa incorporar o TfrImageComboBox nas células do FastGrid, em vez disso escolha o tipo «ImageComboBox» na lista suspensa Properties da coluna desejada.
2. Coloque no formulário um componente padrão TImageList.
3. Preencha o TImageList com imagens.
4. Atribua à propriedade TfrImageComboBox.Properties.ItemImages o componente TImageList por meio da lista suspensa no Inspetor de Objetos.
5. Preencha a coleção TfrImageComboBox.Properties.Items por meio da caixa de diálogo de edição da propriedade ou no código. Por exemplo:

procedure TForm1.FormCreate(Sender: TObject);
var
  I: Integer;
  LItem: TfrImageComboBoxItem;
begin
  frImageComboBox1.BeginUpdate;
  try
    for I := 0 to 9 do
    begin
      LItem := frImageComboBox1.Properties.Items.Add;
      LItem.Caption := 'Item ' + IntToStr(I);
      LItem.ImageIndex := I;
      LItem.Value := I;
    end;
  finally
    frImageComboBox1.EndUpdate;
  end;
end;

E é isso — o componente está pronto para uso.

Conclusão

O TfrImageComboBox transforma a escolha comum em uma lista em um elemento de interface visual e conveniente. As imagens ao lado das legendas ficam mais vantajosas do que as linhas do TComboBox padrão, e a filtragem da lista suspensa pelo texto torna a busca da opção desejada rápida e natural.

Some a isso a configuração flexível da aparência do campo do editor e da lista, os eventos para desenhar os itens manualmente e o suporte integrado ao FastGrid — e você terá uma ferramenta completa para interfaces modernas de aplicativos comerciais: CRM, rastreadores de tarefas, catálogos e sistemas de monitoramento.

Se o seu projeto precisa de uma seleção de opções elegante e moderna com ícones e legendas — experimente o TfrImageComboBox do conjunto FastEditors VCL. Para começar, basta colocar o componente no formulário, conectar o TImageList e preencher a coleção Items, como mostrado no exemplo acima.