Sobre caixas de listagem
Um controle de caixa de listagem contém uma lista simples da qual o usuário geralmente pode selecionar um ou mais itens. As caixas de listagem oferecem flexibilidade limitada em comparação com os controles de Exibição de Lista .
Os itens da caixa de listagem podem ser representados por cadeias de caracteres 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 usuário rola pelos itens da caixa de listagem e aplica ou remove o status 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 em 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 distorcidos. 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 listagem
- Mensagens de notificação de caixas de listagem
- Mensagens para caixas de listagem
- Processamento de mensagens de janela padrão
- Caixas de listagem desenhadas pelo proprietário
- Arrastar caixas de listagem
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 o recurso de diálogo. Para criar uma caixa de listagem dinamicamente ou para criar uma caixa de listagem em uma janela diferente de 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
Há 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 por vez. Em uma caixa de listagem de seleção múltipla, o usuário pode selecionar mais de um item por 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 por estilos de caixa de listagem e 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 os estilos de uma caixa de listagem são normalmente 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 Estilos visuais. Para obter informações sobre manifestos, consulte Habilitando estilos visuais.
Funções de caixa de listagem
A função DlgDirList substitui o conteúdo de uma caixa de listagem pelos nomes de unidades, diretórios e arquivos que correspondem a um conjunto especificado de critérios. A função DlgDirSelectEx recupera a seleção atual em uma caixa de listagem 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ção GetListBoxInfo retorna o número de itens por coluna em uma caixa de listagem especificada.
Mensagens de notificação de caixas de listagem
Quando um evento ocorre em uma caixa de listagem, a caixa de listagem envia um código de notificação, na forma de uma mensagem de WM_COMMAND , para o procedimento de caixa de diálogo da janela de 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 pode 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 os processa.
Um aplicativo deve monitorar e processar os seguintes códigos de notificação de 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 listagem
Um procedimento de caixa de diálogo pode enviar mensagens para uma caixa de listagem para adicionar, excluir, examinar e alterar itens de caixa de listagem. Por exemplo, um procedimento de caixa de diálogo pode enviar uma mensagem de 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, a aparência e o 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 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 às mensagens da caixa de listagem.
| Mensagem | Resposta |
|---|---|
| LB_ADDFILE | Insere um arquivo em uma caixa de listagem de diretório que é preenchida pela função DlgDirList 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 selecionado pelo mouse 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 | Retorna a altura, em pixels, de um item em uma caixa de listagem. |
| LB_GETITEMRECT | Recupera as coordenadas do cliente do item de caixa de listagem especificado. |
| LB_GETLOCALE | Recupera a localidade 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 listagem. |
| 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 da 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 do 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 o retângulo de foco como um item de caixa de listagem especificado. |
| 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 um item de caixa de listagem especificado. |
| 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 de 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 digitado pelo usuário. 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 pai. | |
| WM_ENABLE | Se o controle estiver visível, invalidará 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 | Devoluções DLGC_WANTARROWS | DLGC_WANTCHARS, indicando que o procedimento de caixa de listagem padrão processa as teclas de seta e WM_CHAR mensagens. |
| 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 acento circunflexo. A seleção não é alterada. |
| WM_KILLFOCUS | Desliga o acento circunflexo e o destrói. Envia um código de notificação LBN_KILLFOCUS para o proprietário da caixa de listagem. |
| WM_LBUTTONDBLCLK | 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_LBUTTONDOWN | 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_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 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_PAINT | Executa uma operação de pintura subclassificada usando o identificador de caixa de listagem 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 caixa de listagem. |
| 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 | Rola a caixa de listagem verticalmente. |
O procedimento de caixa de listagem predefinido passa todas as outras mensagens para DefWindowProc para processamento padrão.
Caixas de listagem desenhadas pelo proprietário
Um aplicativo pode criar uma caixa de listagem desenhada pelo proprietário para assumir a responsabilidade pela pintura de itens de lista. A janela pai ou a 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 adicionais a cadeias de caracteres de texto.
O proprietário de uma caixa de listagem desenhada pelo proprietário deve processar a mensagem WM_DRAWITEM. Essa 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 tiverem 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 de WM_MEASUREITEM para especificar as dimensões dos itens da lista. Se o aplicativo criar a caixa de listagem usando o estilo LBS_OWNERDRAWFIXED, o sistema enviará a mensagem de 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 de 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 for classificada, mas não for do estilo LBS_HASSTRINGS , o proprietário deverá processar a mensagem WM_COMPAREITEM .
Em uma caixa de listagem desenhada pelo proprietário, o proprietário deve controlar os itens da lista que contêm informações diferentes ou adicionais ao texto. Uma maneira conveniente de fazer isso é salvar o identificador nas informações como dados de 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 desenhada pelo proprietário.
Arrastar caixas de listagem
Uma caixa de listagem 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 listagem de arrastar
As caixas de listagem de arrastar 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ção MakeDragList. Para converter uma caixa de listagem em uma caixa de diálogo em uma caixa de listagem de arraste, você pode chamar MakeDragList quando a mensagem WM_INITDIALOG for processada.
Arrastar mensagens da caixa de listagem
Uma caixa de listagem de arrastar notifica a janela pai de eventos de arrastar enviando-lhe uma mensagem de lista de arraste. A janela pai deve processar a mensagem da lista de arraste.
A caixa de listagem arrastar registra essa mensagem quando a função MakeDragList é chamada. Para recuperar o identificador da mensagem (valor numérico) da mensagem da lista de arraste, chame a função RegisterWindowMessage e especifique o valor DRAGLISTMSGSTRING.
O parâmetro wParam da mensagem da lista de arrastar é o identificador de controle para a caixa de listagem de arraste. O parâmetro lParam é o endereço de uma estrutura DRAGLISTINFO , que contém o código de notificação para o evento drag 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 arraste, que é identificado pelo membro uNotification da estrutura DRAGLISTINFO incluída com a mensagem da lista de arraste, pode ser DL_BEGINDRAG, DL_DRAGGING, DL_CANCELDRAG ou 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 o arrasto. Dessa forma, a janela pai pode habilitar o arrastar para alguns itens de lista e desabilitá-lo para outros. Você pode determinar qual item de lista está no local especificado usando a função LBItemFromPt.
Se o arrastar 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. Especificando 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 essa 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 com o 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 liberando o botão esquerdo do mouse, mesmo que o cursor não esteja sobre um item de lista. A caixa de listagem arrastar libera a captura do mouse antes de enviar qualquer notificação. O valor de retorno dessas duas notificações é ignorado. Lista de arraste