OPTITEM 结构 (compstui.h)

  • 项目

OPTITEM 结构由 CPSUI 应用程序使用， (包括打印机接口 DLL) ，用于描述属性表页上的一个属性表选项（如果页面由 COMPROPSHEETUI 结构描述）。

语法

typedef struct _OPTITEM {
  WORD      cbSize;
  BYTE      Level;
  BYTE      DlgPageIdx;
  DWORD     Flags;
  ULONG_PTR UserData;
  LPTSTR    pName;
  union {
    LONG   Sel;
    LPTSTR pSel;
  } DUMMYUNIONNAME;
  union {
    PEXTCHKBOX pExtChkBox;
    PEXTPUSH   pExtPush;
  } DUMMYUNIONNAME2;
  POPTTYPE  pOptType;
  DWORD     HelpIndex;
  BYTE      DMPubID;
  BYTE      UserItemID;
  WORD      wReserved;
  POIEXT    pOIExt;
  ULONG_PTR dwReserved[3];
} OPTITEM, *POPTITEM;

成员

cbSize

OPTITEM 结构的大小（以字节为单位）。

Level

在树视图中指定此选项的级别。 有关详细信息，请参阅下面的“备注”部分。

DlgPageIdx

标识选项所属的对话框。 指定由 COMPROPSHEETUI 结构的 pDlgPage 成员指向的 DLGPAGE 数组中的数组索引。

如果 pDlgPage 指向 CPSUI 提供的预定义 DLGPAGE 结构，则 CPSUI 将提供此索引。

Flags

修改选项特征的可选位标志。 OPTIF_CHANGEONCE标志由 CPSUI 设置;所有其他标志由调用方设置。 可以设置以下标志的任意组合。

OPTIF_CALLBACK

当用户修改选项时，CPSUI 应调用 COMPROPSHEETUI 结构中指定的_CPSUICALLBACK类型的回调函数。

OPTIF_CHANGED

如果_CPSUICALLBACK类型的回调函数修改了 选项，则应设置此标志，以便 CPSUI 重新显示它。

OPTIF_CHANGEONCE

如果用户修改了 选项，CPSUI 将设置此位。

OPTIF_COLLAPSE

折叠此选项及其子级，使其不会在树视图中展开。

OPTIF_DISABLED

禁用 选项，使其不可用户修改。

OPTIF_ECB_CHECKED

关联的扩展检查框处于选中状态。

OPTIF_EXT_IS_EXTPUSH

如果设置， 则 pExtPush 成员 (有效，除非 NULL) 。

如果未设置， 则 pExtChkBox 成员 (有效，除非 NULL) 。

OPTIF_EXT_DISABLED

扩展检查框或扩展按钮不可选择。

OPTIF_EXT_HIDE

CPSUI 不会显示扩展检查框或扩展按钮。

OPTIF_HAS_POIEXT

如果已设置， 则 pOIExt 成员有效。

OPTIF_HIDE

CPSUI 不会在树视图中显示此选项。 CPSUI 仅在最初创建树视图时检查此标志，因此从其初始值更改标志不起作用。

OPTIF_INITIAL_TVITEM

如果已设置，CPSUI 在显示树视图时将初始窗口焦点设置为此选项。 CPSUI 会展开树节点，并根据需要将选项滚动到视图中。 如果选项处于隐藏状态，或者未为任何 OPTITEM 结构设置此标志，CPSUI 将选择初始焦点。

OPTIF_NO_GROUPBOX_NAME

如果未设置，并且 pOptype 不为零，CPSUI 将使用 pName 字符串作为组框标题。

如果已设置，CPSUI 将提供组框标题。

OPTIF_OVERLAY_NO_ICON

如果设置 CPSUI，则将其IDI_CPSUI_NO图标覆盖到与 选项关联的图标上。 (请参阅 Sel/pSel 成员.)

OPTIF_OVERLAY_STOP_ICON

如果已设置，CPSUI 会将其IDI_CPSUI_STOP图标覆盖到与 选项关联的图标上。 (请参阅 Sel/pSel 成员.)

OPTIF_OVERLAY_WARNING_ICON

如果已设置，CPSUI 会将其IDI_CPSUI_WARNING图标覆盖到与 选项关联的图标上。 (请参阅 Sel/pSel 成员.)

OPTIF_SEL_AS_HICON

如果已设置， 则 Sel 成员包含图标句柄。

如果未设置， 则 Sel 成员包含图标资源标识符。

仅当 pOptType 包含 NULL 时，才能使用此标志。

UserData

可由调用方设置和使用的可选 32 位值。

(Unidrv 和 Pscript 的打印机接口 DLL 使用此成员提供指向 USERDATA 结构的指针。 用户界面插件 可以引用此结构。)

pName

表示本地化的可显示选项名称的字符串标识符。 这可以是指向以 NULL 结尾的字符串的 32 位指针，也可以是 HIWORD 设置为零的 16 位字符串资源标识符。 (另请参阅下面的 DMPubID 说明。)

DUMMYUNIONNAME

DUMMYUNIONNAME.Sel

此联合指示选项的当前所选参数值。 其用法取决于 CPSUI 选项类型。

如果 pOptType 为 NULL，则选项没有参数，因此此联合标识要与选项的树视图节点关联的图标。 图标标识符可以是图标句柄或图标资源标识符，如 标志中的OPTIF_SEL_AS_HICON所示。

DUMMYUNIONNAME.pSel

此联合指示选项的当前所选参数值。 其用法取决于 CPSUI 选项类型。

如果 pOptType 为 NULL，则选项没有参数，因此此联合标识要与选项的树视图节点关联的图标。 图标标识符可以是图标句柄或图标资源标识符，如 标志中的OPTIF_SEL_AS_HICON所示。

DUMMYUNIONNAME2

定义 DUMMYUNIONNAME2 联合。

DUMMYUNIONNAME2.pExtChkBox

指向 EXTCHKBOX 结构的指针

DUMMYUNIONNAME2.pExtPush

此联合可以是指向 EXTCHKBOX 结构的指针、指向 EXTPUSH 结构的指针或 NULL。

OPTITEM 结构可以选择具有 EXTCHKBOX 结构、EXTPUSH 结构，或者两者都不与之关联。 如果此联合不为 NULL，并且OPTIF_EXT_IS_EXTPUSH在 Flags 中设置， 则 pExtPush 有效。 如果未设置标志， 则 pExtChkBox 有效。

pOptType

指向描述选项显示类型的 OPTTYPE 结构的指针。 如果 为 NULL，则选项没有参数，并且用作具有较高 Level 值的父 级 选项。 子选项必须紧跟 OPTITEM 数组中的父选项。 (请参阅以下“备注”部分。)

HelpIndex

帮助文件索引，用于标识要与 选项关联的帮助文本。 如果为零，则此选项不存在帮助文件文本。 请注意，必须使用 OIEXT 结构的地址设置此结构的 pOIExt 成员，才能存在帮助文本功能。

DMPubID

此成员供打印机接口 DLL 使用，在创建 文档属性 属性表时 (请参阅 DrvDocumentPropertySheets) 。 它是一个常量值，指定 DEVMODEW 结构的公共成员（如果有）与此选项相关联。 下表列出了可用常量、关联的 DEVMODE 结构成员，以及每个常量 pName 的必需值。

常量值 必需的 pName 值 结构成员
DMPUB_COLOR dmColor IDS_CPSUI_COLOR_APPERANCE
DMPUB_COPIES_COLLATE dmCopies 和 dmCollate IDS_CPSUI_COPIES
DMPUB_DEFSOURCE dmDefSource IDS_CPSUI_SOURCE
DMPUB_DITHERTYPE dmDitherType IDS_CPSUI_DITHERING
DMPUB_DUPLEX dmDuplex IDS_CPSUI_DUPLEX
DMPUB_FORMNAME dmFormName IDS_CPSUI_FORMNAME
DMPUB_ICMINTENT dmICMIntent IDS_CPSUI_ICMINTENT
DMPUB_ICMMETHOD dmICMMethod IDS_CPSUI_ICMMETHOD
DMPUB_MEDIATYPE dmMediaType IDS_CPSUI_MEDIA
DMPUB_NUP 未包含在 DEVMODE 的公共部分中。 IDS_CPSUI_NUP
DMPUB_ORIENTATION dmOrientation IDS_CPSUI_ORIENTATION
DMPUB_OUTPUTBIN 未包含在 DEVMODE 的公共部分中。 IDS_CPSUI_OUTPUTBIN
DMPUB_PAGEORDER 未包含在 DEVMODE 的公共部分中。 IDS_CPSUI_PAGEORDER
DMPUB_PRINTQUALITY dmPrintQuality IDS_CPSUI_PRINTQUALITY或IDS_CPSUI_RESOLUTION。 如果未指定，则默认名称为 IDS_CPSUI_RESOLUTION。
DMPUB_QUALITY 未包含在 DEVMODE 的公共部分中。 IDS_CPSUI_QUALITY_SETTINGS
DMPUB_SCALE dmScale IDS_CPSUI_SCALE
DMPUB_TTOPTION dmTTOption IDS_CPSUI_TTOPTION
DMPUB_NONE 未包含在 DEVMODE 的公共部分中。
大于或等于 DMPUB_USER 被 CPSUI 忽略，可以是调用方定义的值。

CPSUI 不维护 DEVMODE 结构。 应用程序负责将用户选择的选项参数复制到 DEVMODE 结构中。 CPSUI 使用 DMPubID 内容来确定标准选项的树视图位置，并确定“布局”和“纸张/质量”选项卡的内容 (请参阅 COMPROPSHEETUI 结构的 pDlgPage 成员) 。

有关使用 DMPubID 成员的其他信息，请参阅以下“备注”部分。

UserItemID

应用程序提供的可选值，可用于选项标识目的。 CPSUI 未引用。

wReserved

保留，必须初始化为零。

pOIExt

指向可选 OIEXT 结构的指针。 调用方负责为此结构分配存储。

dwReserved[3]

保留，必须初始化为零。

注解

OPTITEM 结构应放置在数组中，数组的地址应放置在 COMPROPSHEETUI 结构的 pOptItem 成员中。

Level 成员允许在树视图中创建子节点。 例如，若要在级别 1 父节点下创建一组选项节点，请为每个子节点指定级别 2，并将其 OPTITEM 结构包含在 OPTITEM 数组中，紧接在父节点的 OPTITEM 结构之后。 在父级的 OPTITEM 结构中， pOptType 应为 NULL。

树视图根节点为级别 0。 当用户展开根节点时显示的选项为级别 1。 最大级别数为 256。

对于存储在打印机 DEVMODE 结构中的选项值， DMPubID 成员必须标识该选项。 对于使用的每个 DMPubID 值，打印机接口 DLL 必须指定下表中列出的 CPSUI 选项类型 。

DMPubID 值 必需的 CPSUI 选项类型
DMPUB_COLOR TVOT_2STATES
DMPUB_COPIES_COLLATE TVOT_UDARROW plus EXTCHKBOX (请参阅下表后面的注释。)
DMPUB_DEFSOURCE TVOT_LISTBOX
DMPUB_DITHERTYPE TVOT_LISTBOX
DMPUB_DUPLEX TVOT_2STATES 或 TVOT_3STATES
DMPUB_FORMNAME TVOT_LISTBOX
DMPUB_ICMINTENT TVOT_2STATES 或 TVOT_3STATES
DMPUB_ICMMETHOD TVOT_2STATES 或 TVOT_3STATES
DMPUB_MEDIATYPE TVOT_LISTBOX
DMPUB_NUP TVOT_LISTBOX
DMPUB_ORIENTATION TVOT_2STATES 或 TVOT_3STATES
DMPUB_OUTPUTBIN TVOT_LISTBOX
DMPUB_PAGEORDER TVOT_2STATES 或 TVOT_3STATES
DMPUB_PRINTQUALITY TVOT_LISTBOX
DMPUB_QUALITY TVOT_2STATES 或 TVOT_3STATES
DMPUB_SCALE TVOT_UDARROW
DMPUB_TTOPTION TVOT_LISTBOX

如果 DMPubID 是DMPUB_COPIES_COLLATE并且打印机可以整理副本，则必须提供扩展检查框 (EXTCHKBOX 结构) 。 必须按如下所示设置 EXTCHCKBOX 结构的成员：

pExtCheckbox->cbSize = sizeof(EXTCHKBOX);
pExtCheckbox->pTitle = (PWSTR) IDS_CPSUI_COLLATE;
pExtCheckbox->pCheckedName = (PWSTR) IDS_CPSUI_COLLATED;
pExtCheckbox->IconID = IDI_CPSUI_COLLATE;
pExtCheckbox->Flags = ECBF_CHECKNAME_ONLY_ENABLED;
pExtCheckbox->pSeparator = (PWSTR)IDS_CPSUI_SLASH_SEP;

如果未在“标志”中设置OPTIF_EXT_HIDE，则当用户请求多个副本时，CPSUI 将启用“检查”框;如果只请求一个副本，则禁用它。

此外，CPSUI 将选项的显示文本设置为为一个副本复制，为多个副本复制。

如果 DMPubID 是DMPUB_COLOR，则其第一个 OPTPARAM 结构 (Sel=0) 必须表示灰度，并且 OPTPARAM 结构中的 pData 必须IDS_CPSUI_GRAYSCALE。 其第二个 OPTPARAM 结构 (Sel=1) 必须表示 Color，并且 OPTPARAM 结构中的 pData 必须IDS_CPSUI_COLOR。 如果另一选项的 DMPubID DMPUB_ICMINTENT并且未选择 Color，则 CPSUI 将禁用指定DMPUB_ICMINTENT的选项。

CPSUI 在未选择“颜色”时禁用颜色匹配。

要求

要求 值
Header compstui.h (包括 Compstui.h)