Classe `CListCtrl`

Artigo
07/05/2024

Encapsula a funcionalidade de um "controle de exibição de lista", que mostra uma coleção de itens que consistem em um ícone (de uma lista de imagens) e uma etiqueta.

Sintaxe

class CListCtrl : public CWnd

Membros

Construtores públicos

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

Métodos públicos

Nome	Descrição
`CListCtrl::ApproximateViewRect`	Determina a largura e a altura necessárias para exibir os itens de um controle de exibição de lista.
`CListCtrl::Arrange`	Alinha os itens em uma grade.
`CListCtrl::CancelEditLabel`	Cancela a operação de edição de texto do item.
`CListCtrl::Create`	Cria um controle de lista e o anexa a um objeto `CListCtrl`.
`CListCtrl::CreateDragImage`	Cria uma lista de imagens de arrasto para um item especificado.
`CListCtrl::CreateEx`	Cria um controle de lista com os estilos estendidos especificados do Windows e o anexa a um objeto `CListCtrl`.
`CListCtrl::DeleteAllItems`	Exclui todos os itens do controle.
`CListCtrl::DeleteColumn`	Exclui uma coluna do controle de exibição de lista.
`CListCtrl::DeleteItem`	Exclui um item do controle.
`CListCtrl::DrawItem`	Chamado quando um aspecto visual de um controle desenhado pelo proprietário é alterado.
`CListCtrl::EditLabel`	Inicia a edição in-loco do texto de um item.
`CListCtrl::EnableGroupView`	Habilita ou desabilita se os itens em um controle de exibição de lista são exibidos como um grupo.
`CListCtrl::EnsureVisible`	Garante que um item esteja visível.
`CListCtrl::FindItem`	Pesquisa um item de exibição de lista com características específicas.
`CListCtrl::GetBkColor`	Recupera a cor da tela de fundo de um controle de exibição de lista.
`CListCtrl::GetBkImage`	Recupera a imagem em segundo plano atual de um controle de exibição de lista.
`CListCtrl::GetCallbackMask`	Recupera a máscara de retorno de chamada de um controle de exibição de lista.
`CListCtrl::GetCheck`	Recupera o status de exibição atual da imagem de estado associada a um item.
`CListCtrl::GetColumn`	Recupera os atributos da coluna de um controle.
`CListCtrl::GetColumnOrderArray`	Recupera a ordem da coluna (da esquerda para a direita) de um controle de exibição de lista.
`CListCtrl::GetColumnWidth`	Recupera a largura de uma coluna no modo de exibição de relatório ou de lista.
`CListCtrl::GetCountPerPage`	Calcula o número de itens que podem caber verticalmente em um controle de exibição de lista.
`CListCtrl::GetEditControl`	Recupera o identificador do controle de edição usado para editar o texto de um item.
`CListCtrl::GetEmptyText`	Recupera a cadeia de caracteres a ser exibida se o controle de exibição de lista atual estiver vazio.
`CListCtrl::GetExtendedStyle`	Recupera os estilos estendidos atuais de um controle de exibição de lista.
`CListCtrl::GetFirstSelectedItemPosition`	Recupera a posição do primeiro item de exibição de lista selecionado em um controle de exibição de lista.
`CListCtrl::GetFocusedGroup`	Recupera o grupo com o teclado focado no controle de exibição de lista atual.
`CListCtrl::GetGroupCount`	Recupera o número de grupos no controle de exibição de lista atual.
`CListCtrl::GetGroupInfo`	Obtém as informações para um grupo especificado do controle de exibição de lista.
`CListCtrl::GetGroupInfoByIndex`	Recupera as informações de um grupo especificado no controle de exibição de lista atual.
`CListCtrl::GetGroupMetrics`	Recupera as métricas de um grupo.
`CListCtrl::GetGroupRect`	Recupera o retângulo delimitador para um grupo especificado no controle de exibição de lista atual.
`CListCtrl::GetGroupState`	Recupera o estado para um grupo especificado no controle de exibição de lista atual.
`CListCtrl::GetHeaderCtrl`	Recupera o controle de cabeçalho de um controle de exibição de lista.
`CListCtrl::GetHotCursor`	Recupera o cursor usado quando o rastreio importante está habilitado para um controle de exibição de lista.
`CListCtrl::GetHotItem`	Recupera o item de exibição de lista atualmente no cursor.
`CListCtrl::GetHoverTime`	Recupera o tempo de foco atual de um controle de exibição de lista.
`CListCtrl::GetImageList`	Recupera o identificador de uma lista de imagens usada para desenhar itens de exibição de lista.
`CListCtrl::GetInsertMark`	Recupera a posição atual da marca de inserção.
`CListCtrl::GetInsertMarkColor`	Recupera a cor atual da marca de inserção.
`CListCtrl::GetInsertMarkRect`	Recupera o retângulo que vincula o ponto de inserção.
`CListCtrl::GetItem`	Recupera os atributos de um item de exibição de lista.
`CListCtrl::GetItemCount`	Recupera o número de itens em um controle de exibição de lista.
`CListCtrl::GetItemData`	Recupera o valor específico do aplicativo associado a um item.
`CListCtrl::GetItemIndexRect`	Recupera o retângulo delimitador para todos ou parte de um subitem no controle de exibição de lista atual.
`CListCtrl::GetItemPosition`	Recupera a posição de um item de exibição de lista.
`CListCtrl::GetItemRect`	Recupera o retângulo delimitador de um item.
`CListCtrl::GetItemSpacing`	Calcula o espaçamento entre os itens no controle de exibição de lista atual.
`CListCtrl::GetItemState`	Recupera o estado de um item de exibição de lista.
`CListCtrl::GetItemText`	Recupera o texto de um item ou subitem de exibição de lista.
`CListCtrl::GetNextItem`	Pesquisa um item de exibição de lista com as propriedades especificadas e com a relação especificada para um determinado item.
`CListCtrl::GetNextItemIndex`	Recupera o índice do item no controle de exibição de lista atual com um conjunto de propriedades especificado.
`CListCtrl::GetNextSelectedItem`	Recupera o índice de uma posição de item de exibição de lista e a posição do próximo item de exibição de lista selecionado para iteração.
`CListCtrl::GetNumberOfWorkAreas`	Recupera o número atual de áreas de trabalho para um controle de exibição de lista.
`CListCtrl::GetOrigin`	Recupera a origem do modo de exibição atual para um controle de exibição de lista.
`CListCtrl::GetOutlineColor`	Recupera a cor da borda de um controle de exibição de lista.
`CListCtrl::GetSelectedColumn`	Recupera o índice da coluna selecionada no momento no controle de lista.
`CListCtrl::GetSelectedCount`	Recupera o número de itens selecionados no controle de exibição de lista.
`CListCtrl::GetSelectionMark`	Recupera a marca de seleção de um controle de exibição de lista.
`CListCtrl::GetStringWidth`	Determina a largura mínima da coluna necessária para exibir toda a cadeia de caracteres fornecida.
`CListCtrl::GetSubItemRect`	Recupera o retângulo delimitador de um item em um controle de exibição de lista.
`CListCtrl::GetTextBkColor`	Recupera a cor da tela de fundo do texto de um controle de exibição de lista.
`CListCtrl::GetTextColor`	Recupera a cor do texto de um controle de exibição de lista.
`CListCtrl::GetTileInfo`	Recupera informações sobre um bloco em um controle de exibição de lista.
`CListCtrl::GetTileViewInfo`	Recupera informações sobre um controle de exibição de lista na exibição de bloco.
`CListCtrl::GetToolTips`	Recupera o controle de dica de ferramenta usado pelo controle de exibição de lista para exibir dicas de ferramentas.
`CListCtrl::GetTopIndex`	Recupera o índice do item visível mais alto.
`CListCtrl::GetView`	Obtém a exibição do controle de exibição de lista.
`CListCtrl::GetViewRect`	Recupera o retângulo delimitador de todos os itens no controle de exibição de lista.
`CListCtrl::GetWorkAreas`	Recupera as áreas de trabalho atuais de um controle de exibição de lista.
`CListCtrl::HasGroup`	Determina se o controle de exibição de lista tem o grupo especificado.
`CListCtrl::HitTest`	Determina qual item de exibição de lista está na posição especificada.
`CListCtrl::InsertColumn`	Insere uma nova coluna em um controle de exibição de lista.
`CListCtrl::InsertGroup`	Insere um grupo no controle de exibição de lista.
`CListCtrl::InsertGroupSorted`	Insere o grupo especificado em uma lista ordenada de grupos.
`CListCtrl::InsertItem`	Insere um novo item em um controle de exibição de lista.
`CListCtrl::InsertMarkHitTest`	Recupera o ponto de inserção mais próximo de um ponto especificado.
`CListCtrl::IsGroupViewEnabled`	Determina se a exibição de grupo está habilitada para um controle de exibição de lista.
`CListCtrl::IsItemVisible`	Indica se um item especificado no controle de exibição de lista atual está visível.
`CListCtrl::MapIDToIndex`	Mapeia a ID exclusiva de um item no controle de exibição de lista atual para um índice.
`CListCtrl::MapIndexToID`	Mapeia o índice de um item no controle de exibição de lista atual para uma ID exclusiva.
`CListCtrl::MoveGroup`	Move o grupo especificado.
`CListCtrl::MoveItemToGroup`	Move o grupo especificado para o índice baseado em zero do controle de exibição de lista.
`CListCtrl::RedrawItems`	Força um controle de exibição de lista a redesenhar um intervalo de itens.
`CListCtrl::RemoveAllGroups`	Remove todos os grupos de um controle de exibição de lista.
`CListCtrl::RemoveGroup`	Remove o grupo especificado do controle de exibição de lista.
`CListCtrl::Scroll`	Rola o conteúdo de um controle de exibição de lista.
`CListCtrl::SetBkColor`	Define a cor da tela de fundo do controle de exibição de lista.
`CListCtrl::SetBkImage`	Define a imagem em segundo plano atual de um controle de exibição de lista.
`CListCtrl::SetCallbackMask`	Define a máscara de retorno de chamada de um controle de exibição de lista.
`CListCtrl::SetCheck`	Define o status de exibição atual da imagem de estado associada a um item.
`CListCtrl::SetColumn`	Define os atributos de uma coluna de exibição de lista.
`CListCtrl::SetColumnOrderArray`	Define a ordem da coluna (da esquerda para a direita) de um controle de exibição de lista.
`CListCtrl::SetColumnWidth`	Altera a largura de uma coluna no modo de exibição de relatório ou de lista.
`CListCtrl::SetExtendedStyle`	Define os estilos estendidos atuais de um controle de exibição de lista.
`CListCtrl::SetGroupInfo`	Define as informações do grupo especificado de um controle de exibição de lista.
`CListCtrl::SetGroupMetrics`	Define as métricas de grupo de um controle de exibição de lista.
`CListCtrl::SetHotCursor`	Define o cursor usado quando o rastreio importante está habilitado para um controle de exibição de lista.
`CListCtrl::SetHotItem`	Define o item mais acessado atual de um controle de exibição de lista.
`CListCtrl::SetHoverTime`	Define o tempo de foco atual de um controle de exibição de lista.
`CListCtrl::SetIconSpacing`	Define o espaçamento entre ícones em um controle de exibição de lista.
`CListCtrl::SetImageList`	Atribui uma lista de imagens a um controle de exibição de lista.
`CListCtrl::SetInfoTip`	Define o texto da dica de ferramenta.
`CListCtrl::SetInsertMark`	Define o ponto de inserção como a posição definida.
`CListCtrl::SetInsertMarkColor`	Define a cor do ponto de inserção.
`CListCtrl::SetItem`	Define alguns ou todos os atributos de um item de exibição de lista.
`CListCtrl::SetItemCount`	Prepara um controle de exibição de lista para adicionar um grande número de itens.
`CListCtrl::SetItemCountEx`	Define a contagem de itens para um controle de exibição de lista virtual.
`CListCtrl::SetItemData`	Define o valor específico do aplicativo do item.
`CListCtrl::SetItemIndexState`	Define o estado de um item no controle de exibição de lista atual.
`CListCtrl::SetItemPosition`	Move um item para uma posição especificada em um controle de exibição de lista.
`CListCtrl::SetItemState`	Altera o estado de um item em um controle de exibição de lista.
`CListCtrl::SetItemText`	Altera o texto de um item ou subitem de exibição de lista.
`CListCtrl::SetOutlineColor`	Define a cor da borda de um controle de exibição de lista.
`CListCtrl::SetSelectedColumn`	Define a coluna selecionada do controle de exibição de lista.
`CListCtrl::SetSelectionMark`	Define a marca de seleção de um controle de exibição de lista.
`CListCtrl::SetTextBkColor`	Define a cor da tela de fundo do texto em um controle de exibição de lista.
`CListCtrl::SetTextColor`	Define a cor do texto de um controle de exibição de lista.
`CListCtrl::SetTileInfo`	Define as informações de um bloco do controle de exibição de lista.
`CListCtrl::SetTileViewInfo`	Define informações usadas por um controle de exibição de lista no modo de exibição de bloco.
`CListCtrl::SetToolTips`	Define o controle de dica de ferramenta a ser usado pelo controle de exibição de lista para exibir dicas de ferramentas.
`CListCtrl::SetView`	Define a exibição do controle de exibição de lista.
`CListCtrl::SetWorkAreas`	Define a área em que os ícones podem ser exibidos em um controle de exibição de lista.
`CListCtrl::SortGroups`	Classifica os grupos de um controle de exibição de lista com uma função definida pelo usuário.
`CListCtrl::SortItems`	Classifica itens de exibição de lista usando uma função de comparação definida pelo aplicativo.
`CListCtrl::SortItemsEx`	Classifica itens de exibição de lista usando uma função de comparação definida pelo aplicativo.
`CListCtrl::SubItemHitTest`	Determina qual item de exibição de lista, se houver, está em uma determinada posição.
`CListCtrl::Update`	Força o controle a redesenhar um item especificado.

Comentários

Além de um ícone e um rótulo, cada item pode ter informações exibidas em colunas à direita do ícone e do rótulo. Esse controle (e, portanto, a classe CListCtrl) está disponível apenas para programas em execução no Windows 95/98 e Windows NT versão 3.51 e posteriores.

A seguir está uma breve visão geral da classe CListCtrl. Para obter uma discussão conceitual detalhada, consulte Uso de CListCtrl e Controles.

Exibições

Os controles de exibição de lista podem exibir seu conteúdo de quatro maneiras diferentes, chamadas de "exibições".

Exibição do ícone

Cada item é exibido como um ícone em tamanho normal (32 x 32 pixels) com um rótulo abaixo dele. O usuário pode arrastar os itens para qualquer local na janela de exibição de lista.
Exibição do ícone pequeno

Cada item é exibido como um ícone pequeno (16 x 16 pixels) com o rótulo à sua direita. O usuário pode arrastar os itens para qualquer local na janela de exibição de lista.
Modo de exibição de lista

Cada item é exibido como um pequeno ícone com um rótulo à sua direita. Os itens são organizados em colunas e não podem ser arrastados para qualquer localização na janela de exibição de lista.
Exibição do relatório

Cada item aparece em sua própria linha, com informações adicionais organizadas em colunas à direita. A coluna mais à esquerda contém o ícone pequeno e o rótulo, e as colunas seguintes contêm subitens de acordo com a especificação do aplicativo. Essas colunas são implementadas por um controle de cabeçalho inserido (classe CHeaderCtrl). Para obter mais informações sobre o controle de cabeçalho e as colunas em um modo de exibição de relatório, consulte Uso de CListCtrl: adicionando colunas ao controle (exibição de relatório).

O estilo da exibição de lista atual do controle determina a exibição atual. Para obter mais informações sobre esses estilos e seu uso, consulte Uso de CListCtrl: alterando estilos de controle de lista.

Estilos estendidos

Além dos estilos de lista padrão, a classe CListCtrl dá suporte a um grande conjunto de estilos estendidos, fornecendo funcionalidade enriquecida. Alguns exemplos dessa funcionalidade incluem:

Seleção de foco

Quando habilitada, permite a seleção automática de um item quando o cursor permanece sobre o item por um determinado período de tempo.
Exibições de lista virtual

Quando habilitada, permite que o controle dê suporte a até itens DWORD. Isso é possível posicionando a sobrecarga do gerenciamento de dados de item no aplicativo. Exceto pelas informações de seleção e foco do item, todas as informações do item devem ser gerenciadas pelo aplicativo. Para saber mais, confira Uso de CListCtrl: controles de lista de virtual.
Ativação de um e dois cliques

Quando habilitada, permite o rastreio importante (realce automático do texto do item) e a ativação de um ou dois cliques do item realçado.
Ordenação de colunas do tipo "arrastar e soltar"

Quando habilitado, permite a reordenação do tipo "arrastar e soltar" de colunas em um controle de exibição de lista. Disponível apenas no modo de exibição de relatório.

Para obter informações sobre como usar esses novos estilos estendidos, consulte Uso de CListCtrl: alterando estilos de controle de lista.

Itens e subitems

Cada item em um controle de exibição de lista consiste em um ícone (de uma lista de imagens), um rótulo, um estado atual e um valor definido pelo aplicativo (conhecido como "dados de item"). Um ou mais subitens também podem ser associados a cada item. Um "subitem" é uma cadeia de caracteres que, na exibição de relatório, pode ser exibida em uma coluna à direita do ícone e rótulo de um item. Todos os itens em um controle de exibição de lista devem ter o mesmo número de subitems.

A classe CListCtrl fornece várias funções para inserir, excluir, localizar e modificar esses itens. Para obter mais informações, consulte CListCtrl::GetItem, CListCtrl::InsertItem e CListCtrl::FindItem, Adicionando itens ao controle e Rolando, organizando, classificando e localizando em controles de lista.

Por padrão, o controle de exibição de lista é responsável por armazenar os atributos de texto e ícone de um item. No entanto, além desses tipos de item, a classe CListCtrl dá suporte a "itens de retorno de chamada". Um "item de retorno de chamada" é um item de exibição de lista para o qual o aplicativo, em vez do controle, armazena o texto, o ícone ou ambos. Uma máscara de retorno de chamada é usada para especificar quais atributos de item (texto e/ou ícone) são fornecidos pelo aplicativo. Se um aplicativo usa itens de retorno de chamada, ele deve ser capaz de fornecer os atributos de texto e/ou ícone sob demanda. Os itens de retorno de chamada são úteis quando seu aplicativo já mantém algumas dessas informações. Para obter mais informações, consulte Uso de CListCtrl: itens de retorno de chamada e máscara de retorno de chamada.

Listas de imagens

Os ícones, imagens de item de cabeçalho e estados definidos pelo aplicativo para itens de exibição de lista estão contidos em várias listas de imagens (implementadas pela classe CImageList), que você cria e atribui ao controle de exibição de lista. Cada controle de exibição de lista pode ter até quatro tipos diferentes de listas de imagens:

Ícone grande

Usado na exibição de ícones de tamanho normal.
Ícones pequenos

Usado nas exibições de ícone pequeno, lista e relatório para versões menores dos ícones usados na exibição de ícones.
Estado definido pelo aplicativo

Contém imagens de estado exibidas ao lado do ícone de um item para indicar um estado definido pelo aplicativo.
Item de cabeçalho

Usado na exibição de relatório para imagens pequenas que aparecem em cada item de controle de cabeçalho.

Por padrão, um controle de exibição de lista destrói as listas de imagens atribuídas a ele quando é destruído; no entanto, o desenvolvedor pode personalizar esse comportamento destruindo cada lista de imagens quando ela não for mais usada, conforme determinado pelo aplicativo. Para obter mais informações, consulte USO DE CListCtrl: itens de lista e listas de imagens.

Hierarquia de herança

CObject

CCmdTarget

CWnd

CListCtrl

Requisitos

Cabeçalho: afxcmn.h

`CListCtrl::ApproximateViewRect`

Determina a largura e a altura necessárias para exibir os itens de um controle de exibição de lista.

CSize ApproximateViewRect(
    CSize sz = CSize(-1, -1),
    int iCount = -1) const;

Parâmetros

sz
As dimensões propostas do controle em pixels. Se as dimensões não forem especificadas, a estrutura usará os valores de largura ou altura atuais do controle.

iCount
Número de itens a serem exibidos no controle. Passe -1 para usar o número total de itens no controle atualmente.

Valor de retorno

Um objeto CSize que contém a largura e a altura aproximadas necessárias para exibir os itens, em pixels.

Comentários

Essa função membro implementa o comportamento da macro do Win32 ListView_ApproximateViewRect, conforme descrito no SDK do Windows.

`CListCtrl::Arrange`

Reposiciona os itens em uma exibição de ícone para que eles se alinhem em uma grade.

BOOL Arrange(UINT nCode);

Parâmetros

nCode
Especifica o estilo de alinhamento dos itens. Pode ser um dos seguintes valores:

LVA_ALIGNLEFT Alinha itens ao longo da borda esquerda da janela.
LVA_ALIGNTOP Alinha itens ao longo da borda superior da janela.
LVA_DEFAULT Alinha itens de acordo com os estilos de alinhamento atuais da exibição de lista (o valor padrão).
LVA_SNAPTOGRID Encaixa todos os ícones na posição de grade mais próxima.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Comentários

O parâmetro nCode especifica o estilo de alinhamento.

Exemplo

// Align all of the list view control items along the top
// of the window (the list view control must be in icon or
// small icon mode).
m_myListCtrl.Arrange(LVA_ALIGNTOP);

`CListCtrl::CancelEditLabel`

Cancela a operação de edição de texto do item.

void CancelEditLabel();

Comentários

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

`CListCtrl::CListCtrl`

Constrói um objeto CListCtrl.

CListCtrl();

`CListCtrl::Create`

Cria um controle de lista e o anexa a um objeto CListCtrl.

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

Parâmetros

dwStyle
Especifica o estilo do controle de lista. Aplique qualquer combinação de estilos de controle de lista ao controle. Consulte estilos de janela de exibição de lista no SDK do Windows para obter uma lista completa desses estilos. Defina estilos estendidos específicos para um controle usando SetExtendedStyle.

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

pParentWnd
Especifica a janela pai do controle de lista, geralmente um CDialog. Não pode ser NULL.

nID
Especifica a ID do controle de lista.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Comentários

O CListCtrl é construído em duas etapas. Primeiro, chame o construtor e, em seguida, chame Create, que cria o controle de exibição de lista e o anexa ao objeto CListCtrl.

Para aplicar estilos estendidos do Windows ao objeto de controle de lista, chame CreateEx em vez de Create.

Exemplo

m_myListCtrl.Create(
    WS_CHILD|WS_VISIBLE|WS_BORDER|LVS_REPORT|LVS_EDITLABELS,
    CRect(10,10,400,200), pParentWnd, IDD_MYLISTCTRL);

`CListCtrl::CreateEx`

Cria um controle (uma janela filho) e o associa ao objeto CListCtrl.

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

Parâmetros

dwExStyle
Especifica o estilo estendido do controle que está sendo criado. Para obter uma lista de estilos estendidos do Windows, consulte o parâmetro dwExStyle para CreateWindowEx no SDK do Windows.

dwStyle
Especifica o estilo do controle de lista. Aplique qualquer combinação de estilos de controle de lista ao controle. Para obter uma lista completa desses estilos, consulte estilos de janela de exibição de lista no SDK do Windows.

rect
Uma referência a uma estrutura RECT que descreve o tamanho e a posição da janela a ser criada, nas coordenadas de cliente de pParentWnd.

pParentWnd
Um ponteiro para a janela que é pai do controle.

nID
A ID da janela filho do controle.

Valor de retorno

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

Comentários

Use CreateEx, em vez de Create, para aplicar estilos estendidos do Windows, especificados pelo prefácio WS_EX_ de estilos estendidos do Windows.

CreateEx cria o controle com os estilos estendidos do Windows especificados por dwExStyle. Para definir estilos estendidos específicos para um controle, chame SetExtendedStyle. Por exemplo, use CreateEx para definir estilos como WS_EX_CONTEXTHELP, mas use SetExtendedStyle para definir estilos como LVS_EX_FULLROWSELECT. Para obter mais informações, consulte os estilos descritos no artigo Estilos de Exibição de Lista Estendida no SDK do Windows.

`CListCtrl::CreateDragImage`

Cria uma lista de imagens de arrasto para o item especificado por nItem.

CImageList* CreateDragImage(
    int nItem,
    LPPOINT lpPoint);

Parâmetros

*nItem*
Índice do item cuja lista de imagens de arrasto deve ser criada.

lpPoint
Endereço de uma estrutura POINT que recebe a localização inicial do canto superior esquerdo da imagem, em coordenadas de exibição.

Valor de retorno

Um ponteiro para a lista de imagens de arrasto se tiver êxito; caso contrário NULL.

Comentários

O objeto CImageList é permanente e você deve excluí-lo quando terminar. Por exemplo:

CImageList* pImageList = m_myListCtrl.CreateDragImage(nItem, &point);

// do something

delete pImageList;

`CListCtrl::DeleteAllItems`

Exclui todos os itens do controle de exibição de lista.

BOOL DeleteAllItems();

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Exemplo

// Delete all of the items from the list view control.
m_myListCtrl.DeleteAllItems();
ASSERT(m_myListCtrl.GetItemCount() == 0);

`CListCtrl::DeleteColumn`

Exclui uma coluna do controle de exibição de lista.

BOOL DeleteColumn(int nCol);

Parâmetros

nCol
Índice da coluna a ser excluída.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Exemplo

int nColumnCount = m_myListCtrl.GetHeaderCtrl()->GetItemCount();

// Delete all of the columns.
for (int i=0; i < nColumnCount; i++)
{
    m_myListCtrl.DeleteColumn(0);
}

`CListCtrl::DeleteItem`

Exclui um item de um controle de exibição de lista.

BOOL DeleteItem(int nItem);

Parâmetros

nItem
Especifica o índice do item a ser excluído.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Exemplo

int nCount = m_myListCtrl.GetItemCount();

// Delete all of the items from the list view control.
for (int i=0; i < nCount; i++)
{
    m_myListCtrl.DeleteItem(0);
}

`CListCtrl::DrawItem`

Chamado pela estrutura quando um aspecto visual de um controle de exibição de lista desenhada pelo proprietário mudar.

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

O membro itemAction da estrutura DRAWITEMSTRUCT define 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 CListCtrl 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.

`CListCtrl::EditLabel`

Inicia a edição in-loco do texto de um item.

CEdit* EditLabel(int nItem);

Parâmetros

nItem
Índice do item de exibição de lista que deve ser editado.

Valor de retorno

Se tiver êxito, um ponteiro para o objeto CEdit usado para editar o texto do item; caso contrário, NULL.

Comentários

Um controle de exibição de lista com o estilo de janela LVS_EDITLABELS permite que um usuário edite rótulos de item no local. O usuário começa a editar clicando no rótulo de um item com o foco.

Use essa função para iniciar a edição in-loco do texto do item de exibição de lista especificado.

Exemplo

// Make sure the focus is set to the list view control.
m_myListCtrl.SetFocus();

// Show the edit control on the label of the first
// item in the list view control.
CEdit* pmyEdit = m_myListCtrl.EditLabel(1);
ASSERT(pmyEdit != NULL);

`CListCtrl::EnableGroupView`

Habilita ou desabilita se os itens em um controle de exibição de lista são exibidos como um grupo.

LRESULT EnableGroupView(BOOL fEnable);

Parâmetros

fEnable
Indica se um controle de exibição de lista deve ser habilitado para agrupar os itens exibidos. TRUE para habilitar o agrupamento; FALSE para desabilitá-lo.

Valor de retorno

Retorna um dos seguintes valores:

0 A capacidade de exibir itens de exibição de lista como um grupo já está habilitada ou desabilitada.
1 O estado do controle foi alterado com êxito.
-1 A operação falhou.

Comentários

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

`CListCtrl::EnsureVisible`

Garante que um item de exibição de lista esteja pelo menos parcialmente visível.

BOOL EnsureVisible(
    int nItem,
    BOOL bPartialOK);

Parâmetros

nItem
Índice do item de exibição de lista que deve estar visível.

bPartialOK
Especifica se a visibilidade parcial é aceitável.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Comentários

O controle de exibição de lista é rolado, se necessário. Se o parâmetro bPartialOK for diferente de zero, nenhuma rolagem ocorrerá se o item estiver parcialmente visível.

Exemplo

// Ensure that the last item is visible.
int nCount = m_myListCtrl.GetItemCount();
if (nCount > 0)
    m_myListCtrl.EnsureVisible(nCount-1, FALSE);

`CListCtrl::FindItem`

Pesquisa um item de exibição de lista com características específicas.

int FindItem(
    LVFINDINFO* pFindInfo,
    int nStart = -1) const;

Parâmetros

pFindInfo
Um ponteiro para uma estrutura LVFINDINFO que contém informações sobre o item a ser pesquisado.

nStart
Índice do item com o qual a pesquisa deve ser iniciada ou -1 para iniciar desde o início. O item em nStart é excluído da pesquisa se nStart não for igual a -1.

Valor de retorno

O índice do item se for bem-sucedido; caso contrário, -1.

Comentários

O parâmetro pFindInfo aponta para uma estrutura LVFINDINFO, que contém informações usadas para pesquisar um item de exibição de lista.

Exemplo

LVFINDINFO info;
int nIndex;

info.flags = LVFI_PARTIAL|LVFI_STRING;
info.psz = _T("item");

// Delete all of the items that begin with the string.
while ((nIndex = m_myListCtrl.FindItem(&info)) != -1)
{
    m_myListCtrl.DeleteItem(nIndex);
}

`CListCtrl::GetBkColor`

Recupera a cor da tela de fundo de um controle de exibição de lista.

COLORREF GetBkColor() const;

Valor de retorno

Um valor de 32 bits usado para especificar uma cor RGB.

Exemplo

Confira o exemplo de CListCtrl::SetBkColor.

`CListCtrl::GetBkImage`

Recupera a imagem em segundo plano atual de um controle de exibição de lista.

BOOL GetBkImage(LVBKIMAGE* plvbkImage) const;

Parâmetros

plvbkImage
Um ponteiro para uma estrutura LVBKIMAGE que contém a imagem de plano de fundo atual da exibição de lista.

Valor de retorno

Retorna diferente de zero se tiver êxito; caso contrário, zero.

Comentários

Esse método implementa o comportamento da macro do Win32 ListView_GetBkImage, conforme descrito no SDK do Windows.

Exemplo

LVBKIMAGE bki;

// If no background image is set for the list view control use
// the Microsoft homepage image as the background image.
if (m_myListCtrl.GetBkImage(&bki) && (bki.ulFlags == LVBKIF_SOURCE_NONE))
{
    m_myListCtrl.SetBkImage(
        _T("https://www.microsoft.com/library/images/gifs/homepage/microsoft.gif"),
        TRUE);
}

`CListCtrl::GetCallbackMask`

Recupera a máscara de retorno de chamada de um controle de exibição de lista.

UINT GetCallbackMask() const;

Valor de retorno

A máscara de retorno de chamada do controle de exibição de lista.

Comentários

Um "item de retorno de chamada" é um item de exibição de lista para o qual o aplicativo, e não o controle, armazena o texto, o ícone ou ambos. Embora um controle de exibição de lista possa armazenar esses atributos para você, talvez você queira usar itens de retorno de chamada se seu aplicativo já mantiver algumas dessas informações. A máscara de retorno de chamada especifica quais bits de estado de item são mantidos pelo aplicativo e se aplica a todo o controle em vez de um item específico. A máscara de retorno de chamada é zero por padrão, o que significa que o controle rastreia todos os estados do item. Se um aplicativo usa itens de retorno de chamada ou especifica uma máscara de retorno de chamada diferente de zero, ele deve ser capaz de fornecer atributos de item de exibição de lista sob demanda.

Exemplo

Confira o exemplo de CListCtrl::SetCallbackMask.

`CListCtrl::GetCheck`

Recupera o status de exibição atual da imagem de estado que está associada a um item.

BOOL GetCheck(int nItem) const;

Parâmetros

nItem
O índice com base em zero de um item de controle de lista.

Valor de retorno

Diferentes de zero se o item estiver selecionado; caso contrário, 0.

Comentários

Essa função membro implementa o comportamento da macro do Win32 ListView_GetCheckState, conforme descrito no SDK do Windows.

Exemplo

Confira o exemplo de CListCtrl::SetCheck.

`CListCtrl::GetColumn`

Recupera os atributos da coluna de um controle de exibição de lista.

BOOL GetColumn(
    int nCol,
    LVCOLUMN* pColumn) const;

Parâmetros

nCol
Índice da coluna cujos atributos devem ser recuperados.

pColumn
Endereço de uma estrutura LVCOLUMN que especifica as informações a serem recuperadas e recebe informações sobre a coluna. O membro mask especifica quais atributos de coluna devem ser recuperados. Se o membro mask especificar o valor LVCF_TEXT, o membro pszText deverá conter o endereço do buffer que recebe o texto do item e o membro cchTextMax deverá especificar o tamanho do buffer.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Comentários

A estrutura LVCOLUMN contém informações sobre uma coluna na exibição de relatório.

Exemplo

LVCOLUMN col;

col.mask = LVCF_WIDTH;

// Double the column width of the first column.
if (m_myListCtrl.GetColumn(0, &col))
{
    col.cx *= 2;
    m_myListCtrl.SetColumn(0, &col);
}

`CListCtrl::GetColumnOrderArray`

Recupera a ordem da coluna (da esquerda para a direita) de um controle de exibição de lista.

BOOL GetColumnOrderArray(
    LPINT piArray,
    int iCount = -1);

Parâmetros

piArray
Um ponteiro para um buffer que conterá os valores de índice das colunas no controle de exibição de lista. O buffer deve ser grande o suficiente para conter o número total de colunas no controle de exibição de lista.

iCount
Número de colunas no controle de exibição de lista. Se esse parâmetro for -1, o número de colunas será recuperado automaticamente pela estrutura.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Comentários

Essa função membro implementa o comportamento da macro do Win32 ListView_GetColumnOrderArray, conforme descrito no SDK do Windows.

Exemplo

// Reverse the order of the columns in the list view control
// (i.e. make the first column the last, the last column
// the first, and so on...).
CHeaderCtrl* pHeaderCtrl = m_myListCtrl.GetHeaderCtrl();

if (pHeaderCtrl != NULL)
{
    int  nColumnCount = pHeaderCtrl->GetItemCount();
    LPINT pnOrder = (LPINT) malloc(nColumnCount*sizeof(int));
    ASSERT(pnOrder != NULL);
    m_myListCtrl.GetColumnOrderArray(pnOrder, nColumnCount);

    int i, j, nTemp;
    for (i = 0, j = nColumnCount-1; i < j; i++, j--)
    {
        nTemp = pnOrder[i];
        pnOrder[i] = pnOrder[j];
        pnOrder[j] = nTemp;
    }

    m_myListCtrl.SetColumnOrderArray(nColumnCount, pnOrder);
    free(pnOrder);
}

`CListCtrl::GetColumnWidth`

Recupera a largura de uma coluna no modo de exibição de relatório ou de lista.

int GetColumnWidth(int nCol) const;

Parâmetros

nCol
Especifica o índice da coluna cuja largura deve ser recuperada.

Valor de retorno

A largura, em pixels, da coluna especificada por nCol.

Exemplo

// Increase the column width of the second column by 20.
int nWidth = m_myListCtrl.GetColumnWidth(1);
m_myListCtrl.SetColumnWidth(1, 20 + nWidth);

`CListCtrl::GetCountPerPage`

Calcula o número de itens que podem se ajustar verticalmente na área visível de um controle de exibição de lista quando estiver no modo de exibição de lista ou no modo de exibição de relatório.

int GetCountPerPage() const;

Valor de retorno

O número de itens que podem se ajustar verticalmente na área visível de um controle de exibição de lista quando estiver no modo de exibição de lista ou no modo de exibição de relatório.

Exemplo

Confira o exemplo de CListCtrl::GetTopIndex.

`CListCtrl::GetEditControl`

Recupera o identificador do controle de edição usado para editar o texto de um item de exibição de lista.

CEdit* GetEditControl() const;

Valor de retorno

Se tiver êxito, um ponteiro para o objeto CEdit usado para editar o texto do item; caso contrário, NULL.

Exemplo

// The string replacing the text in the edit control.
LPCTSTR lpszmyString = _T("custom label!");

// If possible, replace the text in the label edit control.
CEdit* pEdit = m_myListCtrl.GetEditControl();

if (pEdit != NULL)
{
    pEdit->SetWindowText(lpszmyString);
}

`CListCtrl::GetEmptyText`

Recupera a cadeia de caracteres a ser exibida se o controle de exibição de lista atual estiver vazio.

CString GetEmptyText() const;

Valor de retorno

CString que contém o texto a ser exibido se o controle estiver vazio.

Comentários

Esse método envia a mensagem LVM_GETEMPTYTEXT, que é descrita no SDK do Windows.

`CListCtrl::GetExtendedStyle`

Recupera os estilos estendidos atuais de um controle de exibição de lista.

DWORD GetExtendedStyle();

Valor de retorno

Uma combinação dos estilos estendidos atualmente usados pelo controle de exibição de lista. Para obter uma lista descritiva desses estilos estendidos, consulte o artigo Estilos de Exibição de Lista Estendida no SDK do Windows.

Comentários

Essa função membro implementa o comportamento da macro do Win32 ListView_GetExtendedListViewStyle, conforme descrito no SDK do Windows.

Exemplo

Confira o exemplo de CListCtrl::SetExtendedStyle.

`CListCtrl::GetFirstSelectedItemPosition`

Obtém a posição do primeiro item selecionado no controle de exibição de lista.

POSITION GetFirstSelectedItemPosition() const;

Valor de retorno

Um valor POSITION que pode ser usado para iteração ou recuperação do ponteiro do objeto; NULL se nenhum item for selecionado.

Exemplo

O exemplo de código a seguir demonstra o uso dessa função.

POSITION pos = m_myListCtrl.GetFirstSelectedItemPosition();
if (pos == NULL)
{
    TRACE(_T("No items were selected!\n"));
}
else
{
    while (pos)
    {
        int nItem = m_myListCtrl.GetNextSelectedItem(pos);
        TRACE(_T("Item %d was selected!\n"), nItem);
        // you could do your own processing on nItem here
    }
}

`CListCtrl::GetFocusedGroup`

Recupera o grupo com o teclado focado no controle de exibição de lista atual.

int GetFocusedGroup() const;

Valor de retorno

O índice do grupo cujo estado é LVGS_FOCUSED, se houver esse grupo; caso contrário, -1.

Comentários

Esse método envia a mensagem LVM_GETFOCUSEDGROUP, que é descrita no SDK do Windows. Para obter mais informações, consulte o valor LVGS_FOCUSED do membro state da estrutura LVGROUP.

`CListCtrl::GetGroupCount`

Recupera o número de grupos no controle de exibição de lista atual.

int GetGroupCount()const;

Valor de retorno

O número de grupos no controle de exibição de lista.

Comentários

Esse método envia a mensagem LVM_GETGROUPCOUNT, que é descrita no SDK do Windows -->.

`CListCtrl::GetGroupInfo`

Obtém as informações para um grupo especificado do controle de exibição de lista.

int GetGroupInfo(
    int iGroupId,
    PLVGROUP pgrp) const;

Parâmetros

iGroupId
O identificador do grupo cujas informações devem ser recuperadas.

pgrp
Um ponteiro para LVGROUP que contém informações sobre o grupo especificado.

Valor de retorno

Retorna a ID do grupo se tiver êxito; caso contrário, -1.

Comentários

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

`CListCtrl::GetGroupInfoByIndex`

Recupera as informações de um grupo especificado no controle de exibição de lista atual.

BOOL GetGroupInfoByIndex(
    int iIndex,
    PLVGROUP pGroup) const;

Parâmetros

iIndex
[in] Índice baseado em zero de um grupo.

pGroup
[out] Ponteiro para uma estrutura LVGROUP que recebe informações sobre o grupo especificado pelo parâmetro iIndex. O chamador é responsável por inicializar os membros da estrutura LVGROUP. Defina o membro cbSize com o tamanho da estrutura e os sinalizadores do membro mask para especificar as informações a serem recuperadas.

Valor de retorno

TRUE se o método for bem-sucedido. Caso contrário, FALSE.

Comentários

Esse método envia a mensagem LVM_GETGROUPINFOBYINDEX, que é descrita no SDK do Windows -->.

Exemplo

O primeiro exemplo de código define uma variável m_listCtrl, que é usada para acessar o controle de exibição de lista atual. Essa variável será usada no próximo exemplo.

public:
    // Variable used to access the list control.
    CListCtrl m_listCtrl;

O próximo exemplo de código demonstra o método GetGroupInfoByIndex. Em uma seção anterior deste exemplo de código, criamos um controle de exibição de lista que exibe duas colunas intituladas "ClientID" e "Grade" em uma exibição de relatório. O exemplo de código a seguir recupera informações sobre o grupo cujo índice é 0, se esse grupo existir.

// GetGroupInfoByIndex
const int GROUP_HEADER_BUFFER_SIZE = 40;

// Initialize the structure
LVGROUP gInfo = {0};
gInfo.cbSize = sizeof(LVGROUP);
wchar_t wstrHeadGet[GROUP_HEADER_BUFFER_SIZE] = {0};
gInfo.cchHeader = GROUP_HEADER_BUFFER_SIZE;
gInfo.pszHeader = wstrHeadGet;
gInfo.mask = (LVGF_ALIGN | LVGF_STATE | LVGF_HEADER | LVGF_GROUPID);
gInfo.state = LVGS_NORMAL;
gInfo.uAlign  = LVGA_HEADER_LEFT;

BOOL bRet = m_listCtrl.GetGroupInfoByIndex( 0, &gInfo );
if (bRet == TRUE) {
    CString strHeader = CString( gInfo.pszHeader );
    CString str;
    str.Format(_T("Header: '%s'"), strHeader);
    AfxMessageBox(str, MB_ICONINFORMATION);
}
else
{
    AfxMessageBox(_T("No group information was retrieved."));
}

`CListCtrl::GetGroupMetrics`

Recupera as métricas de um grupo.

void GetGroupMetrics(PLVGROUPMETRICS pGroupMetrics) const;

Parâmetros

pGroupMetrics
Um ponteiro para um LVGROUPMETRICS que contém as informações de métricas do grupo.

Comentários

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

`CListCtrl::GetGroupRect`

Recupera o retângulo delimitador para um grupo especificado no controle de exibição de lista atual.

BOOL GetGroupRect(
    int iGroupId,
    LPRECT lpRect,
    int iCoords = LVGGR_GROUP) const;

Parâmetros

iGroupId
[in] Especifica um grupo.

lpRect
[in, out] Ponteiro para uma estrutura RECT. Se esse método for bem-sucedido, a estrutura receberá as coordenadas do retângulo do grupo especificado por iGroupId.

iCoords
[in] Especifica as coordenadas do retângulo a serem recuperadas. Use um desses valores:

LVGGR_GROUP - (Padrão) Coordenadas de todo o grupo expandido.
LVGGR_HEADER - Coordenadas somente do cabeçalho (grupo recolhido).
LVGGR_SUBSETLINK - Coordenadas apenas do link do subconjunto (subconjunto de marcação).

Valor de retorno

TRUE se o método for bem-sucedido. Caso contrário, FALSE.

Comentários

O chamador é responsável por alocar a estrutura RECT apontada pelo parâmetro pRect.

Esse método envia a mensagem LVM_GETGROUPRECT, que é descrita no SDK do Windows.

Exemplo

O primeiro exemplo de código define uma variável m_listCtrl, que é usada para acessar o controle de exibição de lista atual. Essa variável será usada no próximo exemplo.

public:
    // Variable used to access the list control.
    CListCtrl m_listCtrl;

O próximo exemplo de código demonstra o método GetGroupRect. Em uma seção anterior deste exemplo de código, criamos um controle de exibição de lista que exibe duas colunas intituladas "ClientID" e "Grade" em uma exibição de relatório. O exemplo de código a seguir desenha um retângulo 3D em torno do grupo cujo índice é 0, se esse grupo existir.

// GetGroupRect

// Get the graphics rectangle that surrounds group 0.
CRect rect;
BOOL bRet = m_listCtrl.GetGroupRect( 0, &rect, LVGGR_GROUP);
// Draw a blue rectangle around group 0.
if (bRet == TRUE) {
    m_listCtrl.GetDC()->Draw3dRect( &rect, RGB(0, 0, 255), RGB(0, 0, 255));
}
else {
    AfxMessageBox(_T("No group information was retrieved."), MB_ICONINFORMATION);
}

`CListCtrl::GetGroupState`

Recupera o estado para um grupo especificado no controle de exibição de lista atual.

UINT GetGroupState(
    int iGroupId,
    DWORD dwMask) const;

Parâmetros

iGroupId
[in] Índice baseado em zero de um grupo.

dwMask
[in] Máscara que especifica o valor de estado a ser recuperado para o grupo especificado. Para obter mais informações, consulte o membro mask da estrutura LVGROUP.

Valor de retorno

O estado solicitado para o grupo especificado ou 0, se o grupo não puder ser encontrado.

Comentários

O valor retornado é o resultado de uma operação AND bit a bit no parâmetro dwMask e o valor do membro state de uma estrutura LVGROUP que representa o controle de exibição de lista atual.

Esse método envia a mensagem LVM_GETGROUPSTATE, que é descrita no SDK do Windows. Para obter mais informações, consulte a macro ListView_GetGroupState.

`CListCtrl::GetHeaderCtrl`

Recupera o controle de cabeçalho de um controle de exibição de lista.

CHeaderCtrl* GetHeaderCtrl();

Valor de retorno

Um ponteiro para o controle de cabeçalho, usado pelo controle de exibição de lista.

Comentários

Essa função membro implementa o comportamento da macro do Win32 ListView_GetHeader, conforme descrito no SDK do Windows.

Exemplo

Confira o exemplo de CListCtrl::GetColumnOrderArray.

`CListCtrl::GetHotCursor`

Recupera o cursor usado quando o rastreio importante está habilitado para um controle de exibição de lista.

HCURSOR GetHotCursor();

Valor de retorno

O identificador do recurso de cursor dinâmico atual que está sendo usado pelo controle de exibição de lista.

Comentários

Essa função membro implementa o comportamento da macro do Win32 ListView_GetHotCursor, conforme descrito no SDK do Windows. O cursor dinâmico, visível somente quando a seleção de foco está habilitada, aparece quando o cursor passa por qualquer item de exibição de lista. A seleção de foco é habilitada definindo o estilo estendido LVS_EX_TRACKSELECT.

Exemplo

// Set the hot cursor to be the system app starting cursor.
HCURSOR hCursor = ::LoadCursor(NULL, IDC_APPSTARTING);
m_myListCtrl.SetHotCursor(hCursor);
ASSERT(m_myListCtrl.GetHotCursor() == hCursor);

`CListCtrl::GetHotItem`

Recupera o item de exibição de lista atualmente no cursor.

int GetHotItem();

Valor de retorno

O índice do item mais acessado atual do controle de exibição de lista.

Comentários

Essa função membro implementa o comportamento da macro do Win32 ListView_GetHotItem, conforme descrito no SDK do Windows. O item mais acessado é definido como o item selecionado no momento quando o rastreio importante (e seleção de foco de foco) está habilitado.

Se o rastreio importante estiver habilitado, quando um usuário pausar um item de exibição de lista, o rótulo do item será realçado automaticamente sem o uso de um botão do mouse.

Exemplo

// Set the hot item to the first item only if no other item is
// highlighted.
if (m_myListCtrl.GetHotItem() == -1)
    m_myListCtrl.SetHotItem(0);

`CListCtrl::GetHoverTime`

Recupera o tempo de foco atual de um controle de exibição de lista.

DWORD GetHoverTime() const;

Valor de retorno

Retorna o atraso, em milissegundos, que o cursor do mouse deve passar sobre um item antes de ser selecionado. Se o valor retornado for -1, o tempo de foco será o padrão.

Comentários

Essa função membro implementa o comportamento da macro do Win32 ListView_GetHoverTime, conforme descrito no SDK do Windows.

Exemplo

// If the hover time is the default set to 1 sec.
DWORD dwTime = m_myListCtrl.GetHoverTime();
if (dwTime == -1)
    m_myListCtrl.SetHoverTime(1000);

`CListCtrl::GetImageList`

Recupera o identificador de uma lista de imagens usada para desenhar itens de exibição de lista.

CImageList* GetImageList(int nImageList) const;

Parâmetros

nImageList
Valor que especifica qual lista de imagens deve ser recuperada. Pode ser um destes valores:

LVSIL_NORMAL Lista de imagens com ícones grandes.
LVSIL_SMALL Lista de imagens com ícones pequenos.
LVSIL_STATE Lista de imagens com imagens de estado.

Valor de retorno

Um ponteiro para a lista de imagens usada para desenhar os itens de exibição de lista.

Exemplo

ASSERT(m_myListCtrl.GetImageList(LVSIL_NORMAL) == NULL);
m_myListCtrl.SetImageList(&m_lcImageList, LVSIL_NORMAL);
ASSERT(m_myListCtrl.GetImageList(LVSIL_NORMAL) == &m_lcImageList);

`CListCtrl::GetInsertMark`

Recupera a posição atual da marca de inserção.

BOOL GetInsertMark(LPLVINSERTMARK plvim) const;

Parâmetros

plvim
Um ponteiro para uma estrutura LVINSERTMARK que contém as informações da marca de inserção.

Valor de retorno

Retorna TRUE, se bem-sucedido; caso contrário, FALSE. FALSE será retornado se o tamanho no membro cbSize da estrutura LVINSERTMARK não for igual ao tamanho real da estrutura.

Comentários

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

`CListCtrl::GetInsertMarkColor`

Recupera a cor atual da marca de inserção.

COLORREF GetInsertMarkColor() const;

Valor de retorno

Retorna uma estrutura COLORREF que contém a cor do ponto de inserção.

Comentários

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

`CListCtrl::GetInsertMarkRect`

Recupera o retângulo que vincula o ponto de inserção.

int GetInsertMarkRect(LPRECT pRect) const;

Parâmetros

pRect
Ponteiro para uma estrutura RECT que contém as coordenadas de um retângulo que vincula o ponto de inserção.

Valor de retorno

Retorna um dos seguintes valores:

0 Nenhum ponto de inserção foi encontrado.
1 O ponto de inserção foi encontrado.

Comentários

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

`CListCtrl::GetItem`

Recupera alguns ou todos os atributos de um item de exibição de lista.

BOOL GetItem(LVITEM* pItem) const;

Parâmetros

pItem
Ponteiro para uma estrutura LVITEM que recebe os atributos do item.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Comentários

A estrutura LVITEM especifica ou recebe os atributos de um item de exibição de lista.

`CListCtrl::GetItemCount`

Recupera o número de itens em um controle de exibição de lista.

int GetItemCount() const;

Valor de retorno

O número de itens no controle de exibição de lista.

Exemplo

Confira o exemplo de CListCtrl::DeleteItem.

`CListCtrl::GetItemData`

Recupera o valor específico do aplicativo de 32 bits (64 bits, se estiver compilando para x64) associado ao item especificado por nItem.

DWORD_PTR GetItemData(int nItem) const;

Parâmetros

nItem
Índice do item de lista cujos dados devem ser recuperados.

Valor de retorno

Um valor específico do aplicativo de 32 bits (64 bits, se você estiver compilando para x64) associado ao item especificado.

Comentários

Esse valor é o membro lParam da estrutura LVITEM, conforme descrito no SDK do Windows

Exemplo

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

`CListCtrl::GetItemIndexRect`

Recupera o retângulo delimitador para todos ou parte de um subitem no controle de exibição de lista atual.

BOOL GetItemIndexRect(
    PLVITEMINDEX pItemIndex,
    int iColumn,
    int rectType,
    LPRECT pRect) const;

Parâmetros

pItemIndex
[in] Ponteiro para uma estrutura LVITEMINDEX para o item pai do subitem. O chamador é responsável por alocar e definir os membros da estrutura LVITEMINDEX. O parâmetro não pode ser NULL.

iColumn
[in] Índice baseado em zero de uma coluna no controle.

rectType
[in] Parte do subitem de exibição de lista para o qual o retângulo delimitador é recuperado. Especifique um dos seguintes valores:

LVIR_BOUNDS - Retorna o retângulo delimitador de todo o subitem, incluindo o ícone e o rótulo.
LVIR_ICON - Retorna o retângulo delimitador do ícone ou ícone pequeno do subitem.
LVIR_LABEL - Retorna o retângulo delimitador do texto do subitem.

pRect
[out] Ponteiro para uma estrutura RECT que recebe informações sobre o retângulo delimitador do subitem. O chamador é responsável por alocar a estrutura RECT. O parâmetro não pode ser NULL.

Valor de retorno

TRUE se o método for bem-sucedido. Caso contrário, FALSE.

Comentários

Esse método envia a mensagem LVM_GETITEMINDEXRECT, que é descrita no SDK do Windows. Para obter mais informações, confira Macro ListView_GetItemIndexRect.

Exemplo

O primeiro exemplo de código define uma variável m_listCtrl, que é usada para acessar o controle de exibição de lista atual. Essa variável será usada no próximo exemplo.

public:
    // Variable used to access the list control.
    CListCtrl m_listCtrl;

O próximo exemplo de código demonstra o método GetGroupRect. Antes de entrar nesse exemplo de código, criamos um controle de exibição de lista que exibe duas colunas intituladas "ClientID" e "Grade" em uma exibição de relatório. O exemplo de código a seguir desenha um retângulo 3D em torno do segundo subitem em ambas as colunas.

// GetItemIndexRect
// Get the rectangle that bounds the second item in the first group.
LVITEMINDEX lvItemIndex;
lvItemIndex.iGroup = 0;
lvItemIndex.iItem = 1;
CRect rect;
BOOL bRet = m_listCtrl.GetItemIndexRect(
    &lvItemIndex, 0, LVIR_BOUNDS, &rect);

// Draw a red rectangle around the item.
m_listCtrl.GetDC()->Draw3dRect( &rect, RGB(255, 0, 0), RGB(255, 0, 0) );

`CListCtrl::GetItemPosition`

Recupera a posição de um item de exibição de lista.

BOOL GetItemPosition(
    int nItem,
    LPPOINT lpPoint) const;

Parâmetros

nItem
O índice do item cuja posição deve ser recuperada.

lpPoint
Endereço de uma estrutura POINT que recebe a posição do canto superior esquerdo do item, em coordenadas de exibição.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Exemplo

POINT pt;

// Move all items in the list control 100 pixels to the right.
UINT i, nCount = m_myListCtrl.GetItemCount();

for (i=0; i < nCount; i++)
{
    m_myListCtrl.GetItemPosition(i, &pt);
    pt.x += 100;
    m_myListCtrl.SetItemPosition(i, pt);
}

`CListCtrl::GetItemRect`

Recupera o retângulo delimitador para todos ou parte de um item na exibição atual.

BOOL GetItemRect(
    int nItem,
    LPRECT lpRect,
    UINT nCode) const;

Parâmetros

nItem
O índice do item cuja posição deve ser recuperada.

lpRect
Endereço de uma estrutura RECT que recebe o retângulo delimitador.

nCode
Uma parte do item de exibição de lista para o qual recuperar o retângulo delimitador. Pode ser um destes valores:

LVIR_BOUNDS Retorna o retângulo delimitador de todo o item, incluindo o ícone e o rótulo.
LVIR_ICONRetorna o retângulo delimitador do ícone ou ícone pequeno.
LVIR_LABEL Retorna o retângulo delimitador do texto do item.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Exemplo

// OnClick is the handler for the NM_CLICK notification
void CListCtrlDlg::OnClick(NMHDR* pNMHDR, LRESULT* pResult)
{
    UNREFERENCED_PARAMETER(pResult);
    LPNMITEMACTIVATE pia = (LPNMITEMACTIVATE)pNMHDR;

    // Get the current mouse location and convert it to client
    // coordinates.
    CPoint pos( ::GetMessagePos() );
    ScreenToClient(&pos);

    // Get indexes of the first and last visible items in
    // the listview control.
    int index = m_myListCtrl.GetTopIndex();
    int last_visible_index = index + m_myListCtrl.GetCountPerPage();
    if (last_visible_index > m_myListCtrl.GetItemCount())
        last_visible_index = m_myListCtrl.GetItemCount();

    // Loop until number visible items has been reached.
    while (index <= last_visible_index)
    {
        // Get the bounding rectangle of an item. If the mouse
        // location is within the bounding rectangle of the item,
        // you know you have found the item that was being clicked.
        CRect r;
        m_myListCtrl.GetItemRect(index, &r, LVIR_BOUNDS);
        if (r.PtInRect(pia->ptAction))
        {
            UINT flag = LVIS_SELECTED | LVIS_FOCUSED;
            m_myListCtrl.SetItemState(index, flag, flag);
            break;
        }

        // Get the next item in listview control.
        index++;
    }
}

`CListCtrl::GetItemSpacing`

Calcula o espaçamento entre os itens no controle de exibição de lista atual.

BOOL GetItemSpacing(
    BOOL fSmall,
    int* pnHorzSpacing,
    int* pnVertSpacing) const;

Parâmetros

fSmall
[in] Exibição para a qual o espaçamento do item deve ser recuperado. Especifique TRUE para exibição de ícone pequeno ou FALSE para exibição de ícone.

pnHorzSpacing
[out] Contém o espaçamento horizontal entre os itens.

pnVertSpacing
[out] Contém o espaçamento vertical entre os itens.

Valor de retorno

TRUE se o método for bem-sucedido. Caso contrário, FALSE.

Comentários

Esse método envia a mensagem LVM_GETITEMSPACING, que é descrita no SDK do Windows.

`CListCtrl::GetItemState`

Recupera o estado de um item de exibição de lista.

UINT GetItemState(
    int nItem,
    UINT nMask) const;

Parâmetros

nItem
O índice do item cujo estado deve ser recuperado.

nMask
Máscara especificando qual sinalizador de estado do item deve ser retornado.

Valor de retorno

Os sinalizadores de estado do item de exibição de lista especificado.

Comentários

O estado de um item é especificado pelo membro state da estrutura LVITEM, conforme descrito no SDK do Windows. Quando você especifica ou altera o estado de um item, o membro stateMask especifica quais bits de estado você deseja alterar.

Exemplo

Confira o exemplo de CListCtrl::GetTopIndex.

`CListCtrl::GetItemText`

Recupera o texto de um item ou subitem de exibição de lista.

int GetItemText(
    int nItem,
    int nSubItem,
    LPTSTR lpszText,
    int nLen) const;

CString GetItemText(
    int nItem,
    int nSubItem) const;

Parâmetros

nItem
O índice do item cujo texto deve ser recuperado.

nSubItem
Especifica o subitem cujo texto deve ser recuperado.

lpszText
Ponteiro para uma cadeia de caracteres que deve receber o texto do item.

nLen
Comprimento do buffer apontado por lpszText.

Valor de retorno

A versão retornando int retorna o comprimento da cadeia de caracteres recuperada.

A versão retornando CString retorna o texto do item.

Comentários

Se nSubItem for zero, essa função recuperará o rótulo do item; se nSubItem for diferente de zero, ela recuperará o texto do subitem. Para obter mais informações sobre o argumento do subitem, consulte a discussão da estrutura LVITEM no SDK do Windows.

`CListCtrl::GetNextItem`

Pesquisa um item de exibição de lista com as propriedades especificadas e que possua a relação especificada com um determinado item.

int GetNextItem(
    int nItem,
    int nFlags) const;

Parâmetros

nItem
Índice do item com o qual a pesquisa deve ser iniciada ou -1 para localizar o primeiro item que corresponde aos sinalizadores especificados. O item especificado é excluído da pesquisa.

nFlags
A relação geométrica entre o item solicitado e o item especificado, bem como o estado do item solicitado. A relação geométrica pode ser um destes valores:

LVNI_ABOVE Pesquisa um item acima do item especificado.
LVNI_ALL Pesquisa um item subsequente por índice (o valor padrão).
LVNI_BELOW Pesquisa um item abaixo do item especificado.
LVNI_TOLEFT Pesquisa um item à esquerda do item especificado.
LVNI_TORIGHT Pesquisa um item à direita do item especificado.

O estado pode ser zero ou pode ser um ou mais desses valores:

LVNI_DROPHILITED O item tem o sinalizador de estado LVIS_DROPHILITED definido.
LVNI_FOCUSED O item tem o sinalizador de estado LVIS_FOCUSED definido.
LVNI_SELECTED O item tem o sinalizador de estado LVIS_SELECTED definido.

Se um item não tiver todos os sinalizadores de estado especificados definidos, a pesquisa continuará com o próximo item.

Valor de retorno

O índice do próximo item se for bem-sucedido; caso contrário, -1.

`CListCtrl::GetNextItemIndex`

Recupera o índice do item no controle de exibição de lista atual com um conjunto de propriedades especificado.

BOOL GetNextItemIndex(
    PLVITEMINDEX pItemIndex,
    int nFlags) const;

Parâmetros

pItemIndex
[in, out] Ponteiro para a estrutura LVITEMINDEX que descreve o item em que a pesquisa começa ou -1 para localizar o primeiro item que corresponde aos sinalizadores no parâmetro nFlags. Se esse método for bem-sucedido, a estrutura LVITEMINDEX descreverá o item encontrado pela pesquisa.

nFlags
[in] Uma combinação bit a bit (OR) de sinalizadores que especificam como executar a pesquisa. A pesquisa pode depender do índice, do estado ou da aparência do item de destino ou da posição física do item de destino em relação ao item especificado pelo parâmetro pItemIndex. Para obter mais informações, consulte o parâmetro flags da mensagem LVM_GETNEXTITEMINDEX.

Valor de retorno

TRUE se o método for bem-sucedido. Caso contrário, FALSE.

Comentários

O chamador é responsável por alocar e definir os membros da estrutura LVITEMINDEX apontada pelo parâmetro pItemIndex.

Esse método envia a mensagem LVM_GETNEXTITEMINDEX, que é descrita no SDK do Windows.

`CListCtrl::GetNextSelectedItem`

Obtém o índice do item de lista identificado por pos, e, em seguida, define pos como o valor POSITION.

int GetNextSelectedItem(POSITION& pos) const;

Parâmetros

pos
Uma referência a um valor POSITION retornado por uma chamada a GetNextSelectedItem ou GetFirstSelectedItemPosition anterior. O valor é atualizado para a próxima posição por essa chamada.

Valor de retorno

O índice do item de lista identificado por pos.

Comentários

Você poderá usar GetNextSelectedItem em um loop de iteração para frente se estabelecer a posição inicial com uma chamada para GetFirstSelectedItemPosition.

Você deve garantir que seu valor POSITION seja válido. Se ele for inválido, a versão de Depuração da biblioteca Microsoft Foundation Class será declarada.

Exemplo

O exemplo de código a seguir demonstra o uso dessa função.

POSITION pos = m_myListCtrl.GetFirstSelectedItemPosition();
if (pos == NULL)
{
    TRACE(_T("No items were selected!\n"));
}
else
{
    while (pos)
    {
        int nItem = m_myListCtrl.GetNextSelectedItem(pos);
        TRACE(_T("Item %d was selected!\n"), nItem);
        // you could do your own processing on nItem here
    }
}

`CListCtrl::GetNumberOfWorkAreas`

Recupera o número atual de áreas de trabalho para um controle de exibição de lista.

UINT GetNumberOfWorkAreas() const;

Valor de retorno

Não usado no momento.

Comentários

Essa função membro implementa o comportamento da macro do Win32 ListView_GetNumberOfWorkAreas, conforme descrito no SDK do Windows.

Exemplo

UINT i, uCount = m_myListCtrl.GetNumberOfWorkAreas();
LPRECT lpRects = (LPRECT) malloc(uCount*sizeof(RECT));

if (lpRects != NULL)
{
    // Dump all of the work area dimensions.
    m_myListCtrl.GetWorkAreas(uCount, lpRects);

    for (i=0; i < uCount; i++)
    {
        TRACE(_T("Work area %d; left = %d, top = %d, right = %d, ")
            _T("bottom = %d\r\n"),
            i, lpRects[i].left, lpRects[i].top, lpRects[i].right,
            lpRects[i].bottom);
    }

    free(lpRects);
}
else
{
    TRACE(_T("Couldn't allocate enough memory!"));
}

`CListCtrl::GetOutlineColor`

Recupera a cor da borda de um controle de exibição de lista.

COLORREF GetOutlineColor() const;

Valor de retorno

Retorna uma estrutura COLORREF que contém a cor do contorno.

Comentários

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

`CListCtrl::GetOrigin`

Recupera a origem do modo de exibição atual para um controle de exibição de lista.

BOOL GetOrigin(LPPOINT lpPoint) const;

Parâmetros

lpPoint
Endereço de uma estrutura POINT que recebe a origem do modo de exibição.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero. No entanto, se o controle estiver na exibição de relatório, o valor retornado será sempre zero.

`CListCtrl::GetSelectedColumn`

Recupera o índice da coluna selecionada no momento no controle de lista.

UINT GetSelectedColumn() const;

Valor de retorno

O índice da coluna selecionada.

Comentários

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

`CListCtrl::GetSelectedCount`

Recupera o número de itens selecionados no controle de exibição de lista.

UINT GetSelectedCount() const;

Valor de retorno

O número de itens selecionados no controle de exibição de lista.

Exemplo

UINT i, uSelectedCount = m_myListCtrl.GetSelectedCount();
int  nItem = -1;

// Update all of the selected items.
if (uSelectedCount > 0)
{
    for (i=0; i < uSelectedCount; i++)
    {
        nItem = m_myListCtrl.GetNextItem(nItem, LVNI_SELECTED);
        ASSERT(nItem != -1);
        m_myListCtrl.Update(nItem);
    }
}

`CListCtrl::GetSelectionMark`

Recupera a marca de seleção de um controle de exibição de lista.

int GetSelectionMark();

Valor de retorno

A marca de seleção baseada em zero ou -1, se não houver marca de seleção.

Comentários

Essa função membro implementa o comportamento da macro do Win32 ListView_GetSelectionMark, conforme descrito no SDK do Windows.

Exemplo

// Set the selection mark to the first item only if no other item is
// selected.
if (m_myListCtrl.GetSelectionMark() == -1)
    m_myListCtrl.SetSelectionMark(0);

`CListCtrl::GetStringWidth`

Determina a largura mínima da coluna necessária para exibir toda a cadeia de caracteres fornecida.

int GetStringWidth(LPCTSTR lpsz) const;

Parâmetros

lpsz
Endereço de uma cadeia de caracteres terminada em nulo cuja largura deve ser determinada.

Valor de retorno

A largura, em pixels, da cadeia de caracteres apontada por lpsz.

Comentários

A largura retornada considera a fonte e as margens de coluna atuais do controle, mas não a largura de um ícone pequeno.

Exemplo

CString strColumn;
int nWidth;

// Insert six columns in the list view control. Make the width of
// the column be the width of the column header plus 50%.
for (int i = 0; i < 6; i++)
{
    strColumn.Format(_T("column %d"), i);
    nWidth = 3*m_myListCtrl.GetStringWidth(strColumn)/2;
    m_myListCtrl.InsertColumn(i, strColumn, LVCFMT_LEFT, nWidth);
}

`CListCtrl::GetSubItemRect`

Recupera o retângulo delimitador de um item em um controle de exibição de lista.

BOOL GetSubItemRect(
    int iItem,
    int iSubItem,
    int nArea,
    CRect& ref);

Parâmetros

iItem
Índice do item pai do subitem.

iSubItem
O índice com base em um do subitem.

nArea
Determina a parte do retângulo delimitador (do subitem de exibição de lista) a ser recuperada. A parte (ícone, rótulo ou ambos) do retângulo delimitador é especificada aplicando o operador bit a bit OR a um ou mais dos seguintes valores:

LVIR_BOUNDS Retorna o retângulo delimitador de todo o item, incluindo o ícone e o rótulo.
LVIR_ICONRetorna o retângulo delimitador do ícone ou ícone pequeno.
LVIR_LABEL Retorna o retângulo delimitador de todo o item, incluindo o ícone e o rótulo. Isso é idêntico a LVIR_BOUNDS.

ref
Referência a um objeto CRect que contém as coordenadas do retângulo delimitador do subitem.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Comentários

Essa função membro implementa o comportamento da macro do Win32 ListView_GetSubItemRect, conforme descrito no SDK do Windows.

`CListCtrl::GetTextBkColor`

Recupera a cor da tela de fundo do texto de um controle de exibição de lista.

COLORREF GetTextBkColor() const;

Valor de retorno

Um valor de 32 bits usado para especificar uma cor RGB.

Exemplo

Confira o exemplo de CListCtrl::SetTextBkColor.

`CListCtrl::GetTextColor`

Recupera a cor do texto de um controle de exibição de lista.

COLORREF GetTextColor() const;

Valor de retorno

Um valor de 32 bits usado para especificar uma cor RGB.

Exemplo

Confira o exemplo de CListCtrl::SetTextColor.

`CListCtrl::GetTileInfo`

Recupera informações sobre um bloco em um controle de exibição de lista.

BOOL GetTileInfo(PLVTILEINFO plvti) const;

Parâmetros

plvti
Um ponteiro para uma estrutura LVTILEINFO que recebe as informações do bloco.

Valor de retorno

O valor retornado não é usado.

Comentários

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

`CListCtrl::GetTileViewInfo`

Recupera informações sobre um controle de exibição de lista na exibição de bloco.

BOOL GetTileViewInfo(PLVTILEVIEWINFO ptvi) const;

Parâmetros

ptvi
Um ponteiro para uma estrutura LVTILEVIEWINFO que recebe as informações recuperadas.

Valor de retorno

O valor retornado não é usado.

Comentários

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

`CListCtrl::GetToolTips`

Recupera o controle de dica de ferramenta usado pelo controle de exibição de lista para exibir dicas de ferramentas.

CToolTipCtrl* GetToolTips() const;

Valor de retorno

Um ponteiro para um objeto CToolTipCtrl a ser usado pelo controle de lista. Se a função membro Create usar o estilo LVS_NOTOOLTIPS, nenhuma dica de ferramenta será usada e NULL será retornado.

Comentários

Essa função membro implementa o comportamento da mensagem LVM_GETTOOLTIPS do Win32, conforme descrito no SDK do Windows. A implementação MFC de GetToolTips retorna um objeto CToolTipCtrl, que é usado pelo controle de lista, em vez de um identificador para um controle de dica de ferramenta.

Exemplo

CToolTipCtrl* pTip = m_myListCtrl.GetToolTips();
if (NULL != pTip)
{
    pTip->UpdateTipText(_T("I'm a list view!"), &m_myListCtrl,
        IDD_MYLISTCTRL);
}

`CListCtrl::GetTopIndex`

Recupera o índice do item visível mais alto quando estiver no modo de exibição de lista ou no modo de exibição de relatório.

int GetTopIndex() const;

Valor de retorno

O índice do item visível mais alto.

Exemplo

// Make sure the focus is set to the list view control.
m_myListCtrl.SetFocus();

// Select all of the items that are completely visible.
int n = m_myListCtrl.GetTopIndex();
int nLast = n + m_myListCtrl.GetCountPerPage();

for (; n < nLast; n++)
{
    m_myListCtrl.SetItemState(n, LVIS_SELECTED, LVIS_SELECTED);
    ASSERT(m_myListCtrl.GetItemState(n, LVIS_SELECTED) == LVIS_SELECTED);
}

`CListCtrl::GetView`

Obtém a exibição do controle de exibição de lista.

DWORD GetView() const;

Valor de retorno

A exibição atual do controle de exibição de lista.

Comentários

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

`CListCtrl::GetViewRect`

Recupera o retângulo delimitador de todos os itens no controle de exibição de lista.

BOOL GetViewRect(LPRECT lpRect) const;

Parâmetros

lpRect
Endereço de uma estrutura RECT.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Comentários

O modo de exibição de lista deve estar na exibição de ícone ou no modo de exibição de ícone pequeno.

`CListCtrl::GetWorkAreas`

Recupera as áreas de trabalho atuais de um controle de exibição de lista.

void GetWorkAreas(
    int nWorkAreas,
    LPRECT pRect) const;

Parâmetros

nWorkAreas
O número de estruturas RECT contidas na matriz pRect.

pRect
Um ponteiro para uma matriz de estruturas RECT (ou objetos CRect) que recebem as áreas de trabalho do controle de exibição de lista. Os valores nessas estruturas estão nas coordenadas de cliente.

Comentários

Essa função membro implementa o comportamento da macro do Win32 ListView_GetWorkAreas, conforme descrito no SDK do Windows.

Exemplo

Confira o exemplo de CListCtrl::GetNumberOfWorkAreas.

`CListCtrl::HasGroup`

Determina se o controle de exibição de lista tem o grupo especificado.

BOOL HasGroup(int iGroupId) const;

Parâmetros

iGroupId
O identificador do grupo que está sendo solicitado.

Valor de retorno

Retornará TRUE se for bem-sucedido, FALSE em caso de falha.

Comentários

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

`CListCtrl::HitTest`

Determina qual item de exibição de lista, se houver, está na posição especificada.

int HitTest(LVHITTESTINFO* pHitTestInfo) const;

int HitTest(
    CPoint pt,
    UINT* pFlags = NULL) const;

Parâmetros

pHitTestInfo
Endereço de uma estrutura LVHITTESTINFO que contém a posição do teste de clique e que recebe informações sobre os resultados do teste de clique.

pt
Ponto a ser testado.

pFlags
Ponteiro para um inteiro que recebe informações sobre os resultados do teste. Confira a explicação do membro flags da estrutura LVHITTESTINFO no SDK do Windows.

Valor de retorno

O índice do item na posição especificada por pHitTestInfo, se houver; caso contrário, -1.

Comentários

Você pode usar os valores LVHT_ABOVE, LVHT_BELOW, LVHT_TOLEFTe LVHT_TORIGHT do membro flag da estrutura para determinar se deseja rolar o conteúdo de um controle de exibição de lista. Dois desses sinalizadores podem ser combinados, por exemplo, se a posição estiver acima e à esquerda da área de cliente.

Você pode testar o valor LVHT_ONITEM do membro flag da estrutura para determinar se uma determinada posição está sobre um item de exibição de lista. Esse valor é uma operação OR bit a bit nos valores LVHT_ONITEMICON, LVHT_ONITEMLABEL e LVHT_ONITEMSTATEICON do membro da estrutura flag.

Exemplo

void CListCtrlDlg::OnRClick(NMHDR* pNMHDR, LRESULT* pResult)
{
    LPNMITEMACTIVATE pia = (LPNMITEMACTIVATE)pNMHDR;
    CPoint point(pia->ptAction);

    // Select the item the user clicked on.
    UINT uFlags;
    int nItem = m_myListCtrl.HitTest(point, &uFlags);

    if (uFlags & LVHT_ONITEMLABEL)
    {
        m_myListCtrl.SetItem(nItem, 0, LVIF_STATE, NULL, 0, LVIS_SELECTED,
            LVIS_SELECTED, 0);
    }

    *pResult = 0;
}

`CListCtrl::InsertColumn`

Insere uma nova coluna em um controle de exibição de lista.

int InsertColumn(
    int nCol,
    const LVCOLUMN* pColumn);

int InsertColumn(
    int nCol,
    LPCTSTR lpszColumnHeading,
    int nFormat = LVCFMT_LEFT,
    int nWidth = -1,
    int nSubItem = -1);

Parâmetros

nCol
O índice da nova coluna.

pColumn
Endereço de uma estrutura LVCOLUMN que contém os atributos da nova coluna.

lpszColumnHeading
Endereço de uma cadeia de caracteres que contém o título da coluna.

nFormat
Inteiro especificando o alinhamento da coluna. Pode ser um dos valores a seguir: LVCFMT_LEFT, LVCFMT_RIGHT ou LVCFMT_CENTER.

nWidth
Largura da coluna em pixels. Se esse parâmetro for -1, a largura da coluna não será definida.

nSubItem
Índice do subitem associado à coluna. Se esse parâmetro for -1, nenhum subitem será associado à coluna.

Valor de retorno

O índice da nova coluna se for bem-sucedido; caso contrário, -1.

Comentários

A primeira coluna à esquerda em um controle de exibição de lista deve ser alinhada à esquerda.

A estrutura LVCOLUMN contém os atributos de uma coluna no modo de exibição de relatório. Ela também é usada para receber informações sobre uma coluna. Essa estrutura está descrita no SDK do Windows.

`CListCtrl::InsertGroup`

Insere um grupo no controle de exibição de lista.

LRESULT InsertGroup(
    int index,
    PLVGROUP pgrp);

Parâmetros

index
O índice do item onde o grupo deve ser inserido.

pgrp
Um ponteiro para uma estrutura LVGROUP que contém o grupo a ser adicionado.

Valor de retorno

Retorna o índice do item ao qual o grupo foi adicionado ou -1 se a operação falhou.

Comentários

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

`CListCtrl::InsertGroupSorted`

Insere o grupo especificado em uma lista ordenada de grupos.

LRESULT InsertGroupSorted(PLVINSERTGROUPSORTED pStructInsert);

Parâmetros

pStructInsert
Um ponteiro para uma estrutura LVINSERTGROUPSORTED que contém o grupo a ser inserido.

Valor de retorno

O valor retornado não é usado.

Comentários

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

`CListCtrl::InsertItem`

Insere um item no controle de exibição de lista.

int InsertItem(const LVITEM* pItem);

int InsertItem(
    int nItem,
    LPCTSTR lpszItem);

int InsertItem(
    int nItem,
    LPCTSTR lpszItem,
    int nImage);

int InsertItem(
    UINT nMask,
    int nItem,
    LPCTSTR lpszItem,
    UINT nState,
    UINT nStateMask,
    int nImage,
    LPARAM lParam);

Parâmetros

pItem
Ponteiro para uma estrutura LVITEM que especifica os atributos do item, conforme descrito no SDK do Windows.

nItem
Índice do item a ser inserido.

lpszItem
Endereço de uma cadeia de caracteres que contém o rótulo do item ou LPSTR_TEXTCALLBACK se for um item de retorno de chamada. Para obter informações sobre itens de retorno de chamada, consulte CListCtrl::GetCallbackMask.

nImage
Índice da imagem do item ou I_IMAGECALLBACK se for um item de retorno de chamada. Para obter informações sobre itens de retorno de chamada, consulte CListCtrl::GetCallbackMask.

nMask
O parâmetro nMask especifica quais atributos de item passados como parâmetros são válidos. Pode ser um ou mais dos valores de máscara descritos em Estrutura LVITEM no SDK do Windows. Os valores válidos podem ser combinados com o operador OR bit a bit.

nState
Indica o estado do item, a imagem de estado e a imagem de sobreposição. Para obter mais informações, consulte os tópicos Estrutura LVITEM do SDK do Windows e Estados do item de exibição de lista para obter uma lista de sinalizadores válidos.

nStateMask
Indica quais bits do membro do estado serão recuperados ou modificados. Para mais informações, confira a Estrutura LVITEM no SDK do Windows.

lParam
Um valor específico do aplicativo de 32 bits (64 bits, se estiver compilando para x64) associado ao item. Se esse parâmetro for especificado, você deverá definir o atributo nMask LVIF_PARAM.

Valor de retorno

O índice do novo item se for bem-sucedido; caso contrário, -1.

Comentários

Chamar esse método pode fazer com que a mensagem LVM_INSERTITEM seja enviada para a janela de controle. O manipulador de mensagens associado para o controle pode falhar ao definir o texto do item em determinadas condições (como usar estilos de janela como LVS_OWNERDRAW). Para obter mais informações sobre essas condições, consulte LVM_INSERTITEM no SDK do Windows.

Exemplo

CString strText;
int nColumnCount = m_myListCtrl.GetHeaderCtrl()->GetItemCount();

// Insert 10 items in the list view control.
for (int i = 0; i < 10; i++)
{
    strText.Format(TEXT("item %d"), i);

    // Insert the item, select every other item.
    m_myListCtrl.InsertItem(LVIF_TEXT | LVIF_STATE, i, strText,
        (i % 2) == 0 ? LVIS_SELECTED : 0, LVIS_SELECTED, 0, 0);

    // Initialize the text of the subitems.
    for (int j = 1; j < nColumnCount; j++)
    {
        strText.Format(TEXT("sub-item %d %d"), i, j);
        m_myListCtrl.SetItemText(i, j, strText);
    }
}

`CListCtrl::InsertMarkHitTest`

Recupera o ponto de inserção mais próximo de um ponto especificado.

int InsertMarkHitTest(
    LPPOINT pPoint,
    LPLVINSERTMARK plvim) const;

Parâmetros

pPoint
Um ponteiro para uma estrutura POINT que contém as coordenadas do teste de clique, em relação à área de cliente do controle de lista.

plvim
Um ponteiro para uma estrutura LVINSERTMARK que especifica o ponto de inserção mais próximo das coordenadas definidas pelo parâmetro do ponto.

Valor de retorno

O ponto de inserção mais próximo do ponto especificado.

Comentários

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

`CListCtrl::IsGroupViewEnabled`

Determina se a exibição de grupo está habilitada para um controle de exibição de lista.

BOOL IsGroupViewEnabled() const;

Valor de retorno

Retorna TRUE se a exibição de grupo estiver habilitada; caso contrário, FALSE.

Comentários

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

`CListCtrl::IsItemVisible`

Indica se um item especificado no controle de exibição de lista atual está visível.

BOOL IsItemVisible(int index) const;

Parâmetros

index
[in] Índice baseado em zero de um item no controle de exibição de lista atual.

Valor de retorno

TRUE se o item especificado estiver visível; caso contrário, FALSE.

Comentários

Esse método envia a mensagem LVM_ISITEMVISIBLE, que é descrita no SDK do Windows.

`CListCtrl::MapIDToIndex`

Mapeia a ID exclusiva de um item no controle de exibição de lista atual para um índice.

UINT MapIDToIndex(UINT id) const;

Parâmetros

id
[in] A ID exclusiva de um item.

Valor de retorno

O índice atual da ID especificada.

Comentários

Um controle de exibição de lista controla internamente os itens por índice. Isso pode apresentar problemas porque os índices podem ser alterados durante o tempo de vida do controle. O controle de exibição de lista pode marcar um item com uma ID quando o item é criado e é possível usar essa ID para garantir a exclusividade durante o tempo de vida do controle de exibição de lista.

Em um ambiente multi-threaded, o índice é garantido apenas no thread que hospeda o controle de exibição de lista, não em threads em segundo plano.

Esse método envia a mensagem LVM_MAPIDTOINDEX, que é descrita no SDK do Windows.

`CListCtrl::MapIndexToID`

Mapeia o índice de um item no controle de exibição de lista atual para uma ID exclusiva.

UINT MapIndexToID(UINT index) const;

Parâmetros

index
[in] O índice de base zero de um item.

Valor de retorno

Uma ID exclusiva para o item especificado.

Comentários

Um controle de exibição de lista controla internamente os itens por índice. Isso pode apresentar problemas porque os índices podem ser alterados durante o tempo de vida do controle. O controle de exibição de lista pode marcar um item com uma ID quando o item é criado. Você pode usar essa ID para acessar um item específico pelo tempo de vida do controle de exibição de lista.

Em um ambiente multi-threaded, o índice é garantido apenas no thread que hospeda o controle de exibição de lista, não em threads em segundo plano.

Esse método envia a mensagem LVM_MAPINDEXTOID, que é descrita no SDK do Windows.

Exemplo

O primeiro exemplo de código define uma variável m_listCtrl, que é usada para acessar o controle de exibição de lista atual. Essa variável será usada no próximo exemplo.

public:
    // Variable used to access the list control.
    CListCtrl m_listCtrl;

O próximo exemplo de código demonstra o método MapIndexToID. Em uma seção anterior deste exemplo de código, criamos um controle de exibição de lista que exibe duas colunas intituladas "ClientID" e "Grade" em uma exibição de relatório. O exemplo a seguir mapeia o índice de cada item de exibição de lista para um número de identificação e, em seguida, recupera o índice para cada número de identificação. Por fim, o exemplo relata se os índices originais foram recuperados.

// MapIndexToID
int iCount = m_listCtrl.GetItemCount();
UINT nId = 0;
UINT nIndex = 0;
for (int iIndexOriginal = 0; iIndexOriginal < iCount; iIndexOriginal++)
{
    // Map index to ID.
    nId = m_listCtrl.MapIndexToID((UINT)iIndexOriginal);

    // Map ID to index.
    nIndex = m_listCtrl.MapIDToIndex(nId);

    if (nIndex != (UINT)(iIndexOriginal))
    {
        CString str;
        str.Format(_T("Mapped index (%d) is not equal to original index (%d)"),
            nIndex, (UINT)(iIndexOriginal));
        AfxMessageBox(str);
        return;
    }
}
AfxMessageBox(_T("The mapped indexes and original indexes are equal."),
    MB_ICONINFORMATION);

`CListCtrl::MoveGroup`

Move o grupo especificado para o índice baseado em zero do controle de exibição de lista.

LRESULT MoveGroup(
    int iGroupId,
    int toIndex);

Parâmetros

iGroupId
O identificador do grupo a ser movido.

toIndex
O índice baseado em zero para o qual o grupo deve ser movido.

Valor de retorno

O valor retornado não é usado.

Comentários

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

`CListCtrl::MoveItemToGroup`

Move o item especificado para o grupo especificado.

void MoveItemToGroup(
    int idItemFrom,
    int idGroupTo);

Parâmetros

idItemFrom
[in] O índice do item a ser movido.

idGroupTo
[in] O identificador do grupo para o qual o item será movido.

Comentários

Observação

Atualmente, esse método não é implementado.

Esse método emula a funcionalidade da mensagem LVM_MOVEITEMTOGROUP, conforme descrito no SDK do Windows.

`CListCtrl::RedrawItems`

Força um controle de exibição de lista a redesenhar um intervalo de itens.

BOOL RedrawItems(
    int nFirst,
    int nLast);

Parâmetros

nFirst
Índice do primeiro item a ser redesenhado.

nLast
Índice do último item a ser redesenhado.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Comentários

Os itens especificados não serão redesenhados até que a janela de exibição de lista receba uma mensagem WM_PAINT. Para redesenhar imediatamente, chame a função UpdateWindow do Windows depois de usar essa função.

`CListCtrl::RemoveAllGroups`

Remove todos os grupos de um controle de exibição de lista.

void RemoveAllGroups();

Comentários

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

`CListCtrl::RemoveGroup`

Remove o grupo especificado do controle de exibição de lista.

LRESULT RemoveGroup(int iGroupId);

Parâmetros

iGroupId
O identificador do grupo a ser removido.

Valor de retorno

Retorna o índice do grupo se tiver êxito; caso contrário, -1.

Comentários

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

`CListCtrl::Scroll`

Rola o conteúdo de um controle de exibição de lista.

BOOL Scroll(CSize size);

Parâmetros

size
Um objeto CSize que especifica a quantidade de rolagem horizontal e vertical, em pixels. O membro y do tamanho é dividido pela altura, em pixels, da linha do controle de exibição de lista e o controle é rolado pelo número resultante de linhas.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

`CListCtrl::SetBkColor`

Define a cor da tela de fundo do controle de exibição de lista.

BOOL SetBkColor(COLORREF cr);

Parâmetros

cr
Cor da tela de fundo a ser definida ou o valor CLR_NONE para nenhuma cor da tela de fundo. Os controles de exibição de lista com cores da tela de fundo são redesenhados significativamente mais rápido do que aqueles sem cores de tela de fundo. Para obter informações, consulte COLORREF no SDK do Windows.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Exemplo

// Use the 3D button face color for the background.
COLORREF crBkColor = ::GetSysColor(COLOR_3DFACE);
m_myListCtrl.SetBkColor(crBkColor);
ASSERT(m_myListCtrl.GetBkColor() == crBkColor);

`CListCtrl::SetBkImage`

Define a imagem em segundo plano de um controle de exibição de lista.

BOOL SetBkImage(LVBKIMAGE* plvbkImage);

BOOL SetBkImage(
    HBITMAP hBitmap,
    BOOL fTile = TRUE,
    int xOffsetPercent = 0,
    int yOffsetPercent = 0);

BOOL SetBkImage(
    LPTSTR pszUrl,
    BOOL fTile = TRUE,
    int xOffsetPercent = 0,
    int yOffsetPercent = 0);

Parâmetros

plvbkImage
Endereço de uma estrutura LVBKIMAGE, contendo as novas informações de imagem em segundo plano.

hBitmap
Identificador para um bitmap.

pszUrl
Uma cadeia de caracteres terminada em NULL que contém a URL da imagem em segundo plano.

fTile
Diferente de zero se a imagem estiver em bloco na tela de fundo do controle de exibição de lista; caso contrário, 0.

xOffsetPercent
O deslocamento em pixels da borda esquerda da imagem, a partir da origem do controle de exibição de lista.

yOffsetPercent
O deslocamento em pixels da borda superior da imagem, a partir da origem do controle de exibição de lista.

Valor de retorno

Retorna diferente de zero se tiver êxito; caso contrário, zero.

Comentários

Observação

Como CListCtrl::SetBkImage usa a funcionalidade OLE COM, as bibliotecas OLE devem ser inicializadas antes de usar SetBkImage. É melhor inicializar as bibliotecas COM quando o aplicativo for inicializado e não inicializar as bibliotecas quando o aplicativo for encerrado. Isso é feito automaticamente nos aplicativos MFC que usam a tecnologia ActiveX, Automação OLE, Vinculação/Inserção OLE ou operações ODBC/DAO.

Exemplo

Confira o exemplo de CListCtrl::GetBkImage.

`CListCtrl::SetCallbackMask`

Define a máscara de retorno de chamada de um controle de exibição de lista.

BOOL SetCallbackMask(UINT nMask);

Parâmetros

nMask
Novo valor da máscara de retorno de chamada.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Exemplo

// Set the callback mask so that only the selected and focused states
// are stored for each item.
m_myListCtrl.SetCallbackMask(LVIS_SELECTED|LVIS_FOCUSED);
ASSERT(m_myListCtrl.GetCallbackMask() ==
    (LVIS_SELECTED|LVIS_FOCUSED));

`CListCtrl::SetCheck`

Determina se a imagem de estado de um item de controle de lista está visível.

BOOL SetCheck(
    int nItem,
    BOOL fCheck = TRUE);

Parâmetros

nItem
O índice com base em zero de um item de controle de lista.

fCheck
Especifica se a imagem de estado do item deve estar visível ou não. Por padrão, fCheck é TRUE e a imagem de estado está visível. Se fCheck for FALSE, não está visível.

Valor de retorno

Diferentes de zero se o item está marcado; caso contrário, 0.

Exemplo

int nCount = m_myListCtrl.GetItemCount();
BOOL fCheck = FALSE;

// Set the check state of every other item to TRUE and
// all others to FALSE.
for (int i = 0; i < nCount; i++)
{
    m_myListCtrl.SetCheck(i, fCheck);
    ASSERT((m_myListCtrl.GetCheck(i) && fCheck) ||
        (!m_myListCtrl.GetCheck(i) && !fCheck));
    fCheck = !fCheck;
}

`CListCtrl::SetColumn`

Define os atributos de uma coluna de exibição de lista.

BOOL SetColumn(
    int nCol,
    const LVCOLUMN* pColumn);

Parâmetros

nCol
Índice da coluna cujos atributos devem ser definidos.

pColumn
Endereço de uma estrutura LVCOLUMN que contém os novos atributos de coluna, conforme descrito no SDK do Windows. O membro mask da estrutura especifica quais atributos de coluna devem ser definidos. Se o membro mask especificar o valor LVCF_TEXT, o membro da estrutura pszText será o endereço de uma cadeia de caracteres terminada em nulo e o membro da estrutura cchTextMax será ignorado.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Exemplo

Confira o exemplo de CListCtrl::GetColumn.

`CListCtrl::SetColumnOrderArray`

Define a ordem da coluna (da esquerda para a direita) de um controle de exibição de lista.

BOOL SetColumnOrderArray(
    int iCount,
    LPINT piArray);

Parâmetros

piArray
Um ponteiro para um buffer que contém os valores de índice das colunas no controle de exibição de lista (da esquerda para a direita). O buffer deve ser grande o suficiente para conter o número total de colunas no controle de exibição de lista.

iCount
Número de colunas no controle de exibição de lista.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Comentários

Essa função membro implementa o comportamento da macro do Win32 ListView_SetColumnOrderArray, conforme descrito no SDK do Windows.

Exemplo

Confira o exemplo de CListCtrl::GetColumnOrderArray.

`CListCtrl::SetColumnWidth`

Altera a largura de uma coluna no modo de exibição de relatório ou de lista.

BOOL SetColumnWidth(
    int nCol,
    int cx);

Parâmetros

nCol
Índice da coluna para a qual a largura deve ser definida. Na exibição de lista, esse parâmetro deve ser 0.

cx
A nova largura da coluna. Pode ser LVSCW_AUTOSIZE ou LVSCW_AUTOSIZE_USEHEADER, conforme descrito em LVM_SETCOLUMNWIDTH no SDK do Windows.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

`CListCtrl::SetExtendedStyle`

Define os estilos estendidos atuais de um controle de exibição de lista.

DWORD SetExtendedStyle(DWORD dwNewStyle);

Parâmetros

dwNewStyle
Uma combinação de estilos estendidos a serem usados pelo controle de exibição de lista. Para obter uma lista descritiva desses estilos, consulte o tópico Estilos de Exibição de Lista Estendida no SDK do Windows.

Valor de retorno

Uma combinação dos estilos estendidos anteriores usados pelo controle de exibição de lista.

Comentários

Essa função membro implementa o comportamento da macro do Win32 ListView_SetExtendedListViewStyle, conforme descrito no SDK do Windows.

Exemplo

// Allow the header controls item to be movable by the user.
m_myListCtrl.SetExtendedStyle
    (m_myListCtrl.GetExtendedStyle()|LVS_EX_HEADERDRAGDROP);

`CListCtrl::SetGroupInfo`

Define as informações que descrevem o grupo especificado do controle de exibição de lista atual.

int SetGroupInfo(
    int iGroupId,
    PLVGROUP pgrp);

Parâmetros

iGroupId
O identificador do grupo cujas informações são definidas.

pgrp
Ponteiro para uma estrutura LVGROUP que contém as informações a serem definidas. O chamador é responsável por alocar essa estrutura e definir seus membros.

Valor de retorno

A ID do grupo se o método for bem-sucedido; caso contrário, -1.

Comentários

Esse método envia a mensagem LVM_SETGROUPINFO, que é descrita no SDK do Windows.

`CListCtrl::SetGroupMetrics`

Define as métricas de grupo de um controle de exibição de lista.

void SetGroupMetrics(PLVGROUPMETRICS pGroupMetrics);

Parâmetros

pGroupMetrics
Um ponteiro para uma estrutura LVGROUPMETRICS que contém as informações de métricas de grupo a serem definidas.

Comentários

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

`CListCtrl::SetHotCursor`

Define o cursor usado quando o rastreio importante está habilitado para um controle de exibição de lista.

HCURSOR SetHotCursor(HCURSOR hc);

Parâmetros

hc
Um identificador para um recurso de cursor, usado para representar o cursor dinâmico.

Valor de retorno

O identificador do recurso de cursor dinâmico anterior que está sendo usado pelo controle de exibição de lista.

Comentários

Essa função membro implementa o comportamento da macro do Win32 ListView_SetHotCursor, conforme descrito no SDK do Windows.

O cursor dinâmico, visível somente quando a seleção de foco está habilitada, aparece conforme o cursor passa por qualquer item de exibição de lista. A seleção de foco está habilitada definindo o estilo estendido LVS_EX_TRACKSELECT.

Exemplo

Confira o exemplo de CListCtrl::GetHotCursor.

`CListCtrl::SetHotItem`

Define o item mais acessado atual de um controle de exibição de lista.

int SetHotItem(int iIndex);

Parâmetros

iIndex
Índice com base em zero do item a ser definido como o item mais acessado.

Valor de retorno

O índice com base em zero do item mais acessado anteriormente.

Comentários

Essa função membro implementa o comportamento da macro do Win32 ListView_SetHotItem, conforme descrito no SDK do Windows.

Exemplo

Confira o exemplo de CListCtrl::GetHotItem.

`CListCtrl::SetHoverTime`

Define o tempo de foco atual de um controle de exibição de lista.

DWORD SetHoverTime(DWORD dwHoverTime = (DWORD)-1);

Parâmetros

dwHoverTime
O novo atraso, em milissegundos, que o cursor do mouse deve passar sobre um item antes de ser selecionado. Se o valor padrão for passado, o tempo será definido como o tempo de foco padrão.

Valor de retorno

O tempo de foco anterior, em milissegundos.

Comentários

Essa função membro implementa o comportamento da macro do Win32 ListView_SetHoverTime, conforme descrito no SDK do Windows.

Exemplo

Confira o exemplo de CListCtrl::GetHoverTime.

`CListCtrl::SetIconSpacing`

Define o espaçamento entre ícones em um controle de exibição de lista.

CSize SetIconSpacing(
    int cx,
    int cy);

CSize SetIconSpacing(CSize size);

Parâmetros

cx
A distância (em pixels) entre os ícones no eixo x.

cy
A distância (em pixels) entre os ícones no eixo y.

size
Um objeto CSize que especifica a distância (em pixels) entre ícones nos eixos x e y.

Valor de retorno

Um objeto CSize que contém os valores anteriores para espaçamento de ícone.

Comentários

Essa função membro implementa o comportamento da macro do Win32 ListView_SetIconSpacing, conforme descrito no SDK do Windows.

Exemplo

// Leave lots of space between icons.
m_myListCtrl.SetIconSpacing(CSize(100, 100));

`CListCtrl::SetImageList`

Atribui uma lista de imagens a um controle de exibição de lista.

CImageList* SetImageList(
    CImageList* pImageList,
    int nImageListType);

Parâmetros

pImageList
Ponteiro para a lista de imagens a ser atribuída.

nImageListType
Tipo de lista de imagens. Pode ser um destes valores:

LVSIL_NORMAL Lista de imagens com ícones grandes.
LVSIL_SMALL Lista de imagens com ícones pequenos.
LVSIL_STATE Lista de imagens com imagens de estado.

Valor de retorno

Um ponteiro para a lista de imagens anterior.

Exemplo

Confira o exemplo de CListCtrl::GetImageList.

`CListCtrl::SetInfoTip`

Define o texto da dica de ferramenta.

BOOL SetInfoTip(PLVSETINFOTIP plvInfoTip);

Parâmetros

plvInfoTip
Um ponteiro para uma estrutura LVFSETINFOTIP que contém as informações a serem definidas.

Valor de retorno

Retornará TRUE se for bem-sucedido, FALSE em caso de falha.

Comentários

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

`CListCtrl::SetInsertMark`

Define o ponto de inserção como a posição definida.

BOOL SetInsertMark(LPLVINSERTMARK plvim);

Parâmetros

plvim
Um ponteiro para uma estrutura LVINSERTMARK que especifica onde definir o ponto de inserção.

Valor de retorno

Retorna TRUE, se bem-sucedido; caso contrário, FALSE. FALSE será retornado se o tamanho no membro cbSize da estrutura LVINSERTMARK não for igual ao tamanho real da estrutura ou quando um ponto de inserção não se aplicar na exibição atual.

Comentários

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

`CListCtrl::SetInsertMarkColor`

Define a cor do ponto de inserção.

COLORREF SetInsertMarkColor(COLORREF color);

Parâmetros

color
Uma estrutura COLORREF que especifica a cor para definir o ponto de inserção.

Valor de retorno

Retorna uma estrutura COLORREF que contém a cor anterior.

Comentários

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

`CListCtrl::SetItem`

Define alguns ou todos os atributos de um item de exibição de lista.

BOOL SetItem(const LVITEM* pItem);

BOOL SetItem(
    int nItem,
    int nSubItem,
    UINT nMask,
    LPCTSTR lpszItem,
    int nImage,
    UINT nState,
    UINT nStateMask,
    LPARAM lParam);

BOOL SetItem(
    int nItem,
    int nSubItem,
    UINT nMask,
    LPCTSTR lpszItem,
    int nImage,
    UINT nState,
    UINT nStateMask,
    LPARAM lParam,
    int nIndent);

Parâmetros

pItem
Endereço de uma estrutura LVITEM que contém os novos atributos de item, conforme descrito no SDK do Windows. Os membros iItem e iSubItem da estrutura identificam o item ou subitem e o membro mask da estrutura especifica quais atributos devem ser definidos. Para obter mais informações sobre o membro mask, consulte as Observações.

nItem
Índice do item cujos atributos devem ser definidos.

nSubItem
Índice do subitem cujos atributos devem ser definidos.

nMask
Especifica quais atributos devem ser definidos (consulte os Comentários).

lpszItem
Endereço de uma cadeia de caracteres terminada em nulo especificando o rótulo do item.

nImage
Índice da imagem do item na lista de imagens.

nState
Especifica os valores dos estados a serem alterados (consulte os Comentários).

nStateMask
Especifica quais estados devem ser alterados (consulte os Comentários).

lParam
Um valor específico do aplicativo de 32 bits (64 bits, se estiver compilando para x64) para associar ao item.

nIndent
Largura, em pixels, do recuo. Se nIndent for menor que a largura mínima definida pelo sistema, a nova largura será definida como o mínimo definido pelo sistema

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Comentários

Os membros iItem e iSubItem da estrutura LVITEM e os parâmetros nItem e nSubItem identificam o item e o subitem cujos atributos devem ser definidos.

O membro mask da estrutura LVITEM e o parâmetro nMask especificam quais atributos de item devem ser definidos:

LVIF_TEXT O membro pszText ou o parâmetro lpszItem é o endereço de uma cadeia de caracteres terminada em nulo; o membro cchTextMax é ignorado.
LVIF_STATE O membro stateMask ou parâmetro nStateMask especifica quais estados de item serão alterados e o membro state ou parâmetro nState contém os valores desses estados.

Exemplo

Confira o exemplo de CListCtrl::HitTest.

`CListCtrl::SetItemCount`

Prepara um controle de exibição de lista para adicionar um grande número de itens.

void SetItemCount(int nItems);

Parâmetros

nItems
Número de itens que o controle conterá em última instância.

Comentários

Para definir a contagem de itens para um controle de exibição de lista virtual, consulte CListCtrl::SetItemCountEx.

Essa função membro implementa o comportamento da macro do Win32 ListView_SetItemCount, conforme descrito no SDK do Windows.

Exemplo

CString str;

// Add 1024 items to the list view control.
m_myListCtrl.SetItemCount(1024);

for (int i = 0; i < 1024; i++)
{
    str.Format(TEXT("item %d"), i);
    m_myListCtrl.InsertItem(i, str);
}

`CListCtrl::SetItemCountEx`

Define a contagem de itens para um controle de exibição de lista virtual.

BOOL SetItemCountEx(
    int iCount,
    DWORD dwFlags = LVSICF_NOINVALIDATEALL);

Parâmetros

iCount
Número de itens que o controle conterá em última instância.

dwFlags
Especifica o comportamento do controle de exibição de lista após redefinir a contagem de itens. Esse valor pode ser uma combinação do seguinte:

LVSICF_NOINVALIDATEALL O controle de exibição de lista não será redesenhado, a menos que os itens afetados estejam atualmente em exibição. Este é o valor padrão.
LVSICF_NOSCROLL O controle de exibição de lista não alterará a posição de rolagem quando a contagem de itens for alterada.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Comentários

Essa função membro implementa o comportamento da macro do Win32 ListView_SetItemCountEx, conforme descrito no SDK do Windows e só deve ser chamado para exibições de lista virtual.

Exemplo

CString str;

// Add 1024 items to the list view control.

// Force my virtual list view control to allocate
// enough memory for my 1024 items.
m_myVirtualListCtrl.SetItemCountEx(1024, LVSICF_NOSCROLL|
    LVSICF_NOINVALIDATEALL);

for (int i = 0; i < 1024; i++)
{
    str.Format(TEXT("item %d"), i);
    m_myVirtualListCtrl.InsertItem(i, str);
}

`CListCtrl::SetItemData`

Define o valor específico do aplicativo de 32 bits (64 bits, se você estiver compilando para x64) associado ao item especificado por nItem.

BOOL SetItemData(int nItem, DWORD_PTR dwData);

Parâmetros

nItem
Índice do item de lista cujos dados devem ser definidos.

dwData
Um valor de 32 bits (64 bits, se estiver compilando para x64) para associar ao item.

Valor de retorno

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

Comentários

Esse valor é o membro lParam da estrutura LVITEM, conforme descrito no SDK do Windows.

Exemplo

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

`CListCtrl::SetItemIndexState`

Define o estado de um item no controle de exibição de lista atual.

BOOL SetItemIndexState(
    PLVITEMINDEX pItemIndex,
    DWORD dwState,
    DWORD dwMask) const;

Parâmetros

pItemIndex
[in] Ponteiro para uma estrutura LVITEMINDEX que descreve um item. O chamador é responsável por alocar essa estrutura e definir seus membros.

dwState
[in] O estado para definir o item, que é uma combinação bit a bit dos estados do item de exibição de lista. Especifique zero para redefinir ou um para definir um estado.

dwMask
[in] Uma máscara dos bits válidos do estado especificados pelo parâmetro dwState. Especifique uma combinação bit a bit (OR) dos estados do item de exibição de lista.

Valor de retorno

TRUE se o método for bem-sucedido. Caso contrário, FALSE.

Comentários

Para obter mais informações sobre o parâmetro dwState, consulte Estados do item de exibição de lista.

Para obter mais informações sobre o parâmetro dwMask, consulte o membro stateMask da estrutura LVITEM.

Esse método envia a mensagem LVM_SETITEMINDEXSTATE, que é descrita no SDK do Windows.

`CListCtrl::SetItemPosition`

Move um item para uma posição especificada em um controle de exibição de lista.

BOOL SetItemPosition(
    int nItem,
    POINT pt);

Parâmetros

nItem
Índice do item cuja posição deve ser definida.

pt
Uma estrutura POINT que especifica a nova posição, em coordenadas de exibição, do canto superior esquerdo do item.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Comentários

O controle deve estar na exibição do ícone ou do ícone pequeno.

Se o controle de exibição de lista tiver o estilo LVS_AUTOARRANGE, a exibição de lista será organizada após a posição do item ser definida.

Exemplo

Confira o exemplo de CListCtrl::GetItemPosition.

`CListCtrl::SetItemState`

Altera o estado de um item em um controle de exibição de lista.

BOOL SetItemState(
    int nItem,
    LVITEM* pItem);

BOOL SetItemState(
    int nItem,
    UINT nState,
    UINT nMask);

Parâmetros

nItem
Índice do item cujo estado deve ser definido. Passe -1 para aplicar a alteração de estado a todos os itens.

pItem
Endereço de uma estrutura LVITEM, conforme descrito no SDK do Windows. O membro stateMask da estrutura especifica quais bits de estado devem ser alterados e o membro state da estrutura contém os novos valores para esses bits. Os outros membros são ignorados.

nState
Novos valores para os bits de estado. Para obter uma lista de valores possíveis, consulte CListCtrl::GetNextItem e o membro do estado LVITEM.

nMask
Mascarar especificando quais bits de estado serão alterados. Esse valor corresponde ao membro stateMask da estrutura LVITEM.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Comentários

O "estado" de um item é um valor que especifica a disponibilidade do item, indica as ações do usuário ou reflete o status do item. Um controle de exibição de lista altera alguns bits de estado, como quando o usuário seleciona um item. Um aplicativo pode alterar outros bits de estado para desabilitar ou ocultar o item ou especificar uma imagem de sobreposição ou imagem de estado.

Exemplo

Confira o exemplo de CListCtrl::GetTopIndex.

`CListCtrl::SetItemText`

Altera o texto de um item ou subitem de exibição de lista.

BOOL SetItemText(
    int nItem,
    int nSubItem,
    LPCTSTR lpszText);

Parâmetros

nItem
Índice do item cujo texto deve ser definido.

nSubItem
Índice do subitem ou zero para definir o rótulo do item.

lpszText
Ponteiro para uma cadeia de caracteres que contém o texto do novo item.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Comentários

Esse método não se destina a ser usado com controles que contêm o estilo de janela LVS_OWNERDATA (na verdade, isso causará uma declaração nos builds de depuração). Para obter mais informações sobre esse estilo de controle de lista, consulte Visão geral dos controles de exibição de lista.

Exemplo

Confira o exemplo de CListCtrl::InsertItem.

`CListCtrl::SetOutlineColor`

Define a cor da borda de um controle de exibição de lista se o estilo de janela estendida LVS_EX_BORDERSELECT estiver definido.

COLORREF SetOutlineColor(COLORREF color);

Parâmetros

color
A nova estrutura COLORREF que contém a cor do contorno.

Valor de retorno

A estrutura COLORREF anterior que contém a cor do contorno

Comentários

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

CListCtrl::SetSelectedColumn

Define a coluna selecionada do controle de exibição de lista.

LRESULT SetSelectedColumn(int iCol);

Parâmetros

iCol
O índice da coluna a ser selecionada.

Valor de retorno

O valor retornado não é usado.

Comentários

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

`CListCtrl::SetSelectionMark`

Define a marca de seleção de um controle de exibição de lista.

int SetSelectionMark(int iIndex);

Parâmetros

iIndex
O índice baseado em zero do primeiro item em uma seleção múltipla.

Valor de retorno

A marca de seleção anterior ou -1 se não houver marca de seleção.

Comentários

Essa função membro implementa o comportamento da macro do Win32 ListView_SetSelectionMark, conforme descrito no SDK do Windows.

Exemplo

Confira o exemplo de CListCtrl::GetSelectionMark.

`CListCtrl::SetTextBkColor`

Define a cor da tela de fundo do texto em um controle de exibição de lista.

BOOL SetTextBkColor(COLORREF cr);

Parâmetros

cr
COLORREF especificando a nova cor da tela de fundo do texto. Para obter informações, consulte COLORREF no SDK do Windows.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Exemplo

// Use the 3D button face color for the background.
COLORREF crBkColor = ::GetSysColor(COLOR_3DFACE);
m_myListCtrl.SetTextBkColor(crBkColor);
ASSERT(m_myListCtrl.GetTextBkColor() == crBkColor);

`CListCtrl::SetTextColor`

Define a cor do texto de um controle de exibição de lista.

BOOL SetTextColor(COLORREF cr);

Parâmetros

cr
COLORREF especificando a nova cor do texto. Para obter informações, consulte COLORREF no SDK do Windows.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Exemplo

// Use the window text color for
// the item text of the list view control.
COLORREF crTextColor = ::GetSysColor(COLOR_WINDOWTEXT);
m_myListCtrl.SetTextColor(crTextColor);
ASSERT(m_myListCtrl.GetTextColor() == crTextColor);

`CListCtrl::SetTileInfo`

Define as informações de um bloco do controle de exibição de lista.

BOOL SetTileInfo(PLVTILEINFO pTileInfo);

Parâmetros

pTileInfo
Um ponteiro para uma estrutura LVTILEINFO que contém as informações a serem definidas.

Valor de retorno

Retornará TRUE se for bem-sucedido, FALSE em caso de falha.

Comentários

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

`CListCtrl::SetTileViewInfo`

Define informações usadas por um controle de exibição de lista no modo de exibição de bloco.

BOOL SetTileViewInfo(PLVTILEVIEWINFO ptvi);

Parâmetros

ptvi
Um ponteiro para uma estrutura LVTILEVIEWINFO que contém as informações a serem definidas.

Valor de retorno

Retornará TRUE se for bem-sucedido, FALSE em caso de falha.

Comentários

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

`CListCtrl::SetToolTips`

Define o controle de dica de ferramenta a ser usado pelo controle de exibição de lista para exibir dicas de ferramentas.

CToolTipCtrl* SetToolTips(CToolTipCtrl* pWndTip);

Parâmetros

pWndTip
Um ponteiro para um objeto CToolTipCtrl a ser usado pelo controle de lista.

Valor de retorno

Um ponteiro para um objeto CToolTipCtrl que contém a dica de ferramenta usada anteriormente pelo controle ou NULL se nenhuma dica de ferramenta foi usada anteriormente.

Comentários

Essa função membro implementa o comportamento da mensagem LVM_SETTOOLTIPS do Win32, conforme descrito no SDK do Windows.

Para não usar dicas de ferramenta, indique o estilo LVS_NOTOOLTIPS ao criar o objeto CListCtrl.

`CListCtrl::SetView`

Define a exibição do controle de exibição de lista.

DWORD SetView(int iView);

Parâmetros

iView
A exibição a ser selecionada.

Valor de retorno

Retorna 1, se bem-sucedido; caso contrário, -1. Por exemplo, -1 será retornado se a exibição for inválida.

Comentários

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

`CListCtrl::SetWorkAreas`

Define a área em que os ícones podem ser exibidos em um controle de exibição de lista.

void SetWorkAreas(
    int nWorkAreas,
    LPRECT lpRect);

Parâmetros

nWorkAreas
O número de estruturas RECT (ou objetos CRect) na matriz apontada por lpRect.

lpRect
O endereço de uma matriz de estruturas RECT (ou objetos CRect) que especificam as novas áreas de trabalho do controle de exibição de lista. Essas áreas devem ser especificadas nas coordenadas de cliente. Se esse parâmetro for NULL, a área de trabalho será definida como a área de cliente do controle.

Comentários

Essa função membro implementa o comportamento da macro do Win32 ListView_SetWorkAreas, conforme descrito no SDK do Windows.

Exemplo

// Remove all working areas.
m_myListCtrl.SetWorkAreas(0, NULL);

`CListCtrl::SortGroups`

Usa uma função de comparação definida pelo aplicativo para classificar os grupos por ID em um controle de exibição de lista.

BOOL SortGroups(
    PFNLVGROUPCOMPARE _pfnGroupCompare,
    LPVOID _plv);

Parâmetros

_pfnGroupCompare
Um ponteiro para a função de comparação de grupo.

_plv
Um ponteiro vazio.

Valor de retorno

Retornará TRUE se for bem-sucedido, FALSE em caso de falha.

Comentários

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

`CListCtrl::SortItems`

Classifica os itens de exibição de lista usando uma função de comparação definida pelo aplicativo.

BOOL SortItems(
    PFNLVCOMPARE pfnCompare,
    DWORD_PTR dwData);

Parâmetros

pfnCompare
[in] Endereço da função de comparação definida pelo aplicativo.

A operação de classificação chama a função de comparação sempre que a ordem relativa de dois itens de lista precisa ser determinada. A função de comparação deve ser um membro estático de uma classe ou uma função autônoma que não seja membro de nenhuma classe.

dwData
[in] Valor definido pelo aplicativo que é passado para a função de comparação.

Valor de retorno

TRUE se o método for bem-sucedido; caso contrário, FALSE.

Comentários

Esse método altera o índice de cada item para refletir a nova sequência.

A função de comparação pfnCompare tem a seguinte forma:

int CALLBACK CompareFunc(LPARAM lParam1,
    LPARAM lParam2,
    LPARAM lParamSort);

A função de comparação deve retornar um valor negativo se o primeiro item preceder o segundo, um valor positivo se o primeiro item seguir o segundo ou zero se os dois itens forem iguais.

O parâmetro lParam1 é o valor de 32 bits (64 bits, se você estiver compilando para x64) associado ao primeiro item que é comparado e o parâmetro lParam2 é o valor associado ao segundo item. Esses valores foram especificados no membro lParam da estrutura LVITEM dos itens quando foram inseridos na lista. O parâmetro lParamSort é o mesmo que o valor dwData.

Esse método envia a mensagem LVM_SORTITEMS, que é descrita no SDK do Windows.

Exemplo

Veja a seguir uma função de comparação simples que resulta na classificação dos itens por seus valores lParam.

// Sort items by associated lParam
int CALLBACK CListCtrlDlg::MyCompareProc(LPARAM lParam1, LPARAM lParam2,
    LPARAM lParamSort)
{
    UNREFERENCED_PARAMETER(lParamSort);
    return (int)(lParam1 - lParam2);
}

// Sort the items by passing in the comparison function.
void CListCtrlDlg::Sort()
{
    m_myListCtrl.SortItems(&CListCtrlDlg::MyCompareProc, 0);
}

`CListCtrl::SortItemsEx`

Classifica os itens do controle de exibição de lista atual usando uma função de comparação definida pelo aplicativo.

BOOL SortItemsEx(
    PFNLVCOMPARE pfnCompare,
    DWORD_PTR dwData);

Parâmetros

pfnCompare
[in] Endereço da função de comparação definida pelo aplicativo. A operação de classificação chama a função de comparação sempre que a ordem relativa de dois itens de lista precisa ser determinada. A função de comparação deve ser um membro estático de uma classe ou uma função autônoma que não seja membro de nenhuma classe.

dwData
[in] Valor definido pelo aplicativo passado para a função de comparação.

Valor de retorno

TRUE se o método for bem-sucedido. Caso contrário, FALSE.

Comentários

Esse método altera o índice de cada item para refletir a nova sequência.

A função de comparação pfnCompare tem a seguinte forma:

int CALLBACK CompareFunc(LPARAM lParam1,
    LPARAM lParam2,
    LPARAM lParamSort);

Essa mensagem é semelhante a LVM_SORTITEMS, exceto pelo tipo de informação passada para a função de comparação. Em LVM_SORTITEMS, lParam1 e lParam2 são os valores dos itens a serem comparados. Em LVM_SORTITEMSEX, lParam1 é o índice atual do primeiro item a ser comparado e lParam2 é o índice atual do segundo item. Você pode enviar uma mensagem LVM_GETITEMTEXT para recuperar mais informações sobre um item.

A função de comparação deve retornar um valor negativo se o primeiro item preceder o segundo, um valor positivo se o primeiro item seguir o segundo ou zero se os dois itens forem iguais.

Observação

Durante o processo de classificação, o conteúdo de exibição de lista é instável. Se a função de retorno de chamada enviar mensagens para o controle de exibição de lista diferente de LVM_GETITEM, os resultados serão imprevisíveis.

Esse método envia a mensagem LVM_SORTITEMSEX, que é descrita no SDK do Windows.

Exemplo

O primeiro exemplo de código define uma variável m_listCtrl, que é usada para acessar o controle de exibição de lista atual. Essa variável será usada no próximo exemplo.

public:
    // Variable used to access the list control.
    CListCtrl m_listCtrl;

O próximo exemplo de código demonstra o método SortItemEx. Em uma seção anterior deste exemplo de código, criamos um controle de exibição de lista que exibe duas colunas intituladas "ClientID" e "Grade" em uma exibição de relatório. O exemplo de código a seguir classifica a tabela usando os valores na coluna "Grade".

// The ListCompareFunc() method is a global function used by SortItemEx().
int CALLBACK ListCompareFunc(
                             LPARAM lParam1,
                             LPARAM lParam2,
                             LPARAM lParamSort)
{
    CListCtrl* pListCtrl = (CListCtrl*) lParamSort;
    CString    strItem1 = pListCtrl->GetItemText(static_cast<int>(lParam1), 1);
    CString    strItem2 = pListCtrl->GetItemText(static_cast<int>(lParam2), 1)
    int x1 = _tstoi(strItem1.GetBuffer());
    int x2 = _tstoi(strItem2.GetBuffer());
    int result = 0;
    if ((x1 - x2) < 0)
        result = -1;
    else if ((x1 - x2) == 0)
        result = 0;
    else
        result = 1;

    return result;
}

void CCListCtrl_s2Dlg::OnBnClickedButton1()
{
    // SortItemsEx
    m_listCtrl.SortItemsEx( ListCompareFunc, (LPARAM)&m_listCtrl );
}

`CListCtrl::SubItemHitTest`

Determina qual item de exibição de lista, se houver, está em uma determinada posição.

int SubItemHitTest(LPLVHITTESTINFO pInfo);

Parâmetros

pInfo
Um ponteiro para a estrutura LVHITTESTINFO.

Valor de retorno

O índice baseado em um do item, ou subitem, que está sendo testado (se houver); caso contrário, -1.

Comentários

Essa função membro implementa o comportamento da macro do Win32 ListView_SubItemHitTest, conforme descrito no SDK do Windows.

Exemplo

void CListCtrlDlg::OnDblClk(NMHDR* pNMHDR, LRESULT* pResult)
{
    UNREFERENCED_PARAMETER(pResult);
    LPNMITEMACTIVATE pia = (LPNMITEMACTIVATE)pNMHDR;
    LVHITTESTINFO lvhti;

    // Clear the subitem text the user clicked on.
    lvhti.pt = pia->ptAction;
    m_myListCtrl.SubItemHitTest(&lvhti);

    if (lvhti.flags & LVHT_ONITEMLABEL)
    {
        m_myListCtrl.SetItemText(lvhti.iItem, lvhti.iSubItem, NULL);
    }
}

`CListCtrl::Update`

Força o controle de exibição de lista a redesenhar o item especificado por nItem.

BOOL Update(int nItem);

Parâmetros

nItem
Índice do item a ser atualizado.

Valor de retorno

Diferente de zero se bem-sucedido; caso contrário, zero.

Comentários

Essa função também organiza o controle de exibição de lista se tiver o estilo LVS_AUTOARRANGE.

Exemplo

Confira o exemplo de CListCtrl::GetSelectedCount.

Confira também

ROWLIST de exemplo do MFC
Classe CWnd
Gráfico da hierarquia
Classe CImageList

Partilhar via

Classe CListCtrl

Sintaxe

Membros

Construtores públicos

Métodos públicos

Comentários

Exibições

Estilos estendidos

Itens e subitems

Listas de imagens

Hierarquia de herança

Requisitos

CListCtrl::ApproximateViewRect

Parâmetros

Valor de retorno

Comentários

CListCtrl::Arrange

Parâmetros

Valor de retorno

Comentários

Exemplo

CListCtrl::CancelEditLabel

Comentários

CListCtrl::CListCtrl

CListCtrl::Create

Parâmetros

Valor de retorno

Comentários

Exemplo

CListCtrl::CreateEx

Parâmetros

Valor de retorno

Comentários

CListCtrl::CreateDragImage

Parâmetros

Valor de retorno

Comentários

CListCtrl::DeleteAllItems

Valor de retorno

Exemplo

CListCtrl::DeleteColumn

Parâmetros

Valor de retorno

Exemplo

CListCtrl::DeleteItem

Parâmetros

Valor de retorno

Exemplo

CListCtrl::DrawItem

Parâmetros

Comentários

CListCtrl::EditLabel

Parâmetros

Valor de retorno

Comentários

Exemplo

CListCtrl::EnableGroupView

Parâmetros

Valor de retorno

Comentários

CListCtrl::EnsureVisible

Parâmetros

Valor de retorno

Comentários

Exemplo

CListCtrl::FindItem

Parâmetros

Valor de retorno

Comentários

Exemplo

CListCtrl::GetBkColor

Valor de retorno

Exemplo

CListCtrl::GetBkImage

Parâmetros

Valor de retorno

Comentários

Exemplo

CListCtrl::GetCallbackMask

Classe `CListCtrl`

`CListCtrl::ApproximateViewRect`

`CListCtrl::Arrange`

`CListCtrl::CancelEditLabel`

`CListCtrl::CListCtrl`

`CListCtrl::Create`

`CListCtrl::CreateEx`

`CListCtrl::CreateDragImage`

`CListCtrl::DeleteAllItems`

`CListCtrl::DeleteColumn`

`CListCtrl::DeleteItem`

`CListCtrl::DrawItem`

`CListCtrl::EditLabel`

`CListCtrl::EnableGroupView`

`CListCtrl::EnsureVisible`

`CListCtrl::FindItem`

`CListCtrl::GetBkColor`

`CListCtrl::GetBkImage`

`CListCtrl::GetCallbackMask`

`CListCtrl::GetCheck`

`CListCtrl::GetColumn`

`CListCtrl::GetColumnOrderArray`

`CListCtrl::GetColumnWidth`

`CListCtrl::GetCountPerPage`

`CListCtrl::GetEditControl`

`CListCtrl::GetEmptyText`

`CListCtrl::GetExtendedStyle`

`CListCtrl::GetFirstSelectedItemPosition`

`CListCtrl::GetFocusedGroup`

`CListCtrl::GetGroupCount`

`CListCtrl::GetGroupInfo`

`CListCtrl::GetGroupInfoByIndex`

`CListCtrl::GetGroupMetrics`

`CListCtrl::GetGroupRect`

`CListCtrl::GetGroupState`

`CListCtrl::GetHeaderCtrl`