Sobre as caixas de listagem
Um controle de caixa de listagem contém uma lista simples a partir da qual o usuário geralmente pode selecionar um ou mais itens. As caixas de listagem oferecem flexibilidade limitada em comparação com controlos de Exibição de Lista.
Os itens da caixa de listagem podem ser representados por cadeias de texto, bitmaps ou ambos. Se a caixa de listagem não for grande o suficiente para exibir todos os itens da caixa de listagem de uma só vez, a caixa de listagem fornecerá uma barra de rolagem. O utilizador percorre os itens da caixa de listagem e aplica ou remove o estado de seleção conforme necessário. A seleção de um item de caixa de listagem altera sua aparência visual, geralmente alterando as cores do texto e do plano de fundo para aquelas especificadas pelas métricas relevantes do sistema operacional. Quando o usuário seleciona ou desmarca um item, o sistema envia uma mensagem de notificação para a janela pai da caixa de listagem.
Para um aplicativo ANSI, o sistema converte o texto em uma caixa de listagem para Unicode usando a página de código CP_ACP. Isso pode causar problemas. Por exemplo, caracteres romanos acentuados em uma caixa de listagem não-Unicode no Windows, versão japonesa sairão ilegíveis. Para corrigir isso, compile o aplicativo como Unicode ou use uma caixa de listagem desenhada pelo proprietário.
Esta seção discute os seguintes tópicos:
- Criando uma caixa de listagem
- Tipos e estilos de caixa de listagem
- Funções da caixa de lista
- mensagens de notificação de caixas de listagem
- mensagens para caixas de lista
- Processamento Padrão de Mensagens de Janela
- Owner-Drawn Caixas de listagem
- Caixas de lista arrastáveis
Criando uma caixa de listagem
A maneira mais fácil de criar uma caixa de listagem em uma caixa de diálogo é arrastá-la da Caixa de Ferramentas no Microsoft Visual Studio para seu recurso de diálogo. Para criar uma caixa de listagem dinamicamente ou para criar uma caixa de listagem em uma janela que não seja uma caixa de diálogo, use a função CreateWindowEx, especificando a classe de janela WC_LISTBOX e os estilos de caixa de listagem apropriados.
Tipos e estilos de caixa de listagem
Existem dois tipos de caixas de listagem: seleção única (o padrão) e seleção múltipla. Em uma caixa de listagem de seleção única, o usuário pode selecionar apenas um item de cada vez. Em uma caixa de listagem de seleção múltipla, o usuário pode selecionar mais de um item de cada vez. Para criar uma caixa de listagem de seleção múltipla, especifique o LBS_MULTIPLESEL ou o estilo LBS_EXTENDEDSEL.
A aparência e a operação de uma caixa de listagem são controladas pelos estilos e da caixa de listagem e pelos estilos de janela. Esses estilos indicam se a lista está classificada, organizada em várias colunas, desenhada pelo aplicativo e assim por diante. As dimensões e estilos de uma caixa de listagem geralmente são definidos em um modelo de caixa de diálogo incluído nos recursos de um aplicativo.
Observação
Para usar estilos visuais com esses controles, um aplicativo deve incluir um manifesto e deve chamar InitCommonControls no início do programa. Para obter informações sobre estilos visuais, consulte Visual Styles. Para obter informações sobre manifestos, consulte Habilitando estilos visuais.
Funções da caixa de listagem
A funçãoDlgDirList substitui o conteúdo de uma caixa de listagem com os nomes de unidades, diretórios e arquivos que correspondem a um conjunto especificado de critérios. A funçãoDlgDirSelectEx recupera a seleção atual em uma caixa de listagem que é inicializada por DlgDirList. Essas funções possibilitam que o usuário selecione uma unidade, diretório ou arquivo de uma caixa de listagem sem digitar o local e o nome do arquivo.
Além disso, a funçãoGetListBoxInfo retorna o número de itens por coluna em uma caixa de listagem especificada.
Mensagens de notificação das caixas de listagem
Quando ocorre um evento em uma caixa de listagem, a caixa de listagem envia um código de notificação, na forma de uma mensagem WM_COMMAND, para o procedimento da caixa de diálogo da janela do proprietário. Os códigos de notificação da caixa de listagem são enviados quando um usuário seleciona, clica duas vezes ou cancela um item da caixa de listagem; quando a caixa de listagem recebe ou perde o foco do teclado; e quando o sistema não consegue alocar memória suficiente para uma solicitação de caixa de listagem. Uma mensagem WM_COMMAND contém o identificador da caixa de listagem na palavra de ordem baixa do parâmetro wParam e o código de notificação na palavra de ordem alta. O parâmetro lParam contém o identificador da janela de controle.
Um procedimento de caixa de diálogo não é necessário para processar essas mensagens; o procedimento de janela padrão processa-os.
Um aplicativo deve monitorar e processar os seguintes códigos de notificação da caixa de listagem.
| Código de notificação | Descrição |
|---|---|
| LBN_DBLCLK | O usuário clica duas vezes em um item na caixa de listagem. |
| LBN_ERRSPACE | A caixa de listagem não pode alocar memória suficiente para atender a uma solicitação. |
| LBN_KILLFOCUS | A caixa de listagem perde o foco do teclado. |
| LBN_SELCANCEL | O usuário cancela a seleção de um item na caixa de listagem. |
| LBN_SELCHANGE | A seleção em uma caixa de listagem está prestes a mudar. |
| LBN_SETFOCUS | A caixa de listagem recebe o foco do teclado. |
Mensagens para Caixas de Lista
Um procedimento de caixa de diálogo pode enviar mensagens para uma caixa de listagem para adicionar, excluir, examinar e alterar itens da caixa de listagem. Por exemplo, um procedimento de caixa de diálogo pode enviar uma mensagem LB_ADDSTRING para uma caixa de listagem para adicionar um item e uma mensagem LB_GETSEL para determinar se o item está selecionado. Outras mensagens definem e recuperam informações sobre o tamanho, aparência e comportamento da caixa de listagem. Por exemplo, a mensagem LB_SETHORIZONTALEXTENT define a largura rolável de uma caixa de listagem. Um procedimento de caixa de diálogo pode enviar qualquer mensagem para uma caixa de listagem usando a função SendMessage ou a função SendDlgItemMessage .
Um item de caixa de listagem geralmente é referenciado por seu índice , um inteiro que representa a posição do item na caixa de listagem. O índice do primeiro item em uma caixa de listagem é 0, o índice do segundo item é 1 e assim por diante.
A tabela a seguir descreve como o procedimento de caixa de listagem predefinido responde a mensagens de caixa de listagem.
| Mensagem | Resposta |
|---|---|
| LB_ADDFILE | Insere um arquivo em uma caixa de listagem de diretório que é preenchida pela funçãoDlgDirList e recupera o índice da caixa de listagem do item inserido. |
| LB_ADDSTRING | Adiciona uma cadeia de caracteres a uma caixa de listagem e retorna seu índice. |
| LB_DELETESTRING | Remove uma cadeia de caracteres de uma caixa de listagem e retorna o número de cadeias de caracteres que permanecem na lista. |
| LB_DIR | Adiciona uma lista de nomes de arquivo a uma caixa de listagem e retorna o índice do último nome de arquivo adicionado. |
| LB_FINDSTRING | Retorna o índice da primeira cadeia de caracteres na caixa de listagem que começa com uma cadeia de caracteres especificada. |
| LB_FINDSTRINGEXACT | Retorna o índice da cadeia de caracteres na caixa de listagem que é igual a uma cadeia de caracteres especificada. |
| LB_GETANCHORINDEX | Retorna o índice do item que o mouse selecionou pela última vez. |
| LB_GETCARETINDEX | Retorna o índice do item que tem o retângulo de foco. |
| LB_GETCOUNT | Retorna o número de itens na caixa de listagem. |
| LB_GETCURSEL | Retorna o índice do item selecionado no momento. |
| LB_GETHORIZONTALEXTENT | Retorna a largura rolável, em pixels, de uma caixa de listagem. |
| LB_GETITEMDATA | Retorna o valor associado ao item especificado. |
| LB_GETITEMHEIGHT | Devolve a altura, em píxeis, de um item numa caixa de listagem. |
| LB_GETITEMRECT | Recupera as coordenadas do cliente do item de caixa de listagem especificado. |
| LB_GETLOCALE | Recupera a localização da caixa de listagem. A palavra de ordem alta contém o código de país/região e a palavra de ordem baixa contém o identificador de idioma. |
| LB_GETSEL | Retorna o estado de seleção de um item de caixa de lista. |
| LB_GETSELCOUNT | Retorna o número de itens selecionados em uma caixa de listagem de seleção múltipla. |
| LB_GETSELITEMS | Cria uma matriz dos índices de todos os itens selecionados em uma caixa de listagem de seleção múltipla e retorna o número total de itens selecionados. |
| LB_GETTEXT | Recupera a cadeia de caracteres associada a um item especificado e o comprimento da cadeia de caracteres. |
| LB_GETTEXTLEN | Retorna o comprimento, em caracteres, da cadeia de caracteres associada a um item especificado. |
| LB_GETTOPINDEX | Retorna o índice do primeiro item visível em uma caixa de listagem. |
| LB_INITSTORAGE | Aloca memória para o número especificado de itens e suas cadeias de caracteres associadas. |
| LB_INSERTSTRING | Insere uma cadeia de caracteres em um índice especificado em uma caixa de listagem. |
| LB_ITEMFROMPOINT | Recupera o índice baseado em zero do item mais próximo do ponto especificado em uma caixa de listagem. |
| LB_RESETCONTENT | Remove todos os itens de uma caixa de listagem. |
| LB_SELECTSTRING | Seleciona a primeira cadeia de caracteres encontrada que corresponde a um prefixo especificado. |
| LB_SELITEMRANGE | Seleciona um intervalo especificado de itens em uma caixa de listagem. |
| LB_SELITEMRANGEEX | Seleciona um intervalo especificado de itens se o índice do primeiro item no intervalo for menor que o índice do último item do intervalo. Cancela a seleção no intervalo se o índice do primeiro item for maior que o último. |
| LB_SETANCHORINDEX | Define o item que o mouse selecionou pela última vez como um item especificado. |
| LB_SETCARETINDEX | Define-se o retângulo de foco para um item especificado da lista. |
| LB_SETCOLUMNWIDTH | Define a largura, em pixels, de todas as colunas em uma caixa de listagem. |
| LB_SETCOUNT | Define o número de itens em uma caixa de listagem. |
| LB_SETCURSEL | Seleciona o item especificado de uma caixa de listagem. |
| LB_SETHORIZONTALEXTENT | Define a largura rolável, em pixels, de uma caixa de listagem. |
| LB_SETITEMDATA | Associa um valor a um item de caixa de listagem. |
| LB_SETITEMHEIGHT | Define a altura, em pixels, de um item ou itens em uma caixa de listagem. |
| LB_SETLOCALE | Define a localidade de uma caixa de listagem e retorna o identificador de localidade anterior. |
| LB_SETSEL | Seleciona um item em uma caixa de listagem de seleção múltipla. |
| LB_SETTABSTOPS | Define as paradas de tabulação como aquelas especificadas em uma matriz especificada. |
| LB_SETTOPINDEX | Rola a caixa de listagem para que o item especificado fique na parte superior do intervalo visível. |
Processamento de mensagens de janela padrão
O procedimento de janela para a classe de janela de caixa de listagem predefinida executa o processamento padrão para todas as mensagens que a caixa de listagem não processa. Quando o procedimento da caixa de listagem retorna FALSE para uma mensagem, o procedimento de janela predefinido verifica a mensagem e executa ações padrão, conforme mostrado na tabela a seguir.
| Mensagem | Ação padrão |
|---|---|
| WM_CHAR | Move a seleção para o primeiro item que começa com o caractere que o usuário digitou. Se a caixa de listagem tiver o estilo LBS_OWNERDRAW, nenhuma ação ocorrerá. Vários caracteres digitados em um curto intervalo são tratados como um grupo e o primeiro item que começa com essa série de caracteres é selecionado. |
| WM_CREATE | Cria uma caixa de listagem vazia. |
| WM_DESTROY | Destrói a caixa de listagem e libera todos os recursos que ela usa. |
| Passa a mensagem para o procedimento da caixa de diálogo ou para o processo da janela mãe. | |
| WM_ENABLE | Se o controle estiver visível, invalida o retângulo para que as cadeias de caracteres possam ser pintadas de cinza. |
| WM_ERASEBKGND | Apaga o plano de fundo de uma caixa de listagem. Se a caixa de listagem tiver o estilo LBS_OWNERDRAW, o plano de fundo não será apagado. |
| WM_GETDLGCODE | Devolve DLGC_WANTARROWS | DLGC_WANTCHARS, indicando que o procedimento de caixa de listagem padrão processa as teclas de seta e as mensagens WM_CHAR. |
| WM_GETFONT | Retorna um identificador para a fonte atual da caixa de listagem. |
| WM_HSCROLL | Rola a caixa de listagem horizontalmente. |
| WM_KEYDOWN | Processa chaves virtuais para rolagem. A chave virtual é o índice do item para o qual mover o cursor. A seleção não é alterada. |
| WM_KILLFOCUS | Desliga o cursor e destrói-o. Envia um código de notificação LBN_KILLFOCUS para o proprietário da caixa de lista. |
| WM_LBUTTONDBLCLK | Acompanha o movimento do rato na área visível da caixa de listagem. Isso permite que o usuário cancele uma seleção se o botão do mouse for liberado fora da área do cliente da caixa de listagem. |
| WM_LBUTTONDOWN | Rastreia o rato na área de exibição da caixa de listagem. Isso permite que o usuário cancele uma seleção se o botão do mouse for liberado fora da área do cliente da caixa de listagem. |
| WM_LBUTTONUP | Rastreia o mouse na área do cliente da caixa de listagem. Isso permite que o usuário cancele uma seleção se o botão do mouse for liberado fora da área do cliente da caixa de listagem. |
| WM_MOUSEMOVE | Rastreia o mouse na área de cliente da caixa de lista. Isso permite que o usuário cancele uma seleção se o botão do mouse for liberado fora da área do cliente da caixa de listagem. |
| WM_PAINT | Executa uma operação de subclassificação de pintura usando o identificador da caixa de listagem de itens para o contexto do dispositivo (DC). |
| WM_SETFOCUS | Ativa o cursor e envia um código de notificação LBN_SETFOCUS para o proprietário da list box. |
| WM_SETFONT | Define uma nova fonte para a caixa de listagem. |
| WM_SETREDRAW | Define ou limpa o sinalizador de redesenho com base no valor de wParam. |
| WM_SIZE | Redimensiona a caixa de listagem para um número integral de itens. |
| WM_VSCROLL | Desloca a lista verticalmente. |
O procedimento de caixa de listagem predefinido passa todas as outras mensagens para DefWindowProc para processamento padrão.
Owner-Drawn Caixas de Listagem
Um aplicativo pode criar uma caixa de listagem desenhada pelo proprietário para assumir a responsabilidade pela pintura de itens da lista. A janela pai ou caixa de diálogo de uma caixa de listagem desenhada pelo proprietário (seu proprietário) recebe WM_DRAWITEM mensagens quando uma parte da caixa de listagem precisa ser pintada. Uma caixa de listagem desenhada pelo proprietário pode listar informações diferentes ou além de cadeias de texto.
O proprietário de uma caixa de listagem desenhada pelo proprietário deve processar a mensagem WM_DRAWITEM. Esta mensagem é enviada sempre que uma parte da caixa de listagem deve ser redesenhada. O proprietário pode precisar processar outras mensagens, dependendo dos estilos especificados para a caixa de listagem.
Um aplicativo pode criar uma caixa de listagem desenhada pelo proprietário especificando o estilo LBS_OWNERDRAWFIXED ou LBS_OWNERDRAWVARIABLE. Se todos os itens de lista na caixa de listagem tiverem a mesma altura, como cadeias de caracteres ou ícones, um aplicativo poderá usar o estilo LBS_OWNERDRAWFIXED. Se os itens de lista forem de altura variável (por exemplo, bitmaps de tamanho diferente), um aplicativo poderá usar o estilo LBS_OWNERDRAWVARIABLE.
O proprietário de uma caixa de listagem desenhada pelo proprietário pode processar uma mensagem WM_MEASUREITEM para especificar as dimensões dos itens da lista. Se o aplicativo cria a caixa de listagem usando o estilo LBS_OWNERDRAWFIXED, o sistema envia a mensagem WM_MEASUREITEM apenas uma vez. As dimensões especificadas pelo proprietário são usadas para todos os itens da lista. Se o estilo LBS_OWNERDRAWVARIABLE for usado, o sistema enviará uma mensagem WM_MEASUREITEM para cada item de lista adicionado à caixa de listagem. O proprietário pode determinar ou definir a altura de um item de lista a qualquer momento usando as mensagens LB_GETITEMHEIGHT e LB_SETITEMHEIGHT, respectivamente.
Se as informações exibidas em uma caixa de listagem desenhada pelo proprietário incluírem texto, um aplicativo poderá controlar o texto de cada item de lista especificando o estilo LBS_HASSTRINGS. As caixas de listagem com o estilo LBS_SORT são classificadas com base neste texto. Se uma caixa de listagem estiver ordenada, mas não tiver o estilo LBS_HASSTRINGS, o proprietário deve processar a mensagem WM_COMPAREITEM.
Em uma caixa de listagem desenhada pelo proprietário, o proprietário deve manter o controle dos itens da lista que contêm informações diferentes ou adicionais ao texto. Uma maneira conveniente de fazer isso é salvar o identificador para as informações como dados do item usando a mensagem LB_SETITEMDATA. Para liberar objetos de dados associados a itens em uma caixa de listagem, o proprietário pode processar a mensagem WM_DELETEITEM.
Para obter um exemplo de uma caixa de listagem desenhada pelo proprietário, consulte Como criar uma caixa de listagem Owner-Drawn.
Arrastar caixas de lista
Uma caixa de listagem de arrastar é um tipo especial de caixa de listagem que permite ao usuário arrastar itens de uma posição para outra. Um aplicativo pode usar uma caixa de listagem de arrastar para exibir cadeias de caracteres em uma sequência específica e permitir que o usuário altere a sequência arrastando os itens para a posição.
Criando caixas de lista de arrastar
As caixas de listagem de arraste têm os mesmos estilos de janela e processam as mesmas mensagens que as caixas de listagem padrão. Para criar uma caixa de listagem de arraste, primeiro crie uma caixa de listagem padrão e, em seguida, chame a funçãoMakeDragList. Para converter uma lista de seleção numa caixa de diálogo numa lista de seleção de arrastar, pode chamar MakeDragList quando a mensagem WM_INITDIALOG for processada.
Arrastar mensagens da caixa de listagem
Uma lista de arrastar notifica a janela-mãe sobre eventos de arrasto enviando-lhe uma mensagem de arrasto. A janela pai deve processar a mensagem da lista de arraste.
A caixa de listagem de arrastar registra essa mensagem quando a função MakeDragList é chamada. Para recuperar o identificador de mensagem (valor numérico) da mensagem da lista de arrastos, chame a funçãoRegisterWindowMessagee especifique o valor DRAGLISTMSGSTRING.
O parâmetro wParam da mensagem da lista de arrasto é o identificador de controle para a caixa de listagem de arrasto. O parâmetro lParam é o endereço de uma estrutura DRAGLISTINFO, que contém o código de notificação para o evento de arrastar e outras informações. O valor de retorno da mensagem depende da notificação.
Arrastar códigos de notificação da caixa de listagem
O código de notificação da lista de arrastos, identificado pelo membro uNotification da estrutura DRAGLISTINFO incluída na mensagem da lista de arrastos, pode ser DL_BEGINDRAG, DL_DRAGGING, DL_CANCELDRAGou DL_DROPPED.
O código de notificação DL_BEGINDRAG é enviado quando o cursor está em um item de lista e o usuário clica no botão esquerdo do mouse. A janela pai pode retornar TRUE para iniciar a operação de arrastar ou FALSE para não permitir arrastar. Desta forma, a janela pai pode ativar o arrasto para alguns itens de lista e desativá-lo para outros. Você pode determinar qual item de lista está no local especificado usando a funçãoLBItemFromPt.
Se o arrasto estiver em vigor, o código de notificação DL_DRAGGING será enviado sempre que o mouse for movido ou em intervalos regulares se o mouse não estiver sendo movido. A janela pai deve primeiro determinar o item de lista sob o cursor usando LBItemFromPt e, em seguida, desenhar o ícone de inserção usando a função DrawInsert. Ao especificar TRUE para o parâmetro bAutoScroll de LBItemFromPt, você pode fazer com que a caixa de listagem role por uma linha se o cursor estiver acima ou abaixo de sua área de cliente. O valor retornado para esta notificação especifica o tipo de cursor do mouse que a caixa de listagem de arrastar deve definir.
O código de notificação DL_CANCELDRAG é enviado se o usuário cancelar uma operação de arrastar clicando no botão direito do mouse ou pressionando a tecla ESC. O código de notificação DL_DROPPED é enviado se o usuário concluir uma operação de arrastar soltando o botão esquerdo do mouse, mesmo que o cursor não esteja sobre um item de lista. A caixa de listagem de arrastar libera a captura do mouse antes de enviar qualquer notificação. O valor de retorno dessas duas notificações é ignorado. Lista de arrasto