PropSheet_RemovePage
Property Sheet Reference

PropSheet_RemovePage


VOID PropSheet_RemovePage(
    HWND hPropSheetDlg, 		
    int index, 		
    HPROPSHEETPAGE hpage		
);		

Removes a page from a property sheet. You can use this macro or send the PSM_REMOVEPAGE message explicitly.

hPropSheetDlg
Handle to the property sheet.
index and hpage
Zero-based index of the page and the handle to the page to remove, respectively. An application can specify the index or the handle, or both. If both are specified, hpage takes precedence.

PropSheet_RestartWindows

VOID PropSheet_RestartWindows(
    HWND hPropSheetDlg		
);		

Sends a PSM_RESTARTWINDOWS message indicating that Windows needs to be restarted for changes to take effect. You can use this macro or send the PSM_RESTARTWINDOWS message explicitly. An application should send the PSM_RESTARTWINDOWS message only in response to the PSN_APPLY or PSN_KILLACTIVE notification message.

hPropSheetDlg
Handle to the property sheet.

The PSM_RESTARTWINDOWS message causes the PropertySheet function to return the ID_PSRESTARTWINDOWS value, but only if the user clicks the OK button to close the property sheet. It is the application's responsibility to restart Windows, which can be done by using the ExitWindowsEx function.

PropSheet_SetCurSel

BOOL PropSheet_SetCurSel(
    HWND hPropSheetDlg, 		
    HPROPSHEETPAGE hpage, 		
    int index		
);		

Activates the specified page in a property sheet. You can use this macro or send the PSM_SETCURSEL message explicitly.

hPropSheetDlg
Handle to the property sheet.
index and hpage
Zero-based index of the page and the handle to the page to activate, respectively. An application can specify the index or the handle, or both. If both are specified, hpage takes precedence.

The window that is losing the activation receives the PSN_KILLACTIVE notification message, and the window that is gaining the activation receives the PSN_SETACTIVE notification message.

PropSheet_SetCurSelByID

BOOL PropSheet_SetCurSelByID(
    HWND hPropSheetDlg, 		
    int id		
);		

Activates the specified page in a property sheet based on the resource identifier of the page. You can use this macro or send the PSM_SETCURSELID message explicitly.

hPropSheetDlg
Handle to the property sheet.
id
Resource identifier of the page to activate.

The window that is losing the activation receives the PSN_KILLACTIVE notification message, and the window that is gaining the activation receives the PSN_SETACTIVE notification message.

PropSheet_SetFinishText

VOID PropSheet_SetFinishText(
    HWND hPropSheetDlg, 		
    LPTSTR lpszText		
);		

Sets the text of the Finish button in a wizard property sheet, shows and enables the button, and hides the Next and Back buttons. You can use this macro or send the PSM_SETFINISHTEXT message explicitly.

hPropSheetDlg
Handle to the property sheet.
lpszText
Address of the new text for the Finish button.

This macro causes the DM_SETDEFID message to be sent to the property sheet dialog box. The wParam parameter specifies the identifier of the Finish button.

PropSheet_SetTitle

VOID PropSheet_SetTitle(
    HWND hPropSheetDlg, 		
    DWORD dwStyle, 		
    LPTSTR lpszText		
);		

Sets the title of a property sheet. You can use this macro or send the PSM_SETTITLE message explicitly.

hPropSheetDlg
Handle to the property sheet.
dwStyle
Flag that indicates whether to include the prefix "Properties for" with the specified title string. If dwStyle is the PSH_PROPTITLE value, the prefix is included. Otherwise, the prefix is not used.
lpszText
Address of a buffer that contains the title string. If the high-order word of this parameter is NULL, the property sheet loads the string resource specified in the low-order word.

PropSheet_SetWizButtons

VOID PropSheet_SetWizButtons(
    HWND  hPropSheetDlg,
    DWORD dwFlags
);		

Posts the PSM_SETWIZBUTTONS message to a wizard property sheet. The PSM_SETWIZBUTTONS message enables or disables the Back, Next, and Finish buttons in a wizard property sheet. You can use this macro or use the PSM_SETWIZBUTTONS message explicitly.

hPropSheetDlg
Handle to the property sheet.
dwFlags
Specifies the buttons to display and enable. A wizard property sheet displays the Back button and either the Next or Finish button. This parameter can include the PSWIZB_BACK flag, which enables the Back button, and one of the following flags:
PSWIZB_NEXT Enables the Next button.
PSWIZB_FINISH Displays an enabled Finish button in place of the Next button.
PSWIZB_DISABLEDFINISH Displays a disabled Finish button in place of the Next button.

PropSheet_UnChanged

VOID PropSheet_UnChanged(hPropSheetDlg, hwndPage)
    HWND hPropSheetDlg, 		
    HWND hwndPage		
);		

Informs a property sheet that information in a page has reverted to the previously saved state. The property sheet disables the Apply Now button if no other pages have registered changes with the property sheet. You can use this macro or send the PSM_UNCHANGED message explicitly.

hPropSheetDlg
Handle to the property sheet.
hwndPage
Handle to the page that has reverted to the previously saved state.

Property Sheet Notification Messages

This section contains information about the notification messages used with property sheets.

PSN_APPLY

PSN_APPLY 
    lpnmhdr = (LPNMHDR) lParam; 

Indicates that the user clicked the OK or Apply Now button and wants all changes to take effect. This notification message is sent in the form of a WM_NOTIFY message.

lpnmhdr
Address of an NMHDR structure. The hwndFrom member is the handle to the property sheet.

To set the return value, the dialog box procedure for the page must use the SetWindowLong function with the DWL_MSGRESULT value, and the dialog box procedure must return TRUE.

A page should not call the EndDialog function when processing this notification message.

The property sheet is destroyed if the user clicks the OK button and the application returns the PSNRET_NOERROR value in response to this notification.

To receive this notification, a page must set the DWL_MSGRESULT value to FALSE in response the PSN_KILLACTIVE notification message.

The PSHNOTIFY structure is supplied with the PSN_APPLY notification message. The lParam member in this structure is TRUE if the user clicked the OK or Cancel button and is FALSE if the user clicked the Close button.

PSN_GETOBJECT

PSN_GETOBJECT
    lpnmon = (LPNMOBJECTNOTIFY) lParam;

Sent by a property sheet to request a drop target object when the cursor passes over one of the tab control's buttons.

lpnmon
Address of an NMOBJECTNOTIFY structure that, on entry, contains information about the notification. If this notification is processed, you must insert object information into this structure.

To provide an object, an application must set values in some members of the NMOBJECTNOTIFY structure at lpnmon. The pObject member must be set to a valid object pointer, and the hResult member must be set to a success flag. To comply with COM standards, always increment the object's reference count when providing an object pointer.

If an application does not provide an object, it must set pObject to NULL and hResult to a failure flag.

Version 4.71

PSN_HELP

PSN_HELP 
    lpnmhdr = (LPNMHDR) lParam; 

Notifies a page that the user has clicked the Help button. This notification message is sent in the form of a WM_NOTIFY message.

lpnmhdr
Address of an NMHDR structure. The hwndFrom member is the handle to the property sheet.

An application should display Help information for the page.

PSN_KILLACTIVE

PSN_KILLACTIVE 
    lpnmhdr = (LPNMHDR) lParam; 

Notifies a page that it is about to lose activation either because another page is being activated or the user has clicked the OK button. This notification message is sent in the form of a WM_NOTIFY message.

lpnmhdr
Address of an NMHDR structure. The hwndFrom member is the handle to the property sheet.

An application should validate the information the user has typed.

To set the return value, the dialog box procedure for the page must use the SetWindowLong function with the DWL_MSGRESULT value, and the dialog box procedure must return TRUE.

If the dialog box procedure sets DWL_MSGRESULT to TRUE, it should display a message box to explain the problem to the user.

PSN_QUERYCANCEL

PSN_QUERYCANCEL 
    lpnmhdr = (LPNMHDR) lParam; 

Indicates the user clicked the Cancel button. This notification message is sent in the form of a WM_NOTIFY message.

lpnmhdr
Address of an NMHDR structure. The hwndFrom member is the handle to the property sheet.

A property sheet page can use this notification message to ask the user to verify the cancel operation.

PSN_RESET

PSN_RESET 
    lpnmhdr = (LPNMHDR) lParam; 

Notifies a page that the user has clicked the Cancel button and the property sheet is about to be destroyed. All changes made since the user last clicked the Apply Now button are canceled. This notification message is sent in the form of a WM_NOTIFY message.

lpnmhdr
Address of an NMHDR structure. The hwndFrom member is the handle to the property sheet.

An application can use this notification message as an opportunity to perform cleanup operations.

A page should not call the EndDialog function when processing this notification message.

The PSHNOTIFY structure is supplied with the PSN_RESET notification message. The lParam member in this structure is TRUE if the user clicked the OK or Cancel button and is FALSE if the user clicked the Close button.

PSN_SETACTIVE

PSN_SETACTIVE 
    lpnmhdr = (LPNMHDR) lParam; 

Notifies a page that it is about to be activated. This notification message is sent in the form of a WM_NOTIFY message.

lpnmhdr
Address of the property sheet.

The PSN_SETACTIVE notification message is sent before the page is visible. An application can use this notification to initialize data in the page.

To set the return value, the dialog box procedure for the page must use the SetWindowLong function with the DWL_MSGRESULT value, and the dialog box procedure must return TRUE.

See also NMHDR

PSN_WIZBACK

PSN_WIZBACK 
    lpnmhdr = (LPNMHDR) lParam; 

Notifies a page that the user has clicked the Back button in a wizard property sheet. This notification message is sent in the form of a WM_NOTIFY message.

lpnmhdr
Address of an NMHDR structure. The hwndFrom member is the handle to the property sheet.

PSN_WIZFINISH

PSN_WIZFINISH 
    lpnmhdr = (LPNMHDR) lParam; 

Notifies a page that the user has clicked the Finish button in a wizard property sheet. This notification message is sent in the form of a WM_NOTIFY message.

lpnmhdr
Address of an NMHDR structure. The hwndFrom member is the handle to the property sheet.

PSN_WIZNEXT

PSN_WIZNEXT 
    lpnmhdr = (LPNMHDR) lParam; 

Notifies a page that the user has clicked the Next button in a wizard property sheet. This notification message is sent in the form of a WM_NOTIFY message.

lpnmhdr
Address of an NMHDR structure. The hwndFrom member is the handle to the property sheet.

Property Sheet Structures

This section contains information about the structures used with property sheets.

PROPSHEETHEADER

typedef struct _PROPSHEETHEADER {
    DWORD dwSize;
    DWORD dwFlags;
    HWND  hwndParent;
    HINSTANCE hInstance;
    union {
        HICON hIcon;
        LPCTSTR pszIcon;
        };
    LPCSTR pszCaption;
    UINT nPages;
    union {
        UINT nStartPage;
        LPCTSTR pStartPage;
        };
    union {
        LPCPROPSHEETPAGE ppsp;
        HPROPSHEETPAGE FAR *phpage;
        };
    PFNPROPSHEETCALLBACK pfnCallback;

#if (_WIN32_IE >= 0x0400)
    union {
        HBITMAP hbmWatermark;
        LPCTSTR pszbmWatermark;
        };
    HPALETTE hplWatermark;
    union {
        HBITMAP hbmHeader; 
        LPCSTR pszbmHeader;
        };
#endif
} PROPSHEETHEADER, FAR *LPPROPSHEETHEADER;

Defines the frame and pages of a property sheet.

dwSize
Size, in bytes, of this structure.
dwFlags
Flags that indicate which options to use when creating the property sheet page. This member can be a combination of the following values:
PSH_DEFAULT Uses the default meaning for all structure members.
PSH_HASHELP Displays the property sheet Help button. The Help button is enabled only when the PSP_HASHELP flag is set in the PROPSHEETPAGE structure for the active page. If any of the initial property sheet pages set the PSP_HASHELP flag, the Help button is automatically displayed regardless of the PSH_HASHELP flag. However, PSH_HASHELP is useful when none of the initial pages set PSP_HASHELP, but pages added later might.
PSH_HEADER Version 4.71. Indicates that a header bitmap will be used. If this value does not include PSH_USEHBMHEADER, the header bitmap is obtained from pszbmHeader. If this value includes PSH_USEHBMHEADER, the header bitmap is obtained from hbmHeader. This flag is ignored if PSH_WIZARD97 is not included.
PSH_MODELESS Causes the PropertySheet function to create the property sheet as a modeless dialog instead of as a modal dialog. When this flag is set, PropertySheet returns immediately after the dialog is created, and the return value from PropertySheet is the window handle to the property sheet dialog.
PSH_NOAPPLYNOW Removes the Apply Now button.
PSH_PROPSHEETPAGE Uses ppsp and ignores phpage when creating the pages for the property sheet.
PSH_PROPTITLE Displays the string "Properties for", followed by the string specified by pszCaption, in the title bar of the property sheet.
PSH_RTLREADING Displays the title of the property sheet dialog using right-to-left reading order on Hebrew or Arabic systems.
PSH_STRETCHWATERMARK Version 4.71. Stretches the bitmap to fit the background of the property sheet instead of tiling the watermark and/or header bitmap. This flag is ignored if PSH_WIZARD97 and PSH_WATERMARK or PSH_HEADER are not included.
PSH_USECALLBACK Calls the function specified by pfnCallback when initializing the property sheet defined by this structure.
PSH_USEHBMHEADER Version 4.71. Obtains the header bitmap from hbmHeader instead of pszbmHeader. This flag is ignored if PSH_WIZARD97 and PSH_HEADER are not included.
PSH_USEHBMWATERMARK Version 4.71. Obtains the watermark bitmap from hbmWatermark instead of pszbmWatermark. This flag is ignored if PSH_WIZARD97 and PSH_WATERMARK are not included.
PSH_USEHICON Uses hIcon as the small icon in the title bar of the property sheet dialog box.
PSH_USEHPLWATERMARK Version 4.71. Obtains the HPALETTE for drawing the watermark bitmap and/or header bitmap from hplWatermark instead of using the default palette. This flag is ignored if PSH_WIZARD97 and PSH_WATERMARK or PSH_HEADER are not included.
PSH_USEICONID Uses pszIcon as the name of the icon resource to load and use as the small icon in the title bar of the property sheet dialog box.
PSH_USEPAGELANG Version 4.71. The language for the property sheet will be taken from the first page's resource.
PSH_USEPSTARTPAGE Uses pStartPage and ignores nStartPage when displaying the initial page of the property sheet.
PSH_WATERMARK Version 4.71. Specifies that a watermark bitmap will be used. If this value does not include PSH_USEHBMWATERMARK, the watermark bitmap is obtained from pszbmWatermark. If this value includes PSH_USEHBMWATERMARK, the header bitmap is obtained from hbmWatermark. This flag is ignored if PSH_WIZARD97 is not included.
PSH_WIZARD Creates a wizard property sheet.
PSH_WIZARD97 Creates a wizard property sheet that allows a header and/or watermark bitmap to be displayed in the background. This and all Wizard 97-associated flags are not currently implemented.
PSH_WIZARDCONTEXTHELP Adds a system menu to the wizard property sheet. This flag is ignored if PSH_WIZARD or PSH_WIZARD97 is not included.
PSH_WIZARDHASFINISH Always displays the Finish button on the wizard. This flag is ignored if PSH_WIZARD or PSH_WIZARD97 is not included.
hwndParent
Handle to the property sheet's owner window.
hInstance
Handle to the instance from which to load the icon or title string resource. If pszIcon or pszCaption identifies a resource to load, this member must be specified.
hIcon
Handle to the icon to use as the small icon in the title bar of the property sheet dialog box. If dwFlags does not include PSH_USEHICON, this member is ignored.
pszIcon
Icon resource to use as the small icon in the title bar of the property sheet dialog box. This member can specify either the identifier of the icon resource or the address of the string that specifies the name of the icon resource. If dwFlags does not include PSH_USEICONID, this member is ignored.
pszCaption
Title of the property sheet dialog box. This member can specify either the identifier of a string resource or the address of a string that specifies the title. If dwFlags includes PSH_PROPTITLE, the string "Properties for" is inserted at the beginning of the title.
nPages
Number of elements in the phpage array.
nStartPage
Zero-based index of the initial page that appears when the property sheet dialog box is created.
pStartPage
Name of the initial page that appears when the property sheet dialog box is created. This member can specify either the identifier of a string resource or the address of a string that specifies the name.
ppsp
Address of an array of PROPSHEETPAGE structures that define the pages in the property sheet. If dwFlags does not include PSH_PROPSHEETPAGE, this member is ignored.
phpage
Address of an array of handles to the property sheet pages. Each handle must have been created by a previous call to the CreatePropertySheetPage function. If dwFlags includes PSH_PROPSHEETPAGE, this member is ignored.
pfnCallback
Address of an application-defined callback function that is called when the property sheet is initialized. For more information about the callback function, see the description of the PropSheetProc function. If dwFlags does not include PSH_USECALLBACK, this member is ignored.
hbmWatermark
Version 4.71. Handle to the watermark bitmap. If dwFlags does not include PSH_USEHBMWATERMARK, this member is ignored.
pszbmWatermark
Version 4.71. Bitmap resource to use as the watermark. This member can specify either the identifier of the bitmap resource or the address of the string that specifies the name of the bitmap resource. If dwFlags includes PSH_USEHBMWATERMARK, this member is ignored.
hplWatermark
Version 4.71. HPALETTE used for drawing the watermark bitmap and/or header bitmap. If dwFlags does not include PSH_USEHPLWATERMARK, this member is ignored.
hbmHeader
Version 4.71. Handle to the header bitmap. If dwFlags does not include PSH_USEHBMHEADER, this member is ignored.
pszbmHeader
Version 4.71. Bitmap resource to use as the header. This member can specify either the identifier of the bitmap resource or the address of the string that specifies the name of the bitmap resource. If dwFlags includes PSH_USEHBMHEADER, this member is ignored.

PROPSHEETPAGE

typedef struct _PROPSHEETPAGE {
    DWORD dwSize;
    DWORD dwFlags;
    HINSTANCE hInstance;
    union {
        LPCSTR pszTemplate;
        LPCDLGTEMPLATE pResource;
        };
    union {
        HICON hIcon;
        LPCSTR pszIcon;
        };
    LPCSTR pszTitle;
    DLGPROC pfnDlgProc;
    LPARAM lParam;
    LPFNPSPCALLBACK pfnCallback;
    UINT FAR * pcRefParent;

#if (_WIN32_IE >= 0x0400)
    LPCTSTR pszHeaderTitle;
    LPCTSTR pszHeaderSubTitle;
#endif
} PROPSHEETPAGE, FAR *LPPROPSHEETPAGE;

This structure defines a page in a property sheet.

dwSize
Size, in bytes, of this structure.
dwFlags
Flags that indicate which options to use when creating the property sheet page. This member can be a combination of the following values:
PSP_DEFAULT Uses the default meaning for all structure members.
PSP_DLGINDIRECT Creates the page from the dialog box template in memory pointed to by pResource. The PropertySheet function assumes that the template is in memory that can be written; a read-only template will cause an exception in some versions of Windows.
PSP_HASHELP Enables the property sheet Help button when this page is active.
PSP_HIDEHEADER Version 4.71. Causes the wizard property sheet to hide the header area when this page is selected.
PSP_PREMATURE Causes the page to be created when the property sheet is created. If this flag is not specified, the page will not be created until it is selected the first time.
PSP_RTLREADING When this page is active, displays the text of pszTitle using right-to-left reading order on Hebrew or Arabic systems.
PSP_USECALLBACK Calls the function specified by pfnCallback when creating or destroying the property sheet page defined by this structure.
PSP_USEHEADERSUBTITLE Version 4.71. Displays the text in pszHeaderSubTitle as the subtitle of the header area. This flag is ignored if PSP_HIDEHEADER is included or the dwFlags member of the PROPSHEETHEADER structure does not contain the PSH_WIZARD97 flag.
PSP_USEHEADERTITLE Version 4.71. Displays the text in pszHeaderTitle as the title of the header area. This flag is ignored if PSP_HIDEHEADER is included or the dwFlags member of the PROPSHEETHEADER structure does not contain the PSH_WIZARD97 flag.
PSP_USEHICON Uses hIcon as the small icon on the tab for the page.
PSP_USEICONID Uses pszIcon as the name of the icon resource to load and use as the small icon on the tab for the page.
PSP_USEREFPARENT Maintains the reference count specified by pcRefParent for the lifetime of the property sheet page created from this structure.
PSP_USETITLE Uses pszTitle as the title of the property sheet dialog box instead of the title stored in the dialog box template.
hInstance
Handle to the instance from which to load the icon or title string resource. If pszIcon or pszCaption identifies a resource to load, this member must be specified.
pszTemplate
Dialog box template to use to create the page. This member can specify either the resource identifier of the template or the address of a string that specifies the name of the template. If dwFlags includes PSP_DLGINDIRECT, this member is ignored.
pResource
Address of a dialog box template in memory. The PropertySheet function assumes that the template is in memory that can be written; a read-only template will cause an exception in some versions of Windows. If dwFlags does not include PSP_DLGINDIRECT, this member is ignored.
hIcon
Handle to the icon to use as the icon in the tab of the page. If dwFlags does not include PSP_USEHICON, this member is ignored.
pszIcon
Icon resource to use as the icon in the tab of the page. This member can specify either the identifier of the icon resource or the address of the string that specifies the name of the icon resource. If dwFlags does not include PSP_USEICONID, this member is ignored.
pszTitle
Title of the property sheet dialog box. This title overrides the title specified in the dialog box template. This member can specify either the identifier of a string resource or the address of a string that specifies the title. If dwFlags does not include PSP_USETITLE, this member is ignored.
pfnDlgProc
Address of the dialog box procedure for the page. Because the pages are created as modeless dialogs, the dialog box procedure must not call the EndDialog function.
lParam
Application-defined data.
pfnCallback
Address of an application-defined callback function that is called when the page is created and when it is about to be destroyed. For more information about the callback function, see PropSheetPageProc. If dwFlags does not include PSP_USECALLBACK, this member is ignored.
pcRefParent
Address of the reference count value. If dwFlags does not include PSP_USEREFPARENT, this member is ignored.
pszHeaderTitle
Version 4.71. Title of the header area. This member is ignored if any of the following are true:
  • The dwFlags member of this structure contains PSP_HIDEHEADER.
  • The dwFlags member of this structure does not contain PSP_USEHEADERTITLE.
  • The dwFlags member of the PROPSHEETHEADER structure does not contain PSH_WIZARD97.
pszHeaderSubTitle
Version 4.71. Subtitle of the header area. This member is ignored if any of the following are true:
  • The dwFlags member of this structure contains PSP_HIDEHEADER.
  • The dwFlags member of this structure does not contain PSP_USEHEADERSUBTITLE.
  • The dwFlags member of the PROPSHEETHEADER structure does not contain PSH_WIZARD97.

PSHNOTIFY

typedef struct _PSHNOTIFY { 
    NMHDR hdr; 
    LPARAM lParam; 
} PSHNOTIFY, FAR *LPPSHNOTIFY; 
 

Contains information for the PSN_APPLY and PSN_RESET notification messages.

hdr
Specifies an NMHDR structure. The code member of the NMHDR structure can be one of the following notification codes that identify the message being sent: PSN_APPLY or PSN_RESET.
lParam
Close flag. TRUE if the OK or Cancel button is used to close the property sheet. FALSE if the Close button used.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.