OPTITEM

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.