Compartilhar via


Caixa de diálogo Imprimir

A caixa de diálogo Imprimir permite que o usuário selecione opções para um trabalho de impressão específico. Por exemplo, o usuário pode especificar a impressora a ser usada, o intervalo de páginas a serem impressas e o número de cópias.

Você pode usar a função PrintDlgEx para exibir uma Folha de Propriedades de Impressão, que tem uma página Geral contendo controles semelhantes à caixa de diálogo Imprimir . A folha de propriedades também pode ter páginas de propriedades adicionais específicas do aplicativo e específicas do driver seguindo a página Geral .

Crie e exiba uma caixa de diálogo Imprimir inicializando uma estrutura PRINTDLG e passando a estrutura para a função PrintDlg .

A ilustração a seguir mostra uma caixa de diálogo Imprimir típica.

caixa de diálogo imprimir

Se o usuário clicar no botão OK , PrintDlg retornará TRUE e usará a estrutura PRINTDLG para retornar informações sobre as seleções do usuário. Por exemplo, os membros hDevMode e hDevNames normalmente retornam identificadores de memória globais para e estruturas DEVNAMES . Você pode usar as informações nessas estruturas para criar um contexto de dispositivo ou um contexto de informações para a impressora selecionada.

Se o usuário cancelar a caixa de diálogo Imprimir ou ocorrer um erro, PrintDlg retornará FALSE. Você pode determinar a causa de um erro usando a função CommDlgExtendedError para recuperar o valor de erro estendido.

A caixa de diálogo Imprimir inclui um grupo de botões de opção Intervalo de Impressão que indica se o usuário deseja imprimir todas as páginas, um intervalo de páginas ou apenas o texto selecionado. Antes de chamar PrintDlg, você pode definir um dos sinalizadores PD_ALLPAGES, PD_SELECTION ou PD_PAGENUMS para indicar qual botão está selecionado inicialmente. Quando PrintDlg retorna TRUE, a função define um desses sinalizadores para indicar as seleções do usuário. Se PD_PAGENUMS estiver definido, os membros nFromPage e nToPage da estrutura PRINTDLG conterão as páginas inicial e final especificadas pelo usuário. Para desabilitar o botão de opção Páginas e seus controles de edição From e To associados, defina o sinalizador PD_NOPAGENUMS . Para desabilitar o botão de opção Seleção , defina o sinalizador PD_NOSELECTION .

A caixa de diálogo inclui um controle de edição no qual o usuário pode digitar o número de cópias a serem impressas. Se o membro hDevMode da estrutura PRINTDLG não for NULL, o membro dmCopies da estrutura especificará o valor inicial para esse controle de edição. Se hDevMode for NULL, o membro nCopies da estrutura PRINTDLG especificará o valor inicial. Quando PrintDlg retorna, nCopies normalmente indica o número de cópias especificadas pelo usuário. No entanto, se você definir o sinalizador PD_USEDEVMODECOPIESANDCOLLATE ao criar a caixa de diálogo, nCopies sempre será definido como 1 no retorno e o membro dmCopies de DEVMODE indicará o número de cópias a serem impressas.

A caixa Agrupar marcar indica se o usuário deseja agrupar as páginas se várias cópias estiverem sendo impressas. O sinalizador PD_COLLATE será definido se a caixa Agrupar marcar estiver selecionada. Se o aplicativo não der suporte a várias cópias ou ordenação simulada, defina o sinalizador PD_USEDEVMODECOPIESANDCOLLATE no membro Flags da estrutura PRINTDLG . Isso desabilita a caixa Agrupar marcar e o controle de edição Número de Cópias, a menos que o driver da impressora dê suporte a várias cópias e ordenação.

A caixa marcar Imprimir em Arquivo indica se o usuário deseja enviar a saída para um arquivo em vez de para uma impressora. Você pode definir o sinalizador PD_PRINTTOFILE para que a caixa de marcar seja selecionada inicialmente. Para ocultar a caixa de marcar, defina o sinalizador PD_HIDEPRINTTOFILE. Para desabilitá-lo, defina o sinalizador PD_DISABLEPRINTTOFILE . Se o usuário selecionar a opção Imprimir em Arquivo , PrintDlg definirá o sinalizador PD_PRINTTOFILE e retornará "FILE:" no deslocamento indicado pelo membro wOutputOffset da estrutura DEVNAMES . Quando você chamar a função para iniciar a operação de impressão, especifique essa cadeia de caracteres "FILE:" no membro lpszOutput da estrutura. 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.

Por padrão, a caixa de diálogo Imprimir exibe inicialmente informações sobre a impressora padrão atual. Para exibir informações de outra impressora instalada, inicialize um e uma estrutura DEVNAMES e atribua o identificador de memória global à estrutura aos membros hDevMode e hDevNames . O nome do dispositivo especificado no membro dmDeviceName da estrutura DEVMODE e no membro wDriverOffset da estrutura DEVNAMES deve identificar um dispositivo de impressora que também está listado na seção [Dispositivos] do arquivo Win.ini. Se o dispositivo não estiver listado, PrintDlg retornará um erro.

Você pode direcionar PrintDlg para criar um contexto de dispositivo ou contexto de informações para a impressora definindo o sinalizador PD_RETURNDC ou PD_RETURNIC no membro Flags da estrutura PRINTDLG . A função retorna um identificador para o contexto do dispositivo ou contexto de informações no membro hDC . Se você usar o sinalizador PD_RETURNDC , poderá usar o contexto do dispositivo para gerar a saída para a impressora.

Para recuperar informações sobre a impressora padrão sem exibir a caixa de diálogo Imprimir , defina o sinalizador PD_RETURNDEFAULT . Nesse caso, PrintDlg retorna imediatamente após definir os membros hDevMode e hDevNames como identificadores para estruturas que contêm as informações.

Por padrão, PrintDlg exibe caixas de mensagem quando ocorrem erros. Por exemplo, a função exibirá uma mensagem de erro se nenhuma impressora estiver instalada. Para impedir que a função exiba essas mensagens de aviso, defina o sinalizador PD_NOWARNING .

Os tópicos a seguir são discutidos nesta seção.

Personalizando a caixa de diálogo Imprimir

Você pode fornecer um modelo personalizado para a caixa de diálogo Imprimir , por exemplo, se quiser incluir controles adicionais exclusivos para seu aplicativo. A função PrintDlg usa seu modelo personalizado no lugar do modelo padrão.

Para fornecer um modelo personalizado para a caixa de diálogo Imprimir :

  1. Crie o modelo personalizado modificando o modelo padrão especificado no arquivo Prnsetup.dlg. Os identificadores de controle usados no modelo de caixa de diálogo Imprimir padrão são definidos no arquivo Dlgs.h.
  2. Use a estrutura PRINTDLG para habilitar o modelo da seguinte maneira:
    • Se o modelo personalizado for um recurso em um aplicativo ou biblioteca de vínculo dinâmico, defina o sinalizador PD_ENABLEPRINTTEMPLATE no membro Flags . Use os membros hInstance e lpPrintTemplateName da estrutura para identificar o módulo e o nome do recurso.

      -Ou-

    • Se o modelo personalizado já estiver na memória, defina o sinalizador PD_ENABLEPRINTTEMPLATEHANDLE . Use o membro hPrintTemplate para identificar o objeto de memória que contém o modelo.

Você pode fornecer um procedimento de gancho PrintHookProc para a caixa de diálogo Imprimir . O procedimento de gancho pode processar mensagens enviadas para a caixa de diálogo. Ele também pode enviar mensagens para a caixa de diálogo. Se você usar um modelo personalizado para definir controles adicionais, deverá fornecer um procedimento de gancho para processar a entrada para seus controles.

Para habilitar um procedimento de gancho para a caixa de diálogo Imprimir :

  1. Defina o sinalizador PD_ENABLEPRINTHOOK no membro Flags da estrutura PRINTDLG .
  2. Especifique o endereço do procedimento de gancho no membro lpfnPrintHook .

Depois de processar sua mensagem de WM_INITDIALOG , o procedimento da caixa de diálogo envia uma mensagem WM_INITDIALOG para o procedimento de gancho. O parâmetro lParam dessa mensagem é um ponteiro para a estrutura PRINTDLG usada para inicializar a caixa de diálogo.

Você pode criar e exibir uma caixa de diálogo Configurar Impressão definindo o sinalizador PD_PRINTSETUP em uma chamada para a função PrintDlg . No entanto, a caixa de diálogo Configurar Impressão foi substituída pela caixa de diálogo Configuração de Página e não deve ser usada em novos aplicativos.

Os seguintes sinalizadores se aplicam somente à caixa de diálogo Configurar Impressão :

  • PD_ENABLESETUPHOOK
  • PD_ENABLESETUPTEMPLATE
  • PD_ENABLESETUPTEMPLATEHANDLE