/**
* @file XTPShellTreeBase.h
*
* @copyright
* (c) 1998-2025 Codejock Software, All Rights Reserved.
*
* This source file is the property of Codejock Software and must not be
* redistributed by any means without the explicit written permission of
* Codejock Software.
*
* The use of this source code is governed by the terms and conditions specified
* in the Toolkit Pro license agreement. Codejock Software grants you, as a
* single software developer, the limited right to use this software on one
* computer only.
*
* Contact Information:
* support@codejock.com
* http://www.codejock.com
*
*/
/** @cond */
#if !defined(__XTPSHELLTREEBASE_H__)
# define __XTPSHELLTREEBASE_H__
/** @endcond */
# if _MSC_VER >= 1000
# pragma once
# endif // _MSC_VER >= 1000
# include "Common/Base/Diagnostic/XTPDisableNoisyWarnings.h"
/**
* @brief
* Enumeration used to determine folder or drive type.
* @details
* XTPFindType type defines the constants used by the CXTPShellTreeBase
* class to determine the type of object enumerated (either folder or drive).
* @see
* CXTPFontListBox, CXTPFontListBox::SetListStyle
*
* @see xtpFindTypeDrive, xtpFindTypeFolder
*/
enum XTPFindType
{
xtpFindTypeDrive, /**< The object type is a drive. */
xtpFindTypeFolder, /**< The object type is a folder. */
xtpFindTypeRoot, /**< The object type is a root folder */
xtpFindTypeShare /**< The object is a UNC share. */
};
/**
* @brief
* CXTPShellTreeBase is a multiple inheritance class derived from CXTPTreeView
* and CXTPShellPidl. It is used to create a CXTPShellTreeBase class object.
*/
class _XTP_EXT_CLASS CXTPShellTreeBase
: public CXTPTreeBase
, public CXTPShellPidl
{
public:
/**
* @brief
* Constructs a CXTPShellTreeBase object.
*/
CXTPShellTreeBase();
/**
* @brief
* Destroys a CXTPShellTreeBase object, handles cleanup and deallocation.
*/
virtual ~CXTPShellTreeBase();
protected:
/**
* @brief
* This member function fills a branch of the TreeView control. Given
* the shell folder, it enumerates the sub-items of this folder and adds
* the appropriate items to the tree.
* @param lpsf Pointer to the parent shell folder.
* @param lpifq Fully qualified item ID list to the item having items enumerated.
* This is the PIDL to the item identified by the 'lpsf' parameter.
* @param hParent Parent tree node.
* @return
* TRUE if successful, otherwise FALSE.
*/
virtual BOOL InitTreeViewItems(LPSHELLFOLDER lpsf, LPITEMIDLIST lpifq, HTREEITEM hParent);
/**
* @brief
* This member function gets the index for the normal and selected
* icons for the current item.
* @param lpifq Fully qualified item ID list for the current item.
* @param lptvitem Pointer to the tree view item being added to the tree.
*/
virtual void GetNormalAndSelectedIcons(LPITEMIDLIST lpifq, LPTV_ITEM lptvitem);
public:
/**
* @brief
* Call this member function to enable/disable the display of the
* shell context menu on right item click.
* @param bEnable TRUE to enable the display of the shell context menu.
*/
void EnableContextMenu(BOOL bEnable);
/**
* @brief
* Call this member to set the root CSIDL folder.
* @param nRootFolder Root folder of tree view.
*/
void SetRootFolder(int nRootFolder = CSIDL_DESKTOP);
/**
* @brief
* Call this member to show all files instead of only folders.
* @param bShowFiles TRUE to show folder's files.
*/
void ShowFiles(BOOL bShowFiles = TRUE);
/**
* @brief
* Call this member function to determine the type of items included in the
* shell enumeration. The default is SHCONTF_FOLDERS | SHCONTF_NONFOLDERS.
* @param uFlags Determines the type of items included in an enumeration. It
* can be one or more of the values listed in the Remarks section.
* @details
* Styles to be added or removed can be combined by using the bitwise
* OR (|) operator. It can be one or more of the following:
* SHCONTF_FOLDERS: Include items that are folders in
* the enumeration.
* SHCONTF_NONFOLDERS: Include items that are not folders
* in the enumeration.
* SHCONTF_INCLUDEHIDDEN: Include hidden items in the
* enumeration.
* SHCONTF_INIT_ON_FIRST_NEXT: IShellFolder::EnumObjects can return
* without validating the enumeration
* object. Validation can be postponed
* until the first call to IEnumIDList::Next.
* This flag is intended to be used when
* a user interface may be displayed prior
* to the first IEnumIDList::Next call.
* For a user interface to be presented,
* 'hwndOwner' must be set to a valid
* window handle.
* SHCONTF_NETPRINTERSRCH: The caller is looking for
* printer objects.
*/
void SetEnumFlags(UINT uFlags);
/**
* @brief
* This member function obtains a handle to the system image list and
* attaches it to the tree control.
* @return
* TRUE if successful, otherwise FALSE.
*/
virtual BOOL InitSystemImageLists();
/**
* @brief
* This member function adds items to the tree view.
*/
virtual void PopulateTreeView();
/**
* @brief
* This member function responds to a TVN_ITEMEXPANDING message in
* order to fill up sub-directories.
* @param pNMTreeView Address of an NM_TREEVIEW struct.
*/
virtual void OnFolderExpanding(NM_TREEVIEW* pNMTreeView);
/**
* @brief
* This member function displays the shell context menu for the selected
* item or folder.
* @return
* A handle to the currently selected HTREEITEM.
*/
virtual HTREEITEM GetContextMenu();
/**
* @brief
* This member function responds to a TVN_SELCHANGED message to retrieve
* the specified folder path.
* @param pNMTreeView Address of an NM_TREEVIEW struct.
* @param strFolderPath Address of a CString object to receive the file system path.
* @return
* TRUE if the folder path was found, otherwise FALSE.
*/
virtual BOOL OnFolderSelected(NM_TREEVIEW* pNMTreeView, CString& strFolderPath);
/**
* @brief
* This member function retrieves the path of the currently selected
* tree item.
* @param strFolderPath Address of a CString object to receive the file system path.
* @return
* TRUE if successful, otherwise FALSE.
*/
virtual BOOL GetSelectedFolderPath(CString& strFolderPath);
/**
* @brief
* This member function recursively searches the tree control beginning
* at 'hItem' to find the item specified by 'lplvid'. This is typically
* used when the user double clicks an item in the list view.
* @param hItem Handle to the tree item to search from.
* @param lplvid Pointer to the list view item data.
* @param bRecursively TRUE to recursively search.
* @return
* TRUE if successful, otherwise FALSE.
*/
virtual BOOL FindTreeItem(HTREEITEM hItem, XTP_LVITEMDATA* lplvid, BOOL bRecursively = TRUE);
/**
* @brief
* This member function is used to associate a CComboBox object with
* the control. Whenever the path changes, the combo is updated.
* @param pWnd Pointer to the combobox that is associated with the tree.
*/
virtual void AssociateCombo(CWnd* pWnd);
/**
* @brief
* This member function is called to initialize a branch of the shell tree.
* @param hItem Handle to a tree node.
* @param lptvid Pointer to the list view item data.
*/
virtual void InitTreeNode(HTREEITEM hItem, XTP_TVITEMDATA* lptvid);
/**
* @brief
* This member function searches the tree for a specified folder.
* @param hItem Tree item to begin the search from.
* @param pABSPidl pidl to match.
* @return
* HTREEITEM of node in tree that resulted in a match.
*/
virtual HTREEITEM SearchTree(HTREEITEM hItem, LPCITEMIDLIST pABSPidl);
/**
* @brief
* This member function will "tunnel" the tree to find the specified
* path. This will work only when the PopulateTreeView() method is used
* to populate the tree.
* @param strFindPath Path to find.
* @return TRUE if successful, FALSE otherwise.
*/
virtual BOOL TunnelTree(CString strFindPath);
/**
* @brief
* This member function retrieves the path of a folder item, which
* does not have to be selected. Pass a CString object that will hold
* the folder path.
* @param hItem Tree item to get the path for.
* @param strFolderPath Reference to a CString object to contain the folder path.
* @return
* TRUE if the path is not in the file system (e.g.
* MyComputer); if none is selected, it returns FALSE.
*/
virtual BOOL GetFolderItemPath(HTREEITEM hItem, CString& strFolderPath);
/**
* @brief
* This member function populates a tree based upon a path. You must
* call InitializeTree() before populating the tree for the first time.
* @param lpszPath Path to populate.
* @see
* InitializeTree()
*/
virtual void PopulateTree(LPCTSTR lpszPath);
/**
* @brief
* Call this member function to initialize the shell tree control prior
* to calling PopulateTree.
* @param dwStyle TVS_ style flags for tree control.
* @return
* TRUE if successful, otherwise FALSE.
* @see
* PopulateTree()
*/
virtual BOOL InitializeTree(DWORD dwStyle = TVS_HASBUTTONS | TVS_HASLINES | TVS_LINESATROOT);
/**
* @brief
* Used by the shell list control to handle a drag event.
* @param pNMTreeView Pointer to a NM_TREEVIEW structure.
*/
virtual void BeginDrag(NM_TREEVIEW* pNMTreeView);
/**
* @brief
* This member function is called to insert the desktop as the root
* item in the shell tree control.
* @param nFolder Root folder CSIDL to insert.
* @return
* A handle to the desktop tree item if successful, otherwise NULL.
*/
virtual HTREEITEM InsertDesktopItem(int nFolder = CSIDL_DESKTOP);
/**
* @brief
* Called after a user makes a new tree selection.
* @details
* This member function is called whenever a user makes a selection
* within the tree control to synchronize any shell list or shell
* comboboxes associated with the tree. You can override this member
* to provide additional functionality.
* @param hItem Handle to the newly selected tree item.
* @param strFolderPath A NULL-terminated string representing the fully
* qualified path to the selected tree item.
*/
virtual void SelectionChanged(HTREEITEM hItem, CString strFolderPath);
public:
/**
* @brief
* Call this method to enable auto-hidden triangles for Windows Vista
* and Windows 7.
*/
void SetExplorerStyle();
protected:
/**
* @brief
* This member function sets the shell attribute flags for the specified
* tree item.
* @param hItem Handle to a HTREEITEM node.
* @param dwAttributes Flags retrieved from SHELLFOLDER::GetAttributesOf.
*/
void SetAttributes(HTREEITEM hItem, DWORD dwAttributes);
/**
* @brief
* Parses a path for the next path component.
* @param pszPath Pointer to a NULL-terminated string with the path. Paths are
* delimited by backslashes or by the NULL at the end of the path.
* @details
* This member function parses a path for the next path component, not
* dependent on shell32.dll, and is a replacement for the Windows API
* PathFindNextComponent.
* @return
* A pointer to a NULL-terminated string with the next path component
* if successful, otherwise FALSE.
* Example:
* The following example demonstrates using the XTFuncPathFindNextComponent
* function:
*
* // Path to find the next part.
* char buffer_1[ ] = "c:\\\\path1\\\\path2\\\\test";
* char *lpStr1;
* lpStr1 = buffer_1;
*
* cout \<\< "Search a path for the next path component "
* \<\< "after the root " \<\< lpStr1 \<\< endl;
* cout \<\< "Return the next path component: \\""
* \<\< XTFuncPathFindNextComponent(lpStr1) \<\< "\\"" \<\< endl;
*
* cout \<\< "\\nSearch a path for the next path component "
* \<\< "after the root \\"c:\\\\path1\\\\path2\\"" \<\< endl;
* cout \<\< "Return the next path component: \\""
* \<\< XTFuncPathFindNextComponent("c:\\\\path1\\\\path2") \<\< "\\"" \<\< endl;
*
* cout \<\< "\\nSearch a path for the next path component "
* \<\< "after the root \\"c:\\\\path1\\"" \<\< endl;
* cout \<\< "Return the next path component: \\""
* \<\< XTFuncPathFindNextComponent("c:\\\\path1") \<\< "\\"" \<\< endl;
*
* OUTPUT:
* Search a path for the next path component after the root c:\\path1\\path2\\test
* Return the next path component: "path1\\path2\\test"
*
* Search a path for the next path component after the root "c:\\path1\\path2"
* Return the next path component: "path1\\path2"
*
* Search a path for the next path component after the root "c:\\path1"
* Return the next path component: "path1"
*
*/
CString PathFindNextComponent(const CString& pszPath);
/**
* @brief
* Sorts items in the control using the provided callback function.
* @param hParent Parent item to sort.
*/
virtual void SortChildren(HTREEITEM hParent);
protected:
/** @cond */
//{{AFX_MSG(CXTPShellTreeBase)
afx_msg void OnItemexpanding(NMHDR* pNMHDR, LRESULT* pResult);
afx_msg void OnSelchanged(NMHDR* pNMHDR, LRESULT* pResult);
afx_msg void OnDeleteTreeItem(NMHDR* pNMHDR, LRESULT* pResult);
afx_msg void OnRclick(NMHDR* pNMHDR, LRESULT* pResult);
afx_msg BOOL OnEraseBkgnd(CDC* pDC);
afx_msg void OnPaint();
//}}AFX_MSG
/** @endcond */
protected:
UINT m_uFlags; /**< Flags indicating which items to include in the enumeration. */
bool m_bTunneling; /**< true if the tree is currently traversing. */
BOOL m_bContextMenu; /**< TRUE to display the shell context menu on right item click. */
CWnd* m_pComboBox; /**< CComboBox that is associated with this control. See AssociateCombo(...).
*/
CXTPShellSettings m_shSettings; /**< Contains SHELLFLAGSTATE info. */
int m_nRootFolder; /**< Root Folder CSIDL. */
BOOL m_bShowFiles; /**< FALSE to only show directories. */
BOOL m_bExplorerStyle; /**< Explorer Style. */
};
//////////////////////////////////////////////////////////////////////
/** @cond */
AFX_INLINE void CXTPShellTreeBase::SetEnumFlags(UINT uFlags)
{
m_uFlags = uFlags;
}
AFX_INLINE void CXTPShellTreeBase::EnableContextMenu(BOOL bEnable)
{
m_bContextMenu = bEnable;
}
AFX_INLINE void CXTPShellTreeBase::SetRootFolder(int nRootFolder /*= CSIDL_DESKTOP*/)
{
m_nRootFolder = nRootFolder;
}
AFX_INLINE void CXTPShellTreeBase::ShowFiles(BOOL bShowFiles /*= TRUE*/)
{
m_bShowFiles = bShowFiles;
}
/** @endcond */
/**
* @brief
* The DECLARE_SHELLTREE_BASE class is a template class used by the
* CXTPShellTreeView and CXTPShellTreeCtrl classes to declare a multiple
* inheritance base class so that both classes can share a common code base.
* @param ClassName Name of the object to be declared as the base class.
* @param Tree Existing class that this object will be derived from.
* @param Base Existing shared class that this object will be derived from.
* @details
* Tree must be an existing class that is derived from either
* CTreeCtrl or CTreeView.
* Example:
* The following example demonstrates how to use DECLARE_SHELLTREE_BASE:
*
* DECLARE_SHELLTREE_BASE(CXTPShellTreeViewBase, CTreeView, CXTPShellTreeBase)
*
* class _XTP_EXT_CLASS CXTPShellTreeView : public CXTPShellTreeViewBase
* {
* public:
* CXTPShellTreeView();
* };
*
*/
# define DECLARE_SHELLTREE_BASE(ClassName, Tree, Base)
/** @cond */
# undef DECLARE_SHELLTREE_BASE
# define DECLARE_SHELLTREE_BASE(ClassName, Tree, Base) \
DECLARE_TREE_BASE(Base##Tree, Tree, Base) \
class _XTP_EXT_CLASS ClassName : public Base##Tree \
{ \
protected: \
void OnPaint() \
{ \
Base::OnPaint(); \
} \
void OnBeginDrag(NMHDR* pNMHDR, LRESULT* pResult) \
{ \
NM_TREEVIEW* pNMTreeView = (NM_TREEVIEW*)pNMHDR; \
BeginDrag(pNMTreeView); \
*pResult = 0; \
} \
void OnSelchanged(NMHDR* pNMHDR, LRESULT* pResult) \
{ \
Base::OnSelchanged(pNMHDR, pResult); \
} \
void OnDeleteTreeItem(NMHDR* pNMHDR, LRESULT* pResult) \
{ \
Base::OnDeleteTreeItem(pNMHDR, pResult); \
} \
void OnRclick(NMHDR* pNMHDR, LRESULT* pResult) \
{ \
Base::OnRclick(pNMHDR, pResult); \
} \
void OnItemexpanding(NMHDR* pNMHDR, LRESULT* pResult) \
{ \
Base::OnItemexpanding(pNMHDR, pResult); \
} \
};
# define ON_SHELLTREE_REFLECT \
ON_NOTIFY_REFLECT(NM_RCLICK, OnRclick) \
ON_NOTIFY_REFLECT(TVN_ITEMEXPANDING, OnItemexpanding) \
ON_NOTIFY_REFLECT(TVN_SELCHANGED, OnSelchanged) \
ON_NOTIFY_REFLECT(TVN_BEGINDRAG, OnBeginDrag) \
ON_NOTIFY_REFLECT(TVN_BEGINRDRAG, OnBeginDrag) \
ON_NOTIFY_REFLECT(TVN_DELETEITEM, OnDeleteTreeItem) \
ON_TREECTRL_REFLECT
/**
* This definition is necessary for backward compatibility
* as previously this macro name has been misspelled.
*/
# define DECLATE_SHELLTREE_BASE(ClassName, Tree, Base) \
DECLARE_SHELLTREE_BASE(ClassName, Tree, Base)
/** @endcond */
# include "Common/Base/Diagnostic/XTPEnableNoisyWarnings.h"
/** @cond */
#endif // __XTPSHELLTREEBASE_H__
/** @endcond */