CMFCShellListCtrl Class
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
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
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for