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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 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.
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.
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.
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.
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.
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.