OPTITEM 構造体 (compstui.h)

[アーティクル]
03/08/2023

OPTITEM 構造体は、ページが COMPROPSHEETUI 構造体によって記述されている場合に、プロパティシートページ上の 1 つのプロパティシートオプションを記述するために CPSUI アプリケーション (プリンターインターフェイス DLL を含む) によって使用されます。

構文

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 が 0 でない場合、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 を 0 に設定した 16 ビット文字列リソース識別子を指定することもできます。 (以下の DMPubID の説明も参照してください。

DUMMYUNIONNAME

DUMMYUNIONNAME.Sel

この共用体は、オプションの現在選択されているパラメーター値を示します。その使用法は、 CPSUI オプションの種類によって異なります。

pOptType が NULL の場合、オプションにはパラメーターがないため、この共用体は、オプションのツリービューノードに関連付けられるアイコンを識別します。アイコン識別子は、 フラグのOPTIF_SEL_AS_HICONで示されているように、アイコンハンドルまたはアイコンリソース識別子のいずれかになります。

DUMMYUNIONNAME.pSel

この共用体は、オプションの現在選択されているパラメーター値を示します。その使用法は、 CPSUI オプションの種類によって異なります。

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

ヘルプファイルのインデックス。オプションに関連付けるヘルプテキストを識別します。 0 の場合、このオプションのヘルプファイルテキストは存在しません。ヘルプテキスト機能が存在するためには、この構造体の pOIExt メンバーに OIEXT 構造体のアドレスを設定する必要があります。

DMPubID

このメンバーは、 Document Properties プロパティシートを作成するときに、プリンターインターフェイス 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

予約済み。は 0 に初期化する必要があります。

pOIExt

オプションの OIEXT 構造体へのポインター。呼び出し元は、この構造体にストレージを割り当てる役割を担います。

dwReserved[3]

予約済み。は 0 に初期化する必要があります。

注釈

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 と 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 は、ユーザーが複数のコピーを要求した場合にチェックボックスを有効にし、1 つのコピーのみが要求された場合に無効にします。

さらに、CPSUI は、オプションの表示テキストを 1 つの コピー 用にコピーし、複数のコピーに対 してコピー するように設定します。

DMPubID がDMPUB_COLOR場合、最初の OPTPARAM 構造体 (Sel=0) はグレースケールを表し、OPTPARAM 構造体の pData はIDS_CPSUI_GRAYSCALEする必要があります。その 2 番目の OPTPARAM 構造体 (Sel=1) は Color を表す必要があり、OPTPARAM 構造体の pData はIDS_CPSUI_COLORする必要があります。別のオプションの DMPubID がDMPUB_ICMINTENTされ、Color が選択されていない場合、CPSUI はDMPUB_ICMINTENTが指定されているオプションを無効にします。

[色] が選択されていない場合、CPSUI は色の一致を無効にします。

要件

要件	値
Header	compstui.h (Compstui.h を含む)