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
strOutFolder
[out] The string used by the method to store the path of the selected folder.
pWndParent
[in] A pointer to the parent window.
lplszInitialFolder
[in] A string that contains the folder that is selected by default when the dialog box is displayed.
lpszTitle
[in] The title for the dialog box.
ulFlags
[in] Flags specifying options for the dialog box. See BROWSEINFO for the detailed description.
piFolderImage
[out] 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
pidl1
[in] The first item.
pidl2
[in] 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
pidlSource
[in] 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
cbSize
[in] 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
pidl
[in] An item list to delete.
CShellManager::GetItemCount
Returns the number of items in an item list.
UINT GetItemCount(LPCITEMIDLIST pidl);
Parameters
pidl
[in] 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
pidl
[in] 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
pidl
[in] 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
lpidl
[in] A PIDL whose parent will be retrieved.
lpidlParent
[out] 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
lpszPath
[in] A string that specifies the path for the item.
pidl
[out] 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.