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 l’option appartient. 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 prédéfinie fournie par CPSUI, 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. Vous pouvez définir n’importe quelle combinaison des indicateurs suivants.

OPTIF_CALLBACK

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

OPTIF_CHANGED

La fonction de rappel _CPSUICALLBACK doit définir cet indicateur si elle 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 zone de case activée étendue associée est dans l’état coché.

OPTIF_EXT_IS_EXTPUSH

S’il est défini, le membre pExtPush est valide (sauf null).

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

OPTIF_EXT_DISABLED

La zone de case activée étendue ou le bouton pousseur étendu ne peut pas être sélectionné.

OPTIF_EXT_HIDE

CPSUI n’affiche pas la zone de case activée étendue ou le bouton poussoir étendu.

OPTIF_HAS_POIEXT

S’il est défini, 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, de sorte que la modification de l’indicateur à partir de sa valeur initiale n’a aucun effet.

OPTIF_INITIAL_TVITEM

Si cette option est définie, CPSUI définit le focus de 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 dans la vue si nécessaire. Si l’option est masquée ou si cet indicateur n’est défini pour aucune structure OPTITEM, CPSUI choisit le focus initial.

OPTIF_NO_GROUPBOX_NAME

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

S’il est défini, CPSUI fournit un titre de zone de groupe.

OPTIF_OVERLAY_NO_ICON

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

OPTIF_OVERLAY_STOP_ICON

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

OPTIF_OVERLAY_WARNING_ICON

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

OPTIF_SEL_AS_HICON

S’il est défini, le membre Sel contient un handle d’icône.

S’il n’est pas défini, 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.

(Les DLL d’interface d’imprimante pour Unidrv et Pscript utilisent ce membre pour fournir un pointeur vers une structure USERDATA . Les plug-ins d’interface utilisateur peuvent 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 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 du paramètre actuellement sélectionné de l’option. Son utilisation dépend du type d’option CPSUI.

Si pOptType a la valeur 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 du paramètre actuellement sélectionné de l’option. Son utilisation dépend du type d’option CPSUI.

Si pOptType a la valeur 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 structure EXTCHKBOX , un pointeur vers une structure EXTPUSH ou NULL.

Une structure OPTITEM peut éventuellement avoir une structure EXTCHKBOX, une structure EXTPUSH ou aucun des deux. 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 la valeur est 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. (Voir la section Remarques suivante.)

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 membre pOIExt de cette structure doit être défini avec l’adresse d’une structure OIEXT pour 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 Propriétés du document (voir DrvDocumentPropertySheets). Il s’agit d’une valeur constante qui spécifie quel, le cas échéant, le membre public de la structure DEVMODEW est associé à 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.

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 le contenu DMPubID pour déterminer l’emplacement des arborescences des options standard et pour déterminer le contenu des onglets Disposition et Papier/Qualité (voir le membre pDlgPage de la structure COMPROPSHEETUI ).

Pour plus d’informations sur l’utilisation du membre DMPubID , consultez la section Notes 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 structure OIEXT facultative. L’appelant est responsable de l’allocation du 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 avoir la valeur 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 membre DMPubID 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.

Si DMPubID est DMPUB_COPIES_COLLATE et que l’imprimante peut rassembler des copies, une zone de case activée étendue (structure EXTCHKBOX) doit être fournie. Les membres de la structure EXTCHCKBOX 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 zone case activée si un utilisateur demande plusieurs copies et la désactive si une seule copie est demandée.

En outre, CPSUI définit le texte d’affichage de l’option à copier pour une copie et les copies 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 le DMPubID d’une autre option est DMPUB_ICMINTENT et si Color n’est pas sélectionné, CPSUI désactive l’option pour laquelle DMPUB_ICMINTENT est spécifié.

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

Configuration requise