Estrutura PRINTDLGA (commdlg.h)

Contém informações que a função PrintDlg usa para inicializar a caixa de diálogo Imprimir. Depois que o usuário fecha a caixa de diálogo, o sistema usa essa estrutura para retornar informações sobre as seleções do usuário.

Sintaxe

typedef struct tagPDA {
  DWORD           lStructSize;
  HWND            hwndOwner;
  HGLOBAL         hDevMode;
  HGLOBAL         hDevNames;
  HDC             hDC;
  DWORD           Flags;
  WORD            nFromPage;
  WORD            nToPage;
  WORD            nMinPage;
  WORD            nMaxPage;
  WORD            nCopies;
  HINSTANCE       hInstance;
  LPARAM          lCustData;
  LPPRINTHOOKPROC lpfnPrintHook;
  LPSETUPHOOKPROC lpfnSetupHook;
  LPCSTR          lpPrintTemplateName;
  LPCSTR          lpSetupTemplateName;
  HGLOBAL         hPrintTemplate;
  HGLOBAL         hSetupTemplate;
} PRINTDLGA, *LPPRINTDLGA;

Membros

lStructSize

Tipo: DWORD

O tamanho da estrutura, em bytes.

hwndOwner

Digite: HWND

Um identificador para a janela que possui a caixa de diálogo. Esse membro pode ser qualquer identificador de janela válido ou pode ser NULL se a caixa de diálogo não tiver proprietário.

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 PrintDlg usa os dados de entrada para inicializar os controles na caixa de diálogo. Quando PrintDlg retorna, os membros DEVMODE indicam a entrada do usuário.

Se hDevMode for NULL na entrada, PrintDlg alocará memória para a estrutura DEVMODE , inicializará seus membros para indicar a entrada do usuário e retornará um identificador que a identifica.

Se o driver de dispositivo da impressora especificada não oferecer suporte a modos de dispositivo estendidos, hDevMode será NULL quando PrintDlg retornar.

Se o nome do dispositivo (especificado pelo membro dmDeviceName da estrutura DEVMODE ) não aparecer na seção [dispositivos] de WIN.INI, PrintDlg retornará um erro.

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 PrintDlg usa os dados de entrada para inicializar os controles na caixa de diálogo. Quando PrintDlg 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, PrintDlg 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.

Flags

Tipo: DWORD

Inicializa a caixa de diálogo Imprimir . Quando a caixa de diálogo retorna, ela define esses sinalizadores para indicar a entrada do usuário. Esse membro pode ser um ou mais dos valores a seguir.

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 e PD_SELECTION não estã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 PrintDlg 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_DISABLEPRINTTOFILE
0x00080000
Desabilita a caixa Imprimir no Arquivo marcar.
PD_ENABLEPRINTHOOK
0x00001000
Habilita o procedimento de gancho especificado no membro lpfnPrintHook . Isso habilita o procedimento de gancho para a caixa de diálogo Imprimir .
PD_ENABLEPRINTTEMPLATE
0x00004000
Indica que os membros hInstance e lpPrintTemplateName especificam uma substituição para o modelo padrão da caixa de diálogo Imprimir .
PD_ENABLEPRINTTEMPLATEHANDLE
0x00010000
Indica que o membro hPrintTemplate identifica um bloco de dados que contém um modelo de caixa de diálogo pré-carregado. Esse modelo substitui o modelo padrão para a caixa de diálogo Imprimir . O sistema ignorará o membro lpPrintTemplateName se esse sinalizador for especificado.
PD_ENABLESETUPHOOK
0x00002000
Habilita o procedimento de gancho especificado no membro lpfnSetupHook . Isso habilita o procedimento de gancho para a caixa de diálogo Configuração de Impressão .
PD_ENABLESETUPTEMPLATE
0x00008000
Indica que os membros hInstance e lpSetupTemplateName especificam uma substituição para o modelo de caixa de diálogo configuração de impressão padrão.
PD_ENABLESETUPTEMPLATEHANDLE
0x00020000
Indica que o membro hSetupTemplate identifica um bloco de dados que contém um modelo de caixa de diálogo pré-carregada. Esse modelo substitui o modelo padrão para a caixa de diálogo Configuração de Impressão . O sistema ignorará o membro lpSetupTemplateName se esse sinalizador for especificado.
PD_HIDEPRINTTOFILE
0x00100000
Oculta a caixa Imprimir no Arquivo marcar.
PD_NONETWORKBUTTON
0x00200000
Oculta e desabilita o botão Rede .
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 não há nenhuma impressora padrão.
PD_PAGENUMS
0x00000002
Se esse sinalizador estiver definido, o botão de opção Páginas será selecionado. Se esse sinalizador for definido quando a função PrintDlg retornar, os membros nFromPage e nToPage indicarão as páginas iniciais e finais especificadas pelo usuário.
PD_PRINTSETUP
0x00000040
Faz com que o sistema exiba a caixa de diálogo Configuração de Impressão em vez da caixa de diálogo Imprimir .
PD_PRINTTOFILE
0x00000020
Se esse sinalizador estiver definido, a caixa Imprimir no Arquivo marcar será selecionada. Se esse sinalizador for definido quando a função PrintDlg 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 esta 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 pelo nome do arquivo de saída.
PD_RETURNDC
0x00000100
Faz com que PrintDlg retorne um contexto de dispositivo correspondente às seleções feitas pelo usuário na caixa de diálogo. O contexto do dispositivo é retornado no hDC.
PD_RETURNDEFAULT
0x00000400
Se esse sinalizador estiver definido, a função PrintDlg não exibirá a caixa de diálogo. Em vez disso, ele define os membros hDevNames e hDevMode para identificadores para estruturas DEVMODE e DEVNAMES inicializadas para a impressora padrão do sistema. HDevNames e hDevMode devem ser NULL ou PrintDlg 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 nem PD_PAGENUMS nem PD_SELECTION estiver definido, o botão de opção Todos será selecionado.
PD_SHOWHELP
0x00000800
Faz com que a caixa de diálogo exiba o botão Ajuda . O membro hwndOwner deve especificar a janela para receber as mensagens registradas HELPMSGSTRING que a caixa de diálogo envia quando o usuário clica no botão Ajuda .
PD_USEDEVMODECOPIES
0x00040000
O mesmo que PD_USEDEVMODECOPIESANDCOLLATE.
PD_USEDEVMODECOPIESANDCOLLATE
0x00040000
Esse sinalizador indica se seu 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 PRINTDLG 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 PRINTDLG 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 a partir 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 oferecer 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 oferecer suporte à ordenação, a caixa Agrupar marcar será desabilitada.

Os membros dmCopies e dmCollate da estrutura DEVMODE contêm as cópias e agrupam informações 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 será sempre zero.

Problema conhecido no Windows 2000/XP/2003: Se esse sinalizador não estiver definido antes de chamar PrintDlg, PrintDlg poderá trocar valores de nCopies e dmCopies quando retornar. A solução alternativa para esse problema é usar dmCopies se seu valor for maior que 1, caso contrário, use nCopies, para que você obtenha o número real de cópias a serem impressas quando PrintDlg retornar.

 

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.

No Windows Vista e no Windows 7, 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.

nFromPage

Tipo: WORD

O valor inicial para o controle de edição de página inicial.

Quando PrintDlg retorna, nFromPage é a página inicial especificada pelo usuário. Se o botão de opção Páginas for selecionado quando o usuário clicar no botão Ok , PrintDlg definirá o sinalizador PD_PAGENUMS e não retornará até que o usuário insira um valor de página inicial dentro do intervalo de páginas mínimo a máximo.

Se o valor de entrada para nFromPage ou nToPage estiver fora do intervalo mínimo/máximo, PrintDlg retornará um erro somente se o sinalizador PD_PAGENUMS for especificado; caso contrário, ele exibe a caixa de diálogo, mas altera o valor fora do intervalo para o valor mínimo ou máximo.

nToPage

Tipo: WORD

O valor inicial para o controle de edição de página final. Quando PrintDlg retorna, nToPage é a página final especificada pelo usuário. Se o botão de opção Páginas for selecionado quando o uso clicar no botão Ok , PrintDlg definirá o sinalizador PD_PAGENUMS e não retornará até que o usuário insira um valor de página final dentro do intervalo de páginas mínimo a máximo.

nMinPage

Tipo: WORD

O valor mínimo para o intervalo de páginas especificado nos controles de edição de página De e Para . Se nMinPage for igual a nMaxPage, o botão de opção Páginas e os controles de edição de página inicial e final serão desabilitados.

nMaxPage

Tipo: WORD

O valor máximo para o intervalo de páginas especificado nos controles de edição de página De e Para .

nCopies

Tipo: WORD

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 PrintDlg retorna, nCopies contém o número real de cópias a serem impressas. 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 será sempre 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 ou PD_ENABLESETUPTEMPLATE estiver definido no membro Flags , hInstance será um identificador para a instância do aplicativo ou módulo que contém o modelo da caixa de diálogo nomeado pelo membro lpPrintTemplateName ou lpSetupTemplateName .

lCustData

Tipo: LPARAM

Dados definidos pelo aplicativo que o sistema passa para o procedimento de gancho identificado pelo membro lpfnPrintHook ou lpfnSetupHook . Quando o sistema envia a mensagem WM_INITDIALOG para o procedimento de gancho, o parâmetro lParam da mensagem é um ponteiro para a estrutura PRINTDLG especificada quando a caixa de diálogo foi criada. O procedimento de gancho pode usar esse ponteiro para obter o valor lCustData .

lpfnPrintHook

Tipo: LPPRINTHOOKPROC

Um ponteiro para um procedimento de gancho PrintHookProc que pode processar mensagens destinadas à caixa de diálogo Imprimir . Esse membro é ignorado, a menos que o sinalizador PD_ENABLEPRINTHOOK seja definido no membro Flags .

lpfnSetupHook

Tipo: LPSETUPHOOKPROC

Um ponteiro para um procedimento de gancho SetupHookProc que pode processar mensagens destinadas à caixa de diálogo Configuração de Impressão . Esse membro é ignorado, a menos que o sinalizador PD_ENABLESETUPHOOK seja definido no membro Flags .

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 padrão da caixa de diálogo Imprimir . Esse membro é ignorado, a menos que o sinalizador PD_ENABLEPRINTTEMPLATE seja definido no membro Flags .

lpSetupTemplateName

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 padrão da caixa de diálogo Configuração de Impressão . Esse membro é ignorado, a menos que o sinalizador PD_ENABLESETUPTEMPLATE seja definido no membro Flags .

hPrintTemplate

Tipo: HGLOBAL

Se o sinalizador PD_ENABLEPRINTTEMPLATEHANDLE estiver definido no membro Flags , hPrintTemplate será um identificador para um objeto de memória que contém um modelo de caixa de diálogo. Esse modelo substitui o modelo padrão da caixa de diálogo Imprimir .

hSetupTemplate

Tipo: HGLOBAL

Se o sinalizador PD_ENABLESETUPTEMPLATEHANDLE for definido no membro Flags , hSetupTemplate será um identificador para um objeto de memória que contém um modelo de caixa de diálogo. Esse modelo substitui o modelo padrão da caixa de diálogo Configuração de Impressão .

Comentários

Se hDevMode e hDevNames forem NULL, PrintDlg inicializará a caixa de diálogo usando a impressora padrão atual. Para inicializar a caixa de diálogo 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, PrintDlg inicializará a caixa de diálogo usando a impressora especificada por wDeviceOffset.

Se o sinalizador PD_RETURNDEFAULT estiver definido e hDevMode e hDevNames forem NULL, PrintDlg usará os membros hDevNames e hDevMode para retornar informações sobre a impressora padrão atual sem exibir a caixa de diálogo.

Observação

O cabeçalho commdlg.h define PRINTDLG 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

DEVMODE

DEVNAMES

Printdlg

Referência

WM_INITDIALOG