Edit

Share via

CMFCShellTreeCtrl Class

  • Article

The CMFCShellTreeCtrl class extends CTreeCtrl Class functionality by displaying a hierarchy of Shell items.

For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

Syntax

class CMFCShellTreeCtrl : public CTreeCtrl

Members

Public Methods

Name Description
CMFCShellTreeCtrl::EnableShellContextMenu Enables or disables the shortcut menu.
CMFCShellTreeCtrl::GetFlags Returns a combination of flags that are passed to IShellFolder::EnumObjects.
CMFCShellTreeCtrl::GetItemPath Retrieves the path to an item.
CMFCShellTreeCtrl::GetRelatedList Returns a pointer to the CMFCShellListCtrl Class object that is used together with this CMFCShellTreeCtrl object to create an Explorer-like window.
CMFCShellTreeCtrl::OnChildNotify This member function is called by this window's parent window when it receives a notification message that applies to this window. (Overrides CWnd::OnChildNotify.)
CMFCShellTreeCtrl::OnGetItemIcon
CMFCShellTreeCtrl::OnGetItemText
CMFCShellTreeCtrl::Refresh Refreshes and repaints the current CMFCShellTreeCtrl object.
CMFCShellTreeCtrl::SelectPath Selects the appropriate tree control item based on a supplied PIDL or string path.
CMFCShellTreeCtrl::SetFlags Sets flags to filter the tree context (similar to the flags used by IShellFolder::EnumObjects).
CMFCShellTreeCtrl::SetRelatedList Sets a relation between the current CMFCShellTreeCtrl object and a CMFCShellListCtrl object.

Remarks

This class extends the CTreeCtrl class by enabling your program to include Windows Shell items in the tree. This class can be associated with a CMFCShellListCtrl object to create a complete Explorer window. Then, selecting an item in the tree will display a list of Windows Shell items in the associated list.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CTreeCtrl

CMFCShellTreeCtrl

Requirements

Header: afxshelltreeCtrl.h

Example

The following example demonstrates how to create an object of the CMFCShellTreeCtrl class. This code snippet is part of the Explorer sample.

CMFCShellTreeCtrl m_wndShellTree;

// const int idTree = 1
CRect rectDummy(0, 0, 0, 0);
const DWORD dwViewStyle = WS_CHILD | WS_VISIBLE | TVS_HASLINES |
                          TVS_LINESATROOT | TVS_HASBUTTONS;

// The this pointer points to CFolderBar class which extends the CDockablePane class
m_wndShellTree.Create(dwViewStyle, rectDummy, this, idTree);

CMFCShellTreeCtrl::EnableShellContextMenu

Enables the shortcut menu.

void EnableShellContextMenu(BOOL bEnable = TRUE);

Parameters

bEnable
[in] A Boolean that specifies whether to enable the shortcut menu.

CMFCShellTreeCtrl::GetFlags

Returns the flags set for the CMFCShellTreeCtrl Class object.

DWORD GetFlags() const;

Return Value

A DWORD value that specifies the combination of flags currently set.

Remarks

The flags set in the CMFCShellTreeCtrl are sent to the method IShellFolder::EnumObjects whenever the object is refreshed. You can change the flags with the CMFCShellTreeCtrl::SetFlags method.

CMFCShellTreeCtrl::GetItemPath

Retrieves the path of an item in the CMFCShellTreeCtrl Class object.

BOOL GetItemPath(
    CString& strPath,
    HTREEITEM htreeItem = NULL) const;

Parameters

strPath
[out] A reference to a string parameter. The method writes the path of the item to this parameter.

htreeItem
[in] The method retrieves the path for this tree control item.

Return Value

Nonzero if successful; 0 otherwise.

Remarks

If this method fails, strPath contains the empty string.

If you do not specify hTreeItem, this method tries to obtain the string for the currently selected item. If no item is selected and hTreeItem is NULL, this method fails.

CMFCShellTreeCtrl::GetRelatedList

Returns a pointer to the CMFCShellListCtrl Class object that is associated with this CMFCShellTreeCtrl object.

CMFCShellListCtrl* GetRelatedList() const;

Return Value

A pointer to the CMFCShellListCtrl object that is associated with this tree control object.

Remarks

By using a CMFCShellListCtrl object together with a CMFCShellTreeCtrl object, you can create an Explorer-like window. Use the method CMFCShellTreeCtrl::SetRelatedList to associate the two classes. After they are associated, the framework automatically updates the CMFCShellListCtrl if the selection in the CMFCShellTreeCtrl changes.

CMFCShellTreeCtrl::OnChildNotify

virtual BOOL OnChildNotify(
    UINT message,
    WPARAM wParam,
    LPARAM lParam,
    LRESULT* pLResult);

Parameters

[in] message
[in] wParam
[in] lParam
[in] pLResult

Return Value

Remarks

CMFCShellTreeCtrl::OnGetItemIcon

virtual int OnGetItemIcon(
    LPAFX_SHELLITEMINFO pItem,
    BOOL bSelected);

Parameters

[in] pItem
[in] bSelected

Return Value

Remarks

CMFCShellTreeCtrl::OnGetItemText

virtual CString OnGetItemText(LPAFX_SHELLITEMINFO pItem);

Parameters

[in] pItem

Return Value

Remarks

CMFCShellTreeCtrl::Refresh

Refreshes and repaints the CMFCShellTreeCtrl.

void Refresh();

Remarks

Call this method to refresh the hierarchy of the items displayed in the CMFCShellTreeCtrl.

CMFCShellTreeCtrl::SelectPath

Selects an item in the CMFCShellTreeCtrl Class based on the supplied path.

BOOL SelectPath(LPCTSTR lpszPath);
BOOL SelectPath(LPCITEMIDLIST lpidl);

Parameters

lpszPath
[in] A string that specifies the path of an item.

lpidl
[in] A PIDL that specifies the item

Return Value

S_OK if successful; E_FAIL otherwise.

CMFCShellTreeCtrl::SetFlags

Sets flags to filter the tree context.

void SetFlags(
    DWORD dwFlags,
    BOOL bRefresh = TRUE);

Parameters

dwFlags
[in] The flags to set.

bRefresh
[in] A Boolean that specifies whether the CMFCShellTreeCtrl should be refreshed immediately.

Remarks

The CMFCShellTreeCtrl passes all set flags to IShellFolder::EnumObjects. For more information about the values of different flags, see IShellFolder::EnumObjects.

CMFCShellTreeCtrl::SetRelatedList

Associates a CMFCShellListCtrl object with a CMFCShellTreeCtrl object.

void SetRelatedList(CMFCShellListCtrl* pShellList);

Parameters

pShellList
[in] A pointer to a CMFCShellListCtrl object.

Remarks

This method associates a CMFCShellListCtrl with a CMFCShellTreeCtrl. These objects may be displayed as an Explorer-like window: if the user selects an object in the CMFCShellTreeCtrl, the associated items in the CMFCShellListCtrl will be automatically updated.

Use the method CMFCShellTreeCtrl::GetRelatedList to retrieve the CMFCShellListCtrl associated with a CMFCShellTreeCtrl.

See also

Hierarchy Chart
Classes
CTreeCtrl Class
CMFCShellListCtrl Class