PROPSHEETUI_INFO

typedef struct _PROPSHEETUI_INFO {

WORD cbSize;

WORD Version;

WORD Flags;

WORD Reason;

HANDLE hComPropSheet;

PFNCOMPROPSHEET pfnComPropSheet;

LPARAM lParamInit;

DWORD UserData;

DWORD Result;

} PROPSHEETUI_INFO, *PPROPSHEETUI_INFO;

The PROPSHEETUI_INFO structure is passed from the CPSUI to the caller-defined PFNPROPSHEETUI function.

Members

cbSize

Size of this structure in bytes.

Version

Version number of this structure. The current version is defined as PROPSHEETUI_INFO_VERSION in compstui.h.

Flags

Flag field in which the following bit can be set.

Flag Description
PSUIINFO_UNICODE The caller's executable was compiled for Unicode.

Reason

Specifies the action to be performed on the property sheet by the PFNPROPSHEETUI callback to which the PROPSHEETUI_INFO structure was passed. It can be one of the following values.

Reason Description
PROPSHEETUI_REASON_INIT This is the first call that the CPSUI makes to PFNPROPSHEETUI. The callback should initialize itself and call the CPSUI function to which pfnComPropSheet points to add new pages to the CPSUI object identified by hComPropSheet.
PROPSHEETUI_REASON_
GET_INFO_HEADER
The CPSUI calls PFNPROPSHEETUI with this reason when the first call with PROPSHEETUI_REASON_INIT set returns successfully. The callback should supply the property sheet title bar information needed by the CPSUI to display the property sheet dialog boxes. The CPSUI passes a PROPSHEETUI_INFO_HEADER structure as the lParam parameter to PFNPROPSHEETUI.
PROPSHEETUI_REASON_
GET_ICON
The CPSUI calls PFNPROPSHEETUI with this reason to retrieve the icon that represents this PFNPROPSHEETUI function.
PROPSHEETUI_REASON_
SET_RESULT
A new handle, added through a call to PFNCOMPROPSHEET with Function set to CPSFUNC_ADD_Xxx, needs to return its result to its parent. The CPSUI provides a pointer to a SETRESULT_INFO structure with the following fields set:

hSetResult specifies the handle that was added;

Result specifies the result from adding the property sheet page(s) identified by hSetResult. This result is to be set in the PROPSHEETUI_INFO Result field in this call to PFNPROPSHEETUI.

PROPSHEETUI_REASON_
DESTROY
Pages previously added by PFNPROPSHEETUI need to be deleted now, or the property sheet is being destroyed entirely. PFNPROPSHEETUI should uninitialize itself and free all memory allocated in this function instance.

When PFNPROPSHEETUI is called with this reason, all children of hComPropSheet are destroyed, and the children's handles are no longer valid.


hComPropSheet

Handle to the CPSUI object on which action is to be performed. This handle is created and managed by the CPSUI, and is typically a parent handle. When PFNPROPSHEETUI calls the function to which pfnComPropSheet points to add or delete property sheet pages, it should pass this handle as the hComPropSheet parameter.

pfnComPropSheet

Pointer to the CPSUI's callback function. PFNPROPSHEETUI calls the function to which pfnComPropSheet points so that the CPSUI can complete the action to be performed on the property sheet.

lParamInit

Specifies the LPARAM value passed in the first call to the caller's PFNPROPSHEETUI callback by the CPSUI; the first call is always made with Reason set to PROPSHEETUI_REASON_INIT. This member is passed to each subsequent call to PFNPROPSHEETUI, regardless of reason.

UserData

Field in which the current PFNPROPSHEETUI call can store data. This field is an IN/OUT parameter whose value depends on Reason as shown in the following table.

Reason Description
PROPSHEETUI_REASON_INIT IN: Set to zero.

OUT: Contains data that was stored by this call to PFNPROPSHEETUI. This data is passed in the next call to PFNPROPSHEETUI for any reason.

All other reasons IN: Specifies the data stored in the last call to PFNPROPSHEETUI for any reason.

OUT: Contains data that was stored by this call to PFNPROPSHEETUI, if any.


Result

Member in which the result of the call to PFNPROPSHEETUI is stored. This field is an IN/OUT parameter whose value depends on Reason as shown in the following table.

Reason Description
PROPSHEETUI_REASON_INIT IN: Set to zero.

OUT: Set to the appropriate result of the current call to PFNPROPSHEETUI.

All other reasons IN: Specifies the result returned by the previous call to PFNPROPSHEETUI for any reason.

OUT: Set to the appropriate result of the current call to PFNPROPSHEETUI.


Comments

The CPSUI allocates, initializes, and maintains the PROPSHEETUI_INFO structure. The CPSUI passes this structure as a parameter to PFNPROPSHEETUI.

The caller's PFNPROPSHEETUI callback can determine and set the UserData and Result fields of the PROPSHEETUI_INFO structure for any PROPSHEETUI_REASON_Xxx reason that it is called.