src/Utils/TreePropSheet/TreePropSheet.h

   1 /********************************************************************
   2 *
   3 * Copyright (c) 2002 Sven Wiegand <mail@sven-wiegand.de>
   4 *
   5 * You can use this and modify this in any way you want,
   6 * BUT LEAVE THIS HEADER INTACT.
   7 *
   8 * Redistribution is appreciated.
   9 *
  10 * $Workfile:$
  11 * $Revision:$
  12 * $Modtime:$
  13 * $Author:$
  14 *
  15 * Revision History:
  16 *   $History:$
  17 *
  18 *********************************************************************/
  19
  20
  21 #if !defined(AFX_TREEPROPSHEET_H__50695CFB_FCE4_4188_ADB4_BF05A5488E41__INCLUDED_)
  22 #define AFX_TREEPROPSHEET_H__50695CFB_FCE4_4188_ADB4_BF05A5488E41__INCLUDED_
  23
  24 #if _MSC_VER > 1000
  25 #pragma once
  26 #endif // _MSC_VER > 1000
  27
  28 #include "PropPageFrame.h"
  29 #include <afxtempl.h>
  30
  31 namespace TreePropSheet
  32 {
  33
  34 /**
  35 A property sheet, which can use a tree control instead of a tab
  36 control, to give the user access to the different pages.
  37
  38 You can use it exactly the same way, as a CPropertySheet object.
  39 Simply create CPropertyPage objects and add them via AddPage() to
  40 the sheet. If you would like to use the tree view mode (default),
  41 you can specify the path of the pages in the tree, by their name:
  42 The names of the pages can contain
  43 double colons ("::"), which will specify the path of that page in the
  44 tree control. I.e. if you have three pages with the following names:
  45 1. _T("Appearance::Toolbars")
  46 2. _T("Appearance::Menus")
  47 3. _T("Directories")
  48 the tree would look as follow:
  49 \verbatim
  50 Appearance
  51 |
  52 +-Toolbars
  53 |
  54 +-Menus
  55
  56 Directories
  57 \endverbatim
  58 If you would like to use a double colon, which should not be
  59 interpreted as a path seperator, prefix it with a backslash ("\\::").
  60
  61 To disable tree view mode and use the standard tabbed mode, call
  62 the SetTreeViewMode() method. This also allows you, to enable page
  63 captions and tree images for tree view mode. If you would like to
  64 have images in the tree, but not all of your pages specify images or
  65 there are tree view items, which are not attached to a page (only
  66 parent items for real page items), you have to set default images
  67 using the SetTreeDefaultImages() method -- otherwise their may appear
  68 display errors.
  69
  70 If the user selects a tree view item, which does not belong to a page,
  71 because it is just a parent item for real page items, no page will
  72 be displayed, instead a message will be displayed, that can be set
  73 via SetEmptyPageText().
  74
  75 @author Sven Wiegand
  76 */
  77 class /*AFX_EXT_CLASS*/ CTreePropSheet : public CPropertySheet
  78 {
  79         DECLARE_DYNAMIC(CTreePropSheet)
  80
  81 // Construction/Destruction
  82 public:
  83         CTreePropSheet();
  84         CTreePropSheet(UINT nIDCaption, CWnd* pParentWnd = NULL, UINT iSelectPage = 0);
  85         CTreePropSheet(LPCTSTR pszCaption, CWnd* pParentWnd = NULL, UINT iSelectPage = 0);
  86         virtual ~CTreePropSheet();
  87
  88 // Operations
  89 public:
  90         /**
  91         Call this method, if you would like to use a tree control to browse
  92         the pages, instead of the tab control.
  93
  94         This method needs to becalled, before DoModal() or Create(). If the
  95         window has already been created, the method will fail.
  96
  97         @param bTreeViewMode
  98                 Pass TRUE to provide a tree view control instead of a tab control
  99                 to browse the pages, pass FALSE to use the normal tab control.
 100         @param bPageCaption
 101                 TRUE if a caption should be displayed for each page. The caption
 102                 contains the page title and an icon if specified with the page.
 103                 Ignored if bTreeViewMode is FALSE.
 104         @param bTreeImages
 105                 TRUE if the page icons should be displayed in the page tree,
 106                 FALSE if there should be no icons in the page tree. Ignored if
 107                 bTreeViewMode is FALSE. If not all of your pages are containing
 108                 icons, or if there will be empty pages (parent nodes without a
 109                 related page, you need to call SetTreeDefaultImages() to avoid
 110                 display errors.
 111
 112         @return
 113                 TRUE on success or FALSE, if the window has already been created.
 114         */
 115         BOOL SetTreeViewMode(BOOL bTreeViewMode = TRUE, BOOL bPageCaption = FALSE, BOOL bTreeImages = FALSE);
 116
 117         /**
 118         Specifies the width of the tree control, when the sheet is in tree
 119         view mode. The default value (if this method is not called) is 150
 120         pixels.
 121
 122         This method needs to be called, before DoModeal() or Create().
 123         Otherwise it will fail.
 124
 125         @param nWidth
 126                 The width in pixels for the page tree.
 127
 128         @return
 129                 TRUE on success, FALSE otherwise (if the window has already been
 130                 created).
 131         */
 132         BOOL SetTreeWidth(int nWidth);
 133
 134         /**
 135         Specifies the text to be drawn on empty pages (pages for tree view
 136         items, that are not related to a page, because they are only
 137         parents for other items). This is only needed in tree view mode.
 138
 139         The specified text can contains a single "%s" placeholder which
 140         will be replaced with the title of the empty page.
 141         */
 142         void SetEmptyPageText(LPCTSTR lpszEmptyPageText);
 143
 144         /**
 145         Allows you to specify, how the empty page message (see
 146         SetEmptyPageText()) should be drawn.
 147
 148         @param dwFormat
 149                 A combination of the DT_* flags available for the Win32-API
 150                 function DrawText(), that should be used to draw the text.
 151                 The default value is:
 152                 \code
 153                 DT_CENTER|DT_VCENTER|DT_NOPREFIX|DT_SINGLELINE
 154                 \endcode
 155
 156         @return
 157                 The previous format.
 158         */
 159         DWORD SetEmptyPageTextFormat(DWORD dwFormat);
 160
 161         //@{
 162         /**
 163         Defines the images, that should be used for pages without icons and
 164         for empty parent nodes. The list contains exactly to images:
 165         1. An image that should be used for parent tree nodes, without a
 166            page asignd.
 167         2. An image that should be used for pages, which are not specifying
 168            any icons.
 169         Standard image size is 16x16 Pixels, but if you call this method
 170         before creating the sheet, the size of image 0 in this list will
 171         be assumed as your preferred image size and all other icons must
 172         have the same size.
 173
 174         @param pImages
 175                 Pointer to an image list with exactly to images, that should be
 176                 used as default images. The images are copied to an internal
 177                 list, so that the given list can be deleted after this call.
 178         @param unBitmapID
 179                 Resource identifier for the bitmap, that contains the default
 180                 images. The resource should contain exactly to images.
 181         @param cx
 182                 Width of a singe image in pixels.
 183         @param crMask
 184                 Color that should be interpreted as transparent.
 185
 186         @return
 187                 TRUE on success, FALSE otherwise.
 188         */
 189         BOOL SetTreeDefaultImages(CImageList *pImages);
 190         BOOL SetTreeDefaultImages(UINT unBitmapID, int cx, COLORREF crMask);
 191         //@}
 192
 193         /**
 194         Returns a pointer to the tree control, when the sheet is in
 195         tree view mode, NULL otherwise.
 196         */
 197         CTreeCtrl* GetPageTreeControl();
 198
 199 // Public helpers
 200 public:
 201         //@{
 202         /**
 203         This helper allows you to easily set the icon of a property page.
 204
 205         This static method does nothing more, than extracting the specified
 206         image as an icon from the given image list and assign the
 207         icon-handle to the hIcon property of the pages PROPSHEETPAGE
 208         structure (m_psp) and modify the structures flags, so that the
 209         image will be recognized.
 210
 211         You need to call this method for a page, before adding the page
 212         to a property sheet.
 213
 214         @important
 215         If you are using the CImageList-version, you are responsible for
 216         destroying the extracted icon with DestroyIcon() or the static
 217         DestroyPageIcon() method.
 218
 219         @see DestroyPageIcon()
 220
 221         @param pPage
 222                 Property page to set the image for.
 223         @param hIcon
 224                 Handle to icon that should be set for the page.
 225         @param unIconId
 226                 Ressource identifier for the icon to set.
 227         @param Images
 228                 Reference of the image list to extract the icon from.
 229         @param nImage
 230                 Zero based index of the image in pImages, that should be used
 231                 as an icon.
 232
 233         @return
 234                 TRUE on success, FALSE if an error occured.
 235         */
 236         static BOOL SetPageIcon(CPropertyPage *pPage, HICON hIcon);
 237         static BOOL SetPageIcon(CPropertyPage *pPage, UINT unIconId);
 238         static BOOL SetPageIcon(CPropertyPage *pPage, CImageList &Images, int nImage);
 239         //@}
 240
 241         /**
 242         Checks, if the PSP_USEHICON flag is set in the PROPSHEETPAGE struct;
 243         If this is the case, the flag will be removed and the icon
 244         specified by the hIcon attribute of the PROPSHEETPAGE struct will
 245         be destroyed using DestroyIcon().
 246
 247         @note
 248         You only have to call DestroyIcon() for icons, that have been
 249         created using CreateIconIndirect() (i.e. used by
 250         CImageList::ExtractIcon()).
 251
 252         @return
 253                 TRUE on success, FALSE if the PSP_USEHICON flag was not set or
 254                 if the icon handle was NULL.
 255         */
 256         static BOOL DestroyPageIcon(CPropertyPage *pPage);
 257
 258 // Overridable implementation helpers
 259 protected:
 260         /**
 261         Will be called to generate the message, that should be displayed on
 262         an empty page, when the sheet is in tree view mode
 263
 264         This default implementation simply returns lpszEmptyPageMessage
 265         with the optional "%s" placeholder replaced by lpszCaption.
 266
 267         @param lpszEmptyPageMessage
 268                 The string, set by SetEmptyPageMessage(). This string may contain
 269                 a "%s" placeholder.
 270         @param lpszCaption
 271                 The title of the empty page.
 272         */
 273         virtual CString GenerateEmptyPageMessage(LPCTSTR lpszEmptyPageMessage, LPCTSTR lpszCaption);
 274
 275         /**
 276         Will be called during creation process, to create the CTreeCtrl
 277         object (the object, not the window!).
 278
 279         Allows you to inject your own CTreeCtrl-derived classes.
 280
 281         This default implementation simply creates a CTreeCtrl with new
 282         and returns it.
 283         */
 284         virtual CTreeCtrl* CreatePageTreeObject();
 285
 286         /**
 287         Will be called during creation process, to create the object, that
 288         is responsible for drawing the frame around the pages, drawing the
 289         empty page message and the caption.
 290
 291         Allows you to inject your own CPropPageFrame-derived classes.
 292
 293         This default implementation simply creates a CPropPageFrameTab with
 294         new and returns it.
 295         */
 296         virtual CPropPageFrame* CreatePageFrame();
 297
 298 // Implementation helpers
 299 protected:
 300         /**
 301         Moves all childs by the specified amount of pixels.
 302
 303         @param nDx
 304                 Pixels to move the childs in horizontal direction (can be
 305                 negative).
 306         @param nDy
 307                 Pixels to move the childs in vertical direction (can be
 308                 negative).
 309         */
 310         void MoveChildWindows(int nDx, int nDy);
 311
 312         /**
 313         Refills the tree that contains the entries for the several pages.
 314         */
 315         void RefillPageTree();
 316
 317         /**
 318         Creates the specified path in the page tree and returns the handle
 319         of the most child item created.
 320
 321         @param lpszPath
 322                 Path of the item to create (see description of this class).
 323         @param hParentItem
 324                 Handle of the item under which the path should be created or
 325                 TVI_ROOT to start from the root.
 326         */
 327         HTREEITEM CreatePageTreeItem(LPCTSTR lpszPath, HTREEITEM hParent = TVI_ROOT);
 328
 329         /**
 330         Splits the given path into the topmost item and the rest. See
 331         description of this class for detailed path information.
 332
 333         I.e. when given the string "Appearance::Toolbars::Customize", the
 334         method will return "Appearance" and after the call strRest will
 335         be "Toolbars::Customize".
 336         */
 337         CString SplitPageTreePath(CString &strRest);
 338
 339         /**
 340         Tries to deactivate the current page, and hides it if successfull,
 341         so that an empty page becomes visible.
 342
 343         @return
 344                 TRUE if the current page has been deactivated successfully,
 345                 FALSE if the currently active page prevents a page change.
 346         */
 347         BOOL KillActiveCurrentPage();
 348
 349         /**
 350         Returns the page tree item, that representates the specified page
 351         or NULL, if no such icon exists.
 352
 353         @param nPage
 354                 Zero based page index, for which the item to retrieve.
 355         @param hRoot
 356                 Item to start the search at or TVI_ROOT to search the whole
 357                 tree.
 358         */
 359         HTREEITEM GetPageTreeItem(int nPage, HTREEITEM hRoot = TVI_ROOT);
 360
 361         /**
 362         Selects and shows the item, representing the specified page.
 363
 364         @param nPage
 365                 Zero based page index.
 366
 367         @return
 368                 TRUE on success, FALSE if no item does exist for the specified
 369                 page.
 370         */
 371         BOOL SelectPageTreeItem(int nPage);
 372
 373         /**
 374         Selects and shows the tree item for the currently active page.
 375
 376         @return
 377                 TRUE on success, FALSE if no item exists for the currently active
 378                 page or if it was not possible to get information about the
 379                 currently active page.
 380         */
 381         BOOL SelectCurrentPageTreeItem();
 382
 383         /**
 384         Updates the caption for the currently selected page (if the caption
 385         is enabled).
 386         */
 387         void UpdateCaption();
 388
 389         /**
 390         Activates the previous page in the page order or the last one, if
 391         the current one is the first.
 392
 393         This method does never fail.
 394         */
 395         void ActivatePreviousPage();
 396
 397         /**
 398         Activates the next page in the page order or the first one, if the
 399         current one is the last.
 400
 401         This method does never fail.
 402         */
 403         void ActivateNextPage();
 404
 405 // Overridings
 406 protected:
 407         //{{AFX_VIRTUAL(CTreePropSheet)
 408         public:
 409         virtual BOOL OnInitDialog();
 410         //}}AFX_VIRTUAL
 411
 412 // Message handlers
 413 protected:
 414         //{{AFX_MSG(CTreePropSheet)
 415         afx_msg void OnDestroy();
 416         //}}AFX_MSG
 417         afx_msg LRESULT OnAddPage(WPARAM wParam, LPARAM lParam);
 418         afx_msg LRESULT OnRemovePage(WPARAM wParam, LPARAM lParam);
 419         afx_msg LRESULT OnSetCurSel(WPARAM wParam, LPARAM lParam);
 420         afx_msg LRESULT OnSetCurSelId(WPARAM wParam, LPARAM lParam);
 421         afx_msg LRESULT OnIsDialogMessage(WPARAM wParam, LPARAM lParam);
 422
 423         afx_msg void OnPageTreeSelChanging(NMHDR *pNotifyStruct, LRESULT *plResult);
 424         afx_msg void OnPageTreeSelChanged(NMHDR *pNotifyStruct, LRESULT *plResult);
 425         DECLARE_MESSAGE_MAP()
 426
 427 // Properties
 428 private:
 429         /** TRUE if we should use the tree control instead of the tab ctrl. */
 430         BOOL m_bTreeViewMode;
 431
 432         /** The tree control */
 433         CTreeCtrl *m_pwndPageTree;
 434
 435         /** The frame around the pages */
 436         CPropPageFrame *m_pFrame;
 437
 438         /**
 439         TRUE, if a tree item selection by OnPageTreeSelChanged() is
 440         performed currently.
 441         */
 442         BOOL m_bPageTreeSelChangedActive;
 443
 444         /** TRUE if a page caption should be displayed, FALSE otherwise. */
 445         BOOL m_bPageCaption;
 446
 447         /** TRUE if images should be displayed in the tree. */
 448         BOOL m_bTreeImages;
 449
 450         /** Images to be displayed in the tree control. */
 451         CImageList m_Images;
 452
 453         /** Default images. */
 454         CImageList m_DefaultImages;
 455
 456         /**
 457         Message to be displayed on empty pages. May contain a "%s"
 458         placeholder which will be replaced by the caption of the empty
 459         page.
 460         */
 461         CString m_strEmptyPageMessage;
 462
 463         /** The width of the page tree control in pixels. */
 464         int m_nPageTreeWidth;
 465
 466 // Static Properties
 467 private:
 468         /** The id of the tree view control, that shows the pages. */
 469         static const UINT s_unPageTreeId;
 470 };
 471
 472
 473 } //namespace TreePropSheet
 474
 475 /////////////////////////////////////////////////////////////////////////////
 476
 477 //{{AFX_INSERT_LOCATION}}
 478 // Microsoft Visual C++ fügt unmittelbar vor der vorhergehenden Zeile zusätzliche Deklarationen ein.
 479
 480 #endif // AFX_TREEPROPSHEET_H__50695CFB_FCE4_4188_ADB4_BF05A5488E41__INCLUDED_