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:

When DMPubID is DMPUB_COLOR, the CPSUI does the following before calling _CPSUICALLBACK if Color is selected over Gray Scale:

The CPSUI requires that Gray Scale be state 0 and Color be state 1.