
This section contains information about the following programming elements used with property sheets.
| Functions |
| AddPropSheetPageProc |
| CreatePropertySheetPage |
| DestroyPropertySheetPage |
| ExtensionPropSheetPageProc |
| PropertySheet |
| PropSheetPageProc |
| PropSheetProc |
| 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 |
This section contains information about the functions used with property sheets.
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.
HPROPSHEETPAGE CreatePropertySheetPage(
LPCPROPSHEETPAGE lppsp
);
Creates a new page for 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.
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.
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.
int PropertySheet(
LPCPROPSHEETHEADER lppsph
);
Creates a property sheet and adds the pages defined in the specified property sheet header structure.
If the dwFlags member of the PROPSHEETHEADER structure specifies the PSH_MODELESS flag, the successful return value is the window handle to the property sheet dialog.
The following return values have a special meaning:
| ID_PSREBOOTSYSTEM | A page sent the PSM_REBOOTSYSTEM message to the property sheet. The computer must be restarted for the user's changes to take effect. |
| ID_PSRESTARTWINDOWS | A page sent the PSM_RESTARTWINDOWS message to the property sheet. Windows must be restarted for the user's changes to take effect. |
To get extended error information, call GetLastError.
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.
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.
| 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. |
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.
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.
| 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. |
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.
This section contains information about the messages used with property sheets.
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.
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
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
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
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.
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
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
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.
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
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.
| 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
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.
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
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.
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
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.
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
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.
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
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.
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
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.
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.
| 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
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.
This section contains information about the macros used with property sheets.
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.
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.
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.
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.
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.
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.
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
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.
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.
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
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.
| 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. |
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.
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.
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.