CMFCPropertySheet Class
The latest version of this topic can be found at CMFCPropertySheet Class.
The CMFCPropertySheet
class supports a property sheet where each property page is denoted by a page tab, a toolbar button, a tree control node, or a list item.
class CMFCPropertySheet : public CPropertySheet
Name | Description |
---|---|
CMFCPropertySheet::CMFCPropertySheet | Constructs a CMFCPropertySheet object. |
CMFCPropertySheet::~CMFCPropertySheet |
Destructor. |
Name | Description |
---|---|
CMFCPropertySheet::AddPage | Adds a page to the property sheet. |
CMFCPropertySheet::AddPageToTree | Adds a new property page to the tree control. |
CMFCPropertySheet::AddTreeCategory | Adds a new node to the tree control. |
CMFCPropertySheet::EnablePageHeader | Reserves space at the top of each page to draw a custom header. |
CMFCPropertySheet::GetHeaderHeight | Retrieves the height of the current header. |
CMFCPropertySheet::GetLook | Retrieves an enumeration value that specifies the appearance of the current property sheet. |
CMFCPropertySheet::GetNavBarWidth | Retries the width of the navigation bar in pixels. |
CMFCPropertySheet::GetTab | Retrieves the internal tab control object that supports the current property sheet control. |
CMFCPropertySheet::GetThisClass |
Used by the framework to obtain a pointer to the CRuntimeClass object that is associated with this class type. |
CMFCPropertySheet::InitNavigationControl | Initializes the appearance of the current property sheet control. |
CMFCPropertySheet::OnActivatePage | Called by the framework when a property page is enabled. |
CMFCPropertySheet::OnDrawPageHeader | Called by the framework to draw a custom property page header. |
CMFCPropertySheet::OnInitDialog |
Handles the WM_INITDIALOG message. (Overrides CPropertySheet::OnInitDialog.) |
CMFCPropertySheet::OnRemoveTreePage | Called by the framework to remove a property page from a tree control. |
CMFCPropertySheet::PreTranslateMessage |
Translates window messages before they are dispatched to the TranslateMessage and DispatchMessage Windows functions. (Overrides CPropertySheet::PreTranslateMessage .) |
CMFCPropertySheet::RemoveCategory | Removes a node from the tree control. |
CMFCPropertySheet::RemovePage | Removes a property page from the property sheet. |
CMFCPropertySheet::SetIconsList | Specifies the list of images that are used in the navigation control of the Outlook pane. |
CMFCPropertySheet::SetLook | Specifies the appearance of the property sheet. |
The CMFCPropertySheet
class represents property sheets, also known as tab dialog boxes. The CMFCPropertySheet
class can display a property page in a variety of ways.
Perform the following steps to use the CMFCPropertySheet
class in your application:
Derive a class from the
CMFCPropertySheet
class and name the class, for example, CMyPropertySheet.Construct a CMFCPropertyPage object for each property page.
Call the CMFCPropertySheet::SetLook method in the CMyPropertySheet constructor. A parameter of that method specifies that property pages shall be displayed either as tabs along the top or left of the property sheet; tabs in the style of a Microsoft OneNote property sheet; buttons on a Microsoft Outlook toolbar control; nodes on a tree control; or as a list of items on the left side of the property sheet.
If you create a property sheet in the style of a Microsoft Outlook toolbar, call the CMFCPropertySheet::SetIconsList method to associate an image list together with the property pages.
Call the CMFCPropertySheet::AddPage method for each property page.
Create a
CMFCPropertySheet
control and call itsDoModal
method.
The following illustration depicts a property sheet that is in the style of an embedded Microsoft Outlook toolbar. The Outlook toolbar appears on the left side of the property sheet.
The following illustration depicts a property sheet that contains a CMFCPropertyGridCtrl Class object. That object is a property sheet in the style of a standard common controls property sheet.
The following illustration depicts a property sheet that is in the style of a tree control.
Header: afxpropertysheet.h
Adds a page to the property sheet.
void AddPage(CPropertyPage* pPage);
[in] pPage
Pointer to a page object. This parameter cannot be NULL
.
This method adds the specified property page as the rightmost tab in the property sheet. Therefore, use this method to add pages in left-to-right order.
If the property sheet is in the style of Microsoft Outlook, the framework displays a list of navigation buttons at the left of the property sheet. After this method adds a property page, it adds a corresponding button to the list. To display a property page, click its corresponding button. For more information about styles of property sheets, see CMFCPropertySheet::SetLook.
Adds a new property page to the tree control.
void AddPageToTree(
CMFCPropertySheetCategoryInfo* pCategory,
CMFCPropertyPage* pPage,
int nIconNum=-1,
int nSelIconNum=-1);
[in] pCategory
Pointer to a parent tree node, or NULL
to associate the specified page with the top-level node. Call the CMFCPropertySheet::AddTreeCategory method to obtain this pointer.
[in] pPage
Pointer to a property page object.
[in] nIconNum
Zero-based index of an icon, or -1 if no icon is used. The icon is displayed next to the tree control property page when the page is not selected. The default value is -1.
[in] nSelIconNum
Zero-based index of an icon, or -1 if no icon is used. The icon is displayed next to the tree control property page when the page is selected. The default value is -1.
This method adds a property page as a leaf of a tree control. To add a property page, create a CMFCPropertySheet
object, call the CMFCPropertySheet::SetLook method with the look
parameter set to CMFCPropertySheet::PropSheetLook_Tree
, and then use this method to add the property page.
Adds a new node to the tree control.
CMFCPropertySheetCategoryInfo* AddTreeCategory(
LPCTSTR lpszLabel,
int nIconNum=-1,
int nSelectedIconNum=-1,
const CMFCPropertySheetCategoryInfo* pParentCategory=NULL);
[in] lpszLabel
The name of the node.
[in] nIconNum
Zero-based index of an icon, or -1 if no icon is used. The icon is displayed next to the tree control property page when the page is not selected. The default value is -1.
[in] nSelectedIconNum
Zero-based index of an icon, or -1 if no icon is used. The icon is displayed next to the tree control property page when the page is selected. The default value is -1.
[in] pParentCategory
Pointer to a parent tree node, or NULL
to associate the specified page with the top-level node. Set this parameter with the CMFCPropertySheet::AddTreeCategory method.
A pointer to the new node in the tree control.
Use this method to add a new node, which is also referred to as a category, to the tree control. To add a node, create a CMFCPropertySheet
object, call the CMFCPropertySheet::SetLook method with the look
parameter set to CMFCPropertySheet::PropSheetLook_Tree
, and then use this method to add the node.
Use the return value of this method in subsequent calls to CMFCPropertySheet::AddPageToTree and CMFCPropertySheet::AddTreeCategory.
Constructs a CMFCPropertySheet
object.
CMFCPropertySheet(
UINT nIDCaption,
CWnd* pParentWnd=NULL,
UINT iSelectPage=0);
CMFCPropertySheet(
LPCTSTR pszCaption,
CWnd* pParentWnd=NULL,
UINT iSelectPage=0);
[in] pszCaption
A string that contains the property sheet caption. Cannot be NULL
.
[in] nIDCaption
A resource ID that contains the property sheet caption.
[in] pParentWnd
Pointer to the parent window of the property sheet, or NULL
if the parent window is the main window of the application. The default value is NULL
.
[in] iSelectPage
The zero-based index of the top property page. The default value is 0.
For more information, see the parameters for the CPropertySheet::CPropertySheet constructor.
Reserves space at the top of each page to draw a custom header.
void EnablePageHeader(int nHeaderHeight);
[in] nHeaderHeight
The height of the header, in pixels.
To use the value of the nHeaderHeight
parameter to draw a custom header, override the CMFCPropertySheet::OnDrawPageHeader method.
Retrieves the height of the current header.
int GetHeaderHeight() const;
The height of the header, in pixels.
Call the CMFCPropertySheet::EnablePageHeader method before you call this method.
Retrieves an enumeration value that specifies the appearance of the current property sheet.
PropSheetLook GetLook() const;
One of the enumeration values that specifies the appearance of the property sheet. For a list of possible values, see the enumeration table in the Remarks section of CMFCPropertySheet::SetLook.
Gets the width of the navigation bar.
int GetNavBarWidth() const;
The width of the navigation bar in pixels.
Retrieves the internal tab control object that supports the current property sheet control.
CMFCTabCtrl& GetTab() const;
An internal tab control object.
You can set a property sheet so that it appears in different styles, such as a tree control, a list of navigation buttons, or a set of tabbed pages.
Before you call this method, call the CMFCPropertySheet::SetLook method to set the appearance of the property sheet control. Then call the CMFCPropertySheet::InitNavigationControl method to initialize the internal tab control object. Use this method to retrieve the tab control object and then use that object to work with the tabs on the property sheet.
This method asserts in debug mode if the property sheet control is not set to appear in the style of Microsoft OneNote.
Initializes the appearance of the current property sheet control.
virtual CWnd* InitNavigationControl();
A pointer to the window of the property sheet control.
A property sheet control can appear in several different forms, such as a set of tabbed pages, a tree control, or a list of navigation buttons. Use the CMFCPropertySheet::SetLook method to specify the appearance of the property sheet control.
Called by the framework when a property page is enabled.
virtual void OnActivatePage(CPropertyPage* pPage);
[in] pPage
Pointer to a property page object that represents the enabled property page.
By default, this method ensures that the enabled property page is scrolled into view. If the style of the current property sheet contains a Microsoft Outlook pane, this method sets the corresponding Outlook button to the checked state.
Called by the framework to draw the header for a custom property page.
virtual void OnDrawPageHeader(
CDC* pDC,
int nPage,
CRect rectHeader);
[in] pDC
Pointer to a device context.
[in] nPage
The zero-based property page number.
[in] rectHeader
A bounding rectangle that specifies where to draw the header.
By default, this method does nothing. If you override this method, call the CMFCPropertySheet::EnablePageHeader method before the framework calls this method.
Called by the framework to remove a property page from a tree control.
virtual BOOL OnRemoveTreePage(CPropertyPage* pPage);
[in] pPage
Pointer to a property page object that represents the property page to remove.
TRUE
if this method is successful; otherwise, FALSE
.
Removes a node from the tree control.
void RemoveCategory(CMFCPropertySheetCategoryInfo* pCategory);
[in] pCategory
Pointer to a category (node) to remove.
Use this method to remove a node, which is also referred to as a category, from a tree control. Use the CMFCPropertySheet::AddTreeCategory method to add a node to a tree control.
Removes a property page from the property sheet.
void RemovePage(CPropertyPage* pPage);
void RemovePage(int nPage);
```
### Parameters
[in] `pPage`
Pointer to property page object that represents the property page to remove. Cannot be `NULL`.
[in] `nPage`
Zero-based index of the page to remove.
### Remarks
This method removes the specified property page and destroys its associated window. The property page object that the `pPage` parameter specifies is not destroyed until the [CMFCPropertySheet](../Topic/CMFCPropertySheet%20Class.md) window is closed.
## <a name="cmfcpropertysheet__seticonslist"></a> CMFCPropertySheet::SetIconsList
Specifies the list of images that are used in the navigation control of the Outlook pane.
BOOL SetIconsList( UINT uiImageListResID,
int cx,
COLORREF clrTransparent=RGB(255, 0, 255)); void SetIconsList(HIMAGELIST hIcons); ```
[in] uiImageListResID
The resource ID of an image list.
[in] cx
The width, in pixels, of icons in the image list.
[in] clrTransparent
The transparent image color. The parts of the image that are this color will be transparent. The default value is the color magenta, RGB(255,0,255).
[in] hIcons
A handle to an existing image list.
In the first method overload syntax, TRUE
if this method is successful; otherwise, FALSE
.
If the property sheet is in the style of Microsoft Outlook, the framework displays a list of navigation buttons, called the Outlook pane control, at the left of the property sheet. Use this method to set the image list to be used by the Outlook pane control.
For more information about the methods that support this method, see CImageList::Create and CImageList::Add. For more information about how to set the style of a property sheet, see CMFCPropertySheet::SetLook.
Specifies the appearance of the property sheet.
void SetLook(
PropSheetLook look,
int nNavControlWidth=100);
[in] look
One of the enumeration values that specifies the appearance of the property sheet. The default style for a property sheet is CMFCPropertySheet::PropSheetLook_Tabs
. For more information, see the table in the Remarks section of this topic.
[in] nNavControlWidth
The width of the navigation control, in pixels. The default value is 100.
To display a property sheet in a style other than the default, call this method before you create the property sheet window.
The following table lists the enumeration values that can be specified in the look
parameter.
Value | Description |
---|---|
CMFCPropertySheet::PropSheetLook_Tabs |
(Default) Displays a tab for each property page. Tabs are displayed at the top of the property sheet and are stacked if there are more tabs than will fit in a single row. |
CMFCPropertySheet::PropSheetLook_OutlookBar |
Displays a list of navigation buttons, in the style of the Microsoft Outlook bar, at the left side of the property sheet. Each button in the list corresponds to a property page. The framework displays scroll arrows if there are more buttons than will fit in the visible area of the list. |
CMFCPropertySheet::PropSheetLook_Tree |
Displays a tree control at the left side of the property sheet. Each parent or child node of the tree control corresponds to a property page. The framework displays scroll arrows if there are more nodes than will fit in the visible area of the tree control. |
CMFCPropertySheet::PropSheetLook_OneNoteTabs |
Displays a tab, in the style of Microsoft OneNote, for each property page. The framework displays tabs at the top of the property sheet and scroll arrows if there are more tabs than will fit in a single row. |
CMFCPropertySheet::PropSheetLook_List |
Displays a list at the left side of the property sheet. Each list item corresponds to a property page. The framework displays scroll arrows if there are more list items than will fit in the visible area of the list. |
Hierarchy Chart
Classes
CMFCPropertyPage Class
CMFCOutlookBar Class