Classe `CListBox`

Artigo
07/05/2024

Fornece a funcionalidade de uma caixa de listagem do Windows.

Sintaxe

class CListBox : public CWnd

Membros

Construtores públicos

Nome	Descrição
`CListBox::CListBox`	Constrói um objeto `CListBox`.

Métodos públicos

Nome	Descrição
`CListBox::AddString`	Adiciona uma cadeia de caracteres a uma caixa de listagem.
`CListBox::CharToItem`	Substitua para fornecer tratamento personalizado `WM_CHAR` para caixas de listagem de desenho de proprietário que não têm cadeias de caracteres.
`CListBox::CompareItem`	Chamado pela estrutura para determinar a posição de um novo item em uma caixa de listagem de desenho de proprietário classificada.
`CListBox::Create`	Cria a caixa de listagem do Windows e a anexa ao objeto `CListBox`.
`CListBox::DeleteItem`	Chamado pela estrutura quando o usuário exclui um item de uma caixa de listagem de desenho do proprietário.
`CListBox::DeleteString`	Exclui uma cadeia de caracteres de uma caixa de listagem.
`CListBox::Dir`	Adiciona nomes de arquivo, unidades ou ambos do diretório atual a uma caixa de listagem.
`CListBox::DrawItem`	Chamado pela estrutura quando um aspecto visual de uma caixa de listagem de desenho do proprietário muda.
`CListBox::FindString`	Pesquisa uma cadeia de caracteres em uma caixa de listagem.
`CListBox::FindStringExact`	Localiza a primeira cadeia de caracteres de caixa de listagem que corresponde a uma cadeia de caracteres especificada.
`CListBox::GetAnchorIndex`	Recupera o índice baseado em zero do item de âncora atual em uma caixa de listagem.
`CListBox::GetCaretIndex`	Determina o índice do item que tem o retângulo de foco em uma caixa de listagem de seleção múltipla.
`CListBox::GetCount`	Retorna o número de cadeias de caracteres em uma caixa de listagem.
`CListBox::GetCurSel`	Retorna o índice baseado em zero da cadeia de caracteres selecionada no momento em uma caixa de listagem.
`CListBox::GetHorizontalExtent`	Retorna a largura em pixels que uma caixa de listagem pode ser rolada horizontalmente.
`CListBox::GetItemData`	Retorna um valor associado ao item de caixa de listagem.
`CListBox::GetItemDataPtr`	Retorna um ponteiro para um item de caixa de listagem.
`CListBox::GetItemHeight`	Determina a altura dos itens em uma caixa de listagem.
`CListBox::GetItemRect`	Retorna o retângulo delimitador do item de caixa de listagem como ele é exibido no momento.
`CListBox::GetListBoxInfo`	Recupera o número de itens por coluna.
`CListBox::GetLocale`	Recupera a ID de localidade para uma caixa de listagem.
`CListBox::GetSel`	Retorna o estado de seleção de um item de caixa de listagem.
`CListBox::GetSelCount`	Retorna o número de cadeias de caracteres selecionadas atualmente em uma caixa de listagem de seleção múltipla.
`CListBox::GetSelItems`	Retorna os índices das cadeias de caracteres selecionadas atualmente em uma caixa de listagem.
`CListBox::GetText`	Copia um item de caixa de listagem para um buffer.
`CListBox::GetTextLen`	Retorna o comprimento em bytes de um item de caixa de lista.
`CListBox::GetTopIndex`	Retorna o índice da primeira cadeia de caracteres visível em uma caixa de listagem.
`CListBox::InitStorage`	Pré-aloca blocos de memória para itens de caixa de listagem e cadeias de caracteres.
`CListBox::InsertString`	Insere uma cadeia de caracteres em um local específico em uma caixa de listagem.
`CListBox::ItemFromPoint`	Retorna o índice do item de caixa de listagem mais próximo de um ponto.
`CListBox::MeasureItem`	Chamado pela estrutura quando uma caixa de listagem de desenho do proprietário é criada para determinar dimensões de caixa de listagem.
`CListBox::ResetContent`	Limpa todas as entradas de uma caixa de listagem.
`CListBox::SelectString`	Pesquisa e seleciona uma cadeia de caracteres em uma caixa de listagem de seleção única.
`CListBox::SelItemRange`	Seleciona ou desmarca um intervalo de cadeias de caracteres em uma caixa de listagem de seleção múltipla.
`CListBox::SetAnchorIndex`	Define a âncora em uma caixa de listagem de seleção múltipla para iniciar uma seleção estendida.
`CListBox::SetCaretIndex`	Define o retângulo de foco para o item no índice especificado em uma caixa de listagem de seleção múltipla.
`CListBox::SetColumnWidth`	Define a largura da coluna de uma caixa de listagem de várias colunas.
`CListBox::SetCurSel`	Seleciona uma cadeia de caracteres de caixa de listagem.
`CListBox::SetHorizontalExtent`	Define a largura em pixels que uma caixa de listagem pode ser rolada horizontalmente.
`CListBox::SetItemData`	Define um valor associado ao item de caixa de listagem.
`CListBox::SetItemDataPtr`	Define um ponteiro para o item de caixa de listagem.
`CListBox::SetItemHeight`	Define a altura dos itens em uma caixa de listagem.
`CListBox::SetLocale`	Define a ID de localidade para uma caixa de listagem.
`CListBox::SetSel`	Seleciona ou desmarca um item de caixa de listagem em uma caixa de listagem de seleção múltipla.
`CListBox::SetTabStops`	Define as posições de parada de tabulação em uma caixa de listagem.
`CListBox::SetTopIndex`	Define o índice baseado em zero da primeira cadeia de caracteres visível em uma caixa de listagem.
`CListBox::VKeyToItem`	Substituição para fornecer tratamento `WM_KEYDOWN` personalizado para caixas de listagem com o conjunto de estilos `LBS_WANTKEYBOARDINPUT`.

Comentários

Uma caixa de listagem exibe uma lista de itens, como nomes de arquivo, que o usuário pode exibir e selecionar.

Em uma caixa de listagem de seleção única, o usuário pode selecionar apenas um item. Em uma caixa de listagem de seleção múltipla, um intervalo de itens pode ser selecionado. Quando o usuário seleciona um item, ele é realçado e a caixa de listagem envia uma mensagem de notificação para a janela pai.

Você pode criar uma caixa de listagem com base em um modelo de caixa de diálogo ou diretamente em seu código. Para criá-lo diretamente, construa o objeto CListBox e chame a função membro Create para criar o controle de caixa de listagem do Windows e anexá-lo ao objeto CListBox. Para usar uma caixa de listagem em um modelo de caixa de diálogo, declare uma variável de caixa de listagem na classe de caixa de diálogo e use DDX_Control na função da classe de caixa de diálogo DoDataExchange para conectar a variável de membro ao controle. (Isso é feito para você automaticamente quando você adiciona uma variável de controle à sua classe de caixa de diálogo.)

A construção pode ser um processo de uma etapa em uma classe derivada de CListBox. Escreva um construtor para a classe derivada e chame Create de dentro do construtor.

Se você quiser lidar com mensagens de notificação do Windows enviadas por uma caixa de listagem para seu pai (geralmente uma classe derivada de CDialog), adicione uma entrada de mapa de mensagens e uma função de membro do manipulador de mensagens à classe pai para cada mensagem.

Cada entrada de mapa de mensagens usa o seguinte formulário:

ON_Notification( id, memberFxn )

em que id especifica a ID da janela filho do controle de caixa de listagem que envia a notificação, e memberFxn é o nome da função de membro pai que você escreveu para lidar com a notificação.

O protótipo de função do pai é o seguinte:

afx_msg void memberFxn( );

Veja a seguinte lista de possíveis entradas de mapa de mensagens e uma descrição dos casos em que elas seriam enviadas ao pai:

ON_LBN_DBLCLK O usuário clica duas vezes em uma cadeia de caracteres em uma caixa de listagem. Somente uma caixa de listagem que tenha o estilo LBS_NOTIFY enviará essa mensagem de notificação.
ON_LBN_ERRSPACE A caixa de listagem não pode alocar memória suficiente para atender à solicitação.
ON_LBN_KILLFOCUS A caixa de listagem está perdendo o foco de entrada.
ON_LBN_SELCANCEL A seleção da caixa de listagem atual é cancelada. Essa mensagem só é enviada quando uma caixa de listagem tem o estilo LBS_NOTIFY.
ON_LBN_SELCHANGE A seleção na caixa de listagem foi alterada. Essa notificação não será enviada se a seleção for alterada pela função membro CListBox::SetCurSel. Essa notificação se aplica a apenas uma caixa de listagem que tenha o estilo LBS_NOTIFY. A mensagem de notificação LBN_SELCHANGE é enviada para uma caixa de listagem de seleção múltipla sempre que o usuário pressiona uma tecla de seta, mesmo que a seleção não mude.
ON_LBN_SETFOCUS A caixa de listagem está recebendo o foco de entrada.
ON_WM_CHARTOITEM Uma caixa de listagem de desenho do proprietário que não tem cadeias de caracteres recebe uma mensagem WM_CHAR.
ON_WM_VKEYTOITEM Uma caixa de listagem com o estilo LBS_WANTKEYBOARDINPUT recebe uma mensagem WM_KEYDOWN.

Se você criar um objeto CListBox dentro de uma caixa de diálogo (por meio de um recurso de caixa de diálogo), o objeto CListBox será destruído automaticamente quando o usuário fechar a caixa de diálogo.

Se você criar um objeto CListBox dentro de uma janela, talvez seja necessário destruir o objeto CListBox. Se você criar o objeto CListBox na pilha, ele será destruído automaticamente. Se você criar o objeto CListBox no heap usando a função new, deverá chamar o objeto delete para destruí-lo quando o usuário fechar a janela pai.

Se você alocar qualquer memória no objeto CListBox, substitua o destruidor CListBox para descartar a alocação.

Hierarquia de herança

CObject

CCmdTarget

CWnd

CListBox

Requisitos

Cabeçalho: afxwin.h

`CListBox::AddString`

Adiciona uma cadeia de caracteres a uma caixa de listagem.

int AddString(LPCTSTR lpszItem);

Parâmetros

lpszItem
Aponta para a cadeia de caracteres terminada em nulo que deve ser adicionada.

Valor de retorno

O índice baseado em zero na cadeia de caracteres na caixa de listagem. O valor retornado será LB_ERR se ocorrer um erro. O valor retornado será LB_ERRSPACE se espaço insuficiente estiver disponível para armazenar a nova cadeia de caracteres.

Comentários

Se a caixa de listagem não foi criada com o estilo LBS_SORT, a cadeia de caracteres será adicionada ao final da lista. Caso contrário, a cadeia de caracteres será inserida na lista e a lista será classificada. Se a caixa de listagem foi criada com o estilo LBS_SORT, mas não com o estilo LBS_HASSTRINGS, a estrutura classificará a lista por uma ou mais chamadas para a função de membro CompareItem.

Use InsertString para inserir uma cadeia de caracteres em um local específico dentro da caixa de listagem.

Exemplo

// Add 10 items to the list box.
CString str;
for (int i = 0; i < 10; i++)
{
   str.Format(_T("item string %d"), i);
   m_myListBox.AddString(str);
}

`CListBox::CharToItem`

Chamado pela estrutura quando a janela pai da caixa de listagem recebe uma mensagem WM_CHARTOITEM da caixa de listagem.

virtual int CharToItem(
    UINT nKey,
    UINT nIndex);

Parâmetros

nKey
O código ANSI do caractere que o usuário digitou.

nIndex
A posição atual do cursor de caixa de listagem.

Valor de retorno

Retorna - 1 ou - 2 para nenhuma ação adicional ou um número não negativo para especificar um índice de um item de caixa de listagem no qual executar a ação padrão para o pressionamento de teclas. A implementação padrão retorna -1.

Comentários

A mensagem WM_CHARTOITEM é enviada pela caixa de listagem quando recebe uma mensagem WM_CHAR, mas somente se a caixa de listagem atender a todos estes critérios:

É uma caixa de listagem de desenho do proprietário.
Não tem o estilo LBS_HASSTRINGS definido.
Tem pelo menos um item.

Você nunca deve chamar essa função por conta própria. Substitua essa função para fornecer um tratamento personalizado próprio de mensagens de teclado.

Na substituição, você deve retornar um valor para informar à estrutura qual ação você executou. Um valor retornado de - 1 ou - 2 indica que você lidou com todos os aspectos da seleção do item e não requer nenhuma ação adicional por parte da caixa de listagem. Antes de retornar - 1 ou - 2, você pode definir a seleção ou mover o cursor ou ambos. Para definir a seleção, use SetCurSel ou SetSel. Para mover o cursor, use SetCaretIndex.

Um valor retornado igual a 0 ou maior especifica o índice de um item na caixa de listagem e indica que a caixa de listagem deve executar a ação padrão para o pressionamento de teclas no item fornecido.

Exemplo

// CMyODListBox is my owner-drawn list box derived from CListBox. This
// example moves the caret down one item on a numeric key and up one item
// on an alphabetic key. The list box control was created with the
// following code:
//   m_myODListBox.Create(
//      WS_CHILD|WS_VISIBLE|WS_BORDER|WS_HSCROLL|WS_VSCROLL|
//      LBS_SORT|LBS_MULTIPLESEL|LBS_OWNERDRAWVARIABLE|LBS_WANTKEYBOARDINPUT,
//      CRect(10,250,200,450), pParentWnd, IDC_MYODLISTBOX);
//
int CMyODListBox::CharToItem(UINT nChar, UINT nIndex)
{
   // On a numeric key, move the caret up one item.
   if (isdigit(nChar) && (nIndex > 0))
   {
      SetCaretIndex(nIndex - 1);
   }
   // On an alphabetic key, move the caret down one item.
   else if (isalpha(nChar) && (nIndex < (UINT)GetCount()))
   {
      SetCaretIndex(nIndex + 1);
   }

   // Do not perform any default processing.
   return -1;
}

`CListBox::CListBox`

Constrói um objeto CListBox.

CListBox();

Comentários

Um objeto CListBox é construído em duas etapas. Primeiro, chame o construtor ClistBox, então chame Create, que inicializa a caixa de listagem do Windows e a anexa ao CListBox.

Exemplo

// Declare a local CListBox object.
CListBox myListBox;

// Declare a dynamic CListBox object.
CListBox *pmyListBox = new CListBox;

`CListBox::CompareItem`

Chamado pela estrutura para determinar a posição relativa de um novo item em uma caixa de listagem de desenho de proprietário classificada.

virtual int CompareItem(LPCOMPAREITEMSTRUCT lpCompareItemStruct);

Parâmetros

lpCompareItemStruct
Um ponteiro longo para uma estrutura COMPAREITEMSTRUCT.

Valor de retorno

Indica a posição relativa dos dois itens descritos na estrutura COMPAREITEMSTRUCT. Pode ser qualquer um dos seguintes valores:

Valor	Significado
-1	O item 1 classifica antes do item 2.
0	O item 1 e o item 2 classificam do mesmo modo.
1	O item 1 classifica depois do item 2.

Confira CWnd::OnCompareItem para uma descrição da estrutura COMPAREITEMSTRUCT.

Comentários

Por padrão, essa função membro não faz nada. Se você criar uma caixa de listagem de desenho de proprietário com o estilo LBS_SORT, deverá substituir essa função membro para ajudar a estrutura na classificação de novos itens adicionados à caixa de listagem.

Exemplo

// CMyODListBox is my owner-drawn list box derived from CListBox. This
// example compares two items using _tcscmp to sort items in reverse
// alphabetical order. The list box control was created with the
// following code:
//   m_myODListBox.Create(
//      WS_CHILD|WS_VISIBLE|WS_BORDER|WS_HSCROLL|WS_VSCROLL|
//      LBS_SORT|LBS_MULTIPLESEL|LBS_OWNERDRAWVARIABLE|LBS_WANTKEYBOARDINPUT,
//      CRect(10,250,200,450), pParentWnd, IDC_MYODLISTBOX);
//
int CMyODListBox::CompareItem(LPCOMPAREITEMSTRUCT lpCompareItemStruct)
{
   ASSERT(lpCompareItemStruct->CtlType == ODT_LISTBOX);
   LPCTSTR lpszText1 = (LPCTSTR)lpCompareItemStruct->itemData1;
   ASSERT(lpszText1 != NULL);
   LPCTSTR lpszText2 = (LPCTSTR)lpCompareItemStruct->itemData2;
   ASSERT(lpszText2 != NULL);

   return _tcscmp(lpszText2, lpszText1);
}

`CListBox::Create`

Cria a caixa de listagem do Windows e a anexa ao objeto CListBox.

virtual BOOL Create(
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

Parâmetros

dwStyle
Especifica o estilo da caixa de listagem. Aplique qualquer combinação de estilos de caixa de listagem à caixa.

rect
Especifica o tamanho e a posição da caixa de listagem. Pode ser um objeto CRect ou uma estrutura RECT.

pParentWnd
Especifica a janela pai da caixa de listagem (geralmente um objeto CDialog). Não deve ser NULL.

nID
Especifica a ID de controle da caixa de listagem.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Um objeto CListBox é construído em duas etapas. Primeiro, chame o construtor e depois chame Create, que inicializa a caixa de listagem do Windows e a anexa ao objeto CListBox.

Quando Create é executado, o Windows envia as mensagens WM_NCCREATE, WM_CREATE, WM_NCCALCSIZEe WM_GETMINMAXINFO mensagens para o controle de caixa de listagem.

Essas mensagens são tratadas por padrão pelas funções de membro OnNcCreate, OnCreate, OnNcCalcSize e OnGetMinMaxInfo na classe base CWnd. Para estender o tratamento de mensagens padrão, derive uma classe de CListBox, adicione um mapa de mensagem à nova classe e substitua as funções de membro do manipulador de mensagens anteriores. Substitua OnCreate, por exemplo, para executar a inicialização necessária para uma nova classe.

Aplique os estilos de janela a seguir a um controle de caixa de listagem.

WS_CHILD Sempre
WS_VISIBLE Geralmente
WS_DISABLED Raramente
WS_VSCROLL Para adicionar uma barra de rolagem vertical
WS_HSCROLL Para adicionar uma barra de rolagem horizontal
WS_GROUP Para grupar controles
WS_TABSTOP Para permitir o tabbing para esse controle

Exemplo

// pParentWnd is a pointer to the parent window.
m_myListBox.Create(WS_CHILD | WS_VISIBLE | LBS_STANDARD | WS_HSCROLL,
                   CRect(10, 10, 200, 200), pParentWnd, IDC_MYLISTBOX);

`CListBox::DeleteItem`

Chamado pela estrutura quando o usuário exclui um item de um objeto CListBox de desenho do proprietário ou destrói a caixa de listagem.

virtual void DeleteItem(LPDELETEITEMSTRUCT lpDeleteItemStruct);

Parâmetros

lpDeleteItemStruct
Um ponteiro longo para uma estrutura DELETEITEMSTRUCT do Windows que contém informações sobre o item excluído.

Comentários

A implementação padrão dessa função não faz nada. Substitua essa função para redesenhar uma caixa de listagem de desenho do proprietário, conforme necessário.

Confira CWnd::OnDeleteItem para uma descrição da estrutura DELETEITEMSTRUCT.

Exemplo

// CMyODListBox is my owner-drawn list box derived from CListBox. This
// example simply frees the item's text. The list box control was created
// with the following code:
//   m_myODListBox.Create(
//      WS_CHILD|WS_VISIBLE|WS_BORDER|WS_HSCROLL|WS_VSCROLL|
//      LBS_SORT|LBS_MULTIPLESEL|LBS_OWNERDRAWVARIABLE|LBS_WANTKEYBOARDINPUT,
//      CRect(10,250,200,450), pParentWnd, IDC_MYODLISTBOX);
//
void CMyODListBox::DeleteItem(LPDELETEITEMSTRUCT lpDeleteItemStruct)
{
   ASSERT(lpDeleteItemStruct->CtlType == ODT_LISTBOX);
   LPVOID lpszText = (LPVOID)lpDeleteItemStruct->itemData;
   ASSERT(lpszText != NULL);

   free(lpszText);

   CListBox::DeleteItem(lpDeleteItemStruct);
}

`CListBox::DeleteString`

Exclui o item na posição nIndex da caixa de listagem.

int DeleteString(UINT nIndex);

Parâmetros

nIndex
Especifica o índice baseado em zero da cadeia de caracteres a ser excluída.

Valor de retorno

Uma contagem das cadeias de caracteres restantes na lista. O valor retornado será LB_ERR se nIndex especificar um índice maior que o número de itens na lista.

Comentários

Todos os itens após nIndex agora se movem para baixo em uma posição. Por exemplo, se uma caixa de listagem contiver dois itens, excluir o primeiro item fará com que o item restante esteja agora na primeira posição. nIndex=0 para o item na primeira posição.

Exemplo

// Delete every other item from the list box.
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   m_myListBox.DeleteString(i);
}

`CListBox::Dir`

Adiciona uma lista de nomes de arquivo, unidades ou ambos a uma caixa de listagem.

int Dir(
    UINT attr,
    LPCTSTR lpszWildCard);

Parâmetros

attr
Pode ser qualquer combinação dos valores enum descritos em CFile::GetStatus ou qualquer combinação dos seguintes valores:

Valor	Significado
0x0000	É possível ler o arquivo ou gravar nele.
0x0001	É possível ler o arquivo, mas não gravar nele.
0x0002	O arquivo está oculto e não aparece em uma listagem de diretórios.
0x0004	O arquivo é um arquivo do sistema.
0x0010	O nome especificado por `lpszWildCard` especifica um diretório.
0x0020	O arquivo foi arquivado.
0x4000	Inclua todas as unidades que correspondem ao nome especificado por `lpszWildCard`.
0x8000	Sinalizador exclusivo. Se o sinalizador exclusivo for definido, somente os arquivos do tipo especificado serão listados. Caso contrário, os arquivos do tipo especificado serão listados além de arquivos "normais".

lpszWildCard
Aponta para uma cadeia de caracteres de especificação de arquivo. A cadeia de caracteres pode conter caracteres curinga (por exemplo, *.*).

Valor de retorno

O índice baseado em zero do último nome de arquivo adicionado à lista. O valor retornado será LB_ERR se ocorrer um erro. O valor retornado será LB_ERRSPACE se espaço insuficiente estiver disponível para armazenar as novas cadeias de caracteres.

Exemplo

// Add all the files and directories in the windows directory.
TCHAR lpszWinPath[MAX_PATH], lpszOldPath[MAX_PATH];
::GetWindowsDirectory(lpszWinPath, MAX_PATH);

::GetCurrentDirectory(MAX_PATH, lpszOldPath);
::SetCurrentDirectory(lpszWinPath);

m_myListBox.ResetContent();
m_myListBox.Dir(DDL_READWRITE | DDL_DIRECTORY, _T("*.*"));

::SetCurrentDirectory(lpszOldPath);

`CListBox::DrawItem`

Chamado pela estrutura quando um aspecto visual de uma caixa de listagem de desenho do proprietário muda.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parâmetros

lpDrawItemStruct
Um ponteiro longo para uma estrutura DRAWITEMSTRUCT que contém informações sobre o tipo de desenho necessário.

Comentários

Os membros itemAction e itemState os membros da estrutura DRAWITEMSTRUCT definem a ação de desenho a ser executada.

Por padrão, essa função membro não faz nada. Substitua essa função de membro para implementar o desenho para um objeto CListBox desenhado pelo proprietário. O aplicativo deve restaurar todos os objetos de GDI (Graphics Device Interface) selecionados para o contexto de exibição fornecido em lpDrawItemStruct antes que a função membro seja encerrada.

Confira CWnd::OnDrawItem para uma descrição da estrutura DRAWITEMSTRUCT.

Exemplo

// CMyODListBox is my owner-drawn list box derived from CListBox. This
// example draws an item's text centered vertically and horizontally. The
// list box control was created with the following code:
//   m_myODListBox.Create(
//      WS_CHILD|WS_VISIBLE|WS_BORDER|WS_HSCROLL|WS_VSCROLL|
//      LBS_SORT|LBS_MULTIPLESEL|LBS_OWNERDRAWVARIABLE|LBS_WANTKEYBOARDINPUT,
//      CRect(10,250,200,450), pParentWnd, IDC_MYODLISTBOX);
//
void CMyODListBox::DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct)
{
   ASSERT(lpDrawItemStruct->CtlType == ODT_LISTBOX);
   LPCTSTR lpszText = (LPCTSTR)lpDrawItemStruct->itemData;
   ASSERT(lpszText != NULL);
   CDC dc;

   dc.Attach(lpDrawItemStruct->hDC);

   // Save these value to restore them when done drawing.
   COLORREF crOldTextColor = dc.GetTextColor();
   COLORREF crOldBkColor = dc.GetBkColor();

   // If this item is selected, set the background color
   // and the text color to appropriate values. Also, erase
   // rect by filling it with the background color.
   if ((lpDrawItemStruct->itemAction | ODA_SELECT) &&
       (lpDrawItemStruct->itemState & ODS_SELECTED))
   {
      dc.SetTextColor(::GetSysColor(COLOR_HIGHLIGHTTEXT));
      dc.SetBkColor(::GetSysColor(COLOR_HIGHLIGHT));
      dc.FillSolidRect(&lpDrawItemStruct->rcItem,
                       ::GetSysColor(COLOR_HIGHLIGHT));
   }
   else
   {
      dc.FillSolidRect(&lpDrawItemStruct->rcItem, crOldBkColor);
   }

   // If this item has the focus, draw a red frame around the
   // item's rect.
   if ((lpDrawItemStruct->itemAction | ODA_FOCUS) &&
       (lpDrawItemStruct->itemState & ODS_FOCUS))
   {
      CBrush br(RGB(255, 0, 0));
      dc.FrameRect(&lpDrawItemStruct->rcItem, &br);
   }

   // Draw the text.
   dc.DrawText(
       lpszText,
       (int)_tcslen(lpszText),
       &lpDrawItemStruct->rcItem,
       DT_CENTER | DT_SINGLELINE | DT_VCENTER);

   // Reset the background color and the text color back to their
   // original values.
   dc.SetTextColor(crOldTextColor);
   dc.SetBkColor(crOldBkColor);

   dc.Detach();
}

`CListBox::FindString`

Localiza a primeira cadeia de caracteres em uma caixa de listagem que contém o prefixo especificado sem alterar a seleção de caixa de listagem.

int FindString(
    int nStartAfter,
    LPCTSTR lpszItem) const;

Parâmetros

nStartAfter
Contém o índice baseado em zero do item antes do primeiro item a ser pesquisado. Quando a pesquisa atinge a parte inferior da caixa de listagem, ela continua da parte superior da caixa de listagem de volta para o item especificado por nStartAfter. Se nStartAfter for -1, a caixa de listagem inteira será pesquisada desde o início.

lpszItem
Aponta para a cadeia de caracteres terminada em nulo que contém o prefixo a ser pesquisado. A pesquisa é independente de maiúsculas e minúsculas. Portanto, essa cadeia de caracteres pode conter qualquer combinação de letras maiúsculas e minúsculas.

Valor de retorno

O índice baseado em zero do item correspondente ou LB_ERR se a pesquisa não foi bem-sucedida.

Comentários

Use a função SelectString membro para localizar e selecionar uma cadeia de caracteres.

Exemplo

// The string to match.
LPCTSTR lpszmyString = _T("item");

// Delete all items that begin with the specified string.
int nIndex = 0;
while ((nIndex = m_myListBox.FindString(nIndex, lpszmyString)) != LB_ERR)
{
   m_myListBox.DeleteString(nIndex);
}

`CListBox::FindStringExact`

Localiza a primeira cadeia de caracteres de caixa de listagem que corresponde à cadeia de caracteres especificada em lpszFind.

int FindStringExact(
    int nIndexStart,
    LPCTSTR lpszFind) const;

Parâmetros

nIndexStart
Especifica o índice baseado em zero do item antes do primeiro item a ser pesquisado. Quando a pesquisa atinge a parte inferior da caixa de listagem, ela continua da parte superior da caixa de listagem de volta para o item especificado por nIndexStart. Se nIndexStart for -1, a caixa de listagem inteira será pesquisada desde o início.

lpszFind
Aponta para a cadeia de caracteres terminada em nulo para pesquisar. Essa cadeia de caracteres pode conter um nome de arquivo completo, incluindo a extensão. A pesquisa não diferencia maiúsculas de minúsculas, portanto, a cadeia de caracteres pode conter qualquer combinação de letras maiúsculas e minúsculas.

Valor de retorno

O índice do item correspondente ou LB_ERR, se a pesquisa não tiver sido bem-sucedida.

Comentários

Se a caixa de listagem tiver sido criada com um estilo de desenho do proprietário, mas sem o estilo LBS_HASSTRINGS, a função de membro FindStringExact tentará combinar o valor de palavra dupla com o valor de lpszFind.

Exemplo

// The string to match.
LPCTSTR lpszmyString = _T("item string 3");

// Delete all items that exactly match the specified string.
int nIndex = 0;
while ((nIndex = m_myListBox.FindStringExact(nIndex, lpszmyString)) != LB_ERR)
{
   m_myListBox.DeleteString(nIndex);
}

`CListBox::GetAnchorIndex`

Recupera o índice baseado em zero do item de âncora atual na caixa de listagem.

int GetAnchorIndex() const;

Valor de retorno

O índice do item de âncora atual, se bem-sucedido; caso contrário, LB_ERR.

Comentários

Em uma caixa de listagem de seleção múltipla, o item de âncora é o primeiro ou último item em um bloco de itens selecionados contíguos.

Exemplo

Confira o exemplo de CListBox::SetAnchorIndex.

`CListBox::GetCaretIndex`

Determina o índice do item que tem o retângulo de foco em uma caixa de listagem de seleção múltipla.

int GetCaretIndex() const;

Valor de retorno

O índice baseado em zero do item que tem o retângulo de foco em uma caixa de listagem. Se a caixa de listagem for uma caixa de listagem de seleção única, o valor retornado será o índice do item selecionado, se houver.

Comentários

O item pode ou não ser selecionado.

Exemplo

Confira o exemplo de CListBox::SetCaretIndex.

`CListBox::GetCount`

Recupera o número de itens em uma caixa de listagem.

int GetCount() const;

Valor de retorno

O número de itens na caixa de listagem ou LB_ERR, se ocorrer um erro.

Comentários

A contagem retornada é maior que o valor do índice do último item (o índice é baseado em zero).

Exemplo

// Add 10 items to the list box.
CString str;
for (int i = 0; i < 10; i++)
{
   str.Format(_T("item %d"), i);
   m_myListBox.AddString(str);
}

// Verify that 10 items were added to the list box.
ASSERT(m_myListBox.GetCount() == 10);

`CListBox::GetCurSel`

Recupera o índice baseado em zero do item selecionado no momento, se houver, em uma caixa de listagem de seleção única.

int GetCurSel() const;

Valor de retorno

O índice baseado em zero do item selecionado no momento se for uma caixa de listagem de seleção única. Será LB_ERR se nenhum item estiver selecionado no momento.

Em uma caixa de listagem de seleção múltipla, o índice do item que tem o foco.

Comentários

Não chame GetCurSel para uma caixa de listagem de seleção múltipla. Use CListBox::GetSelItems em vez disso.

Exemplo

// Select the next item of the currently selected one.
int nIndex = m_myListBox.GetCurSel();
int nCount = m_myListBox.GetCount();
if ((nIndex != LB_ERR) && (nCount > 1))
{
   if (++nIndex < nCount)
      m_myListBox.SetCurSel(nIndex);
   else
      m_myListBox.SetCurSel(0);
}

`CListBox::GetHorizontalExtent`

Recupera da caixa de listagem a largura em pixels pela qual ela pode ser rolada horizontalmente.

int GetHorizontalExtent() const;

Valor de retorno

A largura rolável da caixa de listagem, em pixels.

Comentários

Isso será aplicável somente se a caixa de listagem tiver uma barra de rolagem horizontal.

Exemplo

// Find the longest string in the list box.
CString str;
CSize sz;
int dx = 0;
CDC *pDC = m_myListBox.GetDC();
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   m_myListBox.GetText(i, str);
   sz = pDC->GetTextExtent(str);

   if (sz.cx > dx)
      dx = sz.cx;
}
m_myListBox.ReleaseDC(pDC);

// Set the horizontal extent only if the current extent is not large enough.
if (m_myListBox.GetHorizontalExtent() < dx)
{
   m_myListBox.SetHorizontalExtent(dx);
   ASSERT(m_myListBox.GetHorizontalExtent() == dx);
}

`CListBox::GetItemData`

Recupera o valor de palavra dupla fornecido pelo aplicativo associado ao item de caixa de listagem especificado.

DWORD_PTR GetItemData(int nIndex) const;

Parâmetros

nIndex
Especifica o índice baseado em zero do item da caixa de listagem.

Valor de retorno

O valor associado ao item ou LB_ERR, se ocorrer um erro.

Comentários

O valor de palavra dupla era o parâmetro dwItemData de uma chamada SetItemData.

Exemplo

// If any item's data is equal to zero then reset it to -1.
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   if (m_myListBox.GetItemData(i) == 0)
   {
      m_myListBox.SetItemData(i, (DWORD)-1);
   }
}

`CListBox::GetItemDataPtr`

Recupera o valor de 32 bits fornecido pelo aplicativo associado ao item da caixa de listagem especificado como um ponteiro (void *).

void* GetItemDataPtr(int nIndex) const;

Parâmetros

nIndex
Especifica o índice baseado em zero do item da caixa de listagem.

Valor de retorno

Recupera um ponteiro ou -1 se ocorrer um erro.

Exemplo

LPVOID lpmyPtr = pParentWnd;

// Check all the items in the list box; if an item's
// data pointer is equal to my pointer then reset it to NULL.
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   if (m_myListBox.GetItemDataPtr(i) == lpmyPtr)
   {
      m_myListBox.SetItemDataPtr(i, NULL);
   }
}

`CListBox::GetItemHeight`

Determina a altura dos itens em uma caixa de listagem.

int GetItemHeight(int nIndex) const;

Parâmetros

nIndex
Especifica o índice baseado em zero do item da caixa de listagem. Esse parâmetro será usado somente se a caixa de listagem tiver o estilo LBS_OWNERDRAWVARIABLE; caso contrário, deverá ser definido como 0.

Valor de retorno

A altura, em pixels, dos itens na caixa de listagem. Se a caixa de listagem tiver o estilo LBS_OWNERDRAWVARIABLE, o valor retornado será a altura do item especificado por nIndex. Se ocorrer um erro, o valor retornado será LB_ERR.

Exemplo

// Set the height of every item so the item
// is completely visible.
CString str;
CSize sz;
CDC *pDC = m_myListBox.GetDC();
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   m_myListBox.GetText(i, str);
   sz = pDC->GetTextExtent(str);

   // Only want to set the item height if the current height
   // is not big enough.
   if (m_myListBox.GetItemHeight(i) < sz.cy)
      m_myListBox.SetItemHeight(i, sz.cy);
}
m_myListBox.ReleaseDC(pDC);

`CListBox::GetItemRect`

Recupera as dimensões do retângulo que limita um item de caixa de listagem, pois ele é exibido atualmente na janela de caixa de listagem.

int GetItemRect(
    int nIndex,
    LPRECT lpRect) const;

Parâmetros

nIndex
Especifica o índice de base zero do item.

lpRect
Especifica um ponteiro longo para uma estrutura RECT que recebe as coordenadas de cliente de caixa de listagem do item.

Valor de retorno

LB_ERR se um erro ocorrer.

Exemplo

// Dump all of the items bounds.
CString str;
RECT r;
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   m_myListBox.GetItemRect(i, &r);

   str.Format(_T("item %d: left = %d, top = %d, right = %d, ")
              _T("bottom = %d\r\n"),
              i,
              r.left,
              r.top,
              r.right,
              r.bottom);
   AFXDUMP(str);
}

`CListBox::GetListBoxInfo`

Recupera o número de itens por coluna.

DWORD GetListBoxInfo() const;

Valor de retorno

Número de itens por coluna do objeto CListBox.

Comentários

Essa função de membro emula a funcionalidade da mensagem LB_GETLISTBOXINFO, conforme descrito no SDK do Windows.

`CListBox::GetLocale`

Recupera a localidade usada pela caixa de listagem.

LCID GetLocale() const;

Valor de retorno

O valor de LCID (ID de localidade) para as cadeias de caracteres na caixa de listagem.

Comentários

A localidade é usada, por exemplo, para determinar a ordem de classificação das cadeias de caracteres em uma caixa de listagem classificada.

Exemplo

Confira o exemplo de CListBox::SetLocale.

`CListBox::GetSel`

Recupera o estado de seleção de um item.

int GetSel(int nIndex) const;

Parâmetros

nIndex
Especifica o índice de base zero do item.

Valor de retorno

Um número positivo se o item especificado estiver selecionado; caso contrário, 0. O valor retornado será LB_ERR se ocorrer um erro.

Comentários

Essa função membro funciona com caixas de listagem de seleção única e múltipla.

Para recuperar o índice do item da caixa de listagem atualmente selecionado, use CListBox::GetCurSel.

Exemplo

// Dump all of the items select state.
CString str;
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   str.Format(_T("item %d: select state is %s\r\n"),
              i,
              m_myListBox.GetSel(i) > 0 ? _T("true") : _T("false"));
   AFXDUMP(str);
}

`CListBox::GetSelCount`

Recupera o número total de itens selecionados em uma caixa de listagem de seleção múltipla.

int GetSelCount() const;

Valor de retorno

A contagem de itens selecionados em uma caixa de listagem. Se a caixa de listagem for uma caixa de listagem de seleção única, o valor retornado será LB_ERR.

Exemplo

Confira o exemplo de CListBox::GetSelItems.

`CListBox::GetSelItems`

Preenche um buffer com uma matriz de inteiros que especifica os números de item de itens selecionados em uma caixa de listagem de seleção múltipla.

int GetSelItems(
    int nMaxItems,
    LPINT rgIndex) const;

Parâmetros

nMaxItems
Especifica o número máximo de itens selecionados cujos números de item devem ser colocados no buffer.

rgIndex
Especifica um ponteiro para um buffer grande o suficiente para o número de inteiros especificados por nMaxItems.

Valor de retorno

O número real de itens colocados no buffer. Se a caixa de listagem for uma caixa de listagem de seleção única, o valor retornado será LB_ERR.

Exemplo

// Get the indexes of all the selected items.
int nCount = m_myODListBox.GetSelCount();
CArray<int, int> aryListBoxSel;

aryListBoxSel.SetSize(nCount);
m_myODListBox.GetSelItems(nCount, aryListBoxSel.GetData());

// Dump the selection array.
AFXDUMP(aryListBoxSel);

`CListBox::GetText`

Obtém uma cadeia de caracteres de uma caixa de listagem.

int GetText(
    int nIndex,
    LPTSTR lpszBuffer) const;

void GetText(
    int nIndex,
    CString& rString) const;

Parâmetros

nIndex
Especifica o índice baseado em zero da cadeia de caracteres a ser recuperada.

lpszBuffer
Aponta para o buffer que recebe a cadeia de caracteres. O buffer deve ter espaço suficiente para a cadeia de caracteres e um caractere nulo de terminação. O tamanho da cadeia de caracteres pode ser determinado antecipadamente chamando a função de membro GetTextLen.

rString
Uma referência a um objeto CString.

Valor de retorno

O comprimento (em bytes) da cadeia de caracteres, excluindo o caractere nulo de terminação. Se nIndex não especificar um índice válido, o valor retornado será LB_ERR.

Comentários

A segunda forma dessa função de membro preenche um objeto CString com o texto da cadeia de caracteres.

Exemplo

// Dump all of the items in the list box.
CString str, str2;
int n;
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   n = m_myListBox.GetTextLen(i);
   m_myListBox.GetText(i, str.GetBuffer(n));
   str.ReleaseBuffer();

   str2.Format(_T("item %d: %s\r\n"), i, str.GetBuffer(0));
   AFXDUMP(str2);
}

`CListBox::GetTextLen`

Obtém o comprimento de uma cadeia de caracteres em um item de caixa de listagem.

int GetTextLen(int nIndex) const;

Parâmetros

nIndex
Especifica o índice baseado em zero da cadeia de caracteres.

Valor de retorno

O comprimento da cadeia de caracteres em caracteres, excluindo o caractere nulo de terminação. Se nIndex não especificar um índice válido, o valor retornado será LB_ERR.

Exemplo

Confira o exemplo de CListBox::GetText.

`CListBox::GetTopIndex`

Recupera o índice baseado em zero do primeiro item visível em uma caixa de listagem.

int GetTopIndex() const;

Valor de retorno

O índice baseado em zero do primeiro item visível em uma caixa de listagem, se bem-sucedido; caso contrário, LB_ERR.

Comentários

Inicialmente, o item 0 está na parte superior da caixa de listagem, mas se a caixa de listagem for rolada, outro item poderá estar na parte superior.

Exemplo

// Want an item in the bottom half to be the first visible item.
int n = m_myListBox.GetCount() / 2;
if (m_myListBox.GetTopIndex() < n)
{
   m_myListBox.SetTopIndex(n);
   ASSERT(m_myListBox.GetTopIndex() == n);
}

`CListBox::InitStorage`

Aloca memória para armazenar itens de caixa de listagem.

int InitStorage(
    int nItems,
    UINT nBytes);

Parâmetros

nItems
Especifica o número de itens a adicionar.

nBytes
Especifica a quantidade de memória, em bytes, a ser alocada para cadeias de caracteres de item.

Valor de retorno

Se bem-sucedido, o número máximo de itens que a caixa de listagem pode armazenar antes que uma realocação de memória seja necessária; caso contrário, LB_ERRSPACE, o que significa que não há memória suficiente disponível.

Comentários

Chame essa função antes de adicionar um grande número de itens a um CListBox.

Essa função ajuda a acelerar a inicialização de caixas de listagem que têm vários itens (mais de 100). Ela pré-aloca a quantidade de memória especificada para que as funções subsequentes AddString, InsertString e Dir levem o menor tempo possível. Você pode usar estimativas para os parâmetros. Se você superestimar, memória extra será alocada. Se você subestimar, a alocação normal será usada para itens que excedem a quantidade pré-alocada.

Somente Windows 95/98: o parâmetro nItems é limitado a valores de 16 bits. Isso significa que as caixas de listagem não podem conter mais de 32.767 itens. Embora o número de itens seja restrito, o tamanho total dos itens em uma caixa de listagem é limitado apenas pela memória disponível.

Exemplo

// Initialize the storage of the list box to be 256 strings with
// about 10 characters per string, performance improvement.
int n = m_myListBox.InitStorage(256, 16 * sizeof(TCHAR));
ASSERT(n != LB_ERRSPACE);

// Add 256 items to the list box.
CString str;
for (int i = 0; i < 256; i++)
{
   str.Format(_T("item string %d"), i);
   m_myListBox.AddString(str);
}

`CListBox::InsertString`

Insere uma cadeia de caracteres na caixa de listagem.

int InsertString(
    int nIndex,
    LPCTSTR lpszItem);

Parâmetros

nIndex
Especifica o índice baseado em zero da posição para inserir a cadeia de caracteres. Se esse parâmetro for -1, a cadeia de caracteres será adicionada ao final da lista.

lpszItem
Aponta para a cadeia de caracteres terminada em nulo que deve ser inserida.

Valor de retorno

O índice baseado em zero da posição na qual a cadeia de caracteres foi inserida. O valor retornado será LB_ERR se ocorrer um erro. O valor retornado será LB_ERRSPACE se espaço insuficiente estiver disponível para armazenar a nova cadeia de caracteres.

Comentários

Ao contrário da função de membro AddString, InsertString não faz com que uma lista com o estilo LBS_SORT seja classificada.

Exemplo

// Insert items in between existing items.
CString str;
int n = m_myListBox.GetCount();
for (int i = 0; i < n; i++)
{
   str.Format(_T("item string %c"), (char)('A' + i));
   m_myListBox.InsertString(2 * i, str);
}

`CListBox::ItemFromPoint`

Determina o item de caixa de listagem mais próximo do ponto especificado em pt.

UINT ItemFromPoint(
    CPoint pt,
    BOOL& bOutside) const;

Parâmetros

pt
Ponto para o qual localizar o item mais próximo, especificado em relação ao canto superior esquerdo da área de cliente da caixa de listagem.

bOutside
Referência a uma variável BOOL que será definida como TRUE se pt estiver fora da área de cliente da caixa de listagem, FALSE se pt estiver dentro da área de cliente da caixa de listagem.

Valor de retorno

O índice do item mais próximo ao ponto especificado em pt.

Comentários

Você pode usar essa função para determinar qual item de caixa de listagem o cursor do mouse move.

Exemplo

Confira o exemplo de CListBox::SetAnchorIndex.

`CListBox::MeasureItem`

Chamado pela estrutura quando uma caixa de listagem com um estilo desenhado pelo proprietário é criada.

virtual void MeasureItem(LPMEASUREITEMSTRUCT lpMeasureItemStruct);

Parâmetros

lpMeasureItemStruct
Um ponteiro longo para uma estrutura MEASUREITEMSTRUCT.

Comentários

Por padrão, essa função membro não faz nada. Substitua essa função de membro e preencha a estrutura MEASUREITEMSTRUCT para informar o Windows sobre as dimensões da caixa de listagem. Se a caixa de listagem for criada com o estilo LBS_OWNERDRAWVARIABLE, a estrutura chamará essa função de membro para cada item na caixa de listagem. Caso contrário, esse membro será chamado apenas uma vez.

Para mais informações sobre como usar o estilo LBS_OWNERDRAWFIXED em uma caixa de listagem de desenho de proprietário criada com a função de membro SubclassDlgItem de CWnd, confira a discussão na Nota Técnica 14.

Confira CWnd::OnMeasureItem para uma descrição da estrutura MEASUREITEMSTRUCT.

Exemplo

// CMyODListBox is my owner-drawn list box derived from CListBox. This
// example measures an item and sets the height of the item to twice the
// vertical extent of its text. The list box control was created with the
// following code:
//   m_myODListBox.Create(
//      WS_CHILD|WS_VISIBLE|WS_BORDER|WS_HSCROLL|WS_VSCROLL|
//      LBS_SORT|LBS_MULTIPLESEL|LBS_OWNERDRAWVARIABLE|LBS_WANTKEYBOARDINPUT,
//      CRect(10,250,200,450), pParentWnd, IDC_MYODLISTBOX);
//
void CMyODListBox::MeasureItem(LPMEASUREITEMSTRUCT lpMeasureItemStruct)
{
   ASSERT(lpMeasureItemStruct->CtlType == ODT_LISTBOX);
   LPCTSTR lpszText = (LPCTSTR)lpMeasureItemStruct->itemData;
   ASSERT(lpszText != NULL);
   CSize sz;
   CDC *pDC = GetDC();

   sz = pDC->GetTextExtent(lpszText);

   ReleaseDC(pDC);

   lpMeasureItemStruct->itemHeight = 2 * sz.cy;
}

`CListBox::ResetContent`

Remove todos os itens da caixa de listagem.

void ResetContent();

Exemplo

// Delete all the items from the list box.
m_myListBox.ResetContent();
ASSERT(m_myListBox.GetCount() == 0);

`CListBox::SelectString`

Pesquisa um item de caixa de listagem que corresponde à cadeia de caracteres especificada e, se um item correspondente for encontrado, ele selecionará o item.

int SelectString(
    int nStartAfter,
    LPCTSTR lpszItem);

Parâmetros

Valor de retorno

O índice do item selecionado se a pesquisa tiver sido bem-sucedida. Se a pesquisa não tiver sido bem-sucedida, o valor retornado será LB_ERR e a seleção atual não será alterada.

Comentários

A caixa de listagem é rolada, se necessário, para colocar o item selecionado em exibição.

Essa função de membro não pode ser usada com uma caixa de listagem que tenha o estilo LBS_MULTIPLESEL.

Um item será selecionado somente se seus caracteres iniciais (do ponto de partida) corresponderem aos caracteres na cadeia de caracteres especificada por lpszItem.

Use a função de membro FindString para localizar uma cadeia de caracteres sem selecionar o item.

Exemplo

// The string to match.
LPCTSTR lpszmyString = _T("item 5");

// Select the item that begins with the specified string.
int nIndex = m_myListBox.SelectString(0, lpszmyString);
ASSERT(nIndex != LB_ERR);

`CListBox::SelItemRange`

Seleciona vários itens consecutivos em uma caixa de listagem de seleção múltipla.

int SelItemRange(
    BOOL bSelect,
    int nFirstItem,
    int nLastItem);

Parâmetros

bSelect
Especifica como definir a seleção. Se bSelect for TRUE, a cadeia de caracteres será selecionada e realçada; se FALSE, o realce será removido e a cadeia de caracteres não será mais selecionada.

nFirstItem
Especifica o índice baseado em zero do primeiro item a ser definido.

nLastItem
Especifica o índice baseado em zero do último item a ser definido.

Valor de retorno

LB_ERR se um erro ocorrer.

Comentários

Use essa função de membro apenas com caixas de listagem de várias seleções. Se você precisar selecionar apenas um item em uma caixa de listagem de seleção múltipla, ou seja, se nFirstItem for igual a nLastItem, chame a função de membro SetSel.

Exemplo

// Select half of the items.
m_myODListBox.SelItemRange(TRUE, 0, m_myODListBox.GetCount() / 2);

`CListBox::SetAnchorIndex`

Define a âncora em uma caixa de listagem de seleção múltipla para iniciar uma seleção estendida.

void SetAnchorIndex(int nIndex);

Parâmetros

nIndex
Especifica o índice baseado em zero do item de caixa de listagem que será a âncora.

Comentários

Em uma caixa de listagem de seleção múltipla, o item de âncora é o primeiro ou último item em um bloco de itens selecionados contíguos.

Exemplo

void CMyODListBox::OnLButtonDown(UINT nFlags, CPoint point)
{
   BOOL bOutside = TRUE;
   UINT uItem = ItemFromPoint(point, bOutside);

   if (!bOutside)
   {
      // Set the anchor to be the middle item.
      SetAnchorIndex(uItem);
      ASSERT((UINT)GetAnchorIndex() == uItem);
   }

   CListBox::OnLButtonDown(nFlags, point);
}

`CListBox::SetCaretIndex`

Define o retângulo de foco para o item no índice especificado em uma caixa de listagem de seleção múltipla.

int SetCaretIndex(
    int nIndex,
    BOOL bScroll = TRUE);

Parâmetros

nIndex
Especifica o índice baseado em zero do item para receber o retângulo de foco na caixa de listagem.

bScroll
Se esse valor for 0, o item será rolado até ficar totalmente visível. Se esse valor não for 0, o item será rolado até ficar pelo menos parcialmente visível.

Valor de retorno

LB_ERR se um erro ocorrer.

Comentários

Se o item não estiver visível, ele será rolado para exibição.

Exemplo

// Set the caret to be the middle item.
m_myListBox.SetCaretIndex(m_myListBox.GetCount() / 2);
ASSERT(m_myListBox.GetCaretIndex() == m_myListBox.GetCount() / 2);

`CListBox::SetColumnWidth`

Define a largura em pixels de todas as colunas em uma caixa de listagem de várias colunas (criada com o estilo LBS_MULTICOLUMN).

void SetColumnWidth(int cxWidth);

Parâmetros

cxWidth
Especifica a largura em pixels de todas as colunas.

Exemplo

// Find the pixel width of the largest item.
CString str;
CSize   sz;
int     dx = 0;
CDC* pDC = myListBox.GetDC();
for (int i = 0; i < myListBox.GetCount(); i++)
{
   myListBox.GetText(i, str);
   sz = pDC->GetTextExtent(str);

   if (sz.cx > dx)
      dx = sz.cx;
}
myListBox.ReleaseDC(pDC);

// Set the column width of the first column to be one and 1/3 units
// of the largest string. 
myListBox.SetColumnWidth(dx * 4 / 3);

`CListBox::SetCurSel`

Seleciona uma cadeia de caracteres e rola-a para a exibição, se necessário.

int SetCurSel(int nSelect);

Parâmetros

nSelect
Especifica o índice baseado em zero da cadeia de caracteres a ser selecionada. Se nSelect for -1, a caixa de listagem será definida como sem seleção.

Valor de retorno

LB_ERR se um erro ocorrer.

Comentários

Quando a nova cadeia de caracteres é selecionada, a caixa de listagem remove o realce da cadeia de caracteres selecionada anteriormente.

Use essa função de membro apenas com caixas de listagem de seleção única.

Para definir ou remover uma seleção em uma caixa de listagem de seleção múltipla, use CListBox::SetSel.

Exemplo

// Select the last item in the list box.
int nCount = m_myListBox.GetCount();
if (nCount > 0)
   m_myListBox.SetCurSel(nCount - 1);

`CListBox::SetHorizontalExtent`

Define a largura, em pixels, pela qual uma caixa de listagem pode ser rolada horizontalmente.

void SetHorizontalExtent(int cxExtent);

Parâmetros

cxExtent
Especifica o número de pixels pelos quais a caixa de listagem pode ser rolada horizontalmente.

Comentários

Se o tamanho da caixa de listagem for menor que esse valor, a barra de rolagem horizontal rolará horizontalmente os itens na caixa de listagem. Se a caixa de listagem for tão grande ou maior que esse valor, a barra de rolagem horizontal ficará oculta.

Para responder a uma chamada a SetHorizontalExtent, a caixa de listagem deve ter sido definida com o estilo WS_HSCROLL.

Essa função de membro não é útil para caixas de listagem de várias colunas. Para caixas de listagem de várias colunas, chame a função de membro SetColumnWidth.

Exemplo

// Find the longest string in the list box.
CString str;
CSize sz;
int dx = 0;
TEXTMETRIC tm;
CDC *pDC = m_myListBox.GetDC();
CFont *pFont = m_myListBox.GetFont();

// Select the listbox font, save the old font
CFont *pOldFont = pDC->SelectObject(pFont);
// Get the text metrics for avg char width
pDC->GetTextMetrics(&tm);

for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   m_myListBox.GetText(i, str);
   sz = pDC->GetTextExtent(str);

   // Add the avg width to prevent clipping
   sz.cx += tm.tmAveCharWidth;

   if (sz.cx > dx)
      dx = sz.cx;
}
// Select the old font back into the DC
pDC->SelectObject(pOldFont);
m_myListBox.ReleaseDC(pDC);

// Set the horizontal extent so every character of all strings
// can be scrolled to.
m_myListBox.SetHorizontalExtent(dx);

`CListBox::SetItemData`

Define um valor associado ao item especificado em uma caixa de listagem.

int SetItemData(
    int nIndex,
    DWORD_PTR dwItemData);

Parâmetros

nIndex
Especifica o índice de base zero do item.

dwItemData
Especifica o valor a ser associado ao item.

Valor de retorno

LB_ERR se um erro ocorrer.

Exemplo

// Set the data of each item to be equal to its index.
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   m_myListBox.SetItemData(i, i);
}

`CListBox::SetItemDataPtr`

Define o valor de 32 bits associado ao item especificado em uma caixa de listagem como o ponteiro especificado ( void *).

int SetItemDataPtr(
    int nIndex,
    void* pData);

Parâmetros

nIndex
Especifica o índice de base zero do item.

pData
Especifica o ponteiro a ser associado ao item.

Valor de retorno

LB_ERR se um erro ocorrer.

Comentários

Esse ponteiro permanece válido para a vida útil da caixa de listagem, embora a posição relativa do item dentro da caixa de listagem possa ser alterada à medida que os itens forem adicionados ou removidos. Portanto, o índice do item dentro da caixa pode ser alterado, mas o ponteiro permanece confiável.

Exemplo

// Set the data pointer of each item to be NULL.
for (int i = 0; i < m_myListBox.GetCount(); i++)
{
   m_myListBox.SetItemDataPtr(i, NULL);
}

`CListBox::SetItemHeight`

Define a altura dos itens em uma caixa de listagem.

int SetItemHeight(
    int nIndex,
    UINT cyItemHeight);

Parâmetros

cyItemHeight
Especifica a altura, em pixels, do item.

Valor de retorno

LB_ERR se o índice ou a altura forem inválidos.

Comentários

Se a caixa de listagem tiver o estilo LBS_OWNERDRAWVARIABLE, essa função definirá a altura do item especificado por nIndex. Caso contrário, essa função definirá a altura de todos os itens na caixa de listagem.

Exemplo

// Set the height of every item to be the
// vertical size of the item's text extent.
CString str;
CSize sz;
CDC *pDC = myListBox.GetDC();
for (int i = 0; i < myListBox.GetCount(); i++)
{
   myListBox.GetText(i, str);
   sz = pDC->GetTextExtent(str);

   myListBox.SetItemHeight(i, sz.cy);
}
myListBox.ReleaseDC(pDC);

`CListBox::SetLocale`

Define a ID de localidade para essa caixa de listagem.

LCID SetLocale(LCID nNewLocale);

Parâmetros

nNewLocale
O novo valor LCID (ID de localidade) a ser definido para a caixa de listagem.

Valor de retorno

O valor do LCID (ID de localidade) anterior para essa caixa de listagem.

Comentários

Se SetLocale não for chamado, a localidade padrão será obtida do sistema. Essa localidade padrão do sistema pode ser modificada usando o aplicativo Regional (ou Internacional) do painel de controle.

Exemplo

// My LCID to use.
LCID mylcid = MAKELCID(MAKELANGID(LANG_SPANISH, SUBLANG_SPANISH_MEXICAN),
                       SORT_DEFAULT);

// Force the list box to use my locale.
m_myListBox.SetLocale(mylcid);
ASSERT(m_myListBox.GetLocale() == mylcid);

`CListBox::SetSel`

Seleciona uma cadeia de caracteres em uma caixa de listagem de seleção múltipla.

int SetSel(
    int nIndex,
    BOOL bSelect = TRUE);

Parâmetros

nIndex
Contém o índice baseado em zero da cadeia de caracteres a ser definida. Se -1, a seleção será adicionada ou removida de todas as cadeias de caracteres, dependendo do valor de bSelect.

Valor de retorno

LB_ERR se um erro ocorrer.

Comentários

Use essa função de membro apenas com caixas de listagem de várias seleções.

Para selecionar um item em uma caixa de listagem de seleção única, use CListBox::SetCurSel.

Exemplo

// Select all of the items with an even index and
// deselect all others.
for (int i = 0; i < m_myODListBox.GetCount(); i++)
{
   m_myODListBox.SetSel(i, ((i % 2) == 0));
}

`CListBox::SetTabStops`

Define as posições de parada de tabulação em uma caixa de listagem.

void SetTabStops();
BOOL SetTabStops(const int& cxEachStop);

BOOL SetTabStops(
    int nTabStops,
    LPINT rgTabStops);

Parâmetros

cxEachStop
As paradas de tabulação são definidas em todas as unidades de diálogo cxEachStop. Confira rgTabStops uma descrição de uma unidade de caixa de diálogo.

nTabStops
Especifica o número de paradas de tabulação a serem exibidas na caixa de listagem.

rgTabStops
Aponta para o primeiro membro de uma matriz de inteiros que contém as posições de parada de tabulação em unidades de diálogo. Uma unidade de caixa de diálogo é uma distância horizontal ou vertical. Uma unidade de caixa de diálogo horizontal é igual a um quarto da unidade de largura base da caixa de diálogo atual e uma unidade de diálogo vertical é igual a um oitavo da unidade de altura base da caixa de diálogo atual. As unidades base da caixa de diálogo são calculadas com base na altura e na largura da fonte atual do sistema. A função do Windows GetDialogBaseUnits retorna as unidades base da caixa de diálogo atual em pixels. As paradas de tabulação devem ser classificadas em ordem crescente; guias de retorno não são permitidas.

Valor de retorno

Não zero se todas as guias foram definidas; caso contrário, 0.

Comentários

Para definir paradas de tabulação para o tamanho padrão de 2 unidades de diálogo, chame a versão sem parâmetros dessa função de membro. Para definir paradas de tabulação para um tamanho diferente de 2, chame a versão com o argumento cxEachStop.

Para definir paradas de tabulação para uma matriz de tamanhos, use a versão com os argumentos rgTabStops e nTabStops. Uma parada de tabulação será definida para cada valor em rgTabStops, até o número especificado por nTabStops.

Para responder a uma chamada à função de membro SetTabStops, a caixa de listagem deve ter sido criada com o estilo LBS_USETABSTOPS.

Exemplo

// Find the pixel width of the largest first substring.
CString str;
CSize sz;
int nIndex, dx = 0;
CDC *pDC = myListBox.GetDC();
for (int i = 0; i < myListBox.GetCount(); i++)
{
   myListBox.GetText(i, str);

   if ((nIndex = str.Find('\t')) != -1)
      str = str.Right(nIndex);

   sz = pDC->GetTextExtent(str);

   if (sz.cx > dx)
      dx = sz.cx;
}
myListBox.ReleaseDC(pDC);

// Set tab stops at every one and 1/3 units
// of the largest string.
// NOTE: Convert pixels to dialog units.
myListBox.SetTabStops((dx * 4 / 3 * 4) / LOWORD(::GetDialogBaseUnits()));

`CListBox::SetTopIndex`

Garante que um item de caixa de listagem específico esteja visível.

int SetTopIndex(int nIndex);

Parâmetros

nIndex
Especifica o índice baseado em zero do item da caixa de listagem.

Valor de retorno

Zero se for bem-sucedido. LB_ERR, se ocorrer um erro.

Comentários

O sistema rola a caixa de listagem até que o item especificado por nIndex apareça na parte superior da caixa de listagem ou até que o intervalo de rolagem máximo tenha sido atingido.

Exemplo

// Set the first visible item in the list box to be the middle item
m_myListBox.SetTopIndex(m_myListBox.GetCount() / 2);

`CListBox::VKeyToItem`

Chamado pela estrutura quando a janela pai da caixa de listagem recebe uma mensagem WM_VKEYTOITEM da caixa de listagem.

virtual int VKeyToItem(
    UINT nKey,
    UINT nIndex);

Parâmetros

nKey
O código de chave virtual da chave que o usuário pressionou. Para obter uma lista de códigos de tecla virtual padrão, consulte Winuser.h

nIndex
A posição atual do cursor de caixa de listagem.

Valor de retorno

Retorna - 2 para nenhuma ação adicional, - 1 para a ação padrão ou um número não interno para especificar um índice de um item de caixa de listagem no qual executar a ação padrão para o pressionamento de teclas.

Comentários

A mensagem WM_VKEYTOITEM é enviada pela caixa de listagem quando recebe uma mensagem WM_KEYDOWN, mas somente se a caixa de listagem atender aos dois seguintes:

Tem o conjunto de estilos LBS_WANTKEYBOARDINPUT.
Tem pelo menos um item.

Você nunca deve chamar essa função por conta própria. Substitua essa função para fornecer um tratamento personalizado próprio de mensagens de teclado.

Você deve retornar um valor para informar à estrutura qual ação sua substituição foi executada. Um valor retornado de - 2 indica que o aplicativo lidou com todos os aspectos da seleção do item e não requer nenhuma ação adicional por parte da caixa de listagem. Antes de retornar - 2, você pode definir a seleção ou mover o cursor ou ambos. Para definir a seleção, use SetCurSel ou SetSel. Para mover o cursor, use SetCaretIndex.

Um valor retornado de - 1 indica que a caixa de listagem deve executar a ação padrão em resposta ao pressionamento de tecla. A implementação padrão retorna - 1.

Exemplo

// CMyODListBox is my owner-drawn list box derived from CListBox. This
// example moves the caret down one item on the down key and up one item
// on the up key. The list box control was created with the following
// code:
//   m_myODListBox.Create(
//      WS_CHILD|WS_VISIBLE|WS_BORDER|WS_HSCROLL|WS_VSCROLL|
//      LBS_SORT|LBS_MULTIPLESEL|LBS_OWNERDRAWVARIABLE|LBS_WANTKEYBOARDINPUT,
//      CRect(10,250,200,450), pParentWnd, IDC_MYODLISTBOX);
//
int CMyODListBox::VKeyToItem(UINT nKey, UINT nIndex)
{
   // On key up, move the caret up one item.
   if ((nKey == VK_UP) && (nIndex > 0))
   {
      SetCaretIndex(nIndex - 1);
   }
   // On key down, move the caret down one item.
   else if ((nKey == VK_DOWN) && (nIndex < (UINT)GetCount()))
   {
      SetCaretIndex(nIndex + 1);
   }

   // Do not perform any default processing.
   return -2;
}

Confira também

Exemplo de MFC CTRLTEST
Classe CWnd
Gráfico da hierarquia
Classe CWnd
Classe CButton
Classe CComboBox
Classe CEdit
Classe CScrollBar
Classe CStatic

Partilhar via

Classe CListBox

Sintaxe

Membros

Construtores públicos

Métodos públicos

Comentários

Hierarquia de herança

Requisitos

CListBox::AddString

Parâmetros

Valor de retorno

Comentários

Exemplo

CListBox::CharToItem

Parâmetros

Valor de retorno

Comentários

Exemplo

CListBox::CListBox

Comentários

Exemplo

CListBox::CompareItem

Parâmetros

Valor de retorno

Comentários

Exemplo

CListBox::Create

Parâmetros

Valor de retorno

Comentários

Exemplo

CListBox::DeleteItem

Parâmetros

Comentários

Exemplo

CListBox::DeleteString

Parâmetros

Valor de retorno

Comentários

Exemplo

CListBox::Dir

Parâmetros

Valor de retorno

Exemplo

CListBox::DrawItem

Parâmetros

Comentários

Exemplo

CListBox::FindString

Parâmetros

Valor de retorno

Comentários

Exemplo

CListBox::FindStringExact

Parâmetros

Valor de retorno

Comentários

Exemplo

CListBox::GetAnchorIndex

Valor de retorno

Comentários

Exemplo

CListBox::GetCaretIndex

Valor de retorno

Comentários

Exemplo

CListBox::GetCount

Valor de retorno

Comentários

Exemplo

CListBox::GetCurSel

Valor de retorno

Comentários

Exemplo

CListBox::GetHorizontalExtent

Valor de retorno

Comentários

Exemplo

CListBox::GetItemData

Classe `CListBox`

`CListBox::AddString`

`CListBox::CharToItem`

`CListBox::CListBox`

`CListBox::CompareItem`

`CListBox::Create`

`CListBox::DeleteItem`

`CListBox::DeleteString`

`CListBox::Dir`

`CListBox::DrawItem`

`CListBox::FindString`

`CListBox::FindStringExact`

`CListBox::GetAnchorIndex`

`CListBox::GetCaretIndex`

`CListBox::GetCount`

`CListBox::GetCurSel`

`CListBox::GetHorizontalExtent`

`CListBox::GetItemData`

`CListBox::GetItemDataPtr`

`CListBox::GetItemHeight`

`CListBox::GetItemRect`

`CListBox::GetListBoxInfo`

`CListBox::GetLocale`

`CListBox::GetSel`

`CListBox::GetSelCount`

`CListBox::GetSelItems`

`CListBox::GetText`

`CListBox::GetTextLen`

`CListBox::GetTopIndex`

`CListBox::InitStorage`

`CListBox::InsertString`

`CListBox::ItemFromPoint`

`CListBox::MeasureItem`

`CListBox::ResetContent`