Edit

Share via

CMFCShellListCtrl Class

  • Article

The CMFCShellListCtrl class provides Windows list control functionality and expands it by including the ability to display a list of shell items.

Syntax

class CMFCShellListCtrl : public CMFCListCtrl

Members

Public Methods

Name Description
CMFCShellListCtrl::DisplayFolder Displays a list of items that are contained in a provided folder.
CMFCShellListCtrl::DisplayParentFolder Displays a list of items that are contained in the folder that is the parent of the currently displayed folder.
CMFCShellListCtrl::EnableShellContextMenu Enables or disables the shortcut menu.
CMFCShellListCtrl::GetCurrentFolder Retrieves the path of the current folder.
CMFCShellListCtrl::GetCurrentFolderName Retrieves the name of the current folder.
CMFCShellListCtrl::GetCurrentItemIdList Returns the PIDL of the current list control item.
CMFCShellListCtrl::GetCurrentShellFolder Returns a pointer to the current Shell folder.
CMFCShellListCtrl::GetItemPath Returns the textual path of an item.
CMFCShellListCtrl::GetItemTypes Returns Shell item types that are displayed by the list control.
CMFCShellListCtrl::IsDesktop Checks if the currently selected folder is the desktop folder.
CMFCShellListCtrl::OnCompareItems The framework calls this method when it compares two items. (Overrides CMFCListCtrl::OnCompareItems.)
CMFCShellListCtrl::OnFormatFileDate Called when the framework retrieves the file date displayed by the list control.
CMFCShellListCtrl::OnFormatFileSize Called when the framework converts the file size of a list control.
CMFCShellListCtrl::OnGetItemIcon Called when the framework retrieves the icon of a list control item.
CMFCShellListCtrl::OnGetItemText Called when the framework converts the text of a list control item.
CMFCShellListCtrl::OnSetColumns Called by the framework when it sets the names of the columns.
CMFCShellListCtrl::Refresh Refreshes and repaints the list control.
CMFCShellListCtrl::SetItemTypes Sets the type of items displayed by the list control.

Remarks

The CMFCShellListCtrl class extends the functionality of the CMFCListCtrl Class by enabling your program to list Windows shell items. The display format that is used is like that of a list view for an Explorer window.

A CMFCShellTreeCtrl object can be associated with a CMFCShellListCtrl object to create a complete Explorer window. Then, selecting an item in the CMFCShellTreeCtrl will cause the CMFCShellListCtrl object to list the contents of the selected item.

Example

The following example demonstrates how to create an object of the CMFCShellListCtrl class and how to display the parent folder of the currently displayed folder. This code snippet is part of the Explorer sample.

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

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CListCtrl

CMFCListCtrl

CMFCShellListCtrl

Requirements

Header: afxshelllistCtrl.h

CMFCShellListCtrl::DisplayFolder

Displays a list of items that are contained in the provided folder.

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

Parameters

lpszPath
[in] A string that contains the path of a folder.

lpItemInfo
[in] A pointer to a LPAFX_SHELLITEMINFO structure that describes a folder to display.

Return Value

S_OK if successful; E_FAIL otherwise.

CMFCShellListCtrl::DisplayParentFolder

Updates the CMFCShellListCtrl object to display the parent folder of the currently displayed folder.

virtual HRESULT DisplayParentFolder();

Return Value

S_OK if successful; E_FAIL otherwise.

CMFCShellListCtrl::EnableShellContextMenu

Enables the shortcut menu.

void EnableShellContextMenu(BOOL bEnable = TRUE);

Parameters

bEnable
[in] A Boolean that specifies whether the framework enables the shortcut menu.

CMFCShellListCtrl::GetCurrentFolder

Retrieves the path of the currently selected folder in the CMFCShellListCtrl object.

BOOL GetCurrentFolder(CString& strPath) const;

Parameters

strPath
[out] A reference to a string parameter where the method writes the path.

Return Value

Nonzero if successful; 0 otherwise.

Remarks

This method fails if there is no folder selected in the CMFCShellListCtrl.

CMFCShellListCtrl::GetCurrentFolderName

Retrieves the name of the currently selected folder in the CMFCShellListCtrl object.

BOOL GetCurrentFolderName(CString& strName) const;

Parameters

strName
[out] A reference to a string parameter where the method writes the name.

Return Value

Nonzero if successful; 0 otherwise.

Remarks

This method fails if there is no folder selected in the CMFCShellListCtrl.

CMFCShellListCtrl::GetCurrentItemIdList

Returns the PIDL of the currently selected item.

LPITEMIDLIST GetCurrentItemIdList() const;

Return Value

The PIDL of the current item.

CMFCShellListCtrl::GetCurrentShellFolder

Gets a pointer to the currently selected item in the CMFCShellListCtrl object.

const IShellFolder* GetCurrentShellFolder() const;

Return Value

A pointer to the IShellFolder Interface for the selected object.

Remarks

This method returns NULL if no object is currently selected.

CMFCShellListCtrl::GetItemPath

Retrieves the path for an item.

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

Parameters

strPath
[out] A reference to a string that receives the path.

iItem
[in] The index of the list item.

Return Value

TRUE if successful; FALSE otherwise.

Remarks

The index supplied by iItem is based on the items currently displayed by the CMFCShellListCtrl Class object.

CMFCShellListCtrl::GetItemTypes

Returns the type of items displayed by the CMFCShellListCtrl object.

SHCONTF GetItemTypes() const;

Return Value

A SHCONTF value that contains the type of items listed in the CMFCShellListCtrl.

Remarks

To set the type of items listed in a CMFCShellListCtrl, call CMFCShellListCtrl::SetItemTypes.

CMFCShellListCtrl::IsDesktop

Determines if the folder that is displayed in the CMFCShellListCtrl object is the desktop folder.

BOOL IsDesktop() const;

Return Value

TRUE if the displayed folder is the desktop folder; FALSE otherwise.

CMFCShellListCtrl::OnCompareItems

For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

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

Parameters

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

Return Value

Remarks

CMFCShellListCtrl::OnFormatFileDate

The framework calls this method when it must convert the date associated with an object into a string.

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

Parameters

tmFile
[in] The date associated with a file.

str
[out] A string that contains the formatted file date.

Remarks

When a CMFCShellListCtrl Class object displays the date associated with a file, it must convert that date to a string format. The CMFCShellListCtrl uses this method to make that conversion. By default, this method uses the current locale to format the date into a string.

CMFCShellListCtrl::OnFormatFileSize

The framework calls this method when it converts the size of an object to a string.

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

Parameters

lFileSize
[in] The size of the file that the framework will display.

str
[out] A string that contains the formatted file size.

Remarks

When a CMFCShellListCtrl Class object needs to display the size of a file, it needs to convert the file size into a string format. The CMFCShellListCtrl uses this method to make that conversion. By default, this method converts the file size from bytes to kilobytes and then uses the current locale to format the size into string.

CMFCShellListCtrl::OnGetItemIcon

The framework calls this method to retrieve the icon associated with a shell list item.

virtual int OnGetItemIcon(
    int iItem,
    LPAFX_SHELLITEMINFO pItem);

Parameters

iItem
[in] The item index.

pItem
[in] A LPAFX_SHELLITEMINFO parameter that describes the item.

Return Value

The index of the icon image if successful; -1 if the function fails.

Remarks

The icon image index is based on the system image list.

By default, this method relies on the pItem parameter. The value of iItem is not used in the default implementation. You can use iItem to implement custom behavior.

CMFCShellListCtrl::OnGetItemText

The framework calls this method when it must retrieve the text of a shell item.

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

Parameters

iItem
[in] The item index.

iColumn
[in] The column of interest.

pItem
[in] A LPAFX_SHELLITEMINFO parameter that describes the item.

Return Value

A CString that contains the text associated with the item.

Remarks

Each item in the CMFCShellListCtrl object may have text in one or more columns. When the framework calls this method, it specifies the column that it is interested in. If you call this function manually, you must also specify the column that you are interested in.

By default, this method relies on the pItem parameter to determine which item to process. The value of iItem is not used in the default implementation.

CMFCShellListCtrl::OnSetColumns

The framework calls this method when it sets the names of the columns.

virtual void OnSetColumns();

Remarks

By default, the framework creates four columns in a CMFCShellListCtrl object. The names of these columns are Name, Size, Type, and Modified. You can override this method to customize the number of columns and their names.

CMFCShellListCtrl::Refresh

Refreshes and repaints the CMFCShellListCtrl object.

virtual HRESULT Refresh();

Return Value

S_OK if successful; otherwise an error value.

Remarks

Call this method to refresh the list of items displayed by the CMFCShellListCtrl object.

CMFCShellListCtrl::SetItemTypes

Sets the type of items that are listed in the CMFCShellListCtrl object.

void SetItemTypes(SHCONTF nTypes);

Parameters

nTypes
[in] A list of item types that the CMFCShellListCtrl object supports.

Remarks

For more information about the list of item types, see SHCONTF.

See also

Hierarchy Chart
Classes
CMFCListCtrl Class
CMFCShellTreeCtrl Class