COMPROPSHEETUI

typedef struct _COMPROPSHEETUI {
    WORD                  cbSize;
    WORD                  Flags;
    HINSTANCE             hInstCaller;
    LPTSTR                pCallerName;
    DWORD                 UserData;
    LPTSTR                pHelpFile;
    _CPSUICALLBACK        pfnCallBack;
    POPTITEM              pOptItem;
    PDLGPAGE              pDlgPage;
    WORD                  cOptItem;
    WORD                  cDlgPage;
    DWORD                 IconID;
    LPTSTR                pOptItemName;
    WORD                  CallerVersion;
    WORD                  OptItemVersion;
    DWORD                 dwReserved[4];
} COMPROPSHEETUI, *PCOMPROPSHEETUI;

The COMPROPSHEETUI data structure contains the caller-specific data required by the CPSUI to construct and display the property sheet pages.

Members

cbSize

Size in bytes of this structure.

Flags

Bitmask in which the caller can set any combination of the following flags.

Value	Description
CPSUIF_UPDATE_PERMISSION	All valid items to which pOptItem points are changeable by the user.
CPSUIF_ICONID_AS_HICON	The CPSUI should interpret IconID as a handle to an icon rather than a resource ID.
CPSUIF_ABOUT_CALLBACK	If the end-user selects the About… button in the treeview tab, the CPSUI should call the callback to which pfnCallBack points with the Reason field of the pComPropSheetUICBParam parameter set to CPSUICB_REASON_ABOUT.

hInstCaller

Handle to the caller’s instance of itself. The CPSUI uses this handle to load the caller’s icon and other resources.

pCallerName

Pointer to a null-terminated string that specifies the name of the caller. This string is typically a driver’s name, such as “PostScript Driver”.

UserData

A 32-bit value that is defined and used by the caller. When the CPSUI calls pfnCallBack, it passes this member as the UserData field of the pComPropSheetUICBParam parameter. The CPSUI does not not modify this value.

pHelpFile

Pointer to a null-terminated string that specifies a standard Microsoft help file. This string must contain the complete path to the file. The HelpIndex field of the OPTITEM structure specifies the index location into the help file for the context string associated with the item.

pfnCallBack

Pointer to a _CPSUICALLBACK callback that is defined by the caller. The CPSUI calls this callback for various CPSUICB_REASON_Xxx reasons only when an OPTITEM’s OPTIF_CALLBACK bit is set.

pOptItem

Pointer to an array of OPTITEM structures that describe the option items to be displayed by the CPSUI.

pDlgPage

Pointer to an array of DLGPAGE structures that describe the characteristics of each property sheet page. The CPSUI has defined the following standard dialog boxes for use by the caller.

DLGPAGE	Description
CPSUI_PDLGPAGE_DOCPROP	The property sheet has two standard pages, whose tabs are Page Setup and Advanced. The Advanced page is a treeview.
CPSUI_PDLGPAGE_ADVDOCPROP	The property sheet has one treeview page whose tab reads Advanced.
CPSUI_PDLGPAGE_PRINTERPROP	The property sheet has one treeview page whose tab reads Device Settings. This page is a CPSUI-defined standard printer property sheet.
CPSUI_PDLGPAGE_TREEVIEWONLY	The property sheet has one treeview page.

cOptItem

Specifies the number of OPTITEM structures to which pOptItem points.

cDlgPage

Specifies the number of DLGPAGE structures to which pDlgPage points. The CPSUI ignores this field if pDlgPage specifies a standard CPSUI_PDLGPAGE_Xxx dialog box.

IconID

Identifies the icon to be displayed on the title bar of the property sheet page. This field can be a standard IDI_CPSUI_Xxx icon ID, a caller’s icon resource ID, or, if the CPSUIF_ICONID_AS_HICON bit is set in Flags, a handle to a caller-defined icon. If IconID is zero, the property sheet’s title bar does not have an icon associated with it.

pOptItemName

Pointer to a null-terminated string that identifies the root-level option item. This field is typically the device name, such as “HP 4si”.

CallerVersion

Specifies the caller’s version number. The high byte identifies the major version; the low byte is the minor version. For example, a CallerVersion value of 0x310 specifies a caller version number of 3.16.

OptItemVersion

Specifies the version number for the root-level option item. The high byte identifies the major version; the low byte is the minor version. For example, an OptItemVersion value of 0x3ff specifies a caller version number of 3.255.

dwReserved[4]

Reserved. These fields must be set to zero.

Comments

A COMPROPSHEETUI structure is initialized by the caller and passed to the CPSUI’s PFNCOMPROPSHEET callback as lParam1 when Function is CPSFUNC_ADD_PCOMPROPSHEETUI.

If the CPSUIF_ABOUT_CALLBACK bit is set in the Flags field, the callback to which pfnCallBack points must handle a user request to see the About dialog box. If this bit is not set, the CPSUI calls the Win32 ShellAbout function with the pCallerName and CallerVersion fields formatted as the szApp parameter, and pOptItemName and OptItemVersion formatted as the szOtherStuff parameter.

The CPSUI automatically modifies the DlgPageIdx fields of each OPTITEM when the user specifies CPSUI_PDLGPAGE_Xxx in pDlgPage.