STRUCTURE OPTITEM (compstui.h)

La structure OPTITEM est utilisée par les applications CPSUI (y compris les DLL d’interface d’imprimante) pour décrire une option de feuille de propriétés sur une page de feuille de propriétés, si la page est décrite par une structure COMPROPSHEETUI.

Syntaxe

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;

Membres

cbSize

Taille, en octets, de la structure OPTITEM.

Level

Spécifie le niveau de cette option dans l’arborescence. Pour plus d’informations, consultez la section Remarques ci-dessous.

DlgPageIdx

Identifie la boîte de dialogue à laquelle appartient l’option. Spécifie un index de tableau dans le tableau DLGPAGE pointé par le membre pDlgPage de la structure COMPROPSHEETUI.

Si pDlgPage pointe vers une structure DLGPAGE fournie par cpSUI, le CPSUI fournit cet index.

Flags

Indicateurs de bits facultatifs qui modifient les caractéristiques de l’option. L’indicateur OPTIF_CHANGEONCE est défini par CPSUI ; tous les autres indicateurs sont définis par l’appelant. Toute combinaison des indicateurs suivants peut être définie.

OPTIF_CALLBACK

Lorsqu’un utilisateur modifie l’option, CPSUI doit appeler la fonction de rappel _CPSUICALLBACK-typée spécifiée dans la structure COMPROPSHEETUI.

OPTIF_CHANGED

La fonction de rappel _CPSUICALLBACK-typée doit définir cet indicateur s’il a modifié l’option, de sorte que CPSUI la réaffiche.

OPTIF_CHANGEONCE

CPSUI définit ce bit si un utilisateur a modifié l’option.

OPTIF_COLLAPSE

Réduisez cette option et ses enfants afin qu’elle ne soit pas développée dans l’arborescence.

OPTIF_DISABLED

Désactive l’option afin qu’elle ne soit pas modifiable par l’utilisateur.

OPTIF_ECB_CHECKED

La case à cocher étendue associée est dans l’état activé.

OPTIF_EXT_IS_EXTPUSH

Si la valeur est définie, le membre pExtPush est valide (sauf si NULL).

S’il n’est pas défini, le membre pExtChkBox est valide (sauf si NULL).

OPTIF_EXT_DISABLED

La case à cocher étendue ou le bouton Push étendu n’est pas sélectionnable.

OPTIF_EXT_HIDE

CPSUI n’affiche pas la case à cocher étendue ou le bouton Push étendu.

OPTIF_HAS_POIEXT

Si elle est définie, le membre pOIExt est valide.

OPTIF_HIDE

CPSUI n’affiche pas cette option dans l’arborescence. CPSUI examine cet indicateur uniquement lors de la création initiale de l’arborescence. Par conséquent, la modification de l’indicateur de sa valeur initiale n’a aucun effet.

OPTIF_INITIAL_TVITEM

Si elle est définie, CPSUI définit le focus de la fenêtre initiale sur cette option lorsqu’elle affiche l’arborescence. CPSUI développe les nœuds d’arborescence et fait défiler l’option en mode affichage si nécessaire. Si l’option est masquée ou si cet indicateur n’est pas défini pour une structure OPTITEM, CPSUI choisit le focus initial.

OPTIF_NO_GROUPBOX_NAME

S’il n’est pas défini et pOptype n’est pas égal à zéro, CPSUI utilise la chaîne pName comme titre de la zone de groupe.

Si elle est définie, CPSUI fournit un titre de zone de groupe.

OPTIF_OVERLAY_NO_ICON

Si la définition de CPSUI superpose son icône de IDI_CPSUI_NO sur l’icône associée à l’option. (Consultez le membre Sel/pSel.)

OPTIF_OVERLAY_STOP_ICON

Si cette option est définie, CPSUI superpose son icône de IDI_CPSUI_STOP sur l’icône associée à l’option. (Consultez le membre Sel/pSel.)

OPTIF_OVERLAY_WARNING_ICON

Si cette option est définie, CPSUI superpose son icône de IDI_CPSUI_WARNING sur l’icône associée à l’option. (Consultez le membre Sel/pSel.)

OPTIF_SEL_AS_HICON

Si elle est définie, le membre Sel contient un handle d’icône.

Si ce n’est pas le cas, le membre Sel contient un identificateur de ressource d’icône.

Cet indicateur ne peut être utilisé que lorsque pOptType contient NULL.

UserData

Valeur 32 bits facultative qui peut être définie et utilisée par l’appelant.

(DLL de l’interface d’imprimante pour unidrv et Pscript utiliser ce membre pour fournir un pointeur vers une structure USERDATA. plug-ins d’interface utilisateur pouvez référencer cette structure.)

pName

Identificateur de chaîne représentant un nom d’option localisé et affichable. Il peut s’agir d’un pointeur 32 bits vers une chaîne terminée par NULL, ou il peut s’agir d’un identificateur de ressource de chaîne 16 bits, avec HIWORD défini sur zéro. (Consultez également la description de DMPubID, ci-dessous.)

DUMMYUNIONNAME

DUMMYUNIONNAME.Sel

Cette union indique la valeur de paramètre actuellement sélectionnée de l’option. Son utilisation dépend du type d’option CPSUI.

Si pOptType est NULL, l’option n’a aucun paramètre. Cette union identifie donc une icône à associer au nœud treeview de l’option. L’identificateur d’icône peut être un handle d’icône ou un identificateur de ressource d’icône, comme indiqué par OPTIF_SEL_AS_HICON dans indicateurs.

DUMMYUNIONNAME.pSel

Cette union indique la valeur de paramètre actuellement sélectionnée de l’option. Son utilisation dépend du type d’option CPSUI.

Si pOptType est NULL, l’option n’a aucun paramètre. Cette union identifie donc une icône à associer au nœud treeview de l’option. L’identificateur d’icône peut être un handle d’icône ou un identificateur de ressource d’icône, comme indiqué par OPTIF_SEL_AS_HICON dans indicateurs.

DUMMYUNIONNAME2

Définit l’union DUMMYUNIONNAME2.

DUMMYUNIONNAME2.pExtChkBox

Pointeur vers la structure EXTCHKBOX

DUMMYUNIONNAME2.pExtPush

Cette union peut être un pointeur vers une structureEXTCHKBOX, un pointeur vers une structureEXTPUSHou NULL.

Une structure OPTITEM peut éventuellement avoir une structure EXTCHKBOX, une structure EXTPUSH, ou aucune, associée à celle-ci. Si cette union n’est pas NULL et si OPTIF_EXT_IS_EXTPUSH est défini dans Indicateurs, pExtPush est valide. Si l’indicateur n’est pas défini, pExtChkBox est valide.

pOptType

Pointeur vers une structure OPTTYPE qui décrit le type d’affichage de l’option. Si NULL, l’option n’a aucun paramètre et est utilisée comme parent pour les options avec une valeur de niveau supérieure. Les options enfants doivent suivre immédiatement le parent dans le tableau OPTITEM. (Consultez la section Remarques suivantes.)

HelpIndex

Index du fichier d’aide, qui identifie le texte d’aide à associer à l’option. Si zéro, le texte du fichier d’aide n’existe pas pour cette option. Notez que le pOIExt membre de cette structure doit être défini avec l’adresse d’une structure OIEXT afin que la fonctionnalité de texte d’aide existe.

DMPubID

Ce membre est destiné à être utilisé par les DLL d’interface d’imprimante lors de la création d’une feuille de propriétés document (voir DrvDocumentPropertySheets). Il s’agit d’une valeur constante spécifiant qui, le cas échéant, membre public de la structure DEVMODEW est associée à cette option. Le tableau suivant répertorie les constantes disponibles, le membre de structure DEVMODE associé et la valeur requise pour pName pour chaque constante.

Valeur constante	Valeur pName requise	Membre de structure
DMPUB_COLOR	dmColor	IDS_CPSUI_COLOR_APPERANCE
DMPUB_COPIES_COLLATE	dmCopies et 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	Non contenu dans la section publique de DEVMODE.	IDS_CPSUI_NUP
DMPUB_ORIENTATION	dmOrientation	IDS_CPSUI_ORIENTATION
DMPUB_OUTPUTBIN	Non contenu dans la section publique de DEVMODE.	IDS_CPSUI_OUTPUTBIN
DMPUB_PAGEORDER	Non contenu dans la section publique de DEVMODE.	IDS_CPSUI_PAGEORDER
DMPUB_PRINTQUALITY	dmPrintQuality	IDS_CPSUI_PRINTQUALITY ou IDS_CPSUI_RESOLUTION. Si ce n’est pas spécifié, le nom par défaut est IDS_CPSUI_RESOLUTION.
DMPUB_QUALITY	Non contenu dans la section publique de DEVMODE.	IDS_CPSUI_QUALITY_SETTINGS
DMPUB_SCALE	dmScale	IDS_CPSUI_SCALE
DMPUB_TTOPTION	dmTTOption	IDS_CPSUI_TTOPTION
DMPUB_NONE	Non contenu dans la section publique de DEVMODE.
Supérieur ou égal à DMPUB_USER	Ignoré par CPSUI, il peut s’agir d’une valeur définie par l’appelant.

CPSUI ne gère pas de structure DEVMODE. L’application est chargée de copier les paramètres d’option sélectionnés par l’utilisateur dans une structure DEVMODE. CPSUI utilise contenu DMPubID pour déterminer le positionnement d’arborescence des options standard et déterminer le contenu du de disposition et des onglets Papier/Qualité (voir le membre pDlgPage de la structure COMPROPSHEETUI).

Pour plus d’informations sur l’utilisation du membre DMPubID, consultez la section Remarques suivante.

UserItemID

Valeur facultative fournie par l’application qui peut être utilisée à des fins d’identification d’option. Non référencé par CPSUI.

wReserved

Réservé, doit être initialisé à zéro.

pOIExt

Pointeur vers une structureOIEXT facultative. L’appelant est responsable de l’allocation de stockage pour cette structure.

dwReserved[3]

Réservé, doit être initialisé à zéro.

Remarques

Les structures OPTITEM doivent être placées dans un tableau et l’adresse du tableau doit être placée dans le membre pOptItem d’une structure COMPROPSHEETUI.

Le membre Level vous permet de créer des nœuds enfants dans l’arborescence. Par exemple, pour créer un ensemble de nœuds d’option sous un nœud parent de niveau 1, spécifiez le niveau 2 pour chaque nœud enfant et incluez leurs structures OPTITEM dans le tableau OPTITEM, immédiatement après la structure OPTITEM du parent. Dans la structure OPTITEM du parent, pOptType doit être NULL .

Le nœud racine treeview est de niveau 0. Les options affichées lorsqu’un utilisateur développe le nœud racine sont de niveau 1. Le nombre maximal de niveaux est de 256.

Pour les valeurs d’option stockées dans la structure DEVMODE d’une imprimante, le DMPubID membre doit identifier l’option. Pour chaque valeur DMPubID utilisée, une DLL d’interface d’imprimante doit spécifier le type d’option CPSUI répertorié dans le tableau suivant.

Valeur DMPubID	Type d’option CPSUI requis
DMPUB_COLOR	TVOT_2STATES
DMPUB_COPIES_COLLATE	TVOT_UDARROW plus EXTCHKBOX (consultez les commentaires suivants ce tableau.)
DMPUB_DEFSOURCE	TVOT_LISTBOX
DMPUB_DITHERTYPE	TVOT_LISTBOX
DMPUB_DUPLEX	TVOT_2STATES ou TVOT_3STATES
DMPUB_FORMNAME	TVOT_LISTBOX
DMPUB_ICMINTENT	TVOT_2STATES ou TVOT_3STATES
DMPUB_ICMMETHOD	TVOT_2STATES ou TVOT_3STATES
DMPUB_MEDIATYPE	TVOT_LISTBOX
DMPUB_NUP	TVOT_LISTBOX
DMPUB_ORIENTATION	TVOT_2STATES ou TVOT_3STATES
DMPUB_OUTPUTBIN	TVOT_LISTBOX
DMPUB_PAGEORDER	TVOT_2STATES ou TVOT_3STATES
DMPUB_PRINTQUALITY	TVOT_LISTBOX
DMPUB_QUALITY	TVOT_2STATES ou TVOT_3STATES
DMPUB_SCALE	TVOT_UDARROW
DMPUB_TTOPTION	TVOT_LISTBOX

Si DMPubID est DMPUB_COPIES_COLLATE et que l’imprimante peut assembler des copies, une case à cocher étendue (structure EXTCHKBOX) doit être fournie. Les membres EXTCHCKBOX structure doivent être définis comme suit :

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;

Si OPTIF_EXT_HIDE n’est pas défini dans indicateurs, CPSUI active la case à cocher si un utilisateur demande plusieurs copies et le désactive si une seule copie est demandée.

En outre, CPSUI définit le texte d’affichage de l’option sur copier pour une copie et copie pour plusieurs copies.

Si DMPubID est DMPUB_COLOR, sa première structure OPTPARAM (Sel=0) doit représenter l’échelle grise et pData dans la structure OPTPARAM doit être IDS_CPSUI_GRAYSCALE. Sa deuxième structure OPTPARAM (Sel=1) doit représenter Color et pData dans la structure OPTPARAM doit être IDS_CPSUI_COLOR. Si DMPubID d’une autre option est DMPUB_ICMINTENT et si la couleur n’est pas sélectionnée, CPSUI désactive l’option pour laquelle DMPUB_ICMINTENT est spécifiée.

CPSUI désactive la correspondance des couleurs lorsque la couleur n’est pas sélectionnée.

Exigences

Exigence	Valeur
d’en-tête	compstui.h (include Compstui.h)