Estrutura OPTITEM (compstui.h)
A estrutura OPTITEM é usada por aplicativos CPSUI (incluindo DLLs de interface da impressora) para descrever uma opção de folha de propriedades em uma página de folha de propriedades, se a página for descrita por uma estrutura COMPROPSHEETUI .
Sintaxe
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;
Membros
cbSize
Tamanho, em bytes, da estrutura OPTITEM .
Level
Especifica o nível dessa opção na visão de árvore. Para obter mais informações, consulte a seção Comentários abaixo.
DlgPageIdx
Identifica a caixa de diálogo à qual a opção pertence. Especifica um índice de matriz na matriz DLGPAGE apontada pelo membro pDlgPage da estrutura COMPROPSHEETUI .
Se pDlgPage apontar para uma estrutura DLGPAGE fornecida por CPSUI, a CPSUI fornecerá esse índice.
Flags
Sinalizadores de bit opcionais que modificam as características da opção. O sinalizador OPTIF_CHANGEONCE é definido pelo CPSUI; todos os outros sinalizadores são definidos pelo chamador. Qualquer combinação dos sinalizadores a seguir pode ser definida.
OPTIF_CALLBACK
Quando um usuário modifica a opção , o CPSUI deve chamar a função de retorno de chamada do tipo _CPSUICALLBACK especificada na estrutura COMPROPSHEETUI .
OPTIF_CHANGED
A função de retorno de chamada do tipo _CPSUICALLBACK deve definir esse sinalizador se ele modificou a opção, de modo que o CPSUI o reproduz.
OPTIF_CHANGEONCE
CPSUI define esse bit se um usuário modificou a opção.
OPTIF_COLLAPSE
Recolher essa opção e seus filhos para que ela não seja expandida na visão de árvore.
OPTIF_DISABLED
Desabilita a opção para que ela não seja modificável pelo usuário.
OPTIF_ECB_CHECKED
A caixa de marcar estendida associada está no estado marcado.
OPTIF_EXT_IS_EXTPUSH
Se definido, o membro pExtPush será válido (a menos que NULL).
Se não estiver definido, o membro pExtChkBox será válido (a menos que NULL).
OPTIF_EXT_DISABLED
A caixa de marcar estendida ou o botão de push estendido não é selecionável.
OPTIF_EXT_HIDE
O CPSUI não exibirá a caixa de marcar estendida nem o botão de push estendido.
OPTIF_HAS_POIEXT
Se definido, o membro pOIExt será válido.
OPTIF_HIDE
O CPSUI não exibirá essa opção na visão de árvore. O CPSUI examina esse sinalizador somente ao criar inicialmente a visão de árvore, portanto, alterar o sinalizador de seu valor inicial não tem efeito.
OPTIF_INITIAL_TVITEM
Se definido, CPSUI define o foco da janela inicial para essa opção quando exibe a visão de árvore. O CPSUI expande os nós de árvore e rola a opção para a exibição conforme necessário. Se a opção estiver oculta ou se esse sinalizador não estiver definido para nenhuma estrutura OPTITEM, CPSUI escolherá o foco inicial.
OPTIF_NO_GROUPBOX_NAME
Se não estiver definido e pOptype não for zero, CPSUI usará a cadeia de caracteres pName como o título da caixa de grupo.
Se definido, CPSUI fornecerá um título de caixa de grupo.
OPTIF_OVERLAY_NO_ICON
Se definir CPSUI sobrepõe seu ícone de IDI_CPSUI_NO no ícone associado à opção . (Consulte o membro Sel/pSel .)
OPTIF_OVERLAY_STOP_ICON
Se definido, o CPSUI sobrepõe seu ícone de IDI_CPSUI_STOP no ícone associado à opção . (Consulte o membro Sel/pSel .)
OPTIF_OVERLAY_WARNING_ICON
Se definido, o CPSUI sobrepõe seu ícone de IDI_CPSUI_WARNING no ícone associado à opção . (Consulte o membro Sel/pSel .)
OPTIF_SEL_AS_HICON
Se definido, o membro Sel contém um identificador de ícone.
Se não estiver definido, o membro Sel conterá um identificador de recurso de ícone.
Esse sinalizador só pode ser usado quando pOptType contém NULL.
UserData
Valor opcional de 32 bits que pode ser definido e usado pelo chamador.
(As DLLs da interface da impressora para Unidrv e Pscript usam esse membro para fornecer um ponteiro para uma estrutura USERDATA . Os plug-ins da interface do usuário podem referenciar essa estrutura.)
pName
Identificador de cadeia de caracteres que representa um nome de opção localizado e exibivel. Isso pode ser um ponteiro de 32 bits para uma cadeia de caracteres terminada em NULL ou pode ser um identificador de recurso de cadeia de caracteres de 16 bits, com HIWORD definido como zero. (Consulte também a descrição de DMPubID, abaixo.)
DUMMYUNIONNAME
DUMMYUNIONNAME.Sel
Essa união indica o valor do parâmetro selecionado no momento da opção. Seu uso depende do tipo de opção CPSUI.
Se pOptType for NULL, a opção não terá parâmetros, portanto, essa união identificará um ícone a ser associado ao nó treeview para a opção . O identificador de ícone pode ser um identificador de ícone ou um identificador de recurso de ícone, conforme indicado por OPTIF_SEL_AS_HICON em Sinalizadores.
DUMMYUNIONNAME.pSel
Essa união indica o valor do parâmetro selecionado no momento da opção. Seu uso depende do tipo de opção CPSUI.
Se pOptType for NULL, a opção não terá parâmetros, portanto, essa união identificará um ícone a ser associado ao nó treeview para a opção . O identificador de ícone pode ser um identificador de ícone ou um identificador de recurso de ícone, conforme indicado por OPTIF_SEL_AS_HICON em Sinalizadores.
DUMMYUNIONNAME2
Define a união DUMMYUNIONNAME2 .
DUMMYUNIONNAME2.pExtChkBox
Ponteiro para a estrutura EXTCHKBOX
DUMMYUNIONNAME2.pExtPush
Essa união pode ser um ponteiro para uma estrutura EXTCHKBOX , um ponteiro para uma estrutura EXTPUSH ou NULL.
Opcionalmente, uma estrutura OPTITEM pode ter uma estrutura EXTCHKBOX, uma estrutura EXTPUSH ou nenhuma delas associada a ela. Se essa união não for NULL e se OPTIF_EXT_IS_EXTPUSH estiver definido em Sinalizadores, pExtPush será válido. Se o sinalizador não estiver definido, pExtChkBox será válido.
pOptType
Ponteiro para uma estrutura OPTTYPE que descreve o tipo de exibição da opção. Se NULL, a opção não tem parâmetros e é usada como pai para opções com um valor de Nível mais alto. As opções filho devem seguir imediatamente o pai na matriz OPTITEM. (Consulte a seção Comentários a seguir.)
HelpIndex
Índice de arquivo de ajuda, que identifica o texto de ajuda a ser associado à opção . Se zero, o texto do arquivo de ajuda não existe para essa opção. Observe que o membro pOIExt dessa estrutura deve ser definido com o endereço de uma estrutura OIEXT para que a funcionalidade de texto de ajuda exista.
DMPubID
Esse membro destina-se ao uso por DLLs de interface da impressora ao criar uma folha de propriedades propriedades do documento (consulte DrvDocumentPropertySheets). É um valor constante que especifica qual, se houver, membro público da estrutura DEVMODEW está associado a essa opção. A tabela a seguir lista as constantes disponíveis, o membro da estrutura DEVMODE associado e o valor necessário para pName para cada constante.
| Valor Constante | Valor de pName necessário | Membro da estrutura |
|---|---|---|
| DMPUB_COLOR | dmColor | IDS_CPSUI_COLOR_APPERANCE |
| DMPUB_COPIES_COLLATE | dmCopies e 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 | Não contido na seção pública de DEVMODE. | IDS_CPSUI_NUP |
| DMPUB_ORIENTATION | dmOrientation | IDS_CPSUI_ORIENTATION |
| DMPUB_OUTPUTBIN | Não contido na seção pública de DEVMODE. | IDS_CPSUI_OUTPUTBIN |
| DMPUB_PAGEORDER | Não contido na seção pública de DEVMODE. | IDS_CPSUI_PAGEORDER |
| DMPUB_PRINTQUALITY | dmPrintQuality | IDS_CPSUI_PRINTQUALITY ou IDS_CPSUI_RESOLUTION. Se não for especificado, o nome padrão será IDS_CPSUI_RESOLUTION. |
| DMPUB_QUALITY | Não contido na seção pública de DEVMODE. | IDS_CPSUI_QUALITY_SETTINGS |
| DMPUB_SCALE | dmScale | IDS_CPSUI_SCALE |
| DMPUB_TTOPTION | dmTTOption | IDS_CPSUI_TTOPTION |
| DMPUB_NONE | Não contido na seção pública de DEVMODE. | |
| Maior ou igual a DMPUB_USER | Ignorado pelo CPSUI, pode ser um valor definido pelo chamador. |
O CPSUI não mantém uma estrutura DEVMODE. O aplicativo é responsável por copiar parâmetros de opção selecionados pelo usuário em uma estrutura DEVMODE . O CPSUI usa conteúdo DMPubID para determinar o posicionamento de visão de árvore das opções padrão e determinar o conteúdo das guias Layout e Papel/Qualidade (consulte o membro pDlgPage da estrutura COMPROPSHEETUI ).
Para obter informações adicionais sobre como usar o membro DMPubID , consulte a seção Comentários a seguir.
UserItemID
Valor opcional fornecido pelo aplicativo que pode ser usado para fins de identificação de opção. Não referenciado pelo CPSUI.
wReserved
Reservado, deve ser inicializado como zero.
pOIExt
Ponteiro para uma estrutura OIEXT opcional. O chamador é responsável por alocar armazenamento para essa estrutura.
dwReserved[3]
Reservado, deve ser inicializado como zero.
Comentários
As estruturas OPTITEM devem ser colocadas em uma matriz e o endereço da matriz deve ser colocado no membro pOptItem de uma estrutura COMPROPSHEETUI .
O membro Level permite que você crie nós filho na visão de árvore. Por exemplo, para criar um conjunto de nós de opção em um nó pai de nível 1, especifique o nível 2 para cada nó filho e inclua suas estruturas OPTITEM na matriz OPTITEM, imediatamente após a estrutura OPTITEM do pai. Na estrutura OPTITEM do pai, pOptType deve ser NULL.
O nó raiz treeview é o nível 0. As opções exibidas quando um usuário expande o nó raiz são de nível 1. O número máximo de níveis é 256.
Para valores de opção armazenados na estrutura DEVMODE de uma impressora, o membro DMPubID deve identificar a opção. Para cada valor DMPubID usado, uma DLL de interface de impressora deve especificar o tipo de opção CPSUI listado na tabela a seguir.
| Valor DMPubID | Tipo de opção CPSUI necessário |
|---|---|
| DMPUB_COLOR | TVOT_2STATES |
| DMPUB_COPIES_COLLATE | TVOT_UDARROW mais EXTCHKBOX (consulte comentários seguindo esta tabela.) |
| 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 |
Se DMPubID for DMPUB_COPIES_COLLATE e a impressora puder agrupar cópias, uma caixa de marcar estendida (estrutura EXTCHKBOX) deverá ser fornecida. Os membros da estrutura EXTCHCKBOX devem ser definidos da seguinte maneira:
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;
Se OPTIF_EXT_HIDE não estiver definido em Sinalizadores, o CPSUI habilitará a caixa marcar se um usuário solicitar mais de uma cópia e a desabilitará se apenas uma cópia for solicitada.
Além disso, o CPSUI define o texto de exibição da opção a ser copiado para uma cópia e cópias para mais de uma cópia.
Se DMPubID for DMPUB_COLOR, sua primeira estrutura OPTPARAM (Sel=0) deverá representar Escala de Cinza e pData na estrutura OPTPARAM deverá ser IDS_CPSUI_GRAYSCALE. Sua segunda estrutura OPTPARAM (Sel=1) deve representar Cor e pData na estrutura OPTPARAM deve ser IDS_CPSUI_COLOR. Se o DMPubID de outra opção for DMPUB_ICMINTENT e se Color não estiver selecionado, CPSUI desabilitará a opção para a qual DMPUB_ICMINTENT é especificado.
CPSUI desabilita a correspondência de cores quando Cor não está selecionada.
Requisitos
| Requisito | Valor |
|---|---|
| Cabeçalho | compstui.h (inclua Compstui.h) |