
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
| 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. |
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.
This section contains information about the notification messages used with property sheets.
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.
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
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.
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
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.
An application should display Help information for the page.
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.
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
lpnmhdr = (LPNMHDR) lParam;
Indicates the user clicked the Cancel button. This notification message is sent in the form of a WM_NOTIFY message.
A property sheet page can use this notification message to ask the user to verify the cancel operation.
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.
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
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.
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
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.
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.
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.
This section contains information about the structures used with property sheets.
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.
| 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. |
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.
| 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. |
typedef struct _PSHNOTIFY {
NMHDR hdr;
LPARAM lParam;
} PSHNOTIFY, FAR *LPPSHNOTIFY;
Contains information for the PSN_APPLY and PSN_RESET notification messages.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.