Editéieren

Deelen iwwer

CShellManager Class

Note

The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation.

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

  • Last updated on