CShellManager 类

项目
10/19/2023

实现可使你使用指向标识符列表 (PIDL) 的指针的几种方法。

语法

class CShellManager : public CObject

成员

公共构造函数

名称	描述
CShellManager::CShellManager	构造 `CShellManager` 对象。

公共方法

名称	描述
CShellManager::BrowseForFolder	显示一个对话框，使用户能够选择 shell 文件夹。
CShellManager::ConcatenateItem	连接两个 PIDL。
CShellManager::CopyItem	创建新的 PIDL，并将提供的 PIDL 复制到它。
CShellManager::CreateItem	创建具有指定大小的新 PIDL。
CShellManager::FreeItem	删除提供的 PIDL。
CShellManager::GetItemCount	返回提供的 PIDL 中的项数。
CShellManager::GetItemSize	返回提供的 PIDL 的大小。
CShellManager::GetNextItem	从 PIDL 返回下一项。
CShellManager::GetParentItem	检索提供的项的父项。
CShellManager::ItemFromPath	检索由提供的路径标识的项的 PIDL。

注解

CShellManager 类的方法都涉及到 PIDL。 PIDL 是 shell 对象的唯一标识符。

不应手动创建 CShellManager 对象。它将由应用程序的框架自动创建。但是，应该在应用程序初始化过程中调用 CWinAppEx::InitShellManager。若要为应用程序获取指向 shell 管理器的指针，请调用 CWinAppEx::GetShellManager。

继承层次结构

CObject

CShellManager

要求

标头：afxshellmanager.h

CShellManager::BrowseForFolder

显示一个对话框，使用户能够选择 shell 文件夹。

BOOL BrowseForFolder(
    CString& strOutFolder,
    CWnd* pWndParent = NULL,
    LPCTSTR lplszInitialFolder = NULL,
    LPCTSTR lpszTitle = NULL,
    UINT ulFlags = BIF_RETURNONLYFSDIRS,
    LPINT piFolderImage = NULL);

参数

strOutFolder
[out] 方法用来存储所选文件夹路径的字符串。

pWndParent
[in] 指向父窗口的指针。

lplszInitialFolder
[in] 包含显示对话框时默认选择的文件夹的字符串。

lpszTitle
[in] 对话框的标题。

ulFlags
[in] 指定对话框的选项的标志。有关详细说明，请参阅 BROWSEINFO。

piFolderImage
[out] 指向整数值的指针，方法将在其中写入所选文件夹的图像索引。

返回值

如果用户从对话框中选择文件夹，则返回非零值；否则返回 0。

备注

调用此方法时，应用程序将创建并显示一个对话框，使用户能够选择文件夹。此方法会将文件夹的路径写入 strOutFolder 参数。

示例

以下示例演示如何使用 CWinAppEx::GetShellManager 方法检索对 CShellManager 对象的引用以及如何使用 BrowseForFolder 方法。此代码片段是 Explorer 示例的一部分。

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

创建包含两个 PIDL 的新列表。

LPITEMIDLIST ConcatenateItem(
    LPCITEMIDLIST pidl1,
    LPCITEMIDLIST pidl2);

参数

pidl1
[in] 第一个项。

pidl2
[in] 第二个项。

返回值

如果函数成功，则返回指向新项列表的指针；否则返回 NULL。

备注

此方法创建足够大的新 ITEMIDLIST 以同时包含 pidl1 和 pidl2。然后它将 pidl1 和 pidl2 复制到新列表。

CShellManager::CopyItem

复制项列表。

LPITEMIDLIST CopyItem(LPCITEMIDLIST pidlSource);

参数

pidlSource
[in] 原始项列表。

返回值

如果成功，则返回指向新创建的项列表的指针；否则返回 NULL。

注解

新创建的项列表与源项列表大小相同。

CShellManager::CreateItem

创建新的 PIDL。

LPITEMIDLIST CreateItem(UINT cbSize);

参数

cbSize
[in] 项列表的大小。

返回值

如果成功，则返回指向创建的项列表的指针；否则返回 NULL。

CShellManager::CShellManager

构造 CShellManager 对象。

CShellManager();

备注

大多数情况下都不必直接创建 CShellManager。默认情况下，框架会为你创建。若要获取指向 CShellManager 的指针，请调用 CWinAppEx::GetShellManager。如果确实要手动创建 CShellManager，则必须使用 CWinAppEx::InitShellManager 方法对它进行初始化。

CShellManager::FreeItem

删除项列表。

void FreeItem(LPITEMIDLIST pidl);

参数

pidl
[in] 要删除的项列表。

CShellManager::GetItemCount

返回项列表中的项数。

UINT GetItemCount(LPCITEMIDLIST pidl);

参数

pidl
[in] 指向项列表的指针。

返回值

项列表中的项数。

CShellManager::GetItemSize

返回项列表的大小。

UINT GetItemSize(LPCITEMIDLIST pidl);

参数

pidl
[in] 指向项列表的指针。

返回值

项列表的大小。

CShellManager::GetNextItem

从指向项标识符列表的指针 (PIDL) 中检索下一项。

LPITEMIDLIST GetNextItem(LPCITEMIDLIST pidl);

参数

pidl
[in] 要循环访问的项列表。

返回值

指向列表中下一项的指针。

注解

如果列表中没有其他项了，则此方法返回 NULL。

CShellManager::GetParentItem

检索指向项标识符列表的指针 (PIDL) 的父级。

int GetParentItem(
    LPCITEMIDLIST lpidl,
    LPITEMIDLIST& lpidlParent);

参数

lpidl
[in] 将检索其父级的 PIDL。

lpidlParent
[out] 对 PIDL 的引用，方法将在其中处存储结果。

返回值

父 PIDL 的级别。

备注

PIDL 的级别是相对于桌面的。桌面 PIDL 的级别视为 0。

CShellManager::ItemFromPath

从字符串路径标识的项检索指向项标识符列表的指针 (PIDL)。

HRESULT ItemFromPath(
    LPCTSTR lpszPath,
    LPITEMIDLIST& pidl);

参数

lpszPath
[in] 指定项路径的字符串。

pidl
[out] 对 PIDL 的引用。方法使用此 PIDL 来存储指向其返回值的指针。

返回值

如果成功，则返回 NOERROR；否则，返回 OLE 定义的错误值。

另请参阅

层次结构图
 类

通过