CShellManager Class
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at CShellManager Class.
Implements several methods that enable you to work with pointers to identifier lists (PIDLs).
Syntax
class CShellManager : public CObject
Members
Public Constructors
| Name | Description |
|---|---|
| CShellManager::CShellManager | Constructs a CShellManager object. |
Public Methods
| Name | Description |
|---|---|
| CShellManager::BrowseForFolder | Displays a dialog box that enables the user to select a shell folder. |
| CShellManager::ConcatenateItem | Concatenates two PIDLs. |
| CShellManager::CopyItem | Creates a new PIDL and copies the supplied PIDL to it. |
| CShellManager::CreateItem | Creates a new PIDL of the specified size. |
| CShellManager::FreeItem | Deletes the supplied PIDL. |
| CShellManager::GetItemCount | Returns the number of items in the supplied PIDL. |
| CShellManager::GetItemSize | Returns the size of the supplied PIDL. |
| CShellManager::GetNextItem | Returns the next item from the PIDL. |
| CShellManager::GetParentItem | Retrieves the parent item of the supplied item. |
| CShellManager::ItemFromPath | Retrieves the PIDL for the item identified by the supplied path. |
Remarks
The methods of the CShellManager class all deal with PIDLs. A PIDL is a unique identifier for a shell object.
You should not create a CShellManager object manually. It will be created automatically by the framework of your application. However, you should call CWinAppEx::InitShellManager during the initialization process of your application. To get a pointer to the shell manager for your application, call CWinAppEx::GetShellManager.
Inheritance Hierarchy
Requirements
Header: afxshellmanager.h
CShellManager::BrowseForFolder
Displays a dialog box that enables the user to select a shell folder.
BOOL BrowseForFolder(
CString& strOutFolder,
CWnd* pWndParent = NULL,
LPCTSTR lplszInitialFolder = NULL,
LPCTSTR lpszTitle = NULL,
UINT ulFlags = BIF_RETURNONLYFSDIRS,
LPINT piFolderImage = NULL);
Parameters
[out] strOutFolder
The string used by the method to store the path of the selected folder.
[in] pWndParent
A pointer to the parent window.
[in] lplszInitialFolder
A string that contains the folder that is selected by default when the dialog box is displayed.
[in] lpszTitle
The title for the dialog box.
[in] ulFlags
Flags specifying options for the dialog box. See BROWSEINFO for the detailed description.
[out] piFolderImage
A pointer to the integer value where the method writes the image index of the selected folder.
Return Value
Nonzero if the user selects a folder from the dialog box; otherwise 0.
Remarks
When you call this method, the application creates and shows a dialog box that enables the user to select a folder. The method will write the path of the folder into the strOutFolder parameter.
Example
The following example demonstrates how to retrieve a reference to a CShellManager object by using the CWinAppEx::GetShellManager method and how to use the BrowseForFolder method. This code snippet is part of the Explorer sample.
CString strPath;
// The this pointer points to the CExplorerView class which extends the CView class.
// CMFCShellListCtrl m_wndList
if (m_wndList.GetCurrentFolder (strPath) &&
theApp.GetShellManager ()->BrowseForFolder (strPath,
this, strPath, _T("Copy the selected item(s) to the folder:")))
{
MessageBox (CString (_T("The selected path is: ")) + strPath);
}
CShellManager::ConcatenateItem
Creates a new list containing two PIDLs.
LPITEMIDLIST ConcatenateItem(
LPCITEMIDLIST pidl1,
LPCITEMIDLIST pidl2);
Parameters
[in] pidl1
The first item.
[in] pidl2
The second item.
Return Value
A pointer to the new item list if the function succeeds, otherwise NULL.
Remarks
This method creates a new ITEMIDLIST large enough to contain both pidl1 and pidl2. It then copies pidl1 and pidl2 to the new list.
CShellManager::CopyItem
Copies an item list.
LPITEMIDLIST CopyItem(LPCITEMIDLIST pidlSource);
Parameters
[in] pidlSource
The original item list.
Return Value
A pointer to the newly created item list if successful; otherwise NULL.
Remarks
The newly created item list has the same size as the source item list.
CShellManager::CreateItem
Creates a new PIDL.
LPITEMIDLIST CreateItem(UINT cbSize);
Parameters
[in] cbSize
The size of the item list.
Return Value
A pointer to the created item list if successful; otherwise NULL.
CShellManager::CShellManager
Constructs a CShellManager object.
CShellManager();
Remarks
In most cases, you do not have to create a CShellManager directly. By default, the framework creates one for you. To get a pointer to the CShellManager, call CWinAppEx::GetShellManager. If you do create a CShellManager manually, you must initialize it with the method CWinAppEx::InitShellManager.
CShellManager::FreeItem
Deletes an item list.
void FreeItem(LPITEMIDLIST pidl);
Parameters
[in] pidl
An item list to delete.
CShellManager::GetItemCount
Returns the number of items in an item list.
UINT GetItemCount(LPCITEMIDLIST pidl);
Parameters
[in] pidl
A pointer to an item list.
Return Value
The number of items in the item list.
CShellManager::GetItemSize
Returns the size of an item list.
UINT GetItemSize(LPCITEMIDLIST pidl);
Parameters
[in] pidl
A pointer to an item list.
Return Value
The size of the item list.
CShellManager::GetNextItem
Retrieves the next item from a pointer to an item identifier list (PIDL).
LPITEMIDLIST GetNextItem(LPCITEMIDLIST pidl);
Parameters
[in] pidl
The list of items to iterate.
Return Value
A pointer to the next item in the list.
Remarks
If there are no more items in the list, this method returns NULL.
CShellManager::GetParentItem
Retrieves the parent of a pointer to an item identifier list (PIDL).
int GetParentItem(
LPCITEMIDLIST lpidl,
LPITEMIDLIST& lpidlParent);
Parameters
[in] lpidl
A PIDL whose parent will be retrieved.
[out] lpidlParent
A reference to a PIDL where the method will store the result.
Return Value
The level of the parent PIDL.
Remarks
The level of a PIDL is relative to the desktop. The desktop PIDL is considered to have a level of 0.
CShellManager::ItemFromPath
Retrieves the pointer to an item identifier list (PIDL) from the item identified by a string path.
HRESULT ItemFromPath(
LPCTSTR lpszPath,
LPITEMIDLIST& pidl);
Parameters
[in] lpszPath
A string that specifies the path for the item.
[out] pidl
A reference to a PIDL. The method uses this PIDL to store the pointer to its return value.
Return Value
Returns NOERROR if successful; an OLE-defined error value.