CListCtrl Classe

Encapsula a funcionalidade de um "controlo de vista de lista", que mostra uma coleção de itens, cada um composto por um ícone (de uma lista de imagens) e um rótulo.

Sintaxe

class CListCtrl : public CWnd

Membros

Construtores Públicos

Métodos Públicos

Observações

Para além de um ícone e etiqueta, cada item pode ter informação exibida em colunas à direita do ícone e da etiqueta. Este controlo (e, portanto, a CListCtrl classe) está disponível apenas para programas a correr sob Windows 95/98 e Windows NT versão 3.51 e posteriores.

Segue-se uma breve visão geral da CListCtrl turma. Para uma discussão detalhada e conceptual, veja Utilização CListCtrl e Controlos.

Views

Os controlos da vista de lista podem mostrar o seu conteúdo de quatro formas diferentes, chamadas de "vistas".

• Visualização de ícones

  Cada item aparece como um ícone em tamanho real (32 x 32 píxeis) com um rótulo por baixo. O utilizador pode arrastar os itens para qualquer local na janela da vista de lista.

• Vista de ícones pequenos

  Cada item aparece como um pequeno ícone (16 x 16 píxeis) com o rótulo à direita. O utilizador pode arrastar os itens para qualquer local na janela da vista de lista.

• Visualização da lista

  Cada item aparece como um pequeno ícone com um rótulo à direita. Os itens estão organizados em colunas e não podem ser arrastados para qualquer local na janela de vista de lista.

• Visualização de relatório

  Cada item aparece numa linha própria, com informação adicional disposta em colunas à direita. A coluna mais à esquerda contém o ícone pequeno e o rótulo, e as colunas seguintes contêm subitens especificados pela aplicação. Um controlo de cabeçalho embutido (classe CHeaderCtrl) implementa estas colunas. Para mais informações sobre o controlo do cabeçalho e colunas numa vista de relatório, veja UsarCListCtrl: Adicionar Colunas ao Controlo (Vista de Relatório).

O estilo da vista de lista atual do controlo determina a vista atual. Para mais informações sobre estes estilos e a sua utilização, veja Usar CListCtrl: Alterar Estilos de Controlo de Listas.

Estilos estendidos

Para além dos estilos de lista padrão, a classe CListCtrl suporta um grande conjunto de estilos estendidos, proporcionando funcionalidades enriquecidas. Alguns exemplos desta funcionalidade incluem:

• Seleção de Hover

  Quando ativado, permite a seleção automática de um item quando o cursor permanece sobre o item durante um determinado período de tempo.

• Visualizações de lista virtuais

  Quando ativado, permite que o controlo suporte até itens DWORD. Isto é possível ao colocar a sobrecarga da gestão dos dados dos itens na aplicação. Exceto a seleção de itens e a informação de foco, toda a informação dos itens deve ser gerida pela aplicação. Para mais informações, veja Uso: CListCtrlControlos de Listas Virtuais.

• Ativação de um e dois cliques

  Quando ativado, permite o hot tracking (realce automático do texto do item) e a ativação do item destacado com um ou dois cliques.

• Ordenação de colunas por arrastar e largar

  Quando ativado, permite arrastar e largar a reordenação das colunas num controlo de vista de lista. Disponível apenas na visualização de relatório.

Para informações sobre a utilização destes novos estilos estendidos, veja Usar CListCtrl: Alterar Estilos de Controlo de Lista.

Itens e Subitens

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

O Class CListCtrl fornece várias funções para inserir, eliminar, encontrar e modificar estes itens. Para mais informações, veja CListCtrl::GetItem, CListCtrl::InsertItem, e CListCtrl::FindItem, Adicionar Itens ao Controlo, e Deslocar, Organizar, Ordenar e Encontrar nos controlos da lista.

Por defeito, o controlo da vista de lista é responsável por armazenar o ícone e os atributos de texto de um item. No entanto, para além destes tipos de itens, a classe CListCtrl suporta "itens de retorno". Um "item de callback" é um elemento de vista de lista para o qual a aplicação — em vez do controlo — armazena o texto, o ícone ou ambos. Uma máscara de retorno de chamada é usada para especificar quais os atributos do item (texto e/ou ícone) fornecidos pela aplicação. Se uma aplicação usar itens de callback, deve ser capaz de fornecer os atributos de texto e/ou ícones sob demanda. Itens de retorno de chamada são úteis quando a sua candidatura já mantém parte desta informação. Para mais informações, veja Usar CListCtrl: Itens de Retorno de Chamada e a Máscara de Retorno de Chamada.

Listas de Imagens

Os ícones, imagens de cabeçalhos e estados definidos pela aplicação para itens da vista de lista estão contidos em várias listas de imagens (implementadas por classe CImageList), que cria e atribui ao controlo da vista de lista. Cada controlo de vista de lista pode ter até quatro tipos diferentes de listas de imagens:

• Ícone grande

  Usado na vista de ícones para ícones de tamanho normal.

• Ícone pequeno

  Usado nas vistas de ícones pequenos, listas e relatórios para versões mais pequenas dos ícones usados na visualização de ícones.

• Estado definido pela aplicação

  Contém imagens de estado, que são exibidas ao lado do ícone de um item para indicar um estado definido pela aplicação.

• Item do cabeçalho

  Usado na vista de relatório para pequenas imagens que aparecem em cada item de controlo do cabeçalho.

Por defeito, um controlo de vista de lista destrói as listas de imagens atribuídas quando é destruído; no entanto, o programador pode personalizar este comportamento destruindo cada lista de imagens quando deixa de ser utilizada, conforme determinado pela aplicação. Para mais informações, consulte Utilizar CListCtrl: Itens de Lista e Listas de Imagens.

Hierarquia de herança

CObject

CCmdTarget

CWnd

CListCtrl

Requerimentos

Cabeçalho:afxcmn.h

CListCtrl::ApproximateViewRect

Determina a largura e altura necessárias para exibir os itens de um controlo de vista de lista.

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

Parâmetros

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

iCount
Número de itens a mostrar no controlo. Passe -1 para usar o número total de itens atualmente no controlo.

Valor de retorno

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

Observações

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

CListCtrl::Arrange

Reposiciona os itens numa vista de ícones para que se alinhem numa grelha.

BOOL Arrange(UINT nCode);

Parâmetros

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

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

Valor de retorno

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

Observações

O nCode parâmetro especifica o estilo de alinhamento.

Example

// 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();

Observações

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

CListCtrl::CListCtrl

Constrói um CListCtrl objeto.

CListCtrl();

CListCtrl::Create

Cria um controlo de lista e anexa-o a um CListCtrl objeto.

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

Parâmetros

dwStyle
Especifica o estilo do controlo da lista. Aplique qualquer combinação de estilos de controlo por lista ao controlo. Consulte estilos de janela de vista de lista no SDK do Windows para uma lista completa destes estilos. Defina estilos estendidos específicos para um controlo usando SetExtendedStyle.

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

pParentWnd
Especifica a janela pai do controlo da lista, normalmente um CDialog. Não pode ser NULL.

nID
Especifica o ID do controlo da lista.

Valor de retorno

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

Observações

Constróis um A CListCtrl em dois passos. Primeiro, chama o construtor e depois chama Create, que cria o controlo da vista de lista e o anexa ao CListCtrl objeto.

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

Example

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 controlo (uma janela filha) e associa-o ao CListCtrl objeto.

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

Parâmetros

dwExStyle
Especifica o estilo estendido do controlo que está a ser criado. Para uma lista de estilos estendidos do Windows, veja o parâmetro dwExStyle para CreateWindowEx no SDK do Windows.

dwStyle
Especifica o estilo do controlo da lista. Aplique qualquer combinação de estilos de controlo por lista ao controlo. Para uma lista completa destes estilos, veja Estilos de janela de vista de lista no Windows SDK.

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

pParentWnd
Um apontador para a janela que é o pai do controlo.

nID
O ID da janela criança do controlo.

Valor de retorno

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

Observações

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

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

CListCtrl::CreateDragImage

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

CImageList* CreateDragImage(
    int nItem,
    LPPOINT lpPoint);

Parâmetros

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

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

Valor de retorno

Um apontador para a lista de imagens de arrastar, se for bem-sucedido; caso contrário NULL.

Observações

O CImageList objeto é permanente, e tens de o apagar quando terminares. Por exemplo:

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

// do something

delete pImageList;

CListCtrl::DeleteAllItems

Apaga todos os itens do controlo da vista de lista.

BOOL DeleteAllItems();

Valor de retorno

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

Example

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

CListCtrl::DeleteColumn

Apaga uma coluna do controlo da vista de lista.

BOOL DeleteColumn(int nCol);

Parâmetros

nCol
Índice da coluna a eliminar.

Valor de retorno

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

Example

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

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

CListCtrl::DeleteItem

Apaga um item de um controlo de vista de lista.

BOOL DeleteItem(int nItem);

Parâmetros

nItem
Especifica o índice do item a eliminar.

Valor de retorno

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

Example

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 pelo framework quando um aspeto visual de um controlo de vista de lista de desenho proprietário muda.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parâmetros

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

Observações

O itemAction elemento da DRAWITEMSTRUCT estrutura define a ação de desenho que deve ser realizada.

Por defeito, esta função membro não faz nada. Substitua esta função de membro para implementar desenho para um objeto proprietário-desenho CListCtrl .

A aplicação deve restaurar todos os objetos da interface do dispositivo gráfico (GDI) selecionados para o contexto de visualização fornecido lpDrawItemStruct antes de esta função membro terminar.

CListCtrl::EditLabel

Inicia a edição no local do texto de um item.

CEdit* EditLabel(int nItem);

Parâmetros

nItem
Índice do item da vista de lista que deve ser editado.

Valor de retorno

Se for bem-sucedido, um ponteiro para o CEdit objeto que é usado para editar o texto do item; caso contrário NULL, .

Observações

Um controlo de vista de lista que tem o LVS_EDITLABELS estilo janela permite ao utilizador editar os rótulos dos itens no local. O utilizador começa a editar clicando no rótulo de um item que tem o foco.

Use esta função para iniciar a edição no local do texto do item especificado na vista de lista.

Example

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

Ativa ou desativa se os itens numa vista de lista são exibidos como um grupo.

LRESULT EnableGroupView(BOOL fEnable);

Parâmetros

fEnable
Indica se deve ativar um controlo de vista de lista para agrupar os itens exibidos. TRUE para permitir agrupamento; FALSE para o desativar.

Valor de retorno

Devolve um dos seguintes valores:

• 0 A capacidade de exibir itens em vista de lista como grupo já está ativada ou desativada.
• 1 O estado do controlo foi alterado com sucesso.
• -1 A operação falhou.

Observações

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

CListCtrl::EnsureVisible

Garante que um item na vista de lista é pelo menos parcialmente visível.

BOOL EnsureVisible(
    int nItem,
    BOOL bPartialOK);

Parâmetros

nItem
Índice do item de vista de lista que deve ser visível.

bPartialOK
Especifica se a visibilidade parcial é aceitável.

Valor de retorno

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

Observações

O controlo da vista de lista é deslocado se necessário. Se o parâmetro bPartialOK for diferente de zero, não ocorre scrolling se o item for parcialmente visível.

Example

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

CListCtrl::FindItem

Pesquisa por um item em vista de lista com características especificadas.

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

Parâmetros

pFindInfo
Um apontador para uma LVFINDINFO estrutura contendo informação sobre o item a ser pesquisado.

nStart
Índice do item para iniciar a pesquisa, ou -1 para começar do 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 ou -1 de outra forma.

Observações

O pFindInfo parâmetro aponta para uma LVFINDINFO estrutura que contém informação usada para procurar um item de vista de lista.

Example

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 de fundo de um controlo de vista de lista.

COLORREF GetBkColor() const;

Valor de retorno

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

Example

Veja o exemplo para CListCtrl::SetBkColor.

CListCtrl::GetBkImage

Recupera a imagem de fundo atual de um controlo em vista de lista.

BOOL GetBkImage(LVBKIMAGE* plvbkImage) const;

Parâmetros

plvbkImage
Um ponteiro para uma LVBKIMAGE estrutura que contém a imagem de fundo atual da vista de lista.

Valor de retorno

Retorna diferente de zero se for bem-sucedido, ou zero caso contrário.

Observações

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

Example

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 callback para um controlo em vista de lista.

UINT GetCallbackMask() const;

Valor de retorno

A máscara de retorno do controlo da vista de lista.

Observações

Um "item de callback" é um elemento de vista de lista para o qual a aplicação — em vez do controlo — armazena o texto, o ícone ou ambos. Embora um controlo de vista de lista possa armazenar estes atributos por si, pode querer usar itens de callback se a sua aplicação já mantém parte desta informação. A máscara de callback especifica quais os bits de estado do item mantidos pela aplicação, e aplica-se a todo o controlo em vez de a um item específico. A máscara de callback é zero por padrão, o que significa que o controle rastreia todos os estados do item. Se uma aplicação usar itens de callback ou especificar uma máscara de callback não nula, deve ser capaz de fornecer atributos de item em vista de lista a pedido.

Example

Veja o exemplo para CListCtrl::SetCallbackMask.

CListCtrl::GetCheck

Recupera o estado atual de exibição da imagem de estado associada a um item.

BOOL GetCheck(int nItem) const;

Parâmetros

nItem
O índice baseado em zero de um item de controlo de lista.

Valor de retorno

Diferente de zero se o item for selecionado, caso contrário 0.

Observações

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

Example

Veja o exemplo para CListCtrl::SetCheck.

CListCtrl::GetColumn

Recupera os atributos da coluna de um controlo de vista 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 LVCOLUMN estrutura que especifica a informação a recuperar e recebe informação sobre a coluna. O mask membro especifica quais os atributos da coluna a recuperar. Se o mask membro especificar o valor LVCF_TEXT, deve pszText conter o endereço do buffer que recebe o texto do item e o cchTextMax membro deve especificar o tamanho do buffer.

Valor de retorno

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

Observações

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

Example

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 das colunas (da esquerda para a direita) de um controlo de vista 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 controlo da vista de lista. O buffer deve ser suficientemente grande para conter o número total de colunas no controlo da vista de lista.

iCount
Número de colunas no controlo da vista de lista. Se este parâmetro for -1, o número de colunas é automaticamente recuperado pelo framework.

Valor de retorno

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

Observações

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

Example

// 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 na vista de relatório ou vista 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.

Example

// 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 caber verticalmente na área visível de um controlo de vista de lista quando está na vista de lista ou na vista de relatório.

int GetCountPerPage() const;

Valor de retorno

O número de itens que podem caber verticalmente na área visível de uma vista de lista controla quando está na vista de lista ou na vista de relatório.

Example

Veja o exemplo para CListCtrl::GetTopIndex.

CListCtrl::GetEditControl

Recupera o handle do controlo de edição usado para editar o texto de um item na vista de lista.

CEdit* GetEditControl() const;

Valor de retorno

Se for bem-sucedido, um ponteiro para o CEdit objeto que é usado para editar o texto do item; caso contrário NULL, .

Example

// 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 string para mostrar se o controlo atual da vista de lista estiver vazio.

CString GetEmptyText() const;

Valor de retorno

A CString que contém o texto a mostrar caso o controlo esteja vazio.

Observações

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

CListCtrl::GetExtendedStyle

Recupera os estilos estendidos atuais de um controlo em vista de lista.

DWORD GetExtendedStyle();

Valor de retorno

Uma combinação dos estilos estendidos atualmente usados pelo controlo de vista de lista. Para uma lista descritiva destes estilos estendidos, consulte o artigo Extended List View Styles no Windows SDK.

Observações

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

Example

Veja o exemplo para CListCtrl::SetExtendedStyle.

CListCtrl::GetFirstSelectedItemPosition

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

POSITION GetFirstSelectedItemPosition() const;

Valor de retorno

Um POSITION valor que pode ser usado para iteração ou recuperação de ponteiros de objeto; NULL se não forem selecionados elementos.

Example

O exemplo de código seguinte demonstra a utilização desta 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 que tem o foco do teclado no controlo atual da vista de lista.

int GetFocusedGroup() const;

Valor de retorno

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

Observações

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

CListCtrl::GetGroupCount

Recupera o número de grupos no controlo atual da vista de lista.

int GetGroupCount()const;

Valor de retorno

O número de grupos no controlo de vista de lista.

Observações

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

CListCtrl::GetGroupInfo

Obtém a informação para um grupo especificado do controlo de vista de lista.

int GetGroupInfo(
    int iGroupId,
    PLVGROUP pgrp) const;

Parâmetros

iGroupId
O identificador do grupo cuja informação deve ser recuperada.

pgrp
Um ponteiro para a LVGROUP informação contenda no grupo especificado.

Valor de retorno

Devolve o ID do grupo se for bem-sucedido, ou -1 de outra forma.

Observações

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

CListCtrl::GetGroupInfoByIndex

Recupera informação sobre um grupo especificado no controlo atual da vista de lista.

BOOL GetGroupInfoByIndex(
    int iIndex,
    PLVGROUP pGroup) const;

Parâmetros

iIndex
[dentro] Índice de base zero de um grupo.

pGroup
[fora] Apontador para uma estrutura LVGROUP que recebe informação sobre o grupo especificado pelo parâmetro iIndex . O chamador é responsável por inicializar os membros da estrutura LVGROUP . Defina o cbSize membro para o tamanho da estrutura, e os flags do mask membro para especificar a informação a recuperar.

Valor de retorno

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

Observações

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

Example

O primeiro exemplo de código define uma variável, m_listCtrl, que é usada para aceder ao controlo atual da vista de lista. Esta variável é usada no exemplo seguinte.

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

O próximo exemplo de código demonstra o GetGroupInfoByIndex método. Numa secção anterior deste exemplo de código, criámos um controlo em vista de lista que mostra duas colunas intituladas "ClientID" e "Grade" numa vista de relatório. O seguinte exemplo de código recupera informação sobre o grupo cujo índice é 0, caso tal grupo exista.

// 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 apontador para um LVGROUPMETRICS que contém a informação das métricas do grupo.

Observações

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

CListCtrl::GetGroupRect

Recupera o retângulo delimitador de um grupo especificado no controlo atual da vista de lista.

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

Parâmetros

iGroupId
[dentro] Especifica um grupo.

lpRect
[inspira, expira] Aponta para uma RECT estrutura. Se este método for bem-sucedido, a estrutura recebe as coordenadas retangulares do grupo especificado por iGroupId.

iCoords
[dentro] Especifica as coordenadas retangulares a recuperar. Use um destes valores:

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

Valor de retorno

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

Observações

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

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

Example

O primeiro exemplo de código define uma variável, m_listCtrl, que é usada para aceder ao controlo atual da vista de lista. Esta variável é usada no exemplo seguinte.

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

O próximo exemplo de código demonstra o GetGroupRect método. Numa secção anterior deste exemplo de código, criámos um controlo em vista de lista que mostra duas colunas intituladas "ClientID" e "Grade" numa vista de relatório. O seguinte exemplo de código desenha um retângulo 3D em torno do grupo cujo índice é 0, caso tal grupo exista.

// 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 de um grupo especificado no controlo atual da vista de lista.

UINT GetGroupState(
    int iGroupId,
    DWORD dwMask) const;

Parâmetros

iGroupId
[dentro] Índice de base zero de um grupo.

dwMask
[dentro] Máscara que especifica o valor de estado a recuperar para o grupo especificado. Para mais informações, consulte o mask elemento da LVGROUP estrutura.

Valor de retorno

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

Observações

O valor de retorno é o resultado de uma operação AND bit a bit sobre o dwMask parâmetro e o valor do state membro de uma LVGROUP estrutura que representa o controlo atual da vista de lista.

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

CListCtrl::GetHeaderCtrl

Recupera o controlo de cabeçalho de um controlo em vista de lista.

CHeaderCtrl* GetHeaderCtrl();

Valor de retorno

Um ponteiro para o controlo do cabeçalho, usado pelo controlo da vista de lista.

Observações

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

Example

Veja o exemplo para CListCtrl::GetColumnOrderArray.

CListCtrl::GetHotCursor

Recupera o cursor usado quando o hot tracking está ativado para um controlo de vista de lista.

HCURSOR GetHotCursor();

Valor de retorno

O handle para o recurso de cursor quente atual que está a ser usado pelo controlo de vista de lista.

Observações

Esta função membro implementa o comportamento da macro Win32, ListView_GetHotCursor, conforme descrito no SDK do Windows. O cursor quente, visível apenas quando a seleção de hover está ativada, aparece quando o cursor passa por cima de qualquer item da vista de lista. A seleção de hover é ativada ao definir o LVS_EX_TRACKSELECT estilo estendido.

Example

// 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 vista de lista atualmente sob o cursor.

int GetHotItem();

Valor de retorno

O índice do item quente atual do controlo da vista de lista.

Observações

Esta função membro implementa o comportamento da macro Win32, ListView_GetHotItem, conforme descrito no SDK do Windows. O item quente é definido como o item atualmente selecionado quando o acompanhamento em fase ativa (e a seleção do cursor) estão ativados.

Se o hot tracking estiver ativado, quando um utilizador pausa sobre um item na vista de lista, a etiqueta do item é automaticamente destacada sem o uso de um botão do rato.

Example

// 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 navegação atual de um controlo em vista de lista.

DWORD GetHoverTime() const;

Valor de retorno

Devolve o atraso, em milissegundos, em que o cursor do rato deve passar o cursor sobre um item antes de ser selecionado. Se o valor de retorno for -1, então o tempo de hover é o tempo de hover padrão.

Observações

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

Example

// 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 handle de uma lista de imagens usada para desenhar itens na vista da lista.

CImageList* GetImageList(int nImageList) const;

Parâmetros

nImageList
Valor a especificar qual lista de imagens recuperar. Pode ser um destes valores:

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

Valor de retorno

Um apontador para a lista de imagens usado para desenhar itens na vista de lista.

Example

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 apontador para uma LVINSERTMARK estrutura que contém a informação para a marca de inserção.

Valor de retorno

Retorna TRUE se for bem-sucedido, ou FALSE não. FALSE é devolvido se o tamanho no cbSize elemento da LVINSERTMARK estrutura não for igual ao tamanho real da estrutura.

Observações

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

CListCtrl::GetInsertMarkColor

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

COLORREF GetInsertMarkColor() const;

Valor de retorno

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

Observações

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

CListCtrl::GetInsertMarkRect

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

int GetInsertMarkRect(LPRECT pRect) const;

Parâmetros

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

Valor de retorno

Devolve um dos seguintes valores:

• 0 Sem ponto de inserção encontrado.
• 1 ponto de inserção encontrado.

Observações

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

CListCtrl::GetItem

Recupera alguns ou todos os atributos de um item na vista de lista.

BOOL GetItem(LVITEM* pItem) const;

Parâmetros

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

Valor de retorno

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

Observações

A LVITEM estrutura especifica ou recebe os atributos de um item de vista de lista.

CListCtrl::GetItemCount

Recupera o número de itens num controlo de vista de lista.

int GetItemCount() const;

Valor de retorno

O número de itens na vista de lista controla.

Example

Veja o exemplo para CListCtrl::DeleteItem.

CListCtrl::GetItemData

Recupera o valor específico da aplicação de 32 bits (64 bits se estiver a compilar para x64) associado ao item especificado por nItem.

DWORD_PTR GetItemData(int nItem) const;

Parâmetros

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

Valor de retorno

Um valor específico de aplicação de 32 bits (64 bits se estiver a compilar para x64) associado ao item especificado.

Observações

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

Example

// 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 de todo ou parte de um subitem no controlo atual da vista de lista.

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

Parâmetros

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

iColumn
[dentro] Índice baseado em zero de uma coluna no controlo.

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

• LVIR_BOUNDS - Devolve o retângulo delimitador de todo o subitem, incluindo o ícone e a etiqueta.
• LVIR_ICON - Devolve o retângulo delimitador do ícone ou ícone pequeno do subitem.
• LVIR_LABEL - Devolve o retângulo delimitador do texto do subitem.

pRect
[fora] Apontador para uma RECT estrutura que recebe informação sobre o retângulo delimitador do subitem. O chamador é responsável pela atribuição da RECT estrutura. Este parâmetro não pode ser NULL.

Valor de retorno

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

Observações

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

Example

O primeiro exemplo de código define uma variável, m_listCtrl, que é usada para aceder ao controlo atual da vista de lista. Esta variável é usada no exemplo seguinte.

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

O próximo exemplo de código demonstra o GetGroupRect método. Antes de introduzir este exemplo de código, criámos um controlo em vista de lista que mostra duas colunas intituladas "ClientID" e "Grade" numa vista de relatório. O exemplo de código seguinte 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 em vista 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 POINT estrutura que recebe a posição do canto superior esquerdo do item, em coordenadas de visualização.

Valor de retorno

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

Example

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 de todo ou parte de um item na vista 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çamento de uma RECT estrutura que recebe o retângulo delimitador.

nCode
Parte do item da vista de lista para recuperar o retângulo delimitador. Pode ser um destes valores:

• LVIR_BOUNDS Devolve o retângulo delimitador de todo o item, incluindo o ícone e a etiqueta.
• LVIR_ICON Devolve o retângulo delimitador do ícone ou ícone pequeno.
• LVIR_LABEL Devolve o retângulo delimitador do texto do item.

Valor de retorno

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

Example

// 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 controlo atual da vista de lista.

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

Parâmetros

fSmall
[dentro] Vista para recuperar o espaçamento dos artigos. Especifique TRUE para visualização de ícones pequenos ou FALSE para visualização de ícones.

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

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

Valor de retorno

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

Observações

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

CListCtrl::GetItemState

Recupera o estado de um item em vista de lista.

UINT GetItemState(
    int nItem,
    UINT nMask) const;

Parâmetros

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

nMask
Máscara a especificar qual das bandeiras de estado do item deve devolver.

Valor de retorno

As bandeiras estaduais para o item especificado em vista de lista.

Observações

O estado de um item é especificado pelo state membro da LVITEM estrutura, conforme descrito no Windows SDK. Quando especificas ou alteras o estado de um item, o stateMask membro especifica quais os bits de estado que queres alterar.

Example

Veja o exemplo para CListCtrl::GetTopIndex.

CListCtrl::GetItemText

Recupera o texto de um item ou subitem em vista 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
Apontar para uma cadeia que deve receber o texto do item.

nLen
Comprimento do buffer apontado para por lpszText.

Valor de retorno

A versão que retorna int devolve o comprimento da corda recuperada.

A versão que retorna a CString devolve o texto do item.

Observações

Se nSubItem for zero, esta função recupera o rótulo do item; se nSubItem for diferente de zero, recupera o texto do subitem. Para mais informações sobre o argumento do subitem, veja a discussão sobre a LVITEM estrutura no SDK do Windows.

CListCtrl::GetNextItem

Procura um item de vista de lista que tenha as propriedades especificadas e que tenha a relação especificada com um determinado item.

int GetNextItem(
    int nItem,
    int nFlags) const;

Parâmetros

nItem
Índice do item para iniciar a pesquisa, ou -1 para encontrar o primeiro item que corresponda às bandeiras especificadas. O item especificado em si é excluído da pesquisa.

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

• LVNI_ABOVE Procura um item que esteja acima do item especificado.
• LVNI_ALL Pesquisa por um item subsequente por índice (o valor predefinido).
• LVNI_BELOW Procura um item que esteja abaixo do item especificado.
• LVNI_TOLEFT Procura um item à esquerda do item especificado.
• LVNI_TORIGHT Procura um item à direita do item especificado.

O estado pode ser zero, ou pode ser um ou mais destes valores:

• LVNI_DROPHILITED O item tem a LVIS_DROPHILITED bandeira do estado definida.
• LVNI_FOCUSED O item tem a LVIS_FOCUSED bandeira do estado definida.
• LVNI_SELECTED O item tem a LVIS_SELECTED bandeira do estado definida.

Se um item não tiver todos os flags de estado especificados definidos, a pesquisa continua com o item seguinte.

Valor de retorno

O índice do próximo item se for bem-sucedido, ou -1 de outra forma.

CListCtrl::GetNextItemIndex

Recupera o índice do item no controlo atual da vista de lista que tem um conjunto especificado de propriedades.

BOOL GetNextItemIndex(
    PLVITEMINDEX pItemIndex,
    int nFlags) const;

Parâmetros

pItemIndex
[inspira, expira] Apontar para a LVITEMINDEX estrutura que descreve o item onde a pesquisa começa, ou -1 para encontrar o primeiro item que corresponde às flags no parâmetro nFlags . Se este método for bem-sucedido, a LVITEMINDEX estrutura descreve o item encontrado na pesquisa.

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

Valor de retorno

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

Observações

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

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

CListCtrl::GetNextSelectedItem

Obtém o índice do item da lista identificado por pos, e depois define pos para o valor POSIÇÃO.

int GetNextSelectedItem(POSITION& pos) const;

Parâmetros

pos
Uma referência a um valor POSITION devolvido por uma chamada anterior para GetNextSelectedItem ou GetFirstSelectedItemPosition. O valor é atualizado para a posição seguinte por esta chamada.

Valor de retorno

O índice do item da lista identificado por pos.

Observações

Pode usar GetNextSelectedItem num ciclo de iteração direta se estabelecer a posição inicial com uma chamada para GetFirstSelectedItemPosition.

Deve garantir que o seu POSITION valor é válido. Se for inválido, então a versão Debug da Microsoft Foundation Class Library afirma.

Example

O exemplo de código seguinte demonstra a utilização desta 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 controlo em vista de lista.

UINT GetNumberOfWorkAreas() const;

Valor de retorno

Não foi usado neste momento.

Observações

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

Example

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 controlo em vista de lista.

COLORREF GetOutlineColor() const;

Valor de retorno

Devolve uma COLORREF estrutura contendo a cor do contorno.

Observações

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

CListCtrl::GetOrigin

Recupera a origem da vista atual para um controlo de vista de lista.

BOOL GetOrigin(LPPOINT lpPoint) const;

Parâmetros

lpPoint
Endereço de uma POINT estrutura que recebe a origem da visualização.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, zero. No entanto, se o controlo estiver na vista do relatório, o valor de retorno é sempre zero.

CListCtrl::GetSelectedColumn

Recupera o índice da coluna atualmente selecionada no controlo da lista.

UINT GetSelectedColumn() const;

Valor de retorno

O índice da coluna selecionada.

Observações

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

CListCtrl::GetSelectedCount

Recupera o número de itens selecionados no controlo da vista de lista.

UINT GetSelectedCount() const;

Valor de retorno

O número de itens selecionados no controlo da vista de lista.

Example

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 controlo em vista 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.

Observações

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

Example

// 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 uma dada cadeia.

int GetStringWidth(LPCTSTR lpsz) const;

Parâmetros

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

Valor de retorno

A largura, em pixels, da cadeia apontada para por lpsz.

Observações

A largura devolvida tem em conta a fonte atual do controlo e as margens da coluna, mas não a largura de um ícone pequeno.

Example

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 num controlo de vista de lista.

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

Parâmetros

iItem
Índice do item pai do subitem.

iSubItem
O índice baseado em um do subitem.

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

• LVIR_BOUNDS Devolve o retângulo delimitador de todo o item, incluindo o ícone e a etiqueta.
• LVIR_ICON Devolve o retângulo delimitador do ícone ou ícone pequeno.
• LVIR_LABEL Devolve o retângulo delimitador de todo o item, incluindo o ícone e a etiqueta. Isto é idêntico a LVIR_BOUNDS.

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

Valor de retorno

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

Observações

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

CListCtrl::GetTextBkColor

Recupera a cor de fundo do texto de um controlo em vista de lista.

COLORREF GetTextBkColor() const;

Valor de retorno

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

Example

Veja o exemplo para CListCtrl::SetTextBkColor.

CListCtrl::GetTextColor

Recupera a cor do texto de um controlo de vista de lista.

COLORREF GetTextColor() const;

Valor de retorno

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

Example

Veja o exemplo para CListCtrl::SetTextColor.

CListCtrl::GetTileInfo

Recupera informação sobre um tile num controlo de vista de lista.

BOOL GetTileInfo(PLVTILEINFO plvti) const;

Parâmetros

plvti
Um apontador para uma LVTILEINFO estrutura que recebe a informação do tile.

Valor de retorno

O valor de devolução não é utilizado.

Observações

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

CListCtrl::GetTileViewInfo

Recupera informações sobre um controlo em vista de lista na vista de tile.

BOOL GetTileViewInfo(PLVTILEVIEWINFO ptvi) const;

Parâmetros

ptvi
Um apontador para uma LVTILEVIEWINFO estrutura que recebe a informação recuperada.

Valor de retorno

O valor de devolução não é utilizado.

Observações

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

CListCtrl::GetToolTips

Recupera o controlo de tooltip que o controlo da vista de lista usa para mostrar as dicas de tooltips.

CToolTipCtrl* GetToolTips() const;

Valor de retorno

Um apontador para um CToolTipCtrl objeto a ser usado pelo controlo da lista. Se a Create função membro usar o estilo LVS_NOTOOLTIPS, não são usadas descrições de ferramentas e o NULL é devolvido.

Observações

Esta função membro implementa o comportamento da mensagem LVM_GETTOOLTIPSWin32 , conforme descrito no SDK do Windows. A implementação MFC de GetToolTips devolve um CToolTipCtrl objeto, que é usado pelo controlo de lista, em vez de um handle para um controlo tooltip.

Example

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 mais visível quando está na vista de lista ou na vista de relatório.

int GetTopIndex() const;

Valor de retorno

O índice do item mais visível.

Example

// 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 visualização do controlo da vista de lista.

DWORD GetView() const;

Valor de retorno

A vista atual do controlo da vista de lista.

Observações

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

CListCtrl::GetViewRect

Recupera o retângulo delimitador de todos os itens no controlo da vista de lista.

BOOL GetViewRect(LPRECT lpRect) const;

Parâmetros

lpRect
Endereço de uma RECT estrutura.

Valor de retorno

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

Observações

A vista de lista deve estar na vista de ícones ou em vista de ícone pequeno.

CListCtrl::GetWorkAreas

Recupera as áreas de trabalho atuais de um controlo em vista de lista.

void GetWorkAreas(
    int nWorkAreas,
    LPRECT pRect) const;

Parâmetros

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

pRect
Um ponteiro para um array de RECT estruturas (ou CRect objetos) que recebem as áreas de trabalho do controlo da vista de lista. Os valores nestas estruturas estão em coordenadas do cliente.

Observações

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

Example

Veja o exemplo para CListCtrl::GetNumberOfWorkAreas.

CListCtrl::HasGroup

Determina se o controlo de vista de lista tem o grupo especificado.

BOOL HasGroup(int iGroupId) const;

Parâmetros

iGroupId
O identificador do grupo solicitado.

Valor de retorno

Retornos TRUE do sucesso, FALSE do fracasso.

Observações

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

CListCtrl::HitTest

Determina qual o item da vista de lista, se houver, que está numa posição especificada.

int HitTest(LVHITTESTINFO* pHitTestInfo) const;

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

Parâmetros

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

pt
Ponto a ser testado.

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

Valor de retorno

O índice do item na posição especificada por pHitTestInfo, se existir, ou -1 de outra forma.

Observações

Pode usar os LVHT_ABOVEvalores , LVHT_BELOW, LVHT_TOLEFT, e LVHT_TORIGHT do membro da flag estrutura para determinar se deve deslocar o conteúdo de um controlo de vista de lista. Duas destas bandeiras podem ser combinadas, por exemplo, se a posição estiver acima e à esquerda da área do cliente.

Pode testar o LVHT_ONITEM valor do elemento da flag estrutura para determinar se uma dada posição está sobre um item de vista de lista. Este valor é uma operação bit a bit OR sobre o LVHT_ONITEMICON, , e LVHT_ONITEMSTATEICON valores do membro da flagLVHT_ONITEMLABELestrutura.

Example

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 num controlo de vista 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 LVCOLUMN estrutura que contém os atributos da nova coluna.

lpszColumnHeading
Endereço de uma cadeia contendo o cabeçalho da coluna.

nFormat
Integer especificando o alinhamento da coluna. Pode ser um destes valores: LVCFMT_LEFT, LVCFMT_RIGHT, ou LVCFMT_CENTER.

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

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

Valor de retorno

O índice da nova coluna se for bem-sucedido ou -1 de outra forma.

Observações

A coluna mais à esquerda num controlo de vista de lista deve estar alinhada à esquerda.

A LVCOLUMN estrutura contém os atributos de uma coluna na vista de relatório. Também é usado para receber informações sobre uma coluna. Esta estrutura é descrita no SDK do Windows.

CListCtrl::InsertGroup

Insere um grupo no controlo da vista 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 LVGROUP estrutura que contém o grupo a ser somado.

Valor de retorno

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

Observações

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

CListCtrl::InsertGroupSorted

Insere o grupo especificado numa lista ordenada de grupos.

LRESULT InsertGroupSorted(PLVINSERTGROUPSORTED pStructInsert);

Parâmetros

pStructInsert
Um apontador para uma LVINSERTGROUPSORTED estrutura que contém o grupo a inserir.

Valor de retorno

O valor de devolução não é utilizado.

Observações

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

CListCtrl::InsertItem

Insere um item no controlo da vista 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
Apontador para uma estrutura LVITEM que especifica os atributos do item, conforme descrito no SDK do Windows.

nItem
Índice do item a inserir.

lpszItem
Endereço de uma string contendo a etiqueta do item, ou LPSTR_TEXTCALLBACK se o item for um item de callback. Para informações sobre itens de devolução, veja CListCtrl::GetCallbackMask.

nImage
Índice da imagem do item, ou I_IMAGECALLBACK se o item for um item de callback. Para informações sobre itens de devolução, veja CListCtrl::GetCallbackMask.

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

nState
Indica o estado do item, a imagem do estado e a imagem sobreposta. Para mais informações, consulte os tópicos LVITEM Estrutura e List-View Estados dos Itens do SDK do Windows para uma lista de flags válidos.

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

lParam
Um valor específico de aplicação de 32 bits (64 bits se estiver a compilar para x64) associado ao item. Se este parâmetro for especificado, deve definir o nMask atributo LVIF_PARAM.

Valor de retorno

O índice do novo item se for bem-sucedido ou -1 de outra forma.

Observações

Chamar este método pode fazer com que a LVM_INSERTITEM mensagem seja enviada para a sua janela de controlo. O manipulador de mensagens associado ao controlo pode falhar em definir o texto do item sob certas condições (como usar estilos de janela, como LVS_OWNERDRAW). Para mais informações sobre estas condições, consulte LVM_INSERTITEM o SDK do Windows.

Example

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 POINT estrutura que contém as coordenadas do teste de acerto, relativamente à área cliente do controlo da lista.

plvim
Um ponteiro para uma LVINSERTMARK estrutura 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.

Observações

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

CListCtrl::IsGroupViewEnabled

Determina se a vista de grupo está ativada para um controlo de vista de lista.

BOOL IsGroupViewEnabled() const;

Valor de retorno

Retorna TRUE se a visualização de grupo estiver ativada, ou FALSE de outra forma.

Observações

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

CListCtrl::IsItemVisible

Indica se um item especificado no controlo atual da vista de lista é visível.

BOOL IsItemVisible(int index) const;

Parâmetros

index
[dentro] Índice baseado em zero de um item no controlo atual da vista de lista.

Valor de retorno

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

Observações

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

CListCtrl::MapIDToIndex

Mapeia o ID único de um item no controlo atual da vista de lista para um índice.

UINT MapIDToIndex(UINT id) const;

Parâmetros

id
[dentro] O ID único de um item.

Valor de retorno

O índice atual para o ID especificado.

Observações

Um controlo em vista de lista acompanha internamente os itens por índice. Isto pode apresentar problemas porque os índices podem mudar ao longo da vida útil do controlo. O controlo em vista de lista pode marcar um item com um ID quando o item é criado e pode usar esse ID para garantir a unicidade durante a vida útil do controlo em vista de lista.

Num ambiente multithread, o índice é garantido apenas na thread que hospeda o controlo da vista de lista, não nas threads em segundo plano.

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

CListCtrl::MapIndexToID

Mapeia o índice de um item no controlo atual da vista de lista para um ID único.

UINT MapIndexToID(UINT index) const;

Parâmetros

index
[dentro] O índice zero de um item.

Valor de retorno

Um ID único para o item especificado.

Observações

Um controlo em vista de lista acompanha internamente os itens por índice. Isto pode apresentar problemas porque os índices podem mudar ao longo da vida útil do controlo. O controlo da vista de lista pode marcar um item com um ID quando o item é criado. Pode usar este ID para aceder a um item específico durante toda a vida útil do controlo em vista de lista.

Num ambiente multithread, o índice é garantido apenas na thread que hospeda o controlo da vista de lista, não nas threads em segundo plano.

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

Example

O primeiro exemplo de código define uma variável, m_listCtrl, que é usada para aceder ao controlo atual da vista de lista. Esta variável é usada no exemplo seguinte.

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

O próximo exemplo de código demonstra o MapIndexToID método. Numa secção anterior deste exemplo de código, criámos um controlo em vista de lista que mostra duas colunas intituladas "ClientID" e "Grade" numa vista de relatório. O exemplo seguinte mapeia o índice de cada item em vista de lista para um número de identificação, e depois recupera o índice de cada número de identificação. Finalmente, o exemplo indica 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 especificado do controlo da vista de lista.

LRESULT MoveGroup(
    int iGroupId,
    int toIndex);

Parâmetros

iGroupId
O identificador do grupo a mover.

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

Valor de retorno

O valor de devolução não é utilizado.

Observações

Esta função membro emula a funcionalidade da LVM_MOVEGROUP mensagem, 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
[dentro] O índice do item a mover.

idGroupTo
[dentro] O identificador do grupo para onde o item será movido.

Observações

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

CListCtrl::RedrawItems

Força um controlo em vista de lista a repintar uma série de itens.

BOOL RedrawItems(
    int nFirst,
    int nLast);

Parâmetros

nFirst
Índice do primeiro item a ser repintado.

nLast
Índice do último item a ser repintado.

Valor de retorno

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

Observações

Os itens especificados não são repintados até que a janela de vista de lista receba uma mensagem WM_PAINT. Para repintar imediatamente, chame a função Windows UpdateWindow após usar esta função.

CListCtrl::RemoveAllGroups

Remove todos os grupos de um controlo de vista de lista.

void RemoveAllGroups();

Observações

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

CListCtrl::RemoveGroup

Remove o grupo especificado do controlo de vista de lista.

LRESULT RemoveGroup(int iGroupId);

Parâmetros

iGroupId
O identificador do grupo a ser removido.

Valor de retorno

Devolve o índice do grupo se for bem-sucedido, ou se -1 de outra forma.

Observações

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

CListCtrl::Scroll

Desloca o conteúdo de um controlo de vista de lista.

BOOL Scroll(CSize size);

Parâmetros

size
Um CSize objeto que especifica a quantidade de scroll horizontal e vertical, em pixels. O y elemento de tamanho é dividido pela altura, em pixels, da linha do controlo da vista de lista, e o controlo é deslocado pelo número resultante de linhas.

Valor de retorno

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

CListCtrl::SetBkColor

Define a cor de fundo do controlo de vista de lista.

BOOL SetBkColor(COLORREF cr);

Parâmetros

cr
Cor de fundo para definir, ou o CLR_NONE valor para não ter cor de fundo. Os controlos em vista de lista com cores de fundo redesenham-se significativamente mais rapidamente do que aqueles sem cores de fundo. Para mais informações, consulte COLORREF o SDK do Windows.

Valor de retorno

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

Example

// 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 de fundo de um controlo de vista 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 LVBKIMAGE estrutura, contendo a nova informação da imagem de fundo.

hBitmap
Handle para um bitmap.

pszUrl
Uma NULLcadeia -terminada que contém a URL da imagem de fundo.

fTile
Diferente de zero se a imagem for colocada em mosaico no fundo do controlo de vista de lista; caso contrário, 0.

xOffsetPercent
O deslocamento, em pixels, da borda esquerda da imagem, a partir da origem do controlo da vista de lista.

yOffsetPercent
O deslocamento, em pixels, da borda superior da imagem, a partir da origem do controlo de vista de lista.

Valor de retorno

Retorna diferente de zero se for bem-sucedido, ou zero caso contrário.

Observações

Example

Veja o exemplo para CListCtrl::GetBkImage.

CListCtrl::SetCallbackMask

Define a máscara de retorno para um controlo em vista de lista.

BOOL SetCallbackMask(UINT nMask);

Parâmetros

nMask
Novo valor da máscara de retorno.

Valor de retorno

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

Example

// 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 controlo de lista é visível.

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

Parâmetros

nItem
O índice baseado em zero de um item de controlo de lista.

fCheck
Especifica se a imagem do estado do item deve ser visível ou não. Por defeito, fCheck é TRUE e a imagem de estado são visíveis. Se fCheck for FALSE, não é visível.

Valor de retorno

Diferente de zero se o item estiver marcado, caso contrário 0.

Example

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 vista 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 LVCOLUMN estrutura que contém os novos atributos da coluna, conforme descrito no SDK do Windows. O membro da mask estrutura especifica quais os atributos da coluna a definir. Se o mask membro especificar o LVCF_TEXT valor, o elemento da pszText estrutura é o endereço de uma cadeia terminada por nulo e o membro da cchTextMax estrutura é ignorado.

Valor de retorno

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

Example

Veja o exemplo para CListCtrl::GetColumn.

CListCtrl::SetColumnOrderArray

Define a ordem das colunas (da esquerda para a direita) de um controlo de vista de lista.

BOOL SetColumnOrderArray(
    int iCount,
    LPINT piArray);

Parâmetros

piArray
Um ponteiro para um buffer contendo os valores de índice das colunas no controlo de vista de lista (da esquerda para a direita). O buffer deve ser suficientemente grande para conter o número total de colunas no controlo da vista de lista.

iCount
Número de colunas no controlo da vista de lista.

Valor de retorno

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

Observações

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

Example

Veja o exemplo para CListCtrl::GetColumnOrderArray.

CListCtrl::SetColumnWidth

Altera a largura de uma coluna na vista de relatório ou vista de lista.

BOOL SetColumnWidth(
    int nCol,
    int cx);

Parâmetros

nCol
Índice da coluna para a qual a largura deve ser definida. Na vista de lista, este parâmetro deve ser 0.

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

Valor de retorno

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

CListCtrl::SetExtendedStyle

Define os estilos estendidos atuais de um controlo de vista de lista.

DWORD SetExtendedStyle(DWORD dwNewStyle);

Parâmetros

dwNewStyle
Uma combinação de estilos estendidos a ser usada pelo controlo em vista de lista. Para uma lista descritiva destes estilos, consulte o tópico Estilos de Vista de Lista Estendida no SDK do Windows.

Valor de retorno

Uma combinação dos estilos estendidos anteriores usados pelo controlo em vista de lista.

Observações

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

Example

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

CListCtrl::SetGroupInfo

Define a informação que descreve o grupo especificado do controlo atual da vista de lista.

int SetGroupInfo(
    int iGroupId,
    PLVGROUP pgrp);

Parâmetros

iGroupId
O identificador do grupo cuja informação está definida.

pgrp
Apontador para uma LVGROUP estrutura que contém a informação a definir. O chamador é responsável por alocar esta estrutura e definir os seus membros.

Valor de retorno

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

Observações

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

CListCtrl::SetGroupMetrics

Define as métricas de grupo de um controlo em vista de lista.

void SetGroupMetrics(PLVGROUPMETRICS pGroupMetrics);

Parâmetros

pGroupMetrics
Um apontador para uma LVGROUPMETRICS estrutura que contém a informação das métricas de grupo a ser definida.

Observações

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

CListCtrl::SetHotCursor

Define o cursor usado quando o hot tracking está ativado para um controlo de vista de lista.

HCURSOR SetHotCursor(HCURSOR hc);

Parâmetros

hc
Um handle para um recurso cursor, usado para representar o cursor quente.

Valor de retorno

O handle do recurso hot cursor anterior a ser usado pelo controlo de vista de lista.

Observações

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

O cursor quente, visível apenas quando a seleção de hover está ativada, aparece quando o cursor passa sobre qualquer item da vista da lista. A seleção de hover é ativada ao definir o LVS_EX_TRACKSELECT estilo estendido.

Example

Veja o exemplo para CListCtrl::GetHotCursor.

CListCtrl::SetHotItem

Define o item quente atual de um controlo de vista de lista.

int SetHotItem(int iIndex);

Parâmetros

iIndex
Índice base zero do item a definir como item quente.

Valor de retorno

O índice base zero do item anteriormente quente.

Observações

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

Example

Veja o exemplo para CListCtrl::GetHotItem.

CListCtrl::SetHoverTime

Define o tempo de hover atual de um controlo de vista de lista.

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

Parâmetros

dwHoverTime
O novo atraso, em milissegundos, em que o cursor do rato deve passar o cursor sobre um item antes de ser selecionado. Se o valor padrão for ultrapassado, o tempo é definido para o tempo de hover padrão.

Valor de retorno

O tempo anterior de suspensão, em milissegundos.

Observações

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

Example

Veja o exemplo para CListCtrl::GetHoverTime.

CListCtrl::SetIconSpacing

Define o espaçamento entre ícones num controlo de vista de lista.

CSize SetIconSpacing(
    int cx,
    int cy);

CSize SetIconSpacing(CSize size);

Parâmetros

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

cy
A distância (em píxeis) entre ícones no eixo y.

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

Valor de retorno

Um CSize objeto contendo os valores anteriores do espaçamento dos ícones.

Observações

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

Example

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

CListCtrl::SetImageList

Atribui uma lista de imagens a um controlo de vista de lista.

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

Parâmetros

pImageList
Apontar para a lista de imagens para atribuir.

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 pequenos ícones.
• LVSIL_STATE Lista de imagens com imagens do estado.

Valor de retorno

Um apontador para a lista de imagens anterior.

Example

Veja o exemplo para CListCtrl::GetImageList.

CListCtrl::SetInfoTip

Define o texto da dica de ferramenta.

BOOL SetInfoTip(PLVSETINFOTIP plvInfoTip);

Parâmetros

plvInfoTip
Um ponteiro para uma LVFSETINFOTIP estrutura que contém a informação a definir.

Valor de retorno

Retornos TRUE do sucesso, FALSE do fracasso.

Observações

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

CListCtrl::SetInsertMark

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

BOOL SetInsertMark(LPLVINSERTMARK plvim);

Parâmetros

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

Valor de retorno

Retorna TRUE se for bem-sucedido, ou FALSE não. FALSE é devolvido se o tamanho no cbSize elemento da LVINSERTMARK estrutura não for igual ao tamanho real da estrutura, ou quando um ponto de inserção não se aplica na vista atual.

Observações

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

CListCtrl::SetInsertMarkColor

Define a cor do ponto de inserção.

COLORREF SetInsertMarkColor(COLORREF color);

Parâmetros

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

Valor de retorno

Devolve uma COLORREF estrutura contendo a cor anterior.

Observações

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

CListCtrl::SetItem

Define alguns ou todos os atributos de um item na vista 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 LVITEM estrutura que contém os novos atributos do item, conforme descrito no SDK do Windows. As estruturas iItem e iSubItem os membros identificam o item ou subitem, e o membro da mask estrutura especifica quais os atributos a definir. Para mais informações sobre o mask membro, 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 os atributos a definir (ver as Observações).

lpszItem
Endereço de uma cadeia terminada por null que especifica a etiqueta do item.

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

nState
Especifica os valores dos estados a alterar (ver as Observações).

nStateMask
Especifica quais estados devem ser alterados (ver as Observações).

lParam
Um valor específico de aplicação de 32 bits (64 bits se estiver a compilar para x64) para associar ao item.

nIndent
Largura, em pixels, da reentrância. Se nIndent for inferior à largura mínima definida pelo sistema, a nova largura é definida para a mínima definida pelo sistema

Valor de retorno

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

Observações

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

O mask elemento da LVITEM estrutura e o nMask parâmetro especificam quais os atributos do item a definir:

• LVIF_TEXT O pszText elemento ou parâmetro lpszItem é o endereço de uma cadeia terminada por nulo; o cchTextMax elemento é ignorado.
• LVIF_STATE O stateMask membro ou nStateMask parâmetro especifica quais os estados do item a alterar e o state membro ou nState parâmetro contém os valores desses estados.

Example

Veja o exemplo para CListCtrl::HitTest.

CListCtrl::SetItemCount

Prepara um controlo de vista de lista para adicionar um grande número de itens.

void SetItemCount(int nItems);

Parâmetros

nItems
Número de itens que o controlo irá conter.

Observações

Para definir a contagem de itens para um controlo de vista de lista virtual, veja CListCtrl::SetItemCountEx.

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

Example

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 controlo de vista de lista virtual.

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

Parâmetros

iCount
Número de itens que o controlo irá conter.

dwFlags
Especifica o comportamento do controlo da vista de lista após reiniciar a contagem de itens. Este valor pode ser uma combinação do seguinte:

• LVSICF_NOINVALIDATEALL O controlo da vista de lista não repinta a menos que os itens afetados estejam atualmente à vista. Este é o valor padrão.
• LVSICF_NOSCROLL O controlo da vista de lista não altera a posição do scroll quando o número de itens muda.

Valor de retorno

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

Observações

Esta função membro implementa o comportamento da macro Win32, ListView_SetItemCountEx, conforme descrito no SDK do Windows, e só deve ser chamada para visualizações virtuais de lista.

Example

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 da aplicação de 32 bits (64 bits se estiver a compilar para x64) associado ao item especificado por nItem.

BOOL SetItemData(int nItem, DWORD_PTR dwData);

Parâmetros

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

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

Valor de retorno

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

Observações

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

Example

// 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 controlo atual da vista de lista.

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

Parâmetros

pItemIndex
[dentro] Apontar para uma LVITEMINDEX estrutura que descreve um item. O chamador é responsável por alocar esta estrutura e definir os seus membros.

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

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

Valor de retorno

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

Observações

Para mais informações sobre o dwState parâmetro, consulte List View Item States.

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

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

CListCtrl::SetItemPosition

Move um item para uma posição especificada num controlo de vista de lista.

BOOL SetItemPosition(
    int nItem,
    POINT pt);

Parâmetros

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

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

Valor de retorno

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

Observações

O controlo deve estar na vista de ícones ou em ícone pequeno.

Se o controlo da vista de lista tiver o LVS_AUTOARRANGE estilo, a vista de lista é organizada depois de definir a posição do item.

Example

Veja o exemplo para CListCtrl::GetItemPosition.

CListCtrl::SetItemState

Altera o estado de um item num controlo de vista 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 LVITEM estrutura, conforme descrito no SDK do Windows. O membro da stateMask estrutura especifica quais os bits de estado a alterar, e o membro da state estrutura contém os novos valores desses bits. Os outros membros são ignorados.

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

nMask
Máscara a especificar quais os bits de estado a alterar. Este valor corresponde ao membro stateMask da LVITEM estrutura.

Valor de retorno

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

Observações

O "estado" de um item é um valor que especifica a disponibilidade do item, indica ações do utilizador ou reflete de outra forma o estado do item. Um controlo de vista de lista altera alguns bits de estado, como quando o utilizador seleciona um item. Uma aplicação pode alterar outros bits de estado para desativar ou ocultar o item, ou para especificar uma imagem sobreposta ou imagem de estado.

Example

Veja o exemplo para CListCtrl::GetTopIndex.

CListCtrl::SetItemText

Altera o texto de um item ou subitem em vista 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 a etiqueta do item.

lpszText
Apontar para uma string que contém o texto do novo item.

Valor de retorno

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

Observações

Este método não é destinado a ser usado com controlos que contenham o LVS_OWNERDATA estilo janela (na verdade, isto causará uma asserção em builds de Depuração). Para mais informações sobre este estilo de controlo por lista, consulte List-View Visão Geral dos Controlos.

Example

Veja o exemplo para CListCtrl::InsertItem.

CListCtrl::SetOutlineColor

Define a cor da borda de um controlo de vista de lista se o LVS_EX_BORDERSELECT estilo janela estendido estiver definido.

COLORREF SetOutlineColor(COLORREF color);

Parâmetros

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

Valor de retorno

A estrutura anterior COLORREF continha a cor do contorno

Observações

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

CListCtrl::SetSelectedColumn

Define a coluna selecionada do controlo de vista de lista.

LRESULT SetSelectedColumn(int iCol);

Parâmetros

iCol
O índice da coluna a selecionar.

Valor de retorno

O valor de devolução não é utilizado.

Observações

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

CListCtrl::SetSelectionMark

Define a marca de seleção de um controlo de vista de lista.

int SetSelectionMark(int iIndex);

Parâmetros

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

Valor de retorno

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

Observações

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

Example

Veja o exemplo para CListCtrl::GetSelectionMark.

CListCtrl::SetTextBkColor

Define a cor de fundo do texto num controlo de vista de lista.

BOOL SetTextBkColor(COLORREF cr);

Parâmetros

cr
A COLORREF especificar a nova cor de fundo do texto. Para mais informações, consulte COLORREF o SDK do Windows.

Valor de retorno

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

Example

// 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 controlo de vista de lista.

BOOL SetTextColor(COLORREF cr);

Parâmetros

cr
A COLORREF especificar a nova cor do texto. Para mais informações, consulte COLORREF o SDK do Windows.

Valor de retorno

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

Example

// 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 a informação para um tile do controlo de vista de lista.

BOOL SetTileInfo(PLVTILEINFO pTileInfo);

Parâmetros

pTileInfo
Um ponteiro para uma LVTILEINFO estrutura que contém a informação a definir.

Valor de retorno

Retornos TRUE do sucesso, FALSE do fracasso.

Observações

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

CListCtrl::SetTileViewInfo

Define a informação que um controlo de vista de lista utiliza na vista de tile.

BOOL SetTileViewInfo(PLVTILEVIEWINFO ptvi);

Parâmetros

ptvi
Um ponteiro para uma LVTILEVIEWINFO estrutura que contém a informação a definir.

Valor de retorno

Retornos TRUE do sucesso, FALSE do fracasso.

Observações

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

CListCtrl::SetToolTips

Define o controlo de tooltip que o controlo da vista de lista usará para mostrar tooltips.

CToolTipCtrl* SetToolTips(CToolTipCtrl* pWndTip);

Parâmetros

pWndTip
Um apontador para um CToolTipCtrl objeto que o controlo da lista irá usar.

Valor de retorno

Um apontador para um CToolTipCtrl objeto que contém a dica de ferramenta anteriormente usada pelo controlo, ou NULL se não foram usadas descrições anteriormente.

Observações

Esta função membro implementa o comportamento da mensagem LVM_SETTOOLTIPSWin32 , conforme descrito no SDK do Windows.

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

CListCtrl::SetView

Define a vista do controlo da vista de lista.

DWORD SetView(int iView);

Parâmetros

iView
A visualização a ser selecionada.

Valor de retorno

Retorna 1 se for bem-sucedido ou -1 contrário. Por exemplo, -1 é retornado se o modo de exibição for inválido.

Observações

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

CListCtrl::SetWorkAreas

Define a área onde os ícones podem ser exibidos num controlo de vista de lista.

void SetWorkAreas(
    int nWorkAreas,
    LPRECT lpRect);

Parâmetros

nWorkAreas
O número de RECT estruturas (ou CRect objetos) no array apontado por lpRect.

lpRect
O endereço de um array de RECT estruturas (ou CRect objetos) que especificam as novas áreas de trabalho do controlo da vista de lista. Estas áreas devem ser especificadas nas coordenadas do cliente. Se este parâmetro for NULL, a área de trabalho será definida para a área cliente do controlo.

Observações

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

Example

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

CListCtrl::SortGroups

Utiliza uma função de comparação definida pela aplicação para ordenar grupos por ID dentro de um controlo de vista de lista.

BOOL SortGroups(
    PFNLVGROUPCOMPARE _pfnGroupCompare,
    LPVOID _plv);

Parâmetros

_pfnGroupCompare
Um apontador para a função de comparação de grupos.

_plv
Um apontador de vazio.

Valor de retorno

Retornos TRUE do sucesso, FALSE do fracasso.

Observações

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

CListCtrl::SortItems

Ordena os itens da vista de lista usando uma função de comparação definida pela aplicação.

BOOL SortItems(
    PFNLVCOMPARE pfnCompare,
    DWORD_PTR dwData);

Parâmetros

pfnCompare
[dentro] Endereço da função de comparação definida pela aplicação.

A operação de ordenação chama a função de comparação cada vez que é necessário determinar a ordem relativa de dois itens da lista. A função de comparação deve ser ou um membro estático de uma classe ou uma função autónoma que não pertence a nenhuma classe.

dwData
[dentro] Valor definido pela aplicação que é passado para a função de comparação.

Valor de retorno

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

Observações

Este 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 devolver um valor negativo se o primeiro item for anterior ao segundo, um valor positivo se o primeiro item for após o segundo, ou zero se os dois itens forem iguais.

O lParam1 parâmetro é o valor de 32 bits (64 bits se estiver a compilar para x64) associado ao primeiro item que é comparado, e o lParam2 parâmetro é o valor associado ao segundo item. Estes são os valores especificados na lParam estrutura do membro dos itens LVITEM quando foram inseridos na lista. O lParamSort parâmetro é o mesmo que o dwData valor.

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

Example

Segue-se uma função simples de comparação que resulta em itens ordenados pelos seus lParam valores.

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

Ordena os itens do controlo atual da vista de lista usando uma função de comparação definida pela aplicação.

BOOL SortItemsEx(
    PFNLVCOMPARE pfnCompare,
    DWORD_PTR dwData);

Parâmetros

pfnCompare
[dentro] Endereço da função de comparação definida pela aplicação. A operação de ordenação chama a função de comparação cada vez que é necessário determinar a ordem relativa de dois itens da lista. A função de comparação deve ser ou um membro estático de uma classe ou uma função autónoma que não pertence a nenhuma classe.

dwData
[dentro] Valor definido pela aplicação passado para a função de comparação.

Valor de retorno

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

Observações

Este 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);

Esta mensagem é semelhante LVM_SORTITEMSa , exceto pelo tipo de informação passada à função de comparação. Em LVM_SORTITEMS, lParam1 e lParam2 são os valores dos itens a comparar. Em LVM_SORTITEMSEX, lParam1 é o índice atual do primeiro item a comparar e lParam2 é o índice atual do segundo item. Pode enviar uma LVM_GETITEMTEXT mensagem para obter mais informações sobre um artigo.

A função de comparação deve devolver um valor negativo se o primeiro item for anterior ao segundo, um valor positivo se o primeiro item for após o segundo, ou zero se os dois itens forem iguais.

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

Example

O primeiro exemplo de código define uma variável, m_listCtrl, que é usada para aceder ao controlo atual da vista de lista. Esta variável é usada no exemplo seguinte.

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

O próximo exemplo de código demonstra o SortItemEx método. Numa secção anterior deste exemplo de código, criámos um controlo em vista de lista que mostra duas colunas intituladas "ClientID" e "Grade" numa vista de relatório. O exemplo de código seguinte ordena 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 o item da vista de lista, se algum, está numa determinada posição.

int SubItemHitTest(LPLVHITTESTINFO pInfo);

Parâmetros

pInfo
Um apontador para a LVHITTESTINFO estrutura.

Valor de retorno

O índice baseado num só item do item, ou subitem, que está a ser testado (se houver), ou -1 de outra forma.

Observações

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

Example

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 controlo da vista de lista a repintar o item especificado por nItem.

BOOL Update(int nItem);

Parâmetros

nItem
Índice do item a atualizar.

Valor de retorno

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

Observações

Esta função também organiza o controlo da vista de lista, caso tenha o estilo.LVS_AUTOARRANGE

Example

Veja o exemplo para CListCtrl::GetSelectedCount.

Consulte também

Lista de Exemplos MFC
CWnd Classe
Gráfico de Hierarquia
CImageList Classe