Estrutura PRINTDLGEXA (commdlg.h)

Artigo
07/21/2023

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
PD_ALLPAGES 0x00000000	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.
PD_COLLATE 0x00000010	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.
PD_CURRENTPAGE 0x00400000	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.
PD_DISABLEPRINTTOFILE 0x00080000	Desabilita a caixa Imprimir no Arquivo marcar.
PD_ENABLEPRINTTEMPLATE 0x00004000	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 .
PD_ENABLEPRINTTEMPLATEHANDLE 0x00010000	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.
PD_EXCLUSIONFLAGS 0x01000000	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.
PD_HIDEPRINTTOFILE 0x00100000	Oculta a caixa Imprimir no Arquivo marcar.
PD_NOCURRENTPAGE 0x00800000	Desabilita o botão de opção Página Atual .
PD_NOPAGENUMS 0x00000008	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.
PD_NOSELECTION 0x00000004	Desabilita o botão de opção Seleção .
PD_NOWARNING 0x00000080	Impede que a mensagem de aviso seja exibida quando ocorrer um erro.
PD_PAGENUMS 0x00000002	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.
PD_PRINTTOFILE 0x00000020	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.
PD_RETURNDC 0x00000100	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.
PD_RETURNDEFAULT 0x00000400	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.
PD_RETURNIC 0x00000200	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.
PD_SELECTION 0x00000001	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.
PD_USEDEVMODECOPIES 0x00040000	O mesmo que PD_USEDEVMODECOPIESANDCOLLATE.
PD_USEDEVMODECOPIESANDCOLLATE 0x00040000	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 .
PD_USELARGETEMPLATE 0x10000000	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)