ListBox no VBA: Um Guia Completo

janeiro 3, 2023janeiro 17, 2024 admin 0 comentários

Quer aprender a criar uma Listbox no VBA? Então este post é para você!

Se você estiver criando qualquer tipo de formulário no VBA, então é provável que utilize uma ListBox. Este tipo de controle é ideal para listar informações por meio de uma ou mais colunas. Acompanhe os detalhes a seguir para conhecer este controle e entender como ele funciona.

Navegue pelo tópico de seu interesse:

O que é uma Listbox?

Uma ListBox (Caixa de Listagem) é um controle muito útil. Se você estiver criando qualquer tipo de formulário no Excel ou VBA, provavelmente a usará.

A ListBox é usada para exibir uma lista de itens para que o usuário possa selecionar uma ou mais opções. Uma ListBox pode ter várias colunas e por isso é útil para tarefas como exibir vários registros.

Quando falamos de ListBox no Excel, é preciso destacar que existem três tipos:

ListBox (Controle de Formulário): Geralmente você usará essa opção caso queira inserir uma ListBox dentro de uma planilha.

ListBox (Controle de ActiveX): Uma ListBox (Controle de ActiveX) permite um design mais flexível e deve ser usada quando o trabalho simplesmente não pode ser feito com um ListBox (Controle de Formulário). Por padrão, alguns computadores possuem o ActiveX desativado, sendo necessário ser habilitado manualmente. Outro ponto importante é que o ActiveX é uma tecnologia da Microsoft e pode não ser suportada no Mac ou demais Sistemas Operacionais. Portanto, isso é algo que você também deve considerar, caso você (ou qualquer pessoa a quem forneça uma pasta de trabalho) decida usá-la em um Mac ou outro sistema operacional que não seja da Microsoft.

ListBox no VBA: Essa terceira opção de ListBox está disponível em formulários do VBA e neste post focaremos nossa atenção nela através de exemplos práticos.

Agora que você já conhece os diferentes tipos de ListBox, vamos conferir mais detalhes sobre a criação de cada um deles.

Como Criar ListBox (Controle de Formulário)

Se o seu objetivo é criar um ListBox (Controle de Formulário), então siga as etapas:

1. Acesse a guia Desenvolvedor (Caso não tenha esta guia habilitada em seu Excel, confira aqui o passo a passo).

2. Na guia Desenvolvedor, clique em Inserir > Caixa de Listagem (Controle de Formulário).

3. Desenhe um retângulo na planilha do Excel para criar uma caixa de listagem, conforme mostrado na imagem a seguir.

4. Selecione a caixa de listagem criada, acesse a guia Desenvolvedor e selecione Propriedades. A janela “Formatar Controle” será aberta.

5. Na guia Controle, em Intervalo de entrada, selecione o intervalo de células que contém os dados nos quais você deseja preencher a ListBox. No campo Vínculo da célula, selecione a célula na qual deseja vincular o item que foi selecionado na ListBox.

6. Para finalizar, clique em OK. Pronto! Observe que sua ListBox já está pronta para ser utilizada.

Como Criar ListBox (Controle de ActiveX)

Se o seu objetivo é criar uma ListBox (Controle de ActiveX), então siga as etapas:

1. Acesse a guia Desenvolvedor e clique em Inserir > Caixa de Listagem (Controle Active X).

2. Desenhe um retângulo na planilha do Excel para criar uma caixa de listagem, conforme mostrado na imagem a seguir.

3. Selecione a caixa de listagem criada, acesse a Desenvolvedor e selecione Propriedades. A janela “Propriedades” será aberta.

4. Na janela de propriedades, digite meses na propriedade ListFillRange. “Meses” é o intervalo nomeado para os meses do ano. (Crie o intervalo nomeado conforme a sua necessidade).

6. Em seguida, na propriedade LinkedCell, escolha qual será a célula de vínculo. Essa célula irá exibir o resultado do item que foi selecionado na sua Listbox. No exemplo da imagem abaixo, selecionamos a célula J3 (adapte o exemplo para atender a sua necessidade).

5. Acesse novamente a guia Desenvolvedor e desabilite o Modo Design, clicando no respectivo botão. Pronto! Sua Listbox está finalizada conforme exemplo abaixo.

Como Criar uma Listbox em um Userform no VBA?

Se o seu objetivo é criar uma ListBox através do painel do VBA, então siga as etapas abaixo:

1. Acesse a guia Desenvolvedor > Visual Basic (ou use o atalho Alt+F11).

2. Dentro da janela do VBA, no menu Inserir, clique em Userform.

3. Na caixa de ferramentas, arraste o controle de ListBox no Userform e posicione-o conforme sua preferência.

4. Com a Listbox já adicionada no formulário, dê duplo clique no formulário e selecione o evento Initialize, conforme mostrado na imagem abaixo:

5. Use o seguinte código de exemplo para adicionar dados ao seu ListBox (Observação: Adapte as informação do exemplo conforme a sua necessidade).

6. Pressione F5 para executar o código. Observe que você terá um formulário com ListBox e alguns dados sendo listados.

Exemplos de códigos para ListBox no VBA

Agora que você já sabe como criar uma ListBox no VBA, vamos conferir alguns exemplos de códigos que você poderá utilizar com este controle de formulário.

Exemplo 1: Adicionando uma única coluna

Você pode usar o método “AddItem” quando precisar preencher uma ListBox de coluna única conforme exemplo abaixo:

Private Sub UserForm_Initialize()
ListBox1.AddItem "Item 1"
ListBox1.AddItem "Item 2"
ListBox1.AddItem "Item 3"
ListBox1.AddItem "Item 4"
End Sub

Importante: Se você tentar adicionar itens a uma caixa de listagem que tenha uma propriedade RowSource preenchida, receberá um erro de “permissão negada”.

Exemplo 2: Mostrar item selecionado na ListBox no VBA

Se você precisa saber qual item está selecionado em uma ListBox e exibi-lo em uma caixa de mensagem, então utilize uma das duas opções abaixo:

'Opção 1
MsgBox (ListBox1.Value)

'Opção 2
MsgBox (ListBox1.List(ListBox1.ListIndex))

No exemplo abaixo, aplicamos o código acima dentro de um Botão.

Exemplo 3: Inserindo Múltiplas Colunas

Uma ListBox pode conter várias colunas usando a propriedade ColumnCount.
Você pode usar o método “AddItem” combinado com a propriedade List quando tiver várias colunas.
Todas as entradas da lista começam com um número de linha de 0 e um número de coluna de 0, ou seja, List(0,0) = “text0”

Se você deseja adicionar itens a uma caixa de listagem de várias colunas, você precisa usar “AddItem” para adicionar uma nova linha e, em seguida, “List” ou “Column” para adicionar os itens específicos após a primeira coluna. Veja o exemplo abaixo:

Dim NLinha As Integer
ListBox1.ColumnCount = 3
For NLinha = 1 To 25
ListBox1.AddItem
ListBox1.List(NLinha - 1, 0) = "Item " & NLinha
ListBox1.List(NLinha - 1, 1) = "Item " & NLinha
ListBox1.List(NLinha - 1, 2) = "Item " & NLinha
Next NLinha

Observe que 0s números de coluna e linha em uma ListBox começam em 0 por padrão e não em 1. Deste modo, a única maneira de obter os itens selecionados em uma ListBox de seleção múltipla é percorrer toda a lista conforme exemplo abaixo:

Dim NLinha As Integer
For NLinha = 0 To ListBox1.ListCount - 1
If (ListBox1.Selected(NLinha) = True) Then
MsgBox (ListBox1.List(NLinha))
End If
Next NLinha

Exemplo 4: Inserindo dados no ListBox usando Arrays

Se seus dados forem armazenados em uma matriz unidimensional, você poderá atribuir a matriz diretamente usando a propriedade List. Veja o exemplo abaixo:

Dim NLinha As Integer
Dim vDataArray1(100)
For NLinha = 0 To 100
vDataArray1(NLinha) = NLinha
Next NLinha
ListBox1.List = vDataArray1

Por outro lado, se seus dados forem armazenados em uma matriz bidimensional, você poderá atribuir a matriz diretamente usando a propriedade List conforme exemplo abaixo:

ListBox1.ColumnCount = 2
ListBox1.ColumnWidths = "50,50"
Dim NLinha As Integer
Dim DadosArray2(1 To 50, 1 To 2)
For NLinha = 1 To 50
DadosArray2(NLinha, 1) = NLinha
DadosArray2(NLinha, 2) = NLinha & "b"
Next NLinha
ListBox1.List = DadosArray2

Confira também: Arrays no VBA Excel: O que são e como usar?

Exemplo 5: Remover itens selecionados na ListBox

Se você deseja remover da ListBox um item atualmente selecionado, então use o seguinte código:

ListBox1.RemoveItem (ListBox1.ListIndex)

Exemplo 6: Limpar Listbox no VBA

Para limpar os itens da caixa de listagem, use o seguinte código:

 UserForm1.ListBox1.Clear

Exemplo 7: ListBox com mais de 10 Colunas

Se você deseja ter mais de 10 colunas em sua ListBox, deve usar a propriedade List conforme exemplo abaixo onde são inseridas 13 colunas na ListBox.

Dim MeuArray() As String
Dim Linha As Integer
Dim Coluna As Integer
ReDim MeuArray(1 To 5, 1 To 13)
Linha = 1
While (Linha < 6)
ListBox1.AddItem
For Coluna = 1 To 13
MeuArray(Linha, Coluna) = "Col" & Coluna
Next Coluna
Linha = Linha + 1
Wend
ListBox1.ColumnHeads = True
ListBox1.ColumnCount = 13
ListBox1.ColumnWidths = "40;40;40;40;40;40;40;40;40;40;40;40;40"
ListBox1.List = MeuArray

Exemplo 8: ListBox com Múltipla seleção

Por padrão, apenas um único item pode ser selecionado em uma ListBox. No entanto, você pode alterar essa funcionalidade através da janela de propriedade (propriedade MultiSelect) ou através do código abaixo:

ListBox1.MultiSelect = fmMultiSelectMulti

Exemplo 9: Preenchendo ListBox com intervalo de células

Os itens em uma ListBox podem ser preenchidos utilizando um intervalo de células do Excel através da propriedade RowSource.
Certifique-se de incluir o nome da planilha, caso contrário, a planilha ativa será usada.

ListBox1.RowSource = "Planilha1!A1:A12"

Importante: Se você preencher uma ListBox usando o método RowSource, não poderá preencher a mesma lista usando o método “List”. Do mesmo modo, se você preencher uma caixa de listagem usando o método RowSource, não poderá usar o método RemoveItem.

Exemplo 10: Inserir Cabeçalho na ListBox no VBA

Você só pode exibir cabeçalhos de coluna quando utiliza a propriedade RowSource, não quando usa uma matriz ou adiciona itens individualmente.
Para exibir os cabeçalhos das colunas, defina a propriedade ColumnHeads como True.

Além disso, não inclua os títulos das colunas na planilha no intervalo definido para RowSource. A linha diretamente acima da primeira linha de RowSource será usada automaticamente.

Exemplo 11: Inserir Itens exclusivos na ListBox

Você deve adicionar todos os itens a uma coleção garantindo que apenas itens exclusivos sejam adicionados e, em seguida, adicione todos os itens da coleção à ListBox. Veja o exemplo abaixo:

Dim Celula As Range
Dim ItemSemDuplicidade As New Collection
Dim Item As Variant

On Error Resume Next
For Each Celula In Range("A1:A12")
ItemSemDuplicidade.Add Celula.Value, CStr(Celula.Value)
Next Celula
For Each Item In ItemSemDuplicidade
UserForm1.ListBox1.AddItem Item
Next Item

Exemplo 12: Verificar se ListBox está selecionada

Se você precisa verificar se há algum item selecionado na ListBox, então utilize o código abaixo:

 If UserForm1.ListBox1.ListIndex > 0 Then
   MsgBox "Há um item selecionado"
Else
   MsgBox "Não há nenhum item selecionado"
End If

Exemplo 13: Obter total de itens em uma ListBox no VBA

Para obter a contagem total de itens em uma caixa de listagem, utilize o código abaixo. No exemplo abaixo, ListBox1 é o nome da caixa de listagem e ListCount é a propriedade que realiza a contagem de itens.

MsgBox "O total de itens na ListBox é " & UserForm1.ListBox1.ListCount

Exemplo 14: Obter o total de itens selecionados

Se você estiver usando a propriedade MultiSelect como fmMultiSelectExtended, então você poderá selecionar mais de um item em sua ListBox. Deste modo, se você precisa obter a quantidade de itens selecionados na ListBox, então basta usar o código abaixo:

For i = 0 To ListBox1.ListCount - 1
If ListBox1.Selected(i) = True Then
Numselec = Numselec + 1
End If
Next i
MsgBox Numselec & " iten(s) selecionado(s)"

Propriedades de uma ListBox no VBA

As propriedades de uma Listbox podem ser consultadas e alteradas através da janela de propriedades do objeto. Você poderá acessá-la, clicando com o botão direito do mouse sobre a ListBox e selecionando a opção “Propriedades”. Confira abaixo a lista e o significado de cada propriedade:

BackColor: Especifica a cor de fundo do objeto.
BorderColor: Especifica a cor da borda de um objeto.
BorderStyle: Especifica o tipo de borda usado.
BoundColumn: Identifica a fonte de dados em um ListBox de várias colunas.
ColumnCount: Especifica o número de colunas a serem exibidas em uma caixa de listagem.
ColumnHeads: Exibe uma única linha de cabeçalhos de coluna para caixas de listagem.
ColumnWidths: Especifica a largura de cada coluna em uma caixa de listagem de várias colunas.
ControlSource: Identifica o local de dados usado para definir ou armazenar a propriedade Value de um controle. A propriedade ControlSource aceita intervalos de planilha do Microsoft Excel.
ControlTipText: Especifica o texto que aparece quando o usuário mantém brevemente o ponteiro do mouse sobre um controle sem clicar.
Enabled: Especifica se um controle pode receber o foco e responder a eventos gerados pelo usuário.
Font: Define as características do texto usado por um controle.
ForeColor: Especifica a cor de primeiro plano de um objeto
Height: Especifica a altura do objeto.
IMEMode: Especifica o modo de tempo de execução padrão do Input Method Editor (IME) para um controle. Esta propriedade aplica-se apenas a aplicativos escritos para o Extremo Oriente e é ignorada em outros aplicativos.
IntegralHeight: Indica se um ListBox ou TextBox exibe linhas completas de texto em uma lista ou linhas parciais.
Left: Indica o posicionamento (à esquerda) do ListBox no Userform.
ListIndex: Especifica qual item está selecionado na caixa de listagem. Este é um número inteiro de 0 ao número total de itens menos 1.
ListStyle: Especifica a aparência visual da lista em um ListBox, frmListStylePlain ou fmListStyleOption. Se você tiver uma caixa de listagem que tenha seu estilo de lista definido como opção, para remover a barra de rolagem horizontal, altere a propriedade columnwidths para a largura – 16.
Locked: Especifica se um controle pode ser editado ou não.
MatchEntry: Retorna ou define um valor indicando como um ListBox pesquisa sua lista conforme o usuário digita, fmMatchEntryFirstLetter, fmMatchEntryComplete ou fmMatchEntryNone
MouseIcon: Atribui um ícone personalizado ao objeto.
MousePointer: Especifica o tipo de ponteiro exibido quando o usuário posiciona o mouse sobre um determinado objeto. Pode ser qualquer uma das constantes fmMousePointer.
MultiSelect: Indica se o objeto permite múltiplas seleções.
RowSource: Vincula o controle a um intervalo de células em uma planilha.
SpecialEffect: Especifica a aparência visual de um objeto. Pode ser qualquer uma das constantes fmSpecialEffect.
Specifies the visual appearance of an object. Can be any of the fmSpecialEffect constants.
TabIndex: Define a ordem de tabulação para controles individuais
TabStop: Controla se um usuário pode pressionar Tab para mover o foco para um controle específico.
Tag: Armazena informações adicionais sobre cada controle no UserForm.
Text: Altera a linha selecionada em um ListBox.
TextAlign: Especifica como o texto é alinhado em um controle. Pode ser qualquer uma das constantes fmTextAlign.
TextColumn: Identifica a coluna em um ListBox para armazenar na propriedade Text quando o usuário seleciona uma linha.
TopIndex: Retorna ou define um Long que representa o índice do item da lista exibido na posição mais alta da lista
Value: Especifica o estado ou o conteúdo de um determinado controle. Este é o valor em BoundColumn.
Width: Especifica a largura do objeto.

Métodos de uma Listbox no VBA

Um método é uma ação que um objeto pode executar. Confira abaixo a lista de métodos disponíveis para o objeto ListBox no VBA:

AddItem: Adiciona um novo item à lista de valores exibidos pelo controle de caixa de listagem especificado.
Clear: Limpa o objeto.
Move: Move o objeto especificado para as coordenadas especificadas pelos valores de argumento.
RemoveItem: Remove um item da lista de valores exibida pelo controle caixa de listagem especificado.
SetFocus: Move o foco para o formulário especificado, para o controle especificado no formulário ativo ou para o campo especificado na folha de dados ativa.
ZOrder: Obtém a posição da ordem z do ListBox.

Eventos de uma Listbox no VBA

Um evento é uma ação reconhecida por um objeto, como clicar com o mouse ou pressionar uma tecla e, para a qual é possível escrever um código para responder. Os eventos podem ocorrer como resultado de uma ação do usuário ou de um código do programa, ou podem ser disparados pelo sistema. Confira abaixo a lista de eventos disponíveis para uma ListBox no VBA:

AfterUpdate: Ocorre sempre que a seleção da caixa de listagem é alterada. Isso não é acionado, a menos que a caixa de listagem tenha sua seleção múltipla definida como única.
BeforeDragOver: Ocorre quando uma operação de arrastar e soltar está em andamento.
BeforeDropOrPaste: Ocorre quando o usuário está prestes a soltar ou colar dados em um objeto.
BeforeUpdate: Ocorre antes de os dados alterados em um controle ou registro serem atualizados.
Change: Ocorre quando há alterações na Listbox.
Click: Ocorre quando um usuário pressiona e depois libera um botão do mouse sobre um objeto.
DblClick: Ocorre quando o usuário pressiona e libera o botão esquerdo do mouse duas vezes sobre um objeto, dentro do limite de tempo de clique duplo do sistema.
Enter: Ocorre antes de um controle recebe de fato o foco de um controle no mesmo formulário ou relatório.
Exit: Ocorre logo antes de um controle perde o foco para outro controle no mesmo formulário ou relatório.
KeyDown: Ocorre quando o usuário pressiona uma tecla enquanto um formulário ou controle tenha o foco.
KeyPress: Ocorre quando o usuário pressiona e libera uma tecla ou combinação de teclas que corresponde a um código ANSI enquanto um formulário ou controle tem o foco.
KeyUp: Ocorre quando o usuário libera uma tecla enquanto um formulário ou controle tenha o foco.
MouseDown: Ocorre quando o usuário pressiona um botão do mouse.
MouseMove: Ocorre quando o usuário move o mouse.
MouseUp: Ocorre quando o usuário libera um botão do mouse.

Para conferir mais detalhes e exemplos de uso das Propriedades, Métodos e Eventos de uma ListBox, acesse o Portal da Microsoft.

Confira também as seguintes dicas de Excel:

E então o que achou do post sobre ListBox no VBA? Caso tenha ficado com alguma dúvida ou queira acrescentar alguma informação extra, basta deixar o seu comentário abaixo!