typedef struct _OPTITEM {
WORD cbSize;
BYTE Level;
BYTE DlgPageIdx;
DWORD Flags;
DWORD UserData;
LPTSTR pName;
union {
LONG Sel;
LPTSTR pSel;
};
union {
PEXTCHKBOX pExtChkBox;
PEXTPUSH pExtPush;
};
POPTTYPE pOptType;
DWORD HelpIndex;
BYTE DMPubID;
BYTE UserItemID;
WORD wReserved;
POIEXT pOIExt;
DWORD dwReserved[3];
} OPTITEM, *POPTITEM;
The OPTITEM structure is used to describe each item's name, selection type, and selectability in the dialog box view(s).
Members
cbSize
Size in bytes of this structure.
Level
Specifies the level of this item in the treeview. The root item should have the lowest level, and numbering should start at zero. The maximum number of levels is 256.
DlgPageIdx
Specifies a zero-based index into the array of DLGPAGE structures pointed to by the pDlgPage member of the COMPROPSHEETUI structure. The maximum index possible is MAX_DLGPAGE_COUNT. The CPSUI sets DlgPageIdx if pDlgPage is a standard CPSUI_PDLGPAGE_Xxx DLGPAGE.
Flags
Specifies the flags to apply to the option item identified by this OPTITEM structure. The OPTIF_CHANGEONCE flag is set by the CPSUI; all other flags are set by the caller. Any combination of the following flags can be set in Flags.
Flag | Description |
OPTIF_COLLAPSE | Collapse this treeview item and its children so that it is not expanded initially. |
OPTIF_HIDE | Hide this item from the treeview. The OPTIF_HIDE flag must be set before the item is initially displayed; the CPSUI ignores this bit if it is set after the item is displayed. |
OPTIF_CALLBACK | The CPSUI should call back to the caller-supplied _CPSUICALLBACK function when a user changes this item. |
OPTIF_CHANGED | This item has changed and needs to be redisplayed. The caller should set this flag only when returning from its _CPSUICALLBACK callback. |
OPTIF_CHANGEONCE | This item has been changed. The CPSUI sets this bit. |
OPTIF_DISABLED | This item is not selectable. |
OPTIF_ECB_CHECKED | The associated extended check box is in the checked state. |
OPTIF_EXT_HIDE | Hide the extended check box or extended push button. |
OPTIF_EXT_DISABLED | The extended check box or extended push button is not selectable. |
OPTIF_SEL_AS_HICON | The Sel field contains a handle to an icon rather than an icon resource ID. The CPSUI uses this flag only when pOptType is null. |
OPTIF_EXT_ IS_EXTPUSH |
The CPSUI should use the pExtPush field if it is not null. By default, if the union field contains a valid pointer and the OPTIF_EXT_IS_EXTPUSH bit is not set, the CPSUI assumes that the pointer points to an EXTCHKBOX structure. |
OPTIF_NO_ GROUPBOX_NAME |
The CPSUI should not overwrite the group box's title text if a group box ID is defined. |
OPTIF_OVERLAY_ WARNING_ICON |
The CPSUI overlays its IDI_CPSUI_WARNING icon on the icon associated with this option item. |
OPTIF_OVERLAY_ STOP_ICON |
The CPSUI overlays its IDI_CPSUI_STOP icon on the icon associated with this option item. |
OPTIF_OVERLAY_ NO_ICON |
The CPSUI overlays its IDI_CPSUI_NO icon on the icon associated with this option item. |
OPTIF_INITIAL_TVITEM | This item is the initial item to be selected and displayed on the treeview page. The CPSUI expands tree tiers and scrolls the selection into view as necessary. If this bit is not set or if the item is hidden, the CPSUI chooses the initial item to display. |
OPTIF_HAS_POIEXT | The pOIExt field contains a valid pointer to an OIEXT structure. The CPSUI uses the OIEXT structure only when this bit is set. |
UserData
Specifies a 32-bit value that is set and used by the caller. The CPSUI never uses or modifies this member.
pName
Pointer to a null-terminated string that specifies the name of this option item. Alternatively, it is used as data as described in the DMPubID member.
Sel
Specifies the index number for this item's current selection. If pOptType is null, then this index number is the icon ID to be used for the non-selectable header of child option items.
pSel
Pointer to a null-terminated string that specifies the current selection for this item.
pExtChkBox
Pointer to the EXTCHKBOX structure that describes the extended check box associated with this item. If pExtChkBox is null, then this item does not have a check box associated with it.
The caller must clear the OPTIF_EXT_IS_EXTPUSH flag to notify the CPSUI that the option item has an extended check box associated with it. The OPTIF_ECB_CHECKED flag specifies whether the extended check box is checked or not checked.
pExtPush
Pointer to the EXTPUSH structure that describes the extended push button associated with this item. If pExtPush is null, then this item does not have a push button associated with it. The caller must set the OPTIF_EXT_IS_EXTPUSH flag to notify the CPSUI that the option item has an extended push button associated with it.
pOptType
Pointer to an OPTTYPE structure that describes the display and selections of this item. This item has no selection(s) when pOptType is null, so the CPSUI uses this item as the header for child items. When pOptType is null, the icon ID is specified by Sel.
HelpIndex
Specifies the index into the help file being used for context-sensitive help. A value of zero indicates that help does not exist for this item.
DMPubID
Specifies whether this item is one of the public fields in the DEVMODE structure supported by the CPSUI. For consistency, the caller should set pName to the standard CPSUI-defined resource ID for those DMPUB_Xxx values that identify DEVMODE fields. This field can be one of the following values.
Value | DEVMODE Field and Recommended pName |
DMPUB_NONE | Not a public field of DEVMODE. |
DMPUB_ORIENTATION | The dmOrientation field. Set pName to IDS_CPSUI_ORIENTATION. |
DMPUB_SCALE | The dmScale field. Set pName to IDS_CPSUI_SCALE. |
DMPUB_COPIES_COLLATE | The dmCopies / dmCollate field. Set pName to IDS_CPSUI_COPIES. |
DMPUB_DEFSOURCE | The dmDefSource field. Set pName to IDS_CPSUI_SOURCE. |
DMPUB_PRINTQUALITY | The dmPrintQuality field. Set pName to IDS_CPSUI_PRINTQUALITY or IDS_CPSUI_RESOLUTION. If pName is not set to either of these values, the CPSUI defaults it to IDS_CPSUI_RESOLUTION. |
DMPUB_COLOR | The dmColor field. Set pName to IDS_CPSUI_COLOR_APPERANCE. |
DMPUB_DUPLEX | The dmDuplex field. Set pName to IDS_CPSUI_DUPLEX. |
DMPUB_TTOPTION | The dmTTOption field. Set pName to IDS_CPSUI_TTOPTION. |
DMPUB_FORMNAME | The dmFormName field. Set pName to IDS_CPSUI_FORMNAME. |
DMPUB_ICMMETHOD | The dmICMMethod field. Set pName to IDS_CPSUI_ICMMETHOD. |
DMPUB_ICMINTENT | The dmICMIntent field. Set pName to IDS_CPSUI_ICMINTENT. |
DMPUB_MEDIATYPE | The dmMediaType field. Set pName to IDS_CPSUI_MEDIA. |
DMPUB_DITHERTYPE | The dmDitherType field. Set pName to IDS_CPSUI_DITHERING. |
Greater than or equal to DMPUB_USER | Specifies a caller-defined value. |
UserItemID
Specifies a caller-defined byte ID. The caller can use UserItemID to identify this item.
wReserved
Reserved; this field must be set to zero.
pOIExt
Pointer to an OIEXT structure containing extended data to describe this option item.
dwReserved[3]
Reserved; these fields must be set to zero.
Comments
The OPTITEM structure is used to describe each item's name, selection type, and selectability in the dialog box view(s).
When the CPSUI is called to construct and display the Document Properties page, it automatically groups many of the DEVMODE's public items together. The grouping is CPSUI version-dependent, and cannot be altered by the caller.
When DMPubID is DMPUB_COPIES_COLLATE, the CPSUI does the following before calling the _CPSUICALLBACK callback if the OPTIF_EXT_HIDE flag is not set and pExtChkBox is not null:
·Enable the Collate Copies extended check box when a user requests more than one copy, and disable it when only one copy is requested.
·Set the item's postfix to copy for one copy and copies for more than one copy.
When DMPubID is DMPUB_COLOR, the CPSUI does the following before calling _CPSUICALLBACK if Color is selected over Gray Scale:
·Calls the halftone color adjustment with the current color selection.
·Disables color matching when color is not selected.
The CPSUI requires that Gray Scale be state 0 and Color be state 1.