Classe CMFCShellListCtrl

Artigo
08/04/2024

A classe CMFCShellListCtrl fornece a funcionalidade de controle de lista do Windows e a expande incluindo a capacidade de exibir uma lista de itens de shell.

Sintaxe

class CMFCShellListCtrl : public CMFCListCtrl

Membros

Métodos públicos

Nome	Descrição
CMFCShellListCtrl::DisplayFolder	Exibe uma lista de itens contidos em uma pasta fornecida.
CMFCShellListCtrl::DisplayParentFolder	Exibe uma lista de itens contidos na pasta que é o pai da pasta exibida no momento.
CMFCShellListCtrl::EnableShellContextMenu	Habilita ou desabilita o menu de atalho.
CMFCShellListCtrl::GetCurrentFolder	Recupera o caminho da pasta atual.
CMFCShellListCtrl::GetCurrentFolderName	Recupera o nome da pasta atual.
CMFCShellListCtrl::GetCurrentItemIdList	Retorna o PIDL do item de controle de lista atual.
CMFCShellListCtrl::GetCurrentShellFolder	Retorna um ponteiro para a pasta shell atual.
CMFCShellListCtrl::GetItemPath	Retorna o caminho textual de um item.
CMFCShellListCtrl::GetItemTypes	Retorna tipos de item shell exibidos pelo controle de lista.
CMFCShellListCtrl::IsDesktop	Verifica se a pasta selecionada no momento é a pasta da área de trabalho.
CMFCShellListCtrl::OnCompareItems	A estrutura chama esse método quando compara dois itens. (Substitui CMFCListCtrl::OnCompareItems.)
CMFCShellListCtrl::OnFormatFileDate	Chamado quando a estrutura recupera a data do arquivo exibida pelo controle de lista.
CMFCShellListCtrl::OnFormatFileSize	Chamado quando a estrutura converte o tamanho do arquivo de um controle de lista.
CMFCShellListCtrl::OnGetItemIcon	Chamado quando a estrutura recupera o ícone de um item de controle de lista.
CMFCShellListCtrl::OnGetItemText	Chamado quando a estrutura converte o texto de um item de controle de lista.
CMFCShellListCtrl::OnSetColumns	Chamado pela estrutura quando define os nomes das colunas.
CMFCShellListCtrl::Refresh	Atualiza e pinta novamente o controle de lista.
CMFCShellListCtrl::SetItemTypes	Define o tipo de itens exibidos pelo controle de lista.

Comentários

A classe CMFCShellListCtrl estende a funcionalidade da Classe CMFCListCtrl, permitindo que seu programa liste itens do shell do Windows. O formato de exibição usado é semelhante ao de uma exibição de lista para uma janela do Explorer.

Um objeto CMFCShellTreeCtrl pode ser associado a um objeto CMFCShellListCtrl para criar uma janela completa do Explorer. Em seguida, selecionar um item no CMFCShellTreeCtrl fará com que o objeto CMFCShellListCtrl liste o conteúdo do item selecionado.

Exemplo

O exemplo a seguir demonstra como criar um objeto da classe CMFCShellListCtrl e como exibir a pasta pai da pasta exibida no momento. Este snippet de código faz parte do exemplo do Explorer.

CMFCShellListCtrl m_wndList;

CRect rectDummy(0, 0, 0, 0);
// The this pointer points to CExplorerView class which extends the CView class.
m_wndList.Create(WS_CHILD | WS_VISIBLE | LVS_REPORT, rectDummy, this, 1);

m_wndList.DisplayParentFolder();

Hierarquia de herança

CMFCShellListCtrl

Requisitos

Cabeçalho: afxshelllistCtrl.h

CMFCShellListCtrl::DisplayFolder

Exibe uma lista de itens contidos na pasta fornecida.

virtual HRESULT DisplayFolder(LPCTSTR lpszPath);
virtual HRESULT DisplayFolder(LPAFX_SHELLITEMINFO lpItemInfo);

Parâmetros

lpszPath
[in] Uma cadeia de caracteres que contém o caminho de uma pasta.

lpItemInfo
[in] Um ponteiro para uma estrutura LPAFX_SHELLITEMINFO que descreve uma pasta a ser exibida.

Valor de retorno

S_OK se for bem-sucedido, caso contrário, E_FAIL.

CMFCShellListCtrl::DisplayParentFolder

Atualizações o objeto CMFCShellListCtrl para exibir a pasta pai da pasta exibida no momento.

virtual HRESULT DisplayParentFolder();

Valor de retorno

S_OK se for bem-sucedido, caso contrário, E_FAIL.

CMFCShellListCtrl::EnableShellContextMenu

Habilita o menu de atalho.

void EnableShellContextMenu(BOOL bEnable = TRUE);

Parâmetros

bEnable
[in] Um booliano que especifica se a estrutura habilita o menu de atalho.

CMFCShellListCtrl::GetCurrentFolder

Recupera o caminho da pasta atualmente selecionada no objeto CMFCShellListCtrl.

BOOL GetCurrentFolder(CString& strPath) const;

Parâmetros

strPath
[out] Uma referência a um parâmetro de cadeia de caracteres em que o método grava o caminho.

Valor de retorno

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

Comentários

Esse método falhará se não houver nenhuma pasta selecionada em CMFCShellListCtrl.

CMFCShellListCtrl::GetCurrentFolderName

Recupera o nome da pasta atualmente selecionada no objeto CMFCShellListCtrl.

BOOL GetCurrentFolderName(CString& strName) const;

Parâmetros

strName
[out] Uma referência a um parâmetro de cadeia de caracteres em que o método grava o nome.

Valor de retorno

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

Comentários

Esse método falhará se não houver nenhuma pasta selecionada em CMFCShellListCtrl.

CMFCShellListCtrl::GetCurrentItemIdList

Retorna o PIDL do item selecionado no momento.

LPITEMIDLIST GetCurrentItemIdList() const;

Valor de retorno

O PIDL do item atual.

CMFCShellListCtrl::GetCurrentShellFolder

Obtém um ponteiro para o item selecionado no momento no objeto CMFCShellListCtrl.

const IShellFolder* GetCurrentShellFolder() const;

Valor de retorno

Um ponteiro para a Interface IShellFolder para o objeto selecionado.

Comentários

Esse método retornará NULL se nenhum objeto estiver selecionado no momento.

CMFCShellListCtrl::GetItemPath

Recupera o caminho de um item.

BOOL GetItemPath(
    CString& strPath,
    int iItem) const;

Parâmetros

strPath
[out] Uma referência a uma cadeia de caracteres que recebe o caminho.

iItem
[in] O índice do item de lista.

Valor de retorno

TRUE se tiver êxito; FALSE caso contrário.

Comentários

O índice fornecido pelo iItem se baseia nos itens exibidos atualmente pelo objeto classe CMFCShellListCtrl.

CMFCShellListCtrl::GetItemTypes

Retorna o tipo de itens exibidos pelo objeto CMFCShellListCtrl.

SHCONTF GetItemTypes() const;

Valor de retorno

Um valor SHCONTF que contém o tipo de itens listados em CMFCShellListCtrl.

Comentários

Para definir o tipo de itens listados em um CMFCShellListCtrl, chame CMFCShellListCtrl::SetItemTypes.

CMFCShellListCtrl::IsDesktop

Determina se a pasta exibida no objeto CMFCShellListCtrl é a pasta da área de trabalho.

BOOL IsDesktop() const;

Valor de retorno

TRUE se a pasta exibida for a pasta da área de trabalho; caso contrário, FALSE.

CMFCShellListCtrl::OnCompareItems

Para obter mais detalhes, confira o código-fonte localizado na pasta VC\atlmfc\src\mfc de sua instalação do Visual Studio.

virtual int OnCompareItems(
    LPARAM lParam1,
    LPARAM lParam2,
    int iColumn);

Parâmetros

[in] lParam1
[in] lParam2
[in] iColumn

Valor de retorno

Comentários

CMFCShellListCtrl::OnFormatFileDate

A estrutura chama esse método quando deve converter a data associada a um objeto em uma cadeia de caracteres.

virtual void OnFormatFileDate(
    const CTime& tmFile,
    CString& str);

Parâmetros

tmFile
[in] A data associada a um arquivo.

str
[out] Uma cadeia de caracteres que contém a data do arquivo formatado.

Comentários

Quando um objeto Classe CMFCShellListCtrl exibe a data associada a um arquivo, ele deve converter essa data em um formato de cadeia de caracteres. O método CMFCShellListCtrl usa esse método para fazer a conversão. Por padrão, esse método usa a localidade atual para formatar a data em uma cadeia de caracteres.

CMFCShellListCtrl::OnFormatFileSize

A estrutura chama esse método quando converte o tamanho de um objeto em uma cadeia de caracteres.

virtual void OnFormatFileSize(
    long lFileSize,
    CString& str);

Parâmetros

lFileSize
[in] O tamanho do arquivo que a estrutura exibirá.

str
[out] Uma cadeia de caracteres que contém o tamanho do arquivo formatado.

Comentários

Quando um objeto Classe CMFCShellListCtrl precisar exibir o tamanho de um arquivo, ele precisará converter o tamanho do arquivo em um formato de cadeia de caracteres. O método CMFCShellListCtrl usa esse método para fazer a conversão. Por padrão, esse método converte o tamanho do arquivo de bytes em quilobytes e usa a localidade atual para formatar o tamanho em cadeia de caracteres.

CMFCShellListCtrl::OnGetItemIcon

A estrutura chama esse método para recuperar o ícone associado a um item de lista de shells.

virtual int OnGetItemIcon(
    int iItem,
    LPAFX_SHELLITEMINFO pItem);

Parâmetros

iItem
[in] O índice do item.

pItem
[in] Um parâmetro LPAFX_SHELLITEMINFO que descreve o item.

Valor de retorno

O índice da imagem de ícone se tiver êxito; -1 se a função falhar.

Comentários

O índice de imagem de ícone é baseado na lista de imagens do sistema.

Por padrão, esse método depende do parâmetro pItem. O valor do iItem não é usado na implementação padrão. Você pode usar iItem para implementar o comportamento personalizado.

CMFCShellListCtrl::OnGetItemText

A estrutura chama esse método quando deve recuperar o texto de um item de shell.

virtual CString OnGetItemText(
    int iItem,
    int iColumn,
    LPAFX_SHELLITEMINFO pItem);

Parâmetros

iItem
[in] O índice do item.

iColumn
[in] A coluna de interesse.

pItem
[in] Um parâmetro LPAFX_SHELLITEMINFO que descreve o item.

Valor de retorno

Um CString que contém o texto associado ao item.

Comentários

Cada item no objeto CMFCShellListCtrl pode ter texto em uma ou mais colunas. Quando a estrutura chama esse método, ela especifica a coluna na qual está interessada. Se você chamar essa função manualmente, também deverá especificar a coluna na qual você está interessado.

Por padrão, esse método depende do parâmetro pItem para determinar qual item processar. O valor do iItem não é usado na implementação padrão.

CMFCShellListCtrl::OnSetColumns

A estrutura chama esse método quando define os nomes das colunas.

virtual void OnSetColumns();

Comentários

Por padrão, a estrutura cria quatro colunas em um objeto CMFCShellListCtrl. Os nomes dessas colunas são Nome, Tamanho, Tipo e Modificado. Você pode substituir esse método para personalizar o número de colunas e seus nomes.

CMFCShellListCtrl::Refresh

Atualiza e repinta o objeto CMFCShellListCtrl.

virtual HRESULT Refresh();

Valor de retorno

S_OK se for bem-sucedido; caso contrário, um valor de erro.

Comentários

Chame esse método para atualizar a lista de itens exibidos pelo objeto CMFCShellListCtrl.

CMFCShellListCtrl::SetItemTypes

Define o tipo de itens listados no objeto CMFCShellListCtrl.

void SetItemTypes(SHCONTF nTypes);

Parâmetros

nTypes
[in] Uma lista de tipos de item compatíveis com o objeto CMFCShellListCtrl.

Comentários

Para mais informações sobre a lista de tipos de item, confira SHCONTF.

Confira também

Gráfico da hierarquia
Classes
Classe CMFCListCtrl
Classe CMFCShellTreeCtrl

Compartilhar via

Classe CMFCShellListCtrl

Sintaxe

Membros

Métodos públicos

Comentários

Exemplo

Hierarquia de herança

Requisitos

CMFCShellListCtrl::DisplayFolder

Parâmetros

Valor de retorno

CMFCShellListCtrl::DisplayParentFolder

Valor de retorno

CMFCShellListCtrl::EnableShellContextMenu

Parâmetros

CMFCShellListCtrl::GetCurrentFolder

Parâmetros

Valor de retorno

Comentários

CMFCShellListCtrl::GetCurrentFolderName

Parâmetros

Valor de retorno

Comentários

CMFCShellListCtrl::GetCurrentItemIdList

Valor de retorno

CMFCShellListCtrl::GetCurrentShellFolder

Valor de retorno

Comentários

CMFCShellListCtrl::GetItemPath

Parâmetros

Valor de retorno

Comentários

CMFCShellListCtrl::GetItemTypes

Valor de retorno

Comentários

CMFCShellListCtrl::IsDesktop

Valor de retorno

CMFCShellListCtrl::OnCompareItems

Parâmetros

Valor de retorno

Comentários

CMFCShellListCtrl::OnFormatFileDate

Parâmetros

Comentários

CMFCShellListCtrl::OnFormatFileSize

Parâmetros

Comentários

CMFCShellListCtrl::OnGetItemIcon

Parâmetros

Valor de retorno

Comentários

CMFCShellListCtrl::OnGetItemText

Parâmetros

Valor de retorno

Comentários

CMFCShellListCtrl::OnSetColumns

Comentários

CMFCShellListCtrl::Refresh

Valor de retorno

Comentários

CMFCShellListCtrl::SetItemTypes

Parâmetros

Comentários

Confira também

Comentários

Recursos adicionais