PFNPROPSHEETUI callback function (compstui.h)

Article
11/24/2022

The PFNPROPSHEETUI function type is used by CPSUI applications (including printer interface DLLs) for defining page creation callbacks, which specify property sheet pages for creation.

Syntax

PFNPROPSHEETUI Pfnpropsheetui;

LONG Pfnpropsheetui(
  PPROPSHEETUI_INFO pPSUIInfo,
  LPARAM lParam
)
{...}

Parameters

pPSUIInfo

CPSUI-supplied pointer to a PROPSHEETUI_INFO structure.

lParam

CPSUI-supplied integer value that is dependent on the contents of the Reason member of the PROPSHEETUI_INFO structure. Valid values are as follows:

PROPSHEETUI_REASON_BEFORE_INIT

This value is new to Windows 8 and it is provided only to the original PFNPROPSHEETUI parameter passed to CommonPropertySheetUI.

PROPSHEETUI_REASON_DESTROY

The lParam value is nonzero if the user has selected the property sheet's OK or Cancel button. Otherwise the value is zero.

PROPSHEETUI_REASON_GET_ICON

The lParam value is a pointer to a PROPSHEETUI_GETICON_INFO structure.

PROPSHEETUI_REASON_GET_INFO_HEADER

The lParam value is a pointer to a PROPSHEETUI_INFO_HEADER structure.

PROPSHEETUI_REASON_INIT

If the callback function is specified by the pfnPropSheetUI parameter to CommonPropertySheetUI, lParam is the lParam value passed to CommonPropertySheetUI.

If the callback function is specified using the CPSFUNC_ADD_PFNPROPSHEETUI function code with CPSUI's ComPropSheet function, lParam is the lParam2 value passed to ComPropSheet.

CPSUI copies the lParam value into the lParamInit member of the function's PROPSHEETUI_INFO structure.

The lParam value must not reside on the application's stack.

PROPSHEETUI_REASON_SET_RESULT

The lParam value is a pointer to a SETRESULT_INFO structure.

Return value

If the operation succeeds, the function should return a value of one (or greater). Otherwise it should return a value less than one.

Return code	Description
One or greater.	The PFNPROPSHEETUI function associated with the parent of the current page will be called.
Less than 1.	The PFNPROPSHEETUI function associated with the parent of the current page will not be called.

Remarks

Callback functions specified using the PFNPROPSHEETUI function type are supplied by applications that use CPSUI to manage customized property sheet pages. One such callback function must be specified when an application calls the CommonPropertySheetUI function. For example, when the NT-based operating system print spooler calls CPSUI's CommonPropertySheetUI function to support its DocumentProperties or PrinterProperties functions, the spooler specifies an internal PFNPROPSHEETUI-typed callback function.

Applications can specify additional PFNPROPSHEETUI-typed callback functions by calling CPSUI's ComPropSheet function with a function code of CPSFUNC_ADD_PFNPROPSHEETUI. For example, the NT-based operating system print spooler does this to notify CPSUI of the existence of a printer interface DLL's DrvDocumentPropertySheets and DrvDevicePropertySheets functions. Likewise, Microsoft's Unidrv and Pscript drivers use this technique to notify CPSUI of the existence of IPrintOemUI::DocumentPropertySheets and IPrintOemUI::DevicePropertySheets methods in user interface plug-ins.

Each PFNPROPSHEETUI-typed callback function is called by CPSUI several times. The Reason member of the PROPSHEETUI_INFO structure stipulates the operation that the function should perform, as follows:

Requirements

Requirement	Value
Target Platform	Desktop
Header	compstui.h (include Compstui.h)

Share via