Property Sheet Reference

Property Sheet Reference


This section contains information about the following programming elements used with property sheets.

Functions
AddPropSheetPageProc
CreatePropertySheetPage
DestroyPropertySheetPage
ExtensionPropSheetPageProc
PropertySheet
PropSheetPageProc
PropSheetProc

Messages
PSM_ADDPAGE
PSM_APPLY
PSM_CANCELTOCLOSE
PSM_CHANGED
PSM_GETCURRENTPAGEHWND
PSM_GETTABCONTROL
PSM_ISDIALOGMESSAGE
PSM_PRESSBUTTON
PSM_QUERYSIBLINGS
PSM_REBOOTSYSTEM
PSM_REMOVEPAGE
PSM_RESTARTWINDOWS
PSM_SETCURSEL
PSM_SETCURSELID
PSM_SETFINISHTEXT
PSM_SETTITLE
PSM_SETWIZBUTTONS
PSM_UNCHANGED

Utility Macros
PropSheet_AddPage
PropSheet_Apply
PropSheet_CancelToClose
PropSheet_Changed
PropSheet_GetCurrentPageHwnd
PropSheet_GetTabControl
PropSheet_IsDialogMessage
PropSheet_PressButton
PropSheet_QuerySiblings
PropSheet_RebootSystem
PropSheet_RemovePage
PropSheet_RestartWindows
PropSheet_SetCurSel
PropSheet_SetCurSelByID
PropSheet_SetFinishText
PropSheet_SetTitle
PropSheet_SetWizButtons
PropSheet_UnChanged

Notifications
PSN_APPLY
PSN_GETOBJECT
PSN_HELP
PSN_KILLACTIVE
PSN_QUERYCANCEL
PSN_RESET
PSN_SETACTIVE
PSN_WIZBACK
PSN_WIZFINISH
PSN_WIZNEXT

Structures
PROPSHEETHEADER
PROPSHEETPAGE
PSHNOTIFY

Property Sheet Functions

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

AddPropSheetPageProc

BOOL CALLBACK AddPropSheetPageProc(
    HPROPSHEETPAGE hpage, 		
    LPARAM lParam		
);		

Specifies an application-defined callback function that a property sheet extension uses to add a page to a property sheet.

hpage
Handle to a property sheet page.
lParam
Application-defined 32-bit value.

CreatePropertySheetPage

HPROPSHEETPAGE CreatePropertySheetPage(
    LPCPROPSHEETPAGE lppsp		
);		

Creates a new page for a property sheet.

lppsp
Address of a PROPSHEETPAGE structure that defines a page to be included in a property sheet.

An application uses the PropertySheet function to create a property sheet that includes the new page, or it uses the PSM_ADDPAGE message to add the new page to an existing property sheet.

Windows 95: The system can support a maximum of 16,364 window handles.

DestroyPropertySheetPage

BOOL DestroyPropertySheetPage(
    HPROPSHEETPAGE hPSPage		
);		

Destroys a property sheet page. An application must call this function for pages that have not been passed to the PropertySheet function.

hPSPage
Handle to the property sheet page to delete.

ExtensionPropSheetPageProc

BOOL CALLBACK ExtensionPropSheetPageProc(
    LPVOID lpv, 	
    LPFNADDPROPSHEETPAGE lpfnAddPropSheetPageProc, 	
    LPARAM lParam	
);	

Specifies an application-defined callback function that receives the address of the AddPropSheetPageProc function, which resides in the module that creates a property sheet. A property sheet extension must export the ExtensionPropSheetPageProc function by name.

lpv
Address of an application-defined value that describes an item for which a property sheet page is to be created. This parameter can be NULL.
lpfnAddPropSheetPageProc
Address of the AddPropSheetPageProc function. The extension dynamic-link library (DLL) calls this function to add a page to the property sheet.
lParam
Application-defined 32-bit value.

PropertySheet

int PropertySheet(
    LPCPROPSHEETHEADER lppsph		
);		

Creates a property sheet and adds the pages defined in the specified property sheet header structure.

lppsph
Address of a PROPSHEETHEADER structure that defines the frame and pages of a property sheet.

By default, PropertySheet creates a modal dialog. If the dwFlags member of the PROPSHEETHEADER structure specifies the PSH_MODELESS flag, PropertySheet creates a modeless dialog and returns immediately after the dialog is created. In this case, the PropertySheet return value is the window handle to the modeless dialog.

For a modeless property sheet, your message loop should use PSM_ISDIALOGMESSAGE to pass messages to the property sheet dialog. Your message loop should use PSM_GETCURRENTPAGEHWND to determine when to destroy the dialog. When the user clicks the OK or Cancel button, PSM_GETCURRENTPAGEHWND returns NULL, and you can then use the DestroyWindow function to destroy the dialog.

PropSheetPageProc

UINT CALLBACK PropSheetPageProc(
    HWND hwnd,		
    UINT uMsg,		
    LPPROPSHEETPAGE ppsp		
);		

Specifies an application-defined callback function that a property sheet calls when a page is created and when it is about to be destroyed. An application can use this function to perform initialization and cleanup operations for the page.

hwnd
Reserved; must be NULL.
uMsg
Action flag. This parameter can be one of the following values:
PSPCB_CREATE A page is being created. Return nonzero to allow the page to be created, or zero to prevent it.
PSPCB_RELEASE A page is being destroyed. The return value is ignored.
ppsp
Address of a PROPSHEETPAGE structure that defines the page being created or destroyed.

An application must specify the address of this callback function in the pfnCallback member of a PROPSHEETPAGE structure before specifying the address of the structure in a call to the CreatePropertySheetPage function.

PropSheetProc

int CALLBACK PropSheetProc(
    HWND hwndDlg,
    UINT uMsg,
    LPARAM lParam
);		

An application-defined callback function that the system calls when the property sheet is being created and initialized.

hwndDlg
Handle to the property sheet dialog box.
uMsg
Identifies the message being received. This parameter is one of the following values:
PSCB_INITIALIZED Indicates that the property sheet is being initialized. The lParam value is zero for this message.
PSCB_PRECREATE Indicates that the property sheet is about to be created. The hwndDlg parameter is NULL, and the lParam parameter is the address of a dialog template in memory. This template is in the form of a DLGTEMPLATE structure followed by one or more DLGITEMTEMPLATE structures.
lParam
Specifies additional information about the message. The meaning of this value depends on the uMsg parameter.

To enable a PropSheetProc callback function, use the PROPSHEETHEADER structure when you call the PropertySheet function to create the property sheet. Use the pfnCallback member to specify an address of the callback function, and set the PSP_USECALLBACK flag in the dwFlags member.

PropSheetProc is a placeholder for the application-defined function name. The PFNPROPSHEETCALLBACK type is the address of a PropSheetProc callback function.

Property Sheet Messages

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

PSM_ADDPAGE

PSM_ADDPAGE 
    wParam = 0; 
    lParam = (LPARAM) (HPROPSHEETPAGE) hpage;

Adds a new page to the end of an existing property sheet. You can send this message explicitly or by using the PropSheet_AddPage macro.

hpage
Handle to the page to add. The page must have been created by a previous call to the CreatePropertySheetPage function.

The new page should be no larger than the largest page currently in the property sheet because the property sheet is not resized to fit the new page.

PSM_APPLY

PSM_APPLY 
    wParam = 0; 
    lParam = 0; 

Simulates the selection of the Apply Now button, indicating that one or more pages have changed and the changes need to be validated and recorded. The property sheet sends the PSN_KILLACTIVE notification message to the current page. If the current page returns FALSE, the property sheet sends the PSN_APPLY notification message to all pages. You can send the PSM_APPLY message explicitly or by using the PropSheet_Apply macro.

PSM_CANCELTOCLOSE

PSM_CANCELTOCLOSE 
    wParam = 0; 
    lParam = 0; 

Disables the Cancel button and changes the text of the OK button to "Close." An application sends this message after applying a change that cannot be canceled. You can send this message explicitly or by using the PropSheet_CancelToClose macro.

PSM_CHANGED

PSM_CHANGED 
    wParam = (WPARAM) (HWND) hwndPage; 
    lParam = 0; 

Informs a property sheet that information in a page has changed. The property sheet enables the Apply Now button. You can send this message explicitly or by using the PropSheet_Changed macro.

hwndPage
Handle to the page that has changed.

PSM_GETCURRENTPAGEHWND

PSM_GETCURRENTPAGEHWND 
    wParam = 0; 
    lParam = 0; 

Retrieves a handle to the window of the current page of a property sheet. You can send this message explicitly or by using the PropSheet_GetCurrentPageHwnd macro.

Use the PSM_GETCURRENTPAGEHWND message with modeless property sheets to determine when to destroy the dialog box. When the user clicks the OK or Cancel button, PSM_GETCURRENTPAGEHWND returns NULL, and you can then use the DestroyWindow function to destroy the dialog box.

See also PropertySheet

PSM_GETTABCONTROL

PSM_GETTABCONTROL 
    wParam = 0; 
    lParam = 0; 

Retrieves the handle to the tab control of a property sheet. You can send this message explicitly or by using the PropSheet_GetTabControl macro.

PSM_ISDIALOGMESSAGE

PSM_ISDIALOGMESSAGE
    wParam = 0; 
    lParam = (LPARAM)pMsg; 

Passes a message to a property sheet dialog box and indicates whether the dialog box processed the message. You can send this message explicitly or by using the PropSheet_IsDialogMessage macro.

pMsg
Address of an MSG structure that contains the message to be checked.

Your message loop should use the PSM_ISDIALOGMESSAGE message with modeless property sheets to pass messages to the property sheet dialog box.

If the return value indicates that the message was processed, it must not be passed to the TranslateMessage or DispatchMessage function.

See also PropertySheet

PSM_PRESSBUTTON

PSM_PRESSBUTTON 
    wParam = (WPARAM) (int) iButton; 
    lParam = 0; 

Simulates the selection of a property sheet button. You can send this message explicitly or by using the PropSheet_PressButton macro.

iButton
Index of the button to select. This parameter can be one of the following values:
PSBTN_APPLYNOW Selects the Apply Now button.
PSBTN_BACK Selects the Back button.
PSBTN_CANCEL Selects the Cancel button.
PSBTN_FINISH Selects the Finish button.
PSBTN_HELP Selects the Help button.
PSBTN_NEXT Selects the Next button.
PSBTN_OK Selects the OK button.

PSM_QUERYSIBLINGS

PSM_QUERYSIBLINGS 
    wParam = (WPARAM) param1; 
    lParam = (LPARAM) param2; 

Sent to a property sheet, which then forwards the message to each of its pages. If a page returns a nonzero value, the property sheet does not send the message to subsequent pages. You can send this message explicitly or by using the PropSheet_QuerySiblings macro.

param1
First application-defined parameter.
param2
Second application-defined parameter.

PSM_REBOOTSYSTEM

PSM_REBOOTSYSTEM 
    wParam = 0; 
    lParam = 0; 

Indicates the system needs to be restarted for the changes to take effect. An application should send this message only in response to the PSN_APPLY or PSN_KILLACTIVE notification message. You can send the PSM_REBOOTSYSTEM message explicitly or by using the PropSheet_RebootSystem macro.

This message causes the PropertySheet function to return the ID_PSREBOOTSYSTEM value, but only if the user clicks the OK button to close the property sheet. It is the application's responsibility to reboot the system, which can be done by using the ExitWindowsEx function.

This message supersedes all PSM_RESTARTWINDOWS messages that precede or follow it.

PSM_REMOVEPAGE

PSM_REMOVEPAGE 
    wParam = (WPARAM) (int) index; 
    lParam = (LPARAM) (HPROPSHEETPAGE) hpage); 

Removes a page from a property sheet. You can send this message explicitly or by using the PropSheet_RemovePage macro.

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.

PSM_RESTARTWINDOWS

PSM_RESTARTWINDOWS 
    wParam = 0; 
    lParam = 0;  

Indicates that Windows needs to be restarted for the changes to take effect. An application should send this message only in response to the PSN_APPLY or PSN_KILLACTIVE notification message. You can send the PSM_RESTARTWINDOWS message explicitly or by using the PropSheet_RestartWindows macro.

This 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.

PSM_SETCURSEL

PSM_SETCURSEL 
    wParam = (WPARAM) (int) index; 
    lParam = (LPARAM) (HPROPSHEETPAGE) hpage; 

Activates the specified page in a property sheet. You can send this message explicitly or by using the PropSheet_SetCurSel macro.

index and hpage
The 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.

PSM_SETCURSELID

PSM_SETCURSELID 
    wParam = 0; 
    lParam = (LPARAM) (int) id; 

Activates the given page in a property sheet based on the resource identifier of the page. You can send this message explicitly or by using the PropSheet_SetCurSelByID macro.

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.

PSM_SETFINISHTEXT

PSM_SETFINISHTEXT 
    wParam = 0; 
    lParam = (LPARAM) (LPSTR) 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 send this message explicitly or by using the PropSheet_SetFinishText macro.

lpszText
Address of the new text for the Finish button.

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

PSM_SETTITLE

PSM_SETTITLE 
    wParam = (WPARAM) (DWORD) dwStyle 
    lParam = (LPARAM) (LPCSTR) lpszText; 

Sets the title of a property sheet. You can send this message explicitly or by using the PropSheet_SetTitle macro.

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.

PSM_SETWIZBUTTONS

PSM_SETWIZBUTTONS 
    wParam = 0; 
    lParam = (LPARAM) (DWORD) dwFlags; 

Enables or disables the Back, Next, and Finish buttons in a wizard property sheet. You can send or post this message explicitly to a wizard property sheet, or you can use the PropSheet_SetWizButtons macro to post the message.

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.

If you send the PSM_SETWIZBUTTONS message during your handling of the PSN_SETACTIVE notification message, use the PostMessage function rather than the SendMessage function. Otherwise, the system will not update the buttons properly. At any other time, you can use SendMessage to send PSM_SETWIZBUTTONS.

PSM_UNCHANGED

PSM_UNCHANGED 
    wParam = (WPARAM) (HWND) hwndPage; 
    lParam = 0; 

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 send this message explicitly or by using the PropSheet_UnChanged macro.

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

Property Sheet Macros

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

PropSheet_AddPage

BOOL PropSheet_AddPage(
    HWND hPropSheetDlg, 		
    HPROPSHEETPAGE hpage		
);		

Adds a new page to the end of an existing property sheet. You can use this macro or send the PSM_ADDPAGE message explicitly.

hPropSheetDlg
Handle to the property sheet.
hpage
Handle to the page to add. The page must have been created by a previous call to the CreatePropertySheetPage function.

The new page should be no larger than the largest page currently in the property sheet because the property sheet is not resized to fit the new page.

PropSheet_Apply

BOOL PropSheet_Apply(
    HWND hPropSheetDlg		
);		

Simulates the selection of the Apply Now button, indicating that one or more pages have changed and the changes need to be validated and recorded. The property sheet sends the PSN_KILLACTIVE notification message to the current page. If the current page returns FALSE, the property sheet sends the PSN_APPLY notification message to all pages. You can use this macro or send the PSM_APPLY message explicitly.

hPropSheetDlg
Handle to the property sheet.

PropSheet_CancelToClose

VOID PropSheet_CancelToClose(
    HWND hPropSheetDlg		
);		

Disables the Cancel button and changes the text of the OK button to "Close." An application sends the PSM_CANCELTOCLOSE message after applying a change that cannot be canceled. You can use this macro or send the PSM_CANCELTOCLOSE message explicitly.

hPropSheetDlg
Handle to the property sheet.

PropSheet_Changed

BOOL PropSheet_Changed(
    HWND hPropSheetDlg, 		
    HWND hwndPage		
);		

Informs a property sheet that information in a page has changed. The property sheet enables the Apply Now button. You can use this macro or send the PSM_CHANGED message explicitly.

hPropSheetDlg
Handle to the property sheet.
hwndPage
Handle to the page that has changed.

PropSheet_GetCurrentPageHwnd

HWND PropSheet_GetCurrentPageHwnd(
    HWND hDlg 
);		

Retrieves a handle to the window of the current page of a property sheet. You can use this macro or send the PSM_GETCURRENTPAGEHWND message explicitly.

hDlg
Handle to the property sheet.

Use the PropSheet_GetCurrentPageHwnd macro with modeless property sheets to determine when to destroy the dialog box. When the user clicks the OK or Cancel button, PropSheet_GetCurrentPageHwnd returns NULL, and you can then use the DestroyWindow function to destroy the dialog box.

See also PropertySheet

PropSheet_GetTabControl

HWND PropSheet_GetTabControl(
    HWND hPropSheetDlg		
);		

Retrieves the handle to the tab control of a property sheet. You can use this macro or send the PSM_GETTABCONTROL message explicitly.

hPropSheetDlg
Handle to the property sheet.

PropSheet_IsDialogMessage

BOOL PropSheet_IsDialogMessage(
    HWND hDlg, 		
    LPMSG pMsg		
);		

Passes a message to a property sheet dialog box and indicates whether the dialog box processed the message. You can use this macro or send the PSM_ISDIALOGMESSAGE message explicitly.

hDlg
Handle to the property sheet.
pMsg
Address of an MSG structure that contains the message to be checked.

Your message loop should use the PSM_ISDIALOGMESSAGE message with modeless property sheets to pass messages to the property sheet dialog box.

If the return value indicates that the PSM_ISDIALOGMESSAGE message was processed, it must not be passed to the TranslateMessage or DispatchMessage function.

See also PropertySheet

PropSheet_PressButton

BOOL PropSheet_PressButton(
    HWND hPropSheetDlg, 		
    int iButton		
);		

Simulates the selection of a property sheet button. You can use this macro or send the PSM_PRESSBUTTON message explicitly.

hPropSheetDlg
Handle to the property sheet.
iButton
Index of the button to select. This parameter can be one of the following values:
PSBTN_APPLYNOW Selects the Apply Now button.
PSBTN_BACK Selects the Back button.
PSBTN_CANCEL Selects the Cancel button.
PSBTN_FINISH Selects the Finish button.
PSBTN_HELP Selects the Help button.
PSBTN_NEXT Selects the Next button.
PSBTN_OK Selects the OK button.

PropSheet_QuerySiblings

int PropSheet_QuerySiblings(
    HWND hPropSheetDlg, 		
    WPARAM param1, 		
    LPARAM param2		
);		

Causes a property sheet to send the PSM_QUERYSIBLINGS message to each of its pages. If a page returns a nonzero value, the property sheet does not send the message to subsequent pages. You can use this macro or send the PSM_QUERYSIBLINGS message explicitly.

hPropSheetDlg
Handle to the property sheet.
param1
First application-defined parameter.
param2
Second application-defined parameter.

PropSheet_RebootSystem

VOID PropSheet_RebootSystem(
    HWND hPropSheetDlg		
);		

Indicates the system needs to be restarted for the changes to take effect. You can use this macro or send the PSM_REBOOTSYSTEM message explicitly. An application should send the PSM_REBOOTSYSTEM message only in response to the PSN_APPLY or PSN_KILLACTIVE notification message.

hPropSheetDlg
Handle to the property sheet.

This macro causes the PropertySheet function to return the ID_PSREBOOTSYSTEM value, but only if the user clicks the OK button to close the property sheet. It is the application's responsibility to reboot the system, which can be done by using the ExitWindowsEx function.

This macro supersedes all PropSheet_RebootSystem macros that precede or follow it.

See also PSM_RESTARTWINDOWS

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