Estrutura PRINTDLGEXA (commdlg.h)
Contém informações que a função PrintDlgEx usa para inicializar a folha de propriedades Print. Depois que o usuário fecha a folha de propriedades, o sistema usa essa estrutura para retornar informações sobre as seleções do usuário.
Sintaxe
typedef struct tagPDEXA {
DWORD lStructSize;
HWND hwndOwner;
HGLOBAL hDevMode;
HGLOBAL hDevNames;
HDC hDC;
DWORD Flags;
DWORD Flags2;
DWORD ExclusionFlags;
DWORD nPageRanges;
DWORD nMaxPageRanges;
LPPRINTPAGERANGE lpPageRanges;
DWORD nMinPage;
DWORD nMaxPage;
DWORD nCopies;
HINSTANCE hInstance;
LPCSTR lpPrintTemplateName;
LPUNKNOWN lpCallback;
DWORD nPropertyPages;
HPROPSHEETPAGE *lphPropertyPages;
DWORD nStartPage;
DWORD dwResultAction;
} PRINTDLGEXA, *LPPRINTDLGEXA;
Membros
lStructSize
Tipo: DWORD
O tamanho da estrutura, em bytes.
hwndOwner
Digite: HWND
Um identificador para a janela que possui a folha de propriedades. Esse membro deve ser um identificador de janela válido; não pode ser NULL.
hDevMode
Tipo: HGLOBAL
Um identificador para um objeto de memória global móvel que contém uma estrutura DEVMODE . Se hDevMode não for NULL na entrada, você deverá alocar um bloco móvel de memória para a estrutura DEVMODE e inicializar seus membros. A função PrintDlgEx usa os dados de entrada para inicializar os controles na folha de propriedades. Quando PrintDlgEx retorna, os membros DEVMODE indicam a entrada do usuário.
Se hDevMode for NULL na entrada, PrintDlgEx alocará memória para a estrutura DEVMODE , inicializará seus membros para indicar a entrada do usuário e retornará um identificador que a identifica.
Para obter mais informações sobre os membros hDevMode e hDevNames , consulte a seção Comentários no final deste tópico.
hDevNames
Tipo: HGLOBAL
Um identificador para um objeto de memória global móvel que contém uma estrutura DEVNAMES . Se hDevNames não for NULL na entrada, você deverá alocar um bloco móvel de memória para a estrutura DEVNAMES e inicializar seus membros. A função PrintDlgEx usa os dados de entrada para inicializar os controles na folha de propriedades. Quando PrintDlgEx retorna, os membros DEVNAMES contêm informações para a impressora escolhida pelo usuário. Você pode usar essas informações para criar um contexto de dispositivo ou um contexto de informações.
O membro hDevNames pode ser NULL, nesse caso, PrintDlgEx aloca memória para a estrutura DEVNAMES , inicializa seus membros para indicar a entrada do usuário e retorna um identificador que a identifica.
Para obter mais informações sobre os membros hDevMode e hDevNames , consulte a seção Comentários no final deste tópico.
hDC
Tipo: HDC
Um identificador para um contexto de dispositivo ou um contexto de informações, dependendo se o membro Flags especifica o sinalizador PD_RETURNDC ou PC_RETURNIC . Se nenhum sinalizador for especificado, o valor desse membro será indefinido. Se ambos os sinalizadores forem especificados, PD_RETURNDC terá prioridade. Se hDC não for NULL, você deverá chamar DeleteDC para liberar o objeto GDI depois de não precisar mais dele; caso contrário, você vai vazar objetos GDI sempre que chamar APIs PrintDlgw .
Flags
Tipo: DWORD
Um conjunto de sinalizadores de bits que você pode usar para inicializar a folha de propriedades Imprimir . Quando a função PrintDlgEx retorna, ela define esses sinalizadores para indicar a entrada do usuário. Esse membro pode ser um ou mais dos valores a seguir.
Para garantir que PrintDlg ou PrintDlgEx retorne os valores corretos nos membros dmCopies e dmCollate da estrutura DEVMODE , defina PD_RETURNDC = TRUE e PD_USEDEVMODECOPIESANDCOLLATE = TRUE. Ao fazer isso, o membro nCopies da estrutura PRINTDLG é sempre 1 e PD_COLLATE é sempre FALSE.
Para garantir que PrintDlg ou PrintDlgEx retorne os valores corretos em nCopies e PD_COLLATE, defina PD_RETURNDC = TRUE e PD_USEDEVMODECOPIESANDCOLLATE = FALSE. Ao fazer isso, dmCopies é sempre 1 e dmCollate é sempre FALSE.
A partir do Windows Vista, quando você chama PrintDlg ou PrintDlgEx com PD_RETURNDC definido como TRUE e PD_USEDEVMODECOPIESANDCOLLATE definido como FALSE, a função PrintDlg ou PrintDlgEx define o número de cópias no membro nCopies da estrutura PRINTDLG e define o número de cópias na estrutura representada pelo membro hDC da estrutura PRINTDLG .
Ao fazer chamadas para GDI, você deve ignorar o valor de nCopies, considerar o valor como 1 e usar o hDC retornado para evitar a impressão de cópias duplicadas.
| Valor | Significado |
|---|---|
|
O sinalizador padrão que indica que o botão de opção Todos está selecionado inicialmente. Esse sinalizador é usado como um espaço reservado para indicar que os sinalizadores PD_PAGENUMS, PD_SELECTION e PD_CURRENTPAGE não são especificados. |
|
Se esse sinalizador estiver definido, a caixa Agrupar marcar será selecionada.
Se esse sinalizador for definido quando a função PrintDlgEx retornar, o aplicativo deverá simular a ordenação de várias cópias. Para obter mais informações, consulte a descrição do sinalizador PD_USEDEVMODECOPIESANDCOLLATE . Consulte PD_NOPAGENUMS. |
|
Se esse sinalizador estiver definido, o botão de opção Página Atual será selecionado. Se nenhum dos sinalizadores PD_PAGENUMS, PD_SELECTION ou PD_CURRENTPAGE estiver definido, o botão de opção Todos será selecionado. |
|
Desabilita a caixa Imprimir no Arquivo marcar. |
|
Indica que os membros hInstance e lpPrintTemplateName especificam uma substituição para o modelo de caixa de diálogo padrão na parte inferior da página Geral . O modelo padrão contém controles semelhantes aos da caixa de diálogo Imprimir . O sistema usa o modelo especificado para criar uma janela que é um filho da página Geral . |
|
Indica que o membro hInstance identifica um bloco de dados que contém um modelo de caixa de diálogo pré-carregada. Esse modelo substitui o modelo da caixa de diálogo padrão na parte inferior da página Geral . O sistema usa o modelo especificado para criar uma janela que é um filho da página Geral . O sistema ignorará o membro lpPrintTemplateName se esse sinalizador for especificado. |
|
Indica que o membro ExclusionFlags identifica os itens a serem excluídos das páginas de propriedades do driver da impressora. Se esse sinalizador não estiver definido, os itens serão excluídos por padrão das páginas de propriedades do driver da impressora. As exclusões impedem a duplicação de itens entre a página Geral , as páginas especificadas pelo aplicativo e as páginas do driver da impressora. |
|
Oculta a caixa Imprimir no Arquivo marcar. |
|
Desabilita o botão de opção Página Atual . |
|
Desabilita o botão de opção Páginas e os controles de edição associados. Além disso, faz com que a caixa Agrupar marcar apareça na caixa de diálogo. |
|
Desabilita o botão de opção Seleção . |
|
Impede que a mensagem de aviso seja exibida quando ocorrer um erro. |
|
Se esse sinalizador estiver definido, o botão de opção Páginas será selecionado. Se nenhum dos sinalizadores PD_PAGENUMS, PD_SELECTION ou PD_CURRENTPAGE estiver definido, o botão de opção Todos será selecionado. Se esse sinalizador for definido quando a função PrintDlgEx retornar, o membro lpPageRanges indicará os intervalos de página especificados pelo usuário. |
|
Se esse sinalizador estiver definido, a caixa Imprimir no Arquivo marcar será selecionada. Se esse sinalizador for definido quando PrintDlgEx retornar, o deslocamento indicado pelo membro wOutputOffset da estrutura DEVNAMES conterá a cadeia de caracteres "FILE:". Ao chamar a função StartDoc para iniciar a operação de impressão, especifique essa cadeia de caracteres "FILE:" no membro lpszOutput da estrutura DOCINFO . Especificar essa cadeia de caracteres faz com que o subsistema de impressão consulte o usuário quanto ao nome do arquivo de saída. |
|
Faz com que PrintDlgEx retorne um contexto de dispositivo correspondente às seleções feitas pelo usuário na folha de propriedades. O contexto do dispositivo é retornado no hDC. |
|
Se esse sinalizador estiver definido, a função PrintDlgEx não exibirá a folha de propriedades. Em vez disso, ele define os membros hDevNames e hDevMode como identificadores para estruturas DEVNAMES e DEVMODE que são inicializadas para a impressora padrão do sistema. HDevNames e hDevMode devem ser NULL ou PrintDlgEx retorna um erro. |
|
Semelhante ao sinalizador PD_RETURNDC , exceto que esse sinalizador retorna um contexto de informações em vez de um contexto de dispositivo. Se nem PD_RETURNDC nem PD_RETURNIC for especificado, o hDC será indefinido na saída. |
|
Se esse sinalizador estiver definido, o botão de opção Seleção será selecionado. Se nenhum dos sinalizadores PD_PAGENUMS, PD_SELECTION ou PD_CURRENTPAGE estiver definido, o botão de opção Tudo será selecionado. |
|
O mesmo que PD_USEDEVMODECOPIESANDCOLLATE. |
|
Esse sinalizador indica se o aplicativo dá suporte a várias cópias e ordenação. Defina esse sinalizador na entrada para indicar que seu aplicativo não dá suporte a várias cópias e ordenação. Nesse caso, o membro nCopies da estrutura PRINTDLGEX sempre retorna 1 e PD_COLLATE nunca é definido no membro Flags .
Se esse sinalizador não estiver definido, o aplicativo será responsável por imprimir e agrupar várias cópias. Nesse caso, o membro nCopies da estrutura PRINTDLGEX indica o número de cópias que o usuário deseja imprimir e o sinalizador PD_COLLATE no membro Flags indica se o usuário deseja ordenação. Independentemente de esse sinalizador ser definido, um aplicativo pode determinar de nCopies e PD_COLLATE quantas cópias renderizar e se deseja imprimi-las agrupadas. Se esse sinalizador estiver definido e o driver da impressora não der suporte a várias cópias, o controle de edição Cópias será desabilitado . Da mesma forma, se esse sinalizador estiver definido e o driver da impressora não der suporte à ordenação, a caixa Agrupar marcar será desabilitada. Os membros dmCopies e dmCollate da estrutura DEVMODE contêm as cópias e as informações de agrupamento usadas pelo driver da impressora. Se esse sinalizador estiver definido e o driver da impressora der suporte a várias cópias, o membro dmCopies indicará o número de cópias solicitadas pelo usuário. Se esse sinalizador estiver definido e o driver da impressora der suporte à ordenação, o membro dmCollate da estrutura DEVMODE indicará se o usuário deseja ordenação. Se esse sinalizador não estiver definido, o membro dmCopies sempre retornará 1 e o membro dmCollate sempre será zero. Em versões do Windows anteriores ao Windows Vista, se esse sinalizador não for definido pelo aplicativo de chamada e o membro dmCopies da estrutura DEVMODE for maior que 1, use esse valor para o número de cópias; caso contrário, use o valor do membro nCopies da estrutura PRINTDLGEX . |
|
Força a folha de propriedades a usar um modelo grande para a página Geral . O modelo maior fornece mais espaço para aplicativos que especificam um modelo personalizado para a parte inferior da página Geral . |
Flags2
Tipo: DWORD
ExclusionFlags
Tipo: DWORD
Um conjunto de sinalizadores de bits que pode excluir itens das páginas de propriedades do driver de impressora na folha de propriedades Imprimir . Esse valor será usado somente se o sinalizador PD_EXCLUSIONFLAGS estiver definido no membro Flags . Os sinalizadores de exclusão devem ser usados somente se o item a ser excluído for incluído na página Geral ou em uma página definida pelo aplicativo na folha de propriedades Imprimir . Esse membro pode especificar o sinalizador a seguir.
PD_EXCL_COPIESANDCOLLATE
Exclui os controles Copies e Collate das páginas de propriedades do driver de impressora em uma folha de propriedades Print . Esse sinalizador sempre deve ser definido quando o aplicativo usa os controles Padrão Cópias e Ordenação fornecidos pela parte inferior da página Geral da folha de propriedades Imprimir .
nPageRanges
Tipo: DWORD
Na entrada, defina esse membro como o número inicial de intervalos de página especificados na matriz lpPageRanges . Quando a função PrintDlgEx retorna, nPageRanges indica o número de intervalos de páginas especificados pelo usuário armazenados na matriz lpPageRanges . Se o sinalizador PD_NOPAGENUMS for especificado, esse valor não será válido.
nMaxPageRanges
Tipo: DWORD
O tamanho, em elementos de matriz, do buffer lpPageRanges . Esse valor indica o número máximo de intervalos de páginas que podem ser armazenados na matriz. Se o sinalizador PD_NOPAGENUMS for especificado, esse valor não será válido. Se o sinalizador PD_NOPAGENUMS não for especificado, esse valor deverá ser maior que zero.
lpPageRanges
Tipo: LPPRINTPAGERANGE
Ponteiro para um buffer que contém uma matriz de estruturas PRINTPAGERANGE . Na entrada, a matriz contém os intervalos de página iniciais a serem exibidos no controle de edição Páginas . Quando a função PrintDlgEx retorna, a matriz contém os intervalos de página especificados pelo usuário. Se o sinalizador PD_NOPAGENUMS for especificado, esse valor não será válido. Se o sinalizador PD_NOPAGENUMS não for especificado, lpPageRanges deverá ser não NULL.
nMinPage
Tipo: DWORD
O valor mínimo para os intervalos de página especificados no controle de edição Páginas . Se o sinalizador PD_NOPAGENUMS for especificado, esse valor não será válido.
nMaxPage
Tipo: DWORD
O valor máximo para os intervalos de página especificados no controle de edição Páginas . Se o sinalizador PD_NOPAGENUMS for especificado, esse valor não será válido.
nCopies
Tipo: DWORD
Contém o número inicial de cópias para o controle de edição Cópias se hDevMode for NULL; caso contrário, o membro dmCopies da estrutura DEVMODE contém o valor inicial. Quando PrintDlgEx retorna, nCopies contém o número real de cópias que o aplicativo deve imprimir. Esse valor depende se o aplicativo ou o driver da impressora é responsável por imprimir várias cópias. Se o sinalizador PD_USEDEVMODECOPIESANDCOLLATE for definido no membro Flags , nCopies sempre será 1 no retorno e o driver da impressora será responsável por imprimir várias cópias. Se o sinalizador não estiver definido, o aplicativo será responsável por imprimir o número de cópias especificadas por nCopies. Para obter mais informações, consulte a descrição do sinalizador PD_USEDEVMODECOPIESANDCOLLATE .
hInstance
Tipo: HINSTANCE
Se o sinalizador PD_ENABLEPRINTTEMPLATE for definido no membro Flags , hInstance será um identificador para a instância de aplicativo ou módulo que contém o modelo de caixa de diálogo chamado pelo membro lpPrintTemplateName . Se o sinalizador PD_ENABLEPRINTTEMPLATEHANDLE estiver definido no membro Flags , hInstance será um identificador para um objeto de memória que contém um modelo de caixa de diálogo. Se nenhum dos sinalizadores de modelo estiver definido no membro Flags , hInstance deverá ser NULL.
lpPrintTemplateName
Tipo: LPCTSTR
O nome do recurso de modelo da caixa de diálogo no módulo identificado pelo membro hInstance . Esse modelo substitui o modelo de caixa de diálogo padrão na parte inferior da página Geral . O modelo padrão contém controles semelhantes aos da caixa de diálogo Imprimir . Esse membro é ignorado, a menos que o sinalizador PD_ENABLEPRINTTEMPLATE seja definido no membro Flags .
lpCallback
Tipo: LPUNKNOWN
Um ponteiro para um objeto de retorno de chamada definido pelo aplicativo.
O objeto deve conter a classe IPrintDialogCallback para receber mensagens para a caixa de diálogo filho na parte inferior da página Geral .
O objeto de retorno de chamada também deve conter a classe IObjectWithSite para receber um ponteiro para a interface IPrintDialogServices . A função PrintDlgEx chama IUnknown::QueryInterface no objeto de retorno de chamada para IID_IPrintDialogCallback e IID_IObjectWithSite para determinar quais interfaces têm suporte.
Se você não quiser recuperar nenhuma das informações de retorno de chamada, defina lpCallback como NULL.
nPropertyPages
Tipo: DWORD
O número de identificadores de página de propriedades na matriz lphPropertyPages .
lphPropertyPages
Tipo: HPROPSHEETPAGE*
Contém uma matriz de identificadores de página de propriedades a serem adicionados à folha de propriedades Imprimir . As páginas de propriedades adicionais seguem a página Geral . Use a função CreatePropertySheetPage para criar essas páginas adicionais. Quando a função PrintDlgEx retorna, todos os identificadores HPROPSHEETPAGE na matriz lphPropertyPages foram destruídos . Se nPropertyPages for zero, lphPropertyPages deverá ser NULL.
nStartPage
Tipo: DWORD
A página de propriedades que é inicialmente exibida. Para exibir a página Geral , especifique START_PAGE_GENERAL. Caso contrário, especifique o índice baseado em zero de uma página de propriedades na matriz especificada no membro lphPropertyPages . Para consistência, é recomendável que a folha de propriedades sempre seja iniciada na página Geral .
dwResultAction
Tipo: DWORD
Na entrada, defina esse membro como zero. Se a função PrintDlgEx retornar S_OK, dwResultAction conterá o resultado da caixa de diálogo. Se PrintDlgEx retornar um erro, esse membro deverá ser ignorado. O membro dwResultAction pode ser um dos valores a seguir.
PD_RESULT_APPLY
O usuário clicou no botão Aplicar e, posteriormente, clicou no botão Cancelar . Isso indica que o usuário deseja aplicar as alterações feitas na folha de propriedades, mas ainda não deseja imprimir. A estrutura PRINTDLGEX contém as informações especificadas pelo usuário no momento em que o botão Aplicar foi clicado.
PD_RESULT_CANCEL
O usuário clicou no botão Cancelar . As informações na estrutura PRINTDLGEX não são alteradas.
PD_RESULT_PRINT
O usuário clicou no botão Imprimir . A estrutura PRINTDLGEX contém as informações especificadas pelo usuário.
Comentários
Se hDevMode e hDevNames forem NULL, PrintDlgEx inicializará a folha de propriedades usando a impressora padrão atual. Para inicializar a folha de propriedades de uma impressora diferente, use o membro wDeviceOffset da estrutura DEVNAMES para especificar o nome da impressora.
Observe que o membro dmDeviceName da estrutura DEVMODE também especifica um nome de impressora. No entanto, dmDeviceName é limitado a 32 caracteres e o nome wDeviceOffset não é. Se os nomes wDeviceOffset e dmDeviceName não forem os mesmos, PrintDlgEx inicializará a folha de propriedades usando a impressora especificada por wDeviceOffset.
Se o sinalizador PD_RETURNDEFAULT estiver definido e hDevMode e hDevNames forem NULL, PrintDlgEx usará os membros hDevNames e hDevMode para retornar informações sobre a impressora padrão atual sem exibir a caixa de diálogo.
Durante a execução de PrintDlgEx, as estruturas DEVMODE e DEVNAMES especificadas na estrutura PRINTDLGEX nem sempre podem conter dados atuais. Por esse motivo, as páginas de propriedades específicas do aplicativo, bem como as rotinas IPrintDialogCallback para a página inicial, devem usar a interface IPrintDialogServices para recuperar informações sobre o estado da impressora atual.
Observação
O cabeçalho commdlg.h define PRINTDLGEX como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
Requisitos
| Cliente mínimo com suporte | Windows 2000 Professional [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows 2000 Server [somente aplicativos da área de trabalho] |
| Cabeçalho | commdlg.h (inclua Windows.h) |
Confira também
Biblioteca de caixas de diálogo comuns
Conceitual
Referência
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de