PFNPROPSHEETUI

LONG (FAR *PFNPROPSHEETUI)(

PPROPSHEETUI_INFO pPSUIInfo,
LPARAM lParam
);

PFNPROPSHEETUI is a caller-defined function that the CPSUI calls to enable its caller to add or delete pages from a property sheet.

Parameters

pPSUIInfo

Pointer to a PROPSHEETUI_INFO structure. The CPSUI allocates and initializes this structure with the information needed by PFNPROPSHEETUI to add property sheet pages. This parameter can be null.

lParam

If pPSUIInfo is null, the caller of PFNPROPSHEETUI is not the CPSUI, but is the spooler or Print Folder instead. In this situation, lParam is a parameter whose type is known the caller. If pPSUIInfo is non-null, the CPSUI has called PFNPROPSHEETUI. In this situation, the value of lParam depends on the Reason member of the PROPSHEETUI_INFO structure shown in the following table.

Reason	Description
PROPSHEETUI_REASON_INIT	The lParam parameter is either the unmodified lParam parameter passed to CommonPropertySheetUI, or the lParam2 parameter passed to PFNCOMPROPSHEET with a Function of CPSFUNC_ADD_PFNPROPSHEETUI. The CPSUI has copied this instance of lParam to the lParamInit field of the PROPSHEETUI_INFO structure. The lParamInit field is passed to all subsequent calls to PFNPROPSHEETUI without modification. The lParam parameter must not reside on the calling function’s stack.
PROPSHEETUI_REASON_ GET_INFO_HEADER	The lParam parameter is a pointer to a PROPSHEETUI_INFO_HEADER structure. PFNPROPSHEETUI must fill in the fields of this structure for the CPSUI.
PROPSHEETUI_REASON_ DESTROY	The lParam parameter is zero when the destroy request occurs because the caller has called the CPSUI’s PFNCOMPROPSHEET callback with Function set to CPSFUNC_DELETE_HCOMPROPSHEET, or when the CPSUI’s callback failed a caller’s CPSFUNC_ADD_Xxx request. The lParam parameter is nonzero when the user is exiting the property sheet.
PROPSHEETUI_REASON_ SET_RESULT	The lParam parameter is a pointer to a SETRESULT_INFO structure in which the CPSUI has set the following fields: hSetResult contains the handle to those page(s) added to the sheet through a call to PFNCOMPROPSHEET with a CPSFUNC_ADD_Xxx function index; Result contains the result obtained when hSetResult was generated. PFNPROPSHEETUI should save this result in the Result field of the structure to which pPSUIInfo points. When PFNPROPSHEETUI’s return value is greater than zero, the CPSUI propagates the Result field of the structure to which pPSUIInfo points to its parent.
PROPSHEETUI_REASON_ GET_ICON	The lParam parameter is a pointer to a PROPSHEETUI_GETICON_INFO structure in which the CPSUI has set the following fields: cxIcon is the icon’s width, in pixels; cyIcon is the icon’s height, in pixels; hIcon is null. PFNPROPSHEETUI should create an icon and return its handle, or, if it does not create an icon, should return null.

Return Value

The return value of PFNPROPSHEETUI depends on the Reason field of the PROPSHEETUI_INFO structure shown in the following table.

Reason	Return Value
PROPSHEETUI_REASON_INIT, PROPSHEETUI_REASON_GET_INFO_HEADER, PROPSHEETUI_REASON_DESTROY	Returns greater than zero to indicate success, and less than or equal to zero to indicate failure.
PROPSHEETUI_REASON_SET_RESULT	Returns greater than zero to indicate that the Result field in the structure to which pPSUIInfo points should be set to its parent; returns less than or equal to zero to indicate that Result need not be set to its parent.
PROPSHEETUI_REASON_GET_ICON	Returns greater than zero to indicate success, zero to indicate that no icon was available, and less than zero to indicate failure.

Comments

PFNPROPSHEETUI is a pseudoname; the actual name of this function can be decided upon by the developer. PFNPROPSHEETUI must be implemented.

PFNPROPSHEETUI is a caller-defined function in which the caller can request the CPSUI to add pages to the property sheet. The CPSUI calls this function as follows:

PROPSHEETUI_INFO   PSUIInfo;
PFNPROPSHEETUI(&PSUIInfo, lParam);

The CPSUI stores the reason for calling PFNPROPSHEETUI in the Reason field of the PROPSHEETUI_INFO structure to which pPSUIInfo points. PFNPROPSHEETUI should be implemented as a re-entrant, message-based function, as the CPSUI calls it several times over the lifetime of the property sheet.

The CPSUI calls PFNPROPSHEETUI for the first time with Reason always set to PROPSHEETUI_REASON_INIT. PFNPROPSHEETUI should initialize itself and then call the CPSUI to add new pages to the property sheet root identified by the hComPropSheet member of the PROPSHEETUI_INFO structure. PFNPROPSHEETUI must call back to the CPSUI to actually add (or delete) pages from the property sheet. The CPSUI provides a pointer to its callback in the pfnComPropSheet field. The CPSUI callback returns a value greater than zero to indicate success, and a value less than or equal to zero to indicate failure.

If the first call to PFNPROPSHEETUI does not return successfully, the CPSUI calls PFNPROPSHEETUI with Reason set to PROPSHEETUI_REASON_DESTROY so that PFNPROPSHEETUI can uninitialize itself.

The CPSUI calls PFNPROPSHEETUI with Reason set to PROPSHEETUI_REASON_GET_INFO_HEADER to obtain high-level property sheet information to use when it displays the property sheet dialog boxes.

See Also

CommonPropertySheetUI, PFNCOMPROPSHEET, PROPSHEETUI_INFO, PROPSHEETUI_INFO_HEADER