PFNCOMPROPSHEET

DWORD ( CALLBACK *PFNCOMPROPSHEET)(

HANDLE hComPropSheet,

UINT Function,

LPARAM lParam1,

LPARAM lParam2

);

PFNCOMPROPSHEET is a CPSUI-defined callback that is called by the caller’s PFNPROPSHEETUI callback to perform an action on a property sheet.

Parameters

hComPropSheet: Handle to the CPSUI object on which action is to be performed. This handle is created by the CPSUI, and must be the handle passed from the CPSUI when it called the caller-supplied PFNPROPSHEETUI callback.
Function: Specifies the action to be performed by the CPSUI’s PFNCOMPROPSHEET callback. This value can be one of the CPSFUNC_Xxx definitions. See the Comments section for details.
lParam1: Data required by the CPSUI to process the specified action. The CPSUI’s interpretation of lParam1 depends on Function. See the Comments section for details.
lParam2: Data required by the CPSUI to process the specified action. The CPSUI’s interpretation of lParam2 depends on Function. See the Comments section for details.

Return Value

The value returned by PFNCOMPROPSHEET depends on Function. See the Comments section for details.

Comments

The caller’s PFNPROPSHEETUI calls PFNCOMPROPSHEET to perform an action on the property sheet page(s) identified by hComPropSheet. The action is specified by Function.

The lParam1 and lParam2 parameters and PFNCOMPROPSHEET’s return value all depend on the value of Function, and are summarized in the following topics.

CPSFUNC_ADD_HPROPSHEETPAGE

Adds a page to the CPSUI object identified by hComPropSheet using a handle to a PROPSHEETPAGE structure. The caller obtains a PROPSHEETPAGE handle by calling the Win32 CreatePropertySheetPage function.

lParam1 is a handle to the PROPSHEETPAGE structure to be used by CPSUI to add the page.

lParam2 is not used, and must be set to zero.

PFNCOMPROPSHEET returns a handle to the newly added page if it succeeds; otherwise, it returns null.

CPSFUNC_ADD_PROPSHEETPAGE

Adds a page to the CPSUI object identified by hComPropSheet using a PROPSHEETPAGE structure.

lParam1 is a pointer to a PROPSHEETPAGE structure.

lParam2 is not used and must be set to zero.

PFNCOMPROPSHEET returns a handle to the newly added page if it succeeds; it returns null if it fails.

CPSFUNC_ADD_PCOMPROPSHEETUI

Adds one or more pages to the CPSUI object identified by hComPropSheet using the COMPROPSHEETUI data structure.

lParam1 is a pointer to the COMPROPSHEETUI structure to be used by CPSUI to add the page(s).

lParam2 is a pointer to a 32-bit location in which the CPSUI returns the number of pages added when it succeeds, or ERR_CPSUI_Xxx if it fails.

PFNCOMPROPSHEET returns a handle to the newly added page(s) if it succeeds; otherwise, it returns null.

CPSFUNC_ADD_PFNPROPSHEETUI

Adds the function to which lParam1 points to the CPSUI object identified by hComPropSheet. The CPSUI calls this function to add page(s) to the property sheet as follows:

PROPSHEETUI_INFO            PSUIInfo;
PSUIInfo.cbSize             = sizeof(PROPSHEETUI_INFO);
PSUIInfo.Version            = PROPSHEETUI_INFO_VERSION;
PSUIInfo.Flags              = (Ansi) ? 0 : PSUIINFO_UNICODE;
PSUIInfo.Reason             = PROPSHEETUI_REASON_INIT;
PSUIInfo.hComPropSheet	      = hComPropSheet;
PSUIInfo.pfnComPropSheet    = ComPropSheetUICallBack;
PSUIInfo.lParamInit         = lParam2;
PSUIInfo.UserData           = 0;
PSUIInfo.Result             = 0;
((PFNPROPSHEETUI)lParam1)(&PSUIInfo, lParam2);

lParam1 is a pointer to a PFNPROPSHEETUI callback that is called to add the property sheet page(s). This function’s implementation must use the hComPropSheet parameter as its handle when it calls back to the CPSUI’s PFNCOMPROPSHEET callback to add/delete pages.

lParam2 is a 32-bit data field that is passed to PFNPROPSHEETUI as the lParam parameter.

PFNCOMPROPSHEET returns a handle to the newly added property sheet page(s) if it succeeds; it returns null if it fails or no pages were added.

CPSFUNC_DELETE_HCOMPROPSHEET

Deletes the child page(s) from the parent CPSUI object using the passed child handle. The parent is identified by hComPropSheet.

lParam1 is a handle to the child page(s) to be deleted. This handle must previously have been returned from an executed CPSFUNC_ADD_Xxx or CPSFUNC_INSERT_Xxx function.

lParam2 is not used and must be set to zero.

PFNCOMPROPSHEET returns a value greater than zero if it succeeds; it returns a value less than or equal to zero if it fails.

CPSFUNC_SET_HSTARTPAGE

Marks the page(s) identified by hComPropSheet as the initial page(s) of the property sheet. The caller can call PFNCOMPROPSHEET with this function index both before and after the property sheet is displayed. If it is called after the initial display, the CPSUI switches the top (displayed) property sheet page with the first page of the marked page(s) on top.

lParam1 is a handle to the page(s) to be marked as those page(s) that the CPSUI displays first on the property sheet when it displays the property sheet dialog boxes. This handle must have been returned from an executed CPSFUNC_ADD_Xxx or CPSFUNC_INSERT_Xxx function.

lParam2 is an index to the exact page to be displayed first. If lParam1 is a parent handle, lParam2 is a zero-based index to the child page that should be marked as first. This parameter can also be one of the following special indexes if the handle identified by lParam1 was added by the CPSFUNC_ADD_PCOMPROPSHEETUI function.

Value

Description

SSP_TVPAGE

Mark the specified page as the treeview page.

SSP_STDPAGE

Mark the specified page as the Page Setup document property sheet page.

The SSP_Xxx values apply only to property sheet requests that originated in a call to the Win32 DocumentPropertySheet function.

PFNCOMPROPSHEET returns a value greater than zero if it succeeds; it returns a value less than or equal to zero if it fails.

CPSFUNC_GET_PAGECOUNT

Returns the number of pages that belong to the CPSUI object identified by hComPropSheet.

lParam1 is not used and must be set to zero.

lParam2 is not used and must be set to zero.

PFNCOMPROPSHEET returns the page count if it succeeds; it returns zero if it fails. There are never zero pages.

CPSFUNC_GET_HPSUIPAGES

Returns an array of handles to PROPSHEETPAGE structures. These handles identify the children that belong to the parent CPSUI object identified by hComPropSheet. To obtain all of the children’s handles, the caller should call PFNCOMPROPSHEET as follows:

if (((cPage = PFNCOMPROPSHEET(hComPropSheet,
CPSFUNC_GET_PAGECOUNT, 0L, 0L)) > 0) &&
((phPage = ALLOCMEM(cPage * sizeof(HANDLE))) != NULL) {
PFNCOMPROPSHEET(hComPropSheet, CPSFUNC_GET_HPSUIPAGES,
        (LPARAM)phPage, (LPARAM)cPage);
}

lParam1 is a pointer to an array in which the CPSUI writes the children’s handles.

lParam2 specifies the number of handles that can be stored in the array to which lParam1 points.

PFNCOMPROPSHEET returns the number of handles stored in lParam1 if it succeeds; it returns a value less than or equal to zero if it fails.

CPSFUNC_SET_RESULT

Propagates up the result of the property sheet page to the parent that added it through a CPSFUNC_ADD_Xxx function.

lParam1 is a handle to the page that is setting the result. If lParam1 is null, the CPSUI uses hComPropSheet.

lParam2 specifies the 32-bit DWORD result to be set.

Upon success, PFNCOMPROPSHEET returns the number of parents for which the result was set, or returns zero if the page identified by lParam1 has no parent. It returns a value less than zero if it fails because lParam1 is an invalid handle. The CPSUI propagates the result to the root handle.

CPSFUNC_LOAD_CPSUI_STRING

Loads the CPSUI resource string identified by the resource ID in the high word of lParam2.

lParam1 is a pointer to a null-terminated string of type LPTSTR in which the CPSUI loads the resource string from the CPSUI’s DLL.

lParam2 specifies the following two values.

WORD

Description

LOWORD(lParam2)

Number of characters, including the null terminator, in the string to which lParam1 points.

HIWORD(lParam2)

Specifies the resource ID of the string to be loaded. This value is one of the predefined IDS_CPSUI_Xxx string resource ID definitions.

PFNCOMPROPSHEET returns the number of characters stored in the string to which lParam1 points upon success; this does not include the null terminator. It returns zero when an invalid IDS_CPSUI_Xxx string resource ID is passed in the high word of lParam2. It returns a value less than zero when lParam1 is null or when the low word of lParam2 is zero.

CPSFUNC_LOAD_CPSUI_ICON

Loads the CPSUI resource icon identified by lParam1.

lParam1 specifies the resource ID of the icon to be loaded. This value is one of the predefined IDI_CPSUI_Xxx icon resource ID definitions.

lParam2 specifies the following two values.

WORD

Description

LOWORD(lParam2)

Specifies the icon width in pixels. If this value is zero, the CPSUI uses SM_CXICON.

HIWORD(lParam2)

Specifies the icon height in pixels. If this value is zero, the CPSUI uses SM_CYICON.

PFNCOMPROPSHEET returns a handle to the icon upon success, and null when it fails. The caller must call the Win32 DestroyIcon function when it no longer needs the icon.

CPSFUNC_GET_PFNPROPSHEETUI_ICON

Returns the icon handle that represents the children page(s) specified by lParam1.

lParam1 is a handle to the page(s) whose icon handle is to be queried. This handle must have been returned from a call to PFNCOMPROPSHEET with a CPSFUNC_ADD_PFNPROPSHEETUI function.

PFNCOMPROPSHEET returns a handle to the icon when it succeeds; it returns a null handle when it fails. The caller is responsible for calling the Win32 DestroyIcon function when it no longer needs the icon identified by the returned icon handle.

CPSFUNC_INSERT_PSUIPAGE

Inserts property sheet page(s) at the position specified in lParam2. The CPSUI object identified by hComPropSheet must be the parent handle.

lParam1 specifies a handle to the CPSUI object by which the page(s) are inserted. This handle must have been returned from a call to PFNCOMPROPSHEET with a CPSFUNC_ADD_Xxx function, or with a CPSFUNC_INSERT_PSUIPAGE.

lParam2 is a pointer to an INSERTPSUIPAGE_INFO structure.

PFNCOMPROPSHEET returns a handle to the newly added property sheet page(s) upon success; it returns null when it fails.

CPSFUNC_SET_PSUIPAGE_TITLE

Sets the tab title for a property sheet page.

lParam1 is a handle to the property sheet page whose title is to be set. This handle must have been returned from a call to PFNCOMPROPSHEET with a function of CPSFUNC_ADD_PROPSHEETPAGE, CPSFUNC_ADD_HPROPSHEETPAGE, or CPSFUNC_INSERT_PSUIPAGE with the Type field of the INSERTPSUIPAGE_INFO structure set to PSUIPAGEINSERT_PROPSHEETPAGE or PSUIPAGEINSERT_HPROPSHEETPAGE.

lParam2 is a pointer to a null-terminated string that specifies the new title.

PFNCOMPROPSHEET returns a value greater than zero upon success; it returns a value less than or equal to zero if it fails. This function returns zero if the property sheet page is not currently displayed.

CPSFUNC_SET_PSUIPAGE_ICON

Sets a new icon for display on a property sheet page’s tab.

lParam1 specifies a handle to the page with which the icon is to be associated. This handle must previously have been returned from a call to PFNCOMPROPSHEET with a function of CPSFUNC_ADD_PROPSHEETPAGE, CPSFUNC_ADD_HPROPSHEETPAGE, or CPSFUNC_INSERT_PSUIPAGE with the Type field of the INSERTPSUIPAGE_INFO structure set to PSUIPAGEINSERT_PROPSHEETPAGE or PSUIPAGEINSERT_HPROPSHEETPAGE.

lParam2 is a handle to the icon. The CPSUI stretches or shinks all icons to be of size 16x16 pixels.

If the icon was originally created through a call to the Win32 CreateIcon function, the caller is responsible for destroying the icon by calling the Win32 DestroyIcon function. The caller need not destroy the icon if it was created through a call to the Win32 LoadIcon function.

HANDLE hComPropSheet,
UINT Function,
LPARAM lParam1,
LPARAM lParam2
);

Value	Description
SSP_TVPAGE	Mark the specified page as the treeview page.
SSP_STDPAGE	Mark the specified page as the Page Setup document property sheet page.

WORD	Description
LOWORD(lParam2)	Number of characters, including the null terminator, in the string to which lParam1 points.
HIWORD(lParam2)	Specifies the resource ID of the string to be loaded. This value is one of the predefined IDS_CPSUI_Xxx string resource ID definitions.