OPTITEM-Struktur (compstui.h)

Artikel
08/07/2023

Die OPTITEM-Struktur wird von CPSUI-Anwendungen (einschließlich Druckerschnittstellen-DLLs) zum Beschreiben einer Eigenschaftenblattoption auf einer Eigenschaftenblattseite verwendet, wenn die Seite durch eine COMPROPSHEETUI-Struktur beschrieben wird.

Syntax

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;

Member

cbSize

Größe der OPTITEM-Struktur in Bytes.

Level

Gibt die Ebene dieser Option in der Strukturansicht an. Weitere Informationen finden Sie weiter unten im Abschnitt Hinweise.

DlgPageIdx

Gibt das Dialogfeld an, zu dem die Option gehört. Gibt einen Arrayindex in das DLGPAGE-Array an, auf das das pDlgPage-Element der COMPROPSHEETUI-Struktur verweist.

Wenn pDlgPage auf eine von CPSUI bereitgestellte, vordefinierte DLGPAGE-Struktur verweist, stellt CPSUI diesen Index bereit.

Flags

Optionale Bitflags, die die Eigenschaften der Option ändern. Das OPTIF_CHANGEONCE-Flag wird von CPSUI festgelegt. alle anderen Flags werden vom Aufrufer festgelegt. Es kann eine beliebige Kombination der folgenden Flags festgelegt werden.

OPTIF_CALLBACK

Wenn ein Benutzer die Option ändert, sollte CPSUI die _CPSUICALLBACK-typisierte Rückruffunktion aufrufen, die in der COMPROPSHEETUI-Struktur angegeben ist.

OPTIF_CHANGED

Die _CPSUICALLBACK-typisierte Rückruffunktion sollte dieses Flag festlegen, wenn sie die Option geändert hat, damit CPSUI sie erneut anzeigt.

OPTIF_CHANGEONCE

CPSUI legt dieses Bit fest, wenn ein Benutzer die Option geändert hat.

OPTIF_COLLAPSE

Reduzieren Sie diese Option und ihre untergeordneten Elemente, sodass sie nicht in der Strukturansicht erweitert wird.

OPTIF_DISABLED

Deaktiviert die Option, sodass sie nicht vom Benutzer geändert werden kann.

OPTIF_ECB_CHECKED

Das zugehörige erweiterte Kontrollkästchen befindet sich im aktivierten Zustand.

OPTIF_EXT_IS_EXTPUSH

Wenn festgelegt, ist der pExtPush-Member gültig (außer NULL).

Wenn nicht festgelegt, ist das pExtChkBox-Element gültig (außer NULL).

OPTIF_EXT_DISABLED

Das erweiterte Kontrollkästchen oder die erweiterte Drucktaste kann nicht ausgewählt werden.

OPTIF_EXT_HIDE

CPSUI zeigt weder das erweiterte Kontrollkästchen noch die erweiterte Schaltfläche an.

OPTIF_HAS_POIEXT

Wenn festgelegt, ist der pOIExt-Member gültig.

OPTIF_HIDE

CPSUI zeigt diese Option nicht in der Strukturansicht an. CPSUI untersucht dieses Flag nur beim anfänglichen Erstellen der Strukturansicht, sodass das Ändern des Flags vom Anfangswert keine Auswirkungen hat.

OPTIF_INITIAL_TVITEM

Falls festgelegt, legt CPSUI den Anfänglichen Fensterfokus auf diese Option fest, wenn die Strukturansicht angezeigt wird. CPSUI erweitert Strukturknoten und scrollt die Option nach Bedarf in die Ansicht. Wenn die Option ausgeblendet ist oder dieses Flag für keine OPTITEM-Struktur festgelegt ist, wählt CPSUI den anfänglichen Fokus.

OPTIF_NO_GROUPBOX_NAME

Wenn nicht festgelegt ist und pOptype nicht 0 ist, verwendet CPSUI die pName-Zeichenfolge als Gruppenboxtitel.

Falls festgelegt, stellt CPSUI einen Groupbox-Titel bereit.

OPTIF_OVERLAY_NO_ICON

Wenn set CPSUI sein IDI_CPSUI_NO Symbol auf das der Option zugeordnete Symbol überlagert. (Siehe Sel/pSel-Member .)

OPTIF_OVERLAY_STOP_ICON

Falls festgelegt, überlagert CPSUI sein IDI_CPSUI_STOP-Symbol mit dem der Option zugeordneten Symbol. (Siehe Sel/pSel-Member .)

OPTIF_OVERLAY_WARNING_ICON

Falls festgelegt, überlagert CPSUI sein IDI_CPSUI_WARNING-Symbol mit dem der Option zugeordneten Symbol. (Siehe Sel/pSel-Member .)

OPTIF_SEL_AS_HICON

Wenn festgelegt, enthält das Sel-Element ein Symbolhandle.

Falls nicht festgelegt, enthält das Sel-Element einen Symbolressourcenbezeichner.

Dieses Flag kann nur verwendet werden, wenn pOptTypeNULL enthält.

UserData

Optionaler 32-Bit-Wert, der vom Aufrufer festgelegt und verwendet werden kann.

(Druckerschnittstellen-DLLs für Unidrv und Pscript verwenden diesen Member, um einen Zeiger auf eine USERDATA-Struktur anzugeben. Benutzeroberflächen-Plug-Ins können auf diese Struktur verweisen.)

pName

Zeichenfolgenbezeichner, der einen lokalisierten, anzeigebaren Optionsnamen darstellt. Dies kann ein 32-Bit-Zeiger auf eine NULL-beendete Zeichenfolge oder ein 16-Bit-Zeichenfolgenressourcenbezeichner sein, wobei HIWORD auf 0 festgelegt ist. (Siehe auch die Beschreibung von DMPubID unten.)

DUMMYUNIONNAME

DUMMYUNIONNAME.Sel

Diese Union gibt den aktuell ausgewählten Parameterwert der Option an. Die Verwendung ist vom CPSUI-Optionstyp abhängig.

Wenn pOptTypeNULL ist, enthält die Option keine Parameter, sodass diese Union ein Symbol identifiziert, das dem Treeview-Knoten für die Option zugeordnet werden soll. Der Symbolbezeichner kann entweder ein Symbolhandle oder ein Symbolressourcenbezeichner sein, wie durch OPTIF_SEL_AS_HICON in Flags angegeben.

DUMMYUNIONNAME.pSel

Diese Union gibt den aktuell ausgewählten Parameterwert der Option an. Die Verwendung ist vom CPSUI-Optionstyp abhängig.

DUMMYUNIONNAME2

Definiert die DUMMYUNIONNAME2 Union.

DUMMYUNIONNAME2.pExtChkBox

Zeiger auf die EXTCHKBOX-Struktur

DUMMYUNIONNAME2.pExtPush

Diese Union kann ein Zeiger auf eine EXTCHKBOX-Struktur , ein Zeiger auf eine EXTPUSH-Struktur oder NULL sein.

Einer OPTITEM-Struktur kann optional eine EXTCHKBOX-Struktur, eine EXTPUSH-Struktur oder keines zugeordnet sein. Wenn diese Union nicht NULL ist und OPTIF_EXT_IS_EXTPUSH in Flags festgelegt ist, ist pExtPush gültig. Wenn das Flag nicht festgelegt ist, ist pExtChkBox gültig.

pOptType

Zeiger auf eine OPTTYPE-Struktur , die den Anzeigetyp der Option beschreibt. Bei NULL enthält die Option keine Parameter und wird als übergeordnetes Element für Optionen mit einem höheren Level-Wert verwendet. Die untergeordneten Optionen müssen sofort dem übergeordneten Element im OPTITEM-Array folgen. (Weitere Informationen finden Sie im folgenden Abschnitt mit den Anmerkungen.)

HelpIndex

Hilfedateiindex, der den Hilfetext identifiziert, der der Option zugeordnet werden soll. Wenn null, ist der Text der Hilfedatei für diese Option nicht vorhanden. Beachten Sie, dass das pOIExt-Element dieser Struktur mit der Adresse einer OIEXT-Struktur festgelegt werden muss, damit die Hilfetextfunktionalität vorhanden ist.

DMPubID

Dieses Element ist für die Verwendung durch Druckerschnittstellen-DLLs beim Erstellen eines Dokumenteigenschafteneigenschaften-Eigenschaftenblatts vorgesehen (siehe DrvDocumentPropertySheets). Es handelt sich um einen konstanten Wert, der angibt, welches öffentliche Element der DEVMODEW-Struktur dieser Option zugeordnet ist, falls vorhanden. In der folgenden Tabelle sind verfügbare Konstanten, der zugeordnete DEVMODE-Strukturmember und der erforderliche Wert für pName für jede Konstante aufgeführt.

Konstanter Wert	Erforderlicher pName-Wert	Strukturelement
DMPUB_COLOR	dmColor	IDS_CPSUI_COLOR_APPERANCE
DMPUB_COPIES_COLLATE	dmCopies und 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	Nicht im öffentlichen Abschnitt von DEVMODE enthalten.	IDS_CPSUI_NUP
DMPUB_ORIENTATION	dmOrientation	IDS_CPSUI_ORIENTATION
DMPUB_OUTPUTBIN	Nicht im öffentlichen Abschnitt von DEVMODE enthalten.	IDS_CPSUI_OUTPUTBIN
DMPUB_PAGEORDER	Nicht im öffentlichen Abschnitt von DEVMODE enthalten.	IDS_CPSUI_PAGEORDER
DMPUB_PRINTQUALITY	dmPrintQuality	IDS_CPSUI_PRINTQUALITY oder IDS_CPSUI_RESOLUTION. Wenn nicht angegeben, lautet der Standardname IDS_CPSUI_RESOLUTION.
DMPUB_QUALITY	Nicht im öffentlichen Abschnitt von DEVMODE enthalten.	IDS_CPSUI_QUALITY_SETTINGS
DMPUB_SCALE	dmScale	IDS_CPSUI_SCALE
DMPUB_TTOPTION	dmTTOption	IDS_CPSUI_TTOPTION
DMPUB_NONE	Nicht im öffentlichen Abschnitt von DEVMODE enthalten.
Größer als oder gleich DMPUB_USER	Von CPSUI ignoriert, kann ein vom Aufrufer definierter Wert sein.

CPSUI verwaltet keine DEVMODE-Struktur. Die Anwendung ist für das Kopieren von vom Benutzer ausgewählten Optionsparametern in eine DEVMODE-Struktur verantwortlich. CPSUI verwendet DMPubID-Inhalte , um die Treeview-Platzierung von Standardoptionen zu bestimmen und den Inhalt der Registerkarten Layout und Papier/Qualität zu bestimmen (siehe pDlgPage-Member der COMPROPSHEETUI-Struktur ).

Weitere Informationen zur Verwendung des DMPubID-Members finden Sie im folgenden Abschnitt Hinweise.

UserItemID

Optionaler Anwendungswert, der für Optionsidentifikationszwecke verwendet werden kann. Nicht von CPSUI referenziert.

wReserved

Reserviert, muss mit 0 initialisiert werden.

pOIExt

Zeiger auf eine optionale OIEXT-Struktur . Der Aufrufer ist für die Zuweisung von Speicher für diese Struktur verantwortlich.

dwReserved[3]

Reserviert, muss mit 0 initialisiert werden.

Hinweise

OPTITEM-Strukturen sollten in einem Array platziert werden, und die Adresse des Arrays sollte im pOptItem-Member einer COMPROPSHEETUI-Struktur platziert werden.

Mit dem Level-Member können Sie untergeordnete Knoten in der Strukturansicht erstellen. Wenn Sie beispielsweise einen Satz von Optionsknoten unter einem übergeordneten Knoten der Ebene 1 erstellen möchten, geben Sie ebene 2 für jeden untergeordneten Knoten an, und schließen Sie die zugehörigen OPTITEM-Strukturen direkt nach der OPTITEM-Struktur des übergeordneten Arrays ein. In der OPTITEM-Struktur des übergeordneten Elements sollte pOptTypeNULL sein.

Der Treeview-Stammknoten ist Ebene 0. Die Optionen, die angezeigt werden, wenn ein Benutzer den Stammknoten erweitert, sind Ebene 1. Die maximale Anzahl von Ebenen ist 256.

Für Optionswerte, die in der DEVMODE-Struktur eines Druckers gespeichert sind, muss das DMPubID-Element die Option identifizieren. Für jeden verwendeten DMPubID-Wert muss eine Druckerschnittstellen-DLL den in der folgenden Tabelle aufgeführten CPSUI-Optionstyp angeben.

DMPubID-Wert	Erforderlicher CPSUI-Optionstyp
DMPUB_COLOR	TVOT_2STATES
DMPUB_COPIES_COLLATE	TVOT_UDARROW plus EXTCHKBOX (Siehe Kommentare nach dieser Tabelle.)
DMPUB_DEFSOURCE	TVOT_LISTBOX
DMPUB_DITHERTYPE	TVOT_LISTBOX
DMPUB_DUPLEX	TVOT_2STATES oder TVOT_3STATES
DMPUB_FORMNAME	TVOT_LISTBOX
DMPUB_ICMINTENT	TVOT_2STATES oder TVOT_3STATES
DMPUB_ICMMETHOD	TVOT_2STATES oder TVOT_3STATES
DMPUB_MEDIATYPE	TVOT_LISTBOX
DMPUB_NUP	TVOT_LISTBOX
DMPUB_ORIENTATION	TVOT_2STATES oder TVOT_3STATES
DMPUB_OUTPUTBIN	TVOT_LISTBOX
DMPUB_PAGEORDER	TVOT_2STATES oder TVOT_3STATES
DMPUB_PRINTQUALITY	TVOT_LISTBOX
DMPUB_QUALITY	TVOT_2STATES oder TVOT_3STATES
DMPUB_SCALE	TVOT_UDARROW
DMPUB_TTOPTION	TVOT_LISTBOX

Wenn DMPubID DMPUB_COPIES_COLLATE ist und der Drucker Kopien sortieren kann, muss ein erweitertes Kontrollkästchen (EXTCHKBOX-Struktur ) bereitgestellt werden. Die Member der EXTCHCKBOX-Struktur müssen wie folgt festgelegt werden:

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;

Wenn OPTIF_EXT_HIDE nicht in Flags festgelegt ist, aktiviert CPSUI das Kontrollkästchen, wenn ein Benutzer mehrere Kopien anfordert, und deaktiviert es, wenn nur eine Kopie angefordert wird.

Darüber hinaus legt CPSUI fest, dass der Anzeigetext der Option für eine Kopie undfür mehrere Kopien kopiert werden soll.

Wenn DMPubID DMPUB_COLOR ist, muss die erste OPTPARAM-Struktur (Sel=0) graue Skala darstellen, und pData in der OPTPARAM-Struktur muss IDS_CPSUI_GRAYSCALE sein. Die zweite OPTPARAM-Struktur (Sel=1) muss Color darstellen, und pData in der OPTPARAM-Struktur muss IDS_CPSUI_COLOR sein. Wenn die DMPubID einer anderen Option DMPUB_ICMINTENT ist und Farb nicht ausgewählt ist, deaktiviert CPSUI die Option, für die DMPUB_ICMINTENT angegeben ist.

CPSUI deaktiviert den Farbabgleich, wenn Farbe nicht ausgewählt ist.

Anforderungen

Anforderung	Wert
Header	compstui.h (einschließlich Compstui.h)