Edit

CShellManager Class

  • Article

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

CObject

CShellManager

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.

See also

Hierarchy Chart
Classes