1 /********************************************************************
3 * Copyright (c) 2002 Sven Wiegand <mail@sven-wiegand.de>
5 * You can use this and modify this in any way you want,
6 * BUT LEAVE THIS HEADER INTACT.
8 * Redistribution is appreciated.
18 *********************************************************************/
21 #if !defined(AFX_TREEPROPSHEET_H__50695CFB_FCE4_4188_ADB4_BF05A5488E41__INCLUDED_)
22 #define AFX_TREEPROPSHEET_H__50695CFB_FCE4_4188_ADB4_BF05A5488E41__INCLUDED_
26 #endif // _MSC_VER > 1000
28 #include "PropPageFrame.h"
31 namespace TreePropSheet
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.
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")
48 the tree would look as follow:
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 ("\\::").
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
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().
77 class /*AFX_EXT_CLASS*/ CTreePropSheet
: public CPropertySheet
79 DECLARE_DYNAMIC(CTreePropSheet
)
81 // Construction/Destruction
84 CTreePropSheet(UINT nIDCaption
, CWnd
* pParentWnd
= NULL
, UINT iSelectPage
= 0);
85 CTreePropSheet(LPCTSTR pszCaption
, CWnd
* pParentWnd
= NULL
, UINT iSelectPage
= 0);
86 virtual ~CTreePropSheet();
91 Call this method, if you would like to use a tree control to browse
92 the pages, instead of the tab control.
94 This method needs to becalled, before DoModal() or Create(). If the
95 window has already been created, the method will fail.
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.
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.
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
113 TRUE on success or FALSE, if the window has already been created.
115 BOOL
SetTreeViewMode(BOOL bTreeViewMode
= TRUE
, BOOL bPageCaption
= FALSE
, BOOL bTreeImages
= FALSE
);
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
122 This method needs to be called, before DoModeal() or Create().
123 Otherwise it will fail.
126 The width in pixels for the page tree.
129 TRUE on success, FALSE otherwise (if the window has already been
132 BOOL
SetTreeWidth(int nWidth
);
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.
139 The specified text can contains a single "%s" placeholder which
140 will be replaced with the title of the empty page.
142 void SetEmptyPageText(LPCTSTR lpszEmptyPageText
);
145 Allows you to specify, how the empty page message (see
146 SetEmptyPageText()) should be drawn.
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:
153 DT_CENTER|DT_VCENTER|DT_NOPREFIX|DT_SINGLELINE
159 DWORD
SetEmptyPageTextFormat(DWORD dwFormat
);
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
167 2. An image that should be used for pages, which are not specifying
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
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.
179 Resource identifier for the bitmap, that contains the default
180 images. The resource should contain exactly to images.
182 Width of a singe image in pixels.
184 Color that should be interpreted as transparent.
187 TRUE on success, FALSE otherwise.
189 BOOL
SetTreeDefaultImages(CImageList
*pImages
);
190 BOOL
SetTreeDefaultImages(UINT unBitmapID
, int cx
, COLORREF crMask
);
194 Returns a pointer to the tree control, when the sheet is in
195 tree view mode, NULL otherwise.
197 CTreeCtrl
* GetPageTreeControl();
203 This helper allows you to easily set the icon of a property page.
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.
211 You need to call this method for a page, before adding the page
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.
219 @see DestroyPageIcon()
222 Property page to set the image for.
224 Handle to icon that should be set for the page.
226 Ressource identifier for the icon to set.
228 Reference of the image list to extract the icon from.
230 Zero based index of the image in pImages, that should be used
234 TRUE on success, FALSE if an error occured.
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
);
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().
248 You only have to call DestroyIcon() for icons, that have been
249 created using CreateIconIndirect() (i.e. used by
250 CImageList::ExtractIcon()).
253 TRUE on success, FALSE if the PSP_USEHICON flag was not set or
254 if the icon handle was NULL.
256 static BOOL
DestroyPageIcon(CPropertyPage
*pPage
);
258 // Overridable implementation helpers
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
264 This default implementation simply returns lpszEmptyPageMessage
265 with the optional "%s" placeholder replaced by lpszCaption.
267 @param lpszEmptyPageMessage
268 The string, set by SetEmptyPageMessage(). This string may contain
271 The title of the empty page.
273 virtual CString
GenerateEmptyPageMessage(LPCTSTR lpszEmptyPageMessage
, LPCTSTR lpszCaption
);
276 Will be called during creation process, to create the CTreeCtrl
277 object (the object, not the window!).
279 Allows you to inject your own CTreeCtrl-derived classes.
281 This default implementation simply creates a CTreeCtrl with new
284 virtual CTreeCtrl
* CreatePageTreeObject();
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.
291 Allows you to inject your own CPropPageFrame-derived classes.
293 This default implementation simply creates a CPropPageFrameTab with
296 virtual CPropPageFrame
* CreatePageFrame();
298 // Implementation helpers
301 Moves all childs by the specified amount of pixels.
304 Pixels to move the childs in horizontal direction (can be
307 Pixels to move the childs in vertical direction (can be
310 void MoveChildWindows(int nDx
, int nDy
);
313 Refills the tree that contains the entries for the several pages.
315 void RefillPageTree();
318 Creates the specified path in the page tree and returns the handle
319 of the most child item created.
322 Path of the item to create (see description of this class).
324 Handle of the item under which the path should be created or
325 TVI_ROOT to start from the root.
327 HTREEITEM
CreatePageTreeItem(LPCTSTR lpszPath
, HTREEITEM hParent
= TVI_ROOT
);
330 Splits the given path into the topmost item and the rest. See
331 description of this class for detailed path information.
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".
337 CString
SplitPageTreePath(CString
&strRest
);
340 Tries to deactivate the current page, and hides it if successfull,
341 so that an empty page becomes visible.
344 TRUE if the current page has been deactivated successfully,
345 FALSE if the currently active page prevents a page change.
347 BOOL
KillActiveCurrentPage();
350 Returns the page tree item, that representates the specified page
351 or NULL, if no such icon exists.
354 Zero based page index, for which the item to retrieve.
356 Item to start the search at or TVI_ROOT to search the whole
359 HTREEITEM
GetPageTreeItem(int nPage
, HTREEITEM hRoot
= TVI_ROOT
);
362 Selects and shows the item, representing the specified page.
365 Zero based page index.
368 TRUE on success, FALSE if no item does exist for the specified
371 BOOL
SelectPageTreeItem(int nPage
);
374 Selects and shows the tree item for the currently active page.
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.
381 BOOL
SelectCurrentPageTreeItem();
384 Updates the caption for the currently selected page (if the caption
387 void UpdateCaption();
390 Activates the previous page in the page order or the last one, if
391 the current one is the first.
393 This method does never fail.
395 void ActivatePreviousPage();
398 Activates the next page in the page order or the first one, if the
399 current one is the last.
401 This method does never fail.
403 void ActivateNextPage();
407 //{{AFX_VIRTUAL(CTreePropSheet)
409 virtual BOOL
OnInitDialog();
414 //{{AFX_MSG(CTreePropSheet)
415 afx_msg
void OnDestroy();
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
);
423 afx_msg
void OnPageTreeSelChanging(NMHDR
*pNotifyStruct
, LRESULT
*plResult
);
424 afx_msg
void OnPageTreeSelChanged(NMHDR
*pNotifyStruct
, LRESULT
*plResult
);
425 DECLARE_MESSAGE_MAP()
429 /** TRUE if we should use the tree control instead of the tab ctrl. */
430 BOOL m_bTreeViewMode
;
432 /** The tree control */
433 CTreeCtrl
*m_pwndPageTree
;
435 /** The frame around the pages */
436 CPropPageFrame
*m_pFrame
;
439 TRUE, if a tree item selection by OnPageTreeSelChanged() is
442 BOOL m_bPageTreeSelChangedActive
;
444 /** TRUE if a page caption should be displayed, FALSE otherwise. */
447 /** TRUE if images should be displayed in the tree. */
450 /** Images to be displayed in the tree control. */
453 /** Default images. */
454 CImageList m_DefaultImages
;
457 Message to be displayed on empty pages. May contain a "%s"
458 placeholder which will be replaced by the caption of the empty
461 CString m_strEmptyPageMessage
;
463 /** The width of the page tree control in pixels. */
464 int m_nPageTreeWidth
;
468 /** The id of the tree view control, that shows the pages. */
469 static const UINT s_unPageTreeId
;
473 } //namespace TreePropSheet
475 /////////////////////////////////////////////////////////////////////////////
477 //{{AFX_INSERT_LOCATION}}
478 // Microsoft Visual C++ fügt unmittelbar vor der vorhergehenden Zeile zusätzliche Deklarationen ein.
480 #endif // AFX_TREEPROPSHEET_H__50695CFB_FCE4_4188_ADB4_BF05A5488E41__INCLUDED_