CListBox Classe

Fornece a funcionalidade de uma caixa de listas do Windows.

Sintaxe

class CListBox : public CWnd

Members

Construtores Públicos

Métodos Públicos

Observações

Uma caixa de lista mostra uma lista de itens, como nomes de ficheiros, que o utilizador pode visualizar e selecionar.

Numa caixa de lista de seleção única, o utilizador pode selecionar apenas um item. Numa caixa de lista de múltiplas seleções, pode ser selecionado uma variedade de itens. Quando o utilizador seleciona um item, este é destacado e a caixa de lista envia uma mensagem de notificação para a janela principal.

Podes criar uma caixa de lista a partir de um modelo de diálogo ou diretamente no teu código. Para o criar diretamente, constrói o CListBox objeto, depois chama a Create função membro para criar o controlo da caixa de listas do Windows e anexa-o ao CListBox objeto. Para usar uma caixa de lista num modelo de diálogo, declare uma variável de caixa de lista na sua classe de caixa de diálogo e depois use DDX_Control a função da DoDataExchange sua classe de caixa de diálogo para ligar a variável membro ao controlo. (Isto é feito automaticamente quando adicionas uma variável de controlo à tua classe de caixa de diálogo.)

A construção pode ser um processo de uma etapa numa classe derivada de CListBox. Escreva um construtor para a classe derivada e chame Create a partir do próprio construtor.

Se quiser tratar mensagens de notificação do Windows enviadas por uma caixa de lista para o seu pai (normalmente uma classe derivada de CDialog), adicione uma entrada de mapa de mensagens e uma função membro de manipulador de mensagens à classe pai para cada mensagem.

Cada entrada de mapa de mensagem assume a seguinte forma:

ON_Notification( id, memberFxn )

onde id especifica o ID da janela filho do controlo da caixa de lista que envia a notificação e memberFxn é o nome da função membro pai que escreveu para tratar da notificação.

O protótipo da função dos pais é o seguinte:

afx_msg void memberFxn( );

Segue-se uma lista de potenciais entradas no mapa de mensagens e uma descrição dos casos em que seriam enviadas ao pai:

• ON_LBN_DBLCLK O utilizador faz duplo clique numa string numa caixa de lista. Apenas uma caixa de lista com este LBS_NOTIFY estilo enviará esta mensagem de notificação.

• ON_LBN_ERRSPACE A caixa de lista não consegue alocar memória suficiente para cumprir o pedido.

• ON_LBN_KILLFOCUS A caixa da lista está a perder o foco de entrada.

• ON_LBN_SELCANCEL A seleção atual das caixas de lista está cancelada. Esta mensagem só é enviada quando uma caixa de lista tem o LBS_NOTIFY estilo.

• ON_LBN_SELCHANGE A seleção na caixa da lista mudou. Esta notificação não é enviada se a seleção for alterada pela CListBox::SetCurSel função membro. Esta notificação aplica-se apenas a uma caixa de lista que tenha esse LBS_NOTIFY estilo. A LBN_SELCHANGE mensagem de notificação é enviada para uma caixa de lista de múltiplas seleções sempre que o utilizador pressiona uma seta, mesmo que a seleção não mude.

• ON_LBN_SETFOCUS A caixa da lista está a receber o foco de entrada.

• ON_WM_CHARTOITEM Uma caixa de lista de sorteio do proprietário que não tem sequências recebe uma WM_CHAR mensagem.

• ON_WM_VKEYTOITEM Uma caixa de lista com o LBS_WANTKEYBOARDINPUT estilo recebe uma WM_KEYDOWN mensagem.

Se criar um CListBox objeto dentro de uma caixa de diálogo (através de um recurso de diálogo), o CListBox objeto é automaticamente destruído quando o utilizador fecha a caixa de diálogo.

Se criar um CListBox objeto dentro de uma janela, pode ser necessário destruí-lo CListBox . Se criares o CListBox objeto na pilha, ele é destruído automaticamente. Se criares o CListBox objeto no heap usando a new função, deves invocar delete o objeto para o destruir quando o utilizador fecha a janela principal.

Se alocar alguma memória no CListBox objeto, sobrescrita o CListBox destruidor para eliminar a alocação.

Hierarquia de herança

CObject

CCmdTarget

CWnd

CListBox

Requerimentos

Cabeçalho:afxwin.h

CListBox::AddString

Adiciona uma cadeia a uma caixa de lista.

int AddString(LPCTSTR lpszItem);

Parâmetros

lpszItem
Aponta para a cadeia terminada por nulo que deve ser adicionada.

Valor de retorno

O índice baseado em zero para a string na caixa de lista. O valor de retorno é LB_ERR se ocorrer um erro; o valor de retorno é LB_ERRSPACE se não houver espaço suficiente disponível para armazenar a nova cadeia.

Observações

Se a caixa da lista não foi criada com o LBS_SORT estilo, a cadeia é adicionada ao final da lista. Caso contrário, a cadeia é inserida na lista, e a lista é ordenada. Se a caixa de lista foi criada com o LBS_SORT estilo mas não com o LBS_HASSTRINGS estilo, o framework ordena a lista por uma ou mais chamadas para a CompareItem função membro.

Use InsertString para inserir um fio numa localização específica dentro da caixa da lista.

Example

// 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

Chamada pela framework quando a janela principal da caixa de lista recebe uma WM_CHARTOITEM mensagem da caixa de lista.

virtual int CharToItem(
    UINT nKey,
    UINT nIndex);

Parâmetros

nKey
O código ANSI do carácter que o utilizador escreveu.

nIndex
A posição atual da caixa de lista.

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 da caixa de lista sobre o qual realizar a ação padrão para a tecla pressionada. A implementação padrão retorna - 1.

Observações

A WM_CHARTOITEM mensagem é enviada pela caixa de lista quando recebe uma WM_CHAR mensagem, mas apenas se a caixa de lista cumprir todos estes critérios:

• É uma caixa de lista de sorteio do proprietário.

• Não tem o conjunto de LBS_HASSTRINGS estilos.

• Tem pelo menos um item.

Nunca deves chamar esta função tu próprio. Substitua esta função para fornecer o seu próprio tratamento personalizado das mensagens do teclado.

No seu override, deve devolver um valor para indicar ao framework que ação realizou. Um valor de retorno de - 1 ou - 2 indica que tratou de todos os aspetos da seleção do item e não requer qualquer ação adicional por parte da caixa da lista. Antes de voltar - 1 ou - 2, pode definir a seleção ou mover o caret ou ambos. Para definir a seleção, use SetCurSel ou SetSel. Para mover o cardete, use SetCaretIndex.

Um valor de retorno de 0 ou superior especifica o índice de um item na caixa de lista e indica que a caixa de lista deve executar a ação padrão para a tecla pressionada no item dado.

Example

// 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 CListBox objeto.

CListBox();

Observações

Constroem um CListBox objeto em dois passos. Primeiro, chame o construtor ClistBox e depois chame Create, que inicializa a caixa de lista do Windows e a anexa ao CListBox.

Example

// Declare a local CListBox object.
CListBox myListBox;

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

CListBox::CompareItem

Chamado pelo framework para determinar a posição relativa de um novo item numa caixa ordenada de lista de sorteio do proprietário.

virtual int CompareItem(LPCOMPAREITEMSTRUCT lpCompareItemStruct);

Parâmetros

lpCompareItemStruct
Um longo indicador para uma COMPAREITEMSTRUCT estrutura.

Valor de retorno

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

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

Observações

Por defeito, esta função membro não faz nada. Se criar uma caixa de lista de sorteio proprietário com o LBS_SORT estilo, deve sobrescrever esta função de membro para ajudar o framework a ordenar os novos itens adicionados à caixa da lista.

Example

// 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 lista do Windows e anexa-a ao CListBox objeto.

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

Parâmetros

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

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

pParentWnd
Especifica a janela principal da caixa de lista (normalmente um CDialog objeto). Não pode ser NULL.

nID
Especifica o ID de controlo da caixa de lista.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0.

Observações

Constroem um CListBox objeto em dois passos. Primeiro, chame o construtor e depois chame Create, que inicializa a caixa de lista do Windows e a anexa ao CListBox objeto.

Quando Create executa, o Windows envia as WM_NCCREATEmensagens , WM_CREATE, WM_NCCALCSIZE, e WM_GETMINMAXINFO para o controlo da caixa de lista.

Estas mensagens são tratadas por defeito pelas OnNcCreatefunções , OnCreate, OnNcCalcSize, e OnGetMinMaxInfo membros na CWnd classe base. Para estender o tratamento de mensagens por defeito, derive uma classe a partir de CListBox, adicione um mapa de mensagens à nova classe e sobrescrita as funções membros do manipulador de mensagens anteriores. Override OnCreate, por exemplo, para realizar a inicialização necessária para uma nova classe.

Aplique os seguintes estilos de janela a um controlo de caixa de lista.

• WS_CHILD Sempre

• WS_VISIBLE Normalmente

• WS_DISABLED Raramente

• WS_VSCROLL Para adicionar uma barra de scroll vertical

• WS_HSCROLL Para adicionar uma barra de deslocamento horizontal

• WS_GROUP Para agrupar controlos

• WS_TABSTOP Para permitir a separação para este controlo

Example

// 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

Chamada pela framework quando o utilizador elimina um item de um objeto proprietário-draw CListBox ou destrói a caixa da lista.

virtual void DeleteItem(LPDELETEITEMSTRUCT lpDeleteItemStruct);

Parâmetros

lpDeleteItemStruct
Um ponteiro longo para uma estrutura do Windows DELETEITEMSTRUCT que contém informação sobre o item eliminado.

Observações

A implementação padrão desta função não faz nada. Substitua esta função para redesenhar uma caixa da lista de sorteio do proprietário conforme necessário.

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

Example

// 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

Apaga o item na posição nIndex da caixa da lista.

int DeleteString(UINT nIndex);

Parâmetros

nIndex
Especifica o índice baseado em zero da cadeia a eliminar.

Valor de retorno

Uma contagem das cordas que restam na lista. O valor de retorno é LB_ERR se nIndex especificar um índice superior ao número de itens na lista.

Observações

Todos os itens seguintes nIndex deslocam-se agora uma posição para baixo. Por exemplo, se uma caixa de lista contiver dois itens, eliminar o primeiro item fará com que o restante fique agora na primeira posição. nIndex=0 para o item na primeira posição.

Example

// 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 ficheiros, discos ou ambos a uma caixa de lista.

int Dir(
    UINT attr,
    LPCTSTR lpszWildCard);

Parâmetros

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

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

Valor de retorno

O índice em base zero do último nome de ficheiro foi adicionado à lista. O valor de retorno é LB_ERR se ocorrer um erro; o valor de retorno é LB_ERRSPACE se não houver espaço suficiente disponível para armazenar as novas cadeias.

Example

// 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

Chamada pelo framework quando um aspeto visual de uma caixa de lista de sorteio do proprietário muda.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parâmetros

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

Observações

Os itemAction membros e itemState da DRAWITEMSTRUCT estrutura definem a ação de desenho que deve ser realizada.

Por defeito, esta função membro não faz nada. Substitua esta função de membro para implementar desenho para um objeto proprietário-desenho CListBox . A aplicação deve restaurar todos os objetos da interface do dispositivo gráfico (GDI) selecionados para o contexto de visualização fornecido lpDrawItemStruct antes de esta função membro terminar.

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

Example

// 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

Encontra a primeira cadeia numa caixa de lista que contém o prefixo especificado sem alterar a seleção da caixa de lista.

int FindString(
    int nStartAfter,
    LPCTSTR lpszItem) const;

Parâmetros

nStartAfter
Contém o índice em base zero do item antes do primeiro item a ser pesquisado. Quando a pesquisa chega ao fundo da caixa de lista, continua do topo da caixa de lista de volta ao item especificado por nStartAfter. Se nStartAfter for -1, toda a caixa da lista é pesquisada desde o início.

lpszItem
Aponta para a cadeia terminada por nulo que contém o prefixo a procurar. A pesquisa é independente do caso, pelo que esta cadeia 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 tiver sido bem-sucedida.

Observações

Use a SelectString função membro para encontrar e selecionar uma cadeia.

Example

// 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

Encontra a primeira cadeia de lista que corresponde à cadeia especificada em lpszFind.

int FindStringExact(
    int nIndexStart,
    LPCTSTR lpszFind) const;

Parâmetros

nIndexStart
Especifica o índice base zero do item antes do primeiro item a ser pesquisado. Quando a pesquisa chega ao fundo da caixa de lista, continua do topo da caixa de lista de volta ao item especificado por nIndexStart. Se nIndexStart for -1, toda a caixa da lista é pesquisada desde o início.

lpszFind
Aponta para a cadeia terminada nula a procurar. Esta cadeia pode conter um nome de ficheiro completo, incluindo a extensão. A pesquisa não distingue maiúsculas e minúsculas, pelo que a cadeia 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 tivesse sido bem-sucedida.

Observações

Se a caixa de lista foi criada com um estilo proprietário-draw mas sem o LBS_HASSTRINGS estilo, a FindStringExact função membro tenta comparar o valor da palavra dupla com o valor de lpszFind.

Example

// 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 em base zero do item âncora atual na caixa da lista.

int GetAnchorIndex() const;

Valor de retorno

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

Observações

Numa caixa de lista de seleção múltipla, o item âncora é o primeiro ou último item num bloco de itens selecionados contíguos.

Example

Veja o exemplo para CListBox::SetAnchorIndex.

CListBox::GetCaretIndex

Determina o índice do item que tem o rectângulo de foco numa caixa de lista de seleção múltipla.

int GetCaretIndex() const;

Valor de retorno

O índice em base zero do item que tem o retângulo de foco numa caixa de lista. Se a caixa de lista for de seleção única, o valor de retorno é o índice do item selecionado, se existir.

Observações

O item pode ou não ser selecionado.

Example

Veja o exemplo para CListBox::SetCaretIndex.

CListBox::GetCount

Recupera o número de itens numa caixa de lista.

int GetCount() const;

Valor de retorno

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

Observações

A contagem devolvida é um acima do valor do índice do último item (o índice é baseado em zero).

Example

// 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 em base zero do item atualmente selecionado, se existir, numa caixa de lista de seleção única.

int GetCurSel() const;

Valor de retorno

O índice em base zero do item atualmente selecionado se for uma caixa de lista de seleção única. É LB_ERR se não for selecionado nenhum item no momento.

Numa caixa de lista de múltiplas seleções, o índice do item que tem o foco.

Observações

Não peça GetCurSel uma caixa de lista de múltiplas seleções. Utilize CListBox::GetSelItems em substituição.

Example

// 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 lista a largura em pixels pela qual pode ser deslocado horizontalmente.

int GetHorizontalExtent() const;

Valor de retorno

A largura deslizável da caixa da lista, em pixels.

Observações

Isto aplica-se apenas se a caixa de lista tiver uma barra de scroll horizontal.

Example

// 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 pela aplicação associado ao item especificado da caixa de lista.

DWORD_PTR GetItemData(int nIndex) const;

Parâmetros

nIndex
Especifica o índice em base zero do item na caixa da lista.

Valor de retorno

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

Observações

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

Example

// 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 pela aplicação associado ao item especificado da caixa de lista como um ponteiro (void*).

void* GetItemDataPtr(int nIndex) const;

Parâmetros

nIndex
Especifica o índice em base zero do item na caixa da lista.

Valor de retorno

Recupera um ponteiro, ou -1 se ocorrer um erro.

Example

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 numa caixa de lista.

int GetItemHeight(int nIndex) const;

Parâmetros

nIndex
Especifica o índice em base zero do item na caixa da lista. Este parâmetro é usado apenas se a caixa da lista tiver o estilo; LBS_OWNERDRAWVARIABLE caso contrário, deve ser definido para 0.

Valor de retorno

A altura, em pixels, dos itens na caixa da lista. Se a caixa da lista tiver o LBS_OWNERDRAWVARIABLE estilo, o valor de retorno é a altura do item especificado por nIndex. Se ocorrer um erro, o valor de retorno é LB_ERR.

Example

// 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 da caixa de lista tal como está atualmente exibido na janela da caixa de lista.

int GetItemRect(
    int nIndex,
    LPRECT lpRect) const;

Parâmetros

nIndex
Especifica o índice baseado em zero do item.

lpRect
Especifica um ponteiro longo para uma RECT estrutura que recebe as coordenadas do cliente list-box do item.

Valor de retorno

LB_ERR se ocorrer um erro.

Example

// 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 CListBox objeto.

Observações

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

CListBox::GetLocale

Recupera a localização usada pela caixa da lista.

LCID GetLocale() const;

Valor de retorno

O valor do identificador local (LCID) para as strings na caixa da lista.

Observações

A localização é usada, por exemplo, para determinar a ordem de ordenação das cadeias numa caixa de lista ordenada.

Example

Veja o exemplo para CListBox::SetLocale.

CListBox::GetSel

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

int GetSel(int nIndex) const;

Parâmetros

nIndex
Especifica o índice baseado em zero do item.

Valor de retorno

Um número positivo se o item especificado for selecionado; caso contrário, é 0. O valor de retorno é LB_ERR se ocorrer um erro.

Observações

Esta função de membro funciona tanto com caixas de lista de seleção única como múltipla.

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

Example

// 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 numa caixa de lista de múltiplas seleções.

int GetSelCount() const;

Valor de retorno

A contagem de itens selecionados numa caixa de lista. Se a caixa de lista for uma caixa de lista de seleção única, o valor de retorno é LB_ERR.

Example

Veja o exemplo para CListBox::GetSelItems.

CListBox::GetSelItems

Preenche um buffer com um array de inteiros que especifica os números dos itens selecionados numa caixa de lista de múltiplas seleções.

int GetSelItems(
    int nMaxItems,
    LPINT rgIndex) const;

Parâmetros

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

rgIndex
Especifica um ponteiro para um buffer suficientemente grande 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 lista for uma caixa de lista de seleção única, o valor de retorno é LB_ERR.

Example

// 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 um fio de uma caixa de lista.

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 a recuperar.

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

rString
Uma referência a um CString objeto.

Valor de retorno

O comprimento (em bytes) da string, excluindo o carácter nulo que termina. Se nIndex não especificar um índice válido, o valor de retorno é LB_ERR.

Observações

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

Example

// 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 string num item da caixa de lista.

int GetTextLen(int nIndex) const;

Parâmetros

nIndex
Especifica o índice baseado em zero da cadeia.

Valor de retorno

O comprimento da cadeia em caracteres, excluindo o carácter nulo de terminação. Se nIndex não especificar um índice válido, o valor de retorno é LB_ERR.

Example

Veja o exemplo para CListBox::GetText.

CListBox::GetTopIndex

Recupera o índice baseado em zero do primeiro item visível numa caixa de lista.

int GetTopIndex() const;

Valor de retorno

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

Observações

Inicialmente, o item 0 está no topo da caixa da lista, mas se a caixa da lista estiver deslocada, outro item pode estar no topo.

Example

// 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 da caixa de lista.

int InitStorage(
    int nItems,
    UINT nBytes);

Parâmetros

nItems
Especifica o número de itens para os quais reservar espaço.

nBytes
Especifica a quantidade de memória adicional, em bytes, a alocar para cadeias de itens.

Valor de retorno

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

Observações

Pode chamar esta função antes de adicionar um grande número de itens a um CListBox.

Esta função ajuda a acelerar a inicialização de caixas de lista que contêm um grande número de itens (mais de 100). Pré-aloca a quantidade de memória especificada para que as funções subsequentes AddStringsejam mais eficientesInsertStringDir. Pode usar estimativas para os parâmetros. Se sobrestimar, a memória extra permanece alocada; Se subestimar, a caixa da lista aloca memória adicional conforme necessário.

A memória necessária para armazenar uma cadeia inclui o terminador nulo. Portanto, se planeia adicionar 100 cadeias, cada uma com um comprimento de 10 caracteres, passaria um wParam de 100 e um lParam de 100 × (10 + 1) × tamanho de (TCHAR).

Apenas Windows 95/98: O nItems parâmetro está limitado a valores de 16 bits. Isto significa que as caixas de lista não podem conter mais de 32.767 itens. Embora o número de itens seja limitado, o tamanho total dos itens numa caixa de lista é limitado apenas pela memória disponível.

Example

// Reserve space in the list box for 256 additional strings with
// about 15 characters per string.
int n = m_myListBox.InitStorage(256, 256 * (15 + 1) * 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 um fio na caixa da lista.

int InsertString(
    int nIndex,
    LPCTSTR lpszItem);

Parâmetros

nIndex
Especifica o índice baseado em zero da posição a inserir a cadeia. Se este parâmetro for -1, a cadeia é adicionada ao final da lista.

lpszItem
Aponta para a cadeia terminada por nulo que deve ser inserida.

Valor de retorno

O índice baseado em zero da posição em que a sequência foi inserida. O valor de retorno é LB_ERR se ocorrer um erro; o valor de retorno é LB_ERRSPACE se não houver espaço suficiente disponível para armazenar a nova cadeia.

Observações

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

Example

// 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 da caixa de lista mais próximo do ponto especificado em pt.

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

Parâmetros

pt
Ponto para encontrar o item mais próximo, especificado em relação ao canto superior esquerdo da área do cliente na caixa da lista.

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

Valor de retorno

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

Observações

Podes usar esta função para determinar em que item da caixa de lista o cursor do rato se move.

Example

Veja o exemplo para CListBox::SetAnchorIndex.

CListBox::MeasureItem

Chamada pelo framework quando é criada uma caixa de lista com um estilo proprietário-draw.

virtual void MeasureItem(LPMEASUREITEMSTRUCT lpMeasureItemStruct);

Parâmetros

lpMeasureItemStruct
Um longo indicador para uma MEASUREITEMSTRUCT estrutura.

Observações

Por defeito, esta função membro não faz nada. Sobrescreva esta função membro e preencha a MEASUREITEMSTRUCT estrutura para informar o Windows das dimensões da caixa de lista. Se a caixa de lista for criada com o LBS_OWNERDRAWVARIABLE estilo, o framework chama esta função membro para cada item na caixa de lista. Caso contrário, este membro é chamado apenas uma vez.

Para mais informações sobre o uso do LBS_OWNERDRAWFIXED estilo numa caixa de lista de sorteio do proprietário criada com a SubclassDlgItem função membro de CWnd, veja a discussão na Nota Técnica 14.

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

Example

// 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 de uma caixa de lista.

void ResetContent();

Example

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

CListBox::SelectString

Procura um item na caixa de lista que corresponda à string especificada e, se for encontrado um item correspondente, seleciona esse item.

int SelectString(
    int nStartAfter,
    LPCTSTR lpszItem);

Parâmetros

nStartAfter
Contém o índice em base zero do item antes do primeiro item a ser pesquisado. Quando a pesquisa chega ao fundo da caixa de lista, continua do topo da caixa de lista de volta ao item especificado por nStartAfter. Se nStartAfter for -1, toda a caixa da lista é pesquisada desde o início.

lpszItem
Aponta para a cadeia terminada por nulo que contém o prefixo a procurar. A pesquisa é independente do caso, pelo que esta cadeia pode conter qualquer combinação de letras maiúsculas e minúsculas.

Valor de retorno

O índice do item selecionado caso a pesquisa tenha sido bem-sucedida. Se a pesquisa não foi bem-sucedida, o valor de retorno é LB_ERR e a seleção atual não são alterados.

Observações

A caixa da lista é deslocada, se necessário, para mostrar o item selecionado.

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

Um item só é selecionado se os seus caracteres iniciais (a partir do ponto de partida) coincidirem com os caracteres da cadeia especificada por lpszItem.

Use a FindString função membro para encontrar uma cadeia sem selecionar o item.

Example

// 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 múltiplos itens consecutivos numa caixa de lista de múltiplas seleções.

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

Parâmetros

bSelect
Especifica como definir a seleção. Se bSelect for TRUE, a corda é selecionada e destacada; se FALSE, o destaque é removido e a sequência deixa de ser selecionada.

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

nLastItem
Especifica o índice em base zero do último item a definir.

Valor de retorno

LB_ERR se ocorrer um erro.

Observações

Use esta função de membro apenas com caixas de lista de múltiplas seleções. Se precisar de selecionar apenas um item numa caixa de lista de múltiplas seleções — ou seja, se nFirstItem for igual a nLastItem — chame a SetSel função membro em vez disso.

Example

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

CListBox::SetAnchorIndex

Coloca a âncora numa caixa de lista de múltiplas seleções para iniciar uma seleção prolongada.

void SetAnchorIndex(int nIndex);

Parâmetros

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

Observações

Numa caixa de lista de seleção múltipla, o item âncora é o primeiro ou último item num bloco de itens selecionados contíguos.

Example

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 numa caixa de lista de múltiplas seleções.

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

Parâmetros

nIndex
Especifica o índice base zero do item a receber o retângulo de foco na caixa da lista.

bScroll
Se este valor for 0, o item é deslocado até ficar totalmente visível. Se este valor não for 0, o item é deslocado até ficar pelo menos parcialmente visível.

Valor de retorno

LB_ERR se ocorrer um erro.

Observações

Se o item não for visível, ele é deslocado para a vista.

Example

// 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 numa caixa de lista multicoluna (criada com o estilo).LBS_MULTICOLUMN

void SetColumnWidth(int cxWidth);

Parâmetros

cxWidth
Especifica a largura em píxeis de todas as colunas.

Example

// 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 um fio e desliza-o para a vista, se necessário.

int SetCurSel(int nSelect);

Parâmetros

nSelect
Especifica o índice baseado em zero da cadeia a selecionar. Se nSelect for -1, a caixa da lista está definida para não ter seleção.

Valor de retorno

LB_ERR se ocorrer um erro.

Observações

Quando a nova cadeia é selecionada, a caixa da lista remove o destaque da cadeia previamente selecionada.

Use esta função de membro apenas com caixas de lista de seleção única.

Para definir ou remover uma seleção numa caixa de lista de múltiplas seleções, use CListBox::SetSel.

Example

// 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 lista pode ser deslocada horizontalmente.

void SetHorizontalExtent(int cxExtent);

Parâmetros

cxExtent
Especifica o número de píxeis pelos quais a caixa de lista pode ser deslocada horizontalmente.

Observações

Se o tamanho da caixa da lista for menor do que este valor, a barra horizontal de scroll irá deslocar horizontalmente os itens na caixa da lista. Se a caixa da lista for tão grande ou maior do que este valor, a barra horizontal de scroll fica oculta.

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

Esta função membro não é útil para caixas de lista multicolunas. Para caixas de lista multicolunas, chame a SetColumnWidth função membro.

Example

// 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 numa caixa de lista.

int SetItemData(
    int nIndex,
    DWORD_PTR dwItemData);

Parâmetros

nIndex
Especifica o índice baseado em zero do item.

dwItemData
Especifica o valor a associar ao item.

Valor de retorno

LB_ERR se ocorrer um erro.

Example

// 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 numa caixa de lista como o ponteiro especificado ( void*).

int SetItemDataPtr(
    int nIndex,
    void* pData);

Parâmetros

nIndex
Especifica o índice baseado em zero do item.

pData
Especifica o ponteiro a ser associado ao item.

Valor de retorno

LB_ERR se ocorrer um erro.

Observações

Este ponteiro mantém-se válido durante toda a vida útil da caixa da lista, mesmo que a posição relativa do item dentro da caixa da lista possa mudar à medida que os itens são adicionados ou removidos. Assim, o índice do item dentro da caixa pode mudar, mas o ponteiro mantém-se fiável.

Example

// 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 numa caixa de lista.

int SetItemHeight(
    int nIndex,
    UINT cyItemHeight);

Parâmetros

nIndex
Especifica o índice em base zero do item na caixa da lista. Este parâmetro é usado apenas se a caixa da lista tiver o estilo; LBS_OWNERDRAWVARIABLE caso contrário, deve ser definido para 0.

cyItemHeight
Especifica a altura, em pixels, do item.

Valor de retorno

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

Observações

Se a caixa de lista tiver o LBS_OWNERDRAWVARIABLE estilo, esta função define a altura do item especificado por nIndex. Caso contrário, esta função define a altura de todos os itens na caixa da lista.

Example

// 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 o identificador local para esta caixa de lista.

LCID SetLocale(LCID nNewLocale);

Parâmetros

nNewLocale
O novo valor do identificador local (LCID) a definir para a caixa de lista.

Valor de retorno

O valor anterior do identificador local (LCID) para esta caixa de lista.

Observações

Se SetLocale não for chamado, a localização padrão é obtida do sistema. Esta localização por defeito do sistema pode ser modificada usando a aplicação Regional (ou Internacional) do Painel de Controlo.

Example

// 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 numa caixa de lista de múltiplas seleções.

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

Parâmetros

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

bSelect
Especifica como definir a seleção. Se bSelect for TRUE, a corda é selecionada e destacada; se FALSE, o destaque é removido e a sequência deixa de ser selecionada. A cadeia especificada é selecionada e destacada por defeito.

Valor de retorno

LB_ERR se ocorrer um erro.

Observações

Use esta função de membro apenas com caixas de lista de múltiplas seleções.

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

Example

// 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 do tab-stop numa caixa de lista.

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 cxEachStop unidades de diálogo. Veja rgTabStops para uma descrição de uma unidade de diálogo.

nTabStops
Especifica o número de tabulações a ter na caixa da lista.

rgTabStops
Aponta para o primeiro membro de um array de inteiros contendo as posições tab-stop nas unidades de diálogo. Uma unidade de diálogo é uma distância horizontal ou vertical. Uma unidade horizontal de diálogo é igual a um quarto da unidade atual de largura da base de diálogo, e uma unidade vertical de diálogo é igual a um oitavo da unidade atual de altura da base de diálogo. As unidades base de diálogo são calculadas com base na altura e largura da fonte atual do sistema. A GetDialogBaseUnits função Windows devolve as unidades base de diálogo atuais em pixels. Os registos de tabulação devem ser organizados por ordem crescente; As abas traseiras não são permitidas.

Valor de retorno

Diferente de zero se todos os separadores estivessem definidos; caso contrário, 0.

Observações

Para definir os tabs stops para o tamanho padrão de 2 unidades de diálogo, chame a versão sem parâmetros desta função membro. Para definir as tabulações para um tamanho diferente de 2, chame a versão com o cxEachStop argumento.

Para definir os tabs stops para um array de tamanhos, use a versão com os rgTabStops argumentos e nTabStops . Será definida uma parada de tabulação para cada valor em rgTabStops, até ao número especificado por nTabStops.

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

Example

// 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 determinado item da caixa de lista é visível.

int SetTopIndex(int nIndex);

Parâmetros

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

Valor de retorno

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

Observações

O sistema percorre a caixa de lista até que o item especificado por nIndex apareça no topo da caixa de lista ou até que o intervalo máximo de scroll seja atingido.

Example

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

CListBox::VKeyToItem

Chamada pela framework quando a janela principal da caixa de lista recebe uma WM_VKEYTOITEM mensagem da caixa de lista.

virtual int VKeyToItem(
    UINT nKey,
    UINT nIndex);

Parâmetros

nKey
O código virtual da tecla pressionada pelo utilizador. Para uma lista de códigos de chave virtuais padrão, veja Winuser.h

nIndex
A posição atual da caixa de lista.

Valor de retorno

Devolve - 2 para não haver mais ação, - 1 para ação por defeito, ou um número não negativo para especificar um índice de um item da caixa de lista onde realizar a ação padrão para a tecla pressionada.

Observações

A WM_VKEYTOITEM mensagem é enviada pela caixa de lista quando recebe uma WM_KEYDOWN mensagem, mas apenas se a caixa de lista cumprir ambos os seguintes critérios:

• Tem o LBS_WANTKEYBOARDINPUT estilo definido.

• Tem pelo menos um item.

Nunca deves chamar esta função tu próprio. Substitua esta função para fornecer o seu próprio tratamento personalizado das mensagens do teclado.

Deve devolver um valor para indicar ao framework qual a ação que a sua sobreposição realizou. Um valor de retorno de - 2 indica que a aplicação tratou de todos os aspetos da seleção do item e não requer qualquer ação adicional na caixa da lista. Antes de voltar - 2, podes definir a seleção ou mover o caret ou ambos. Para definir a seleção, use SetCurSel ou SetSel. Para mover o cardete, use SetCaretIndex.

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

Um valor de retorno de 0 ou superior especifica o índice de um item na caixa de lista e indica que a caixa de lista deve executar a ação padrão para a tecla pressionada no item dado.

Example

// 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;
}

Consulte também

CTRLTEST de Exemplo MFC
CWnd Classe
Quadro Hierárquico
CWnd Classe
CButton Classe
CComboBox Classe
CEdit Classe
CScrollBar Classe
CStatic Classe