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.