Classe CPrintDialog

Encapsula os serviços fornecidos pela caixa de diálogo comum do Windows para impressão.

Sintaxe

class CPrintDialog : public CCommonDialog

Membros

Construtores públicos

Nome	Descrição
CPrintDialog::CPrintDialog	Constrói um objeto CPrintDialog.

Métodos públicos

Nome	Descrição
CPrintDialog::CreatePrinterDC	Cria um contexto de dispositivo de impressora sem exibir a caixa de diálogo Imprimir.
CPrintDialog::DoModal	Exibe a caixa de diálogo e permite que o usuário faça uma seleção.
CPrintDialog::GetCopies	Recupera o número de cópias solicitadas.
CPrintDialog::GetDefaults	Recupera os padrões do dispositivo sem exibir uma caixa de diálogo.
CPrintDialog::GetDeviceName	Recupera o nome do dispositivo de impressora selecionado no momento.
CPrintDialog::GetDevMode	Recupera a estrutura DEVMODE.
CPrintDialog::GetDriverName	Recupera o nome do driver de impressora selecionado no momento.
CPrintDialog::GetFromPage	Recupera a página inicial do intervalo de impressão.
CPrintDialog::GetPortName	Recupera o nome da porta da impressora selecionada no momento.
CPrintDialog::GetPrinterDC	Recupera um identificador para o contexto do dispositivo de impressora.
CPrintDialog::GetToPage	Recupera a página final do intervalo de impressão.
CPrintDialog::PrintAll	Determina se todas as páginas do documento devem ser impressas.
CPrintDialog::PrintCollate	Determina se as cópias agrupadas são solicitadas.
CPrintDialog::PrintRange	Determina se é necessário imprimir apenas um intervalo de páginas especificado.
CPrintDialog::PrintSelection	Determina se os itens selecionados no momento devem ser impressos.

Membros de Dados Públicos

Nome	Descrição
CPrintDialog::m_pd	Uma estrutura usada para personalizar um objeto CPrintDialog.

Comentários

As caixas de diálogo de impressão comuns fornecem um m odo fácil de implementar caixas de diálogo Impressão e Configuração de Impressão de maneira consistente com os padrões do Windows.

Observação

A classe CPrintDialogEx encapsula os serviços fornecidos pela folha de propriedades do Windows Print. Para mais informações, confira a visão geral de CPrintDialogEx.

A funcionalidade de CPrintDialog é substituída pela de CPageSetupDialog, que foi projetada para fornecer uma caixa de diálogo comum para configuração de impressão e configuração de página.

Você pode contar com a estrutura para lidar com muitos aspectos do processo de impressão para seu aplicativo. Nesse caso, a estrutura exibe automaticamente a caixa de diálogo comum do Windows para impressão. Você também pode ter o identificador de estrutura de impressão para seu aplicativo, mas substituir a caixa de diálogo Imprimir comum pela sua caixa de diálogo de impressão. Para mais informações sobre como usar a estrutura para lidar com tarefas de impressão, confira o artigo Como imprimir.

Se você quiser que seu aplicativo manipule a impressão sem o envolvimento da estrutura, você pode usar a classe CPrintDialog "no estado em que se encontra" com o construtor fornecido ou derivar sua classe de diálogo de CPrintDialog e escrever um construtor para atender às suas necessidades. Em ambos os casos, essas caixas de diálogo se comportarão como caixas de diálogo MFC padrão porque são derivadas da classe CCommonDialog.

Para usar um objeto CPrintDialog, primeiro crie o objeto usando o construtor CPrintDialog. Depois que a caixa de diálogo for construída, você poderá definir ou modificar qualquer valor na estrutura m_pd para inicializar os valores dos controles da caixa de diálogo. A estrutura m_pd é do tipo PRINTDLG. Para obter mais informações sobre essa estrutura, confira o SDK do Windows.

Se você não fornecer identificadores próprios em m_pd para os membros hDevMode e hDevNames, chame a função GlobalFree do Windows para esses identificadores quando terminar de usar a caixa de diálogo. Ao usar a implementação de Instalação de Impressão da estrutura fornecida por CWinApp::OnFilePrintSetup, você não precisa liberar esses identificadores. Os identificadores são mantidos por CWinApp e são liberados no destruidor de CWinApp. Só é necessário liberar essas alças ao usar o CPrintDialog autônomo.

Depois de inicializar os controles da caixa de diálogo, chame a função de membro DoModal para exibir a caixa de diálogo e permitir que o usuário selecione opções de impressão. DoModal retornará se o usuário tiver selecionado o botão OK (IDOK) ou Cancelar (IDCANCEL).

Se DoModal retornar IDOK, você poderá usar uma das funções de membro CPrintDialog para recuperar a entrada de informações pelo usuário.

A função de membro CPrintDialog::GetDefaults é útil para recuperar os padrões atuais da impressora sem exibir uma caixa de diálogo. Essa função de membro não requer interação do usuário.

Você pode usar a função CommDlgExtendedError do Windows para determinar se ocorreu um erro durante a inicialização da caixa de diálogo e saber mais sobre o erro. Para obter mais informações sobre essa função, confira o SDK do Windows.

CPrintDialog depende do arquivo COMMDLG.DLL fornecido com as versões 3.1 e posteriores do Windows.

Para personalizar a caixa de diálogo, derive uma classe de CPrintDialog, forneça um modelo de caixa de diálogo personalizado e adicione um mapa de mensagem para processar as mensagens de notificação dos controles estendidos. Todas as mensagens não processadas devem ser passadas para a classe base. A personalização da função de gancho não é necessária.

Para processar a mesma mensagem de modo diferente, dependendo se a caixa de diálogo é Imprimir ou Configurar Impressão, você deve derivar uma classe para cada caixa de diálogo. Você também deve substituir a função AttachOnSetup do Windows, que manipula a criação de uma nova caixa de diálogo quando o botão Configurar Impressão é selecionado em uma caixa de diálogo Imprimir.

Para obter mais informações sobre como usar CPrintDialog, confira Classes de diálogo comuns.

Hierarquia de herança

CObject

CCmdTarget

CWnd

CDialog

CCommonDialog

CPrintDialog

Requisitos

Cabeçalho: afxdlgs.h

CPrintDialog::CPrintDialog

Constrói um objeto de caixa de diálogo Impressão ou Configuração de Impressão do Windows.

CPrintDialog(
    BOOL bPrintSetupOnly,
    DWORD dwFlags = PD_ALLPAGES | PD_USEDEVMODECOPIES | PD_NOPAGENUMS | PD_HIDEPRINTTOFILE | PD_NOSELECTION,
    CWnd* pParentWnd = NULL);

Parâmetros

bPrintSetupOnly
Especifica se a caixa de diálogo Padrão do Windows Print ou a caixa de diálogo Configuração de Impressão é exibida. Defina esse parâmetro para TRUE para exibir a caixa de diálogo configuração de impressão padrão do Windows. Defina-o para FALSE exibir a caixa de diálogo Impressão do Windows. Se bPrintSetupOnly for FALSE, um botão de opção Configuração de Impressão ainda será exibido na caixa de diálogo Imprimir.

dwFlags
Um ou mais sinalizadores que você pode usar para personalizar as configurações da caixa de diálogo, combinados usando o operador OR bit a bit. Por exemplo, o sinalizador PD_ALLPAGES define o intervalo de impressão padrão para todas as páginas do documento. Confira a estrutura PRINTDLG no SDK do Windows para obter informações sobre esses sinalizadores.

pParentWnd
Um ponteiro para a janela pai ou proprietária da caixa de diálogo.

Comentários

Essa função de membro só constrói o objeto. Use a função de membro DoModal para exibir a caixa de diálogo.

Observe que, quando você chama o construtor com bPrintSetupOnly definido como FALSE, o sinalizador PD_RETURNDC é usado automaticamente. Depois de chamar DoModal, GetDefaults ou GetPrinterDC, um DC de impressora será retornado em m_pd.hDC. Este DC deve ser liberado com uma chamada para DeleteDC pelo chamador de CPrintDialog.

Exemplo

// Display the Windows Print dialog box with "All" radio button 
// initially selected. All other radio buttons are disabled.
CPrintDialog dlg1(FALSE);

// Display the Windows Print dialog box with Collate check box checked.  
CPrintDialog dlg2(FALSE, PD_ALLPAGES | PD_COLLATE | PD_NOPAGENUMS | PD_HIDEPRINTTOFILE);

// Display the Windows Print dialog box with "Selection" radio
// button initially selected. "All" radio button is enabled
// but "Pages" radio button is disabled.
CPrintDialog dlg3(FALSE, PD_SELECTION | PD_USEDEVMODECOPIES);

CPrintDialog::CreatePrinterDC

Cria um DC (contexto de dispositivo) de impressora com base nas estruturas DEVMODE e DEVNAMES.

HDC CreatePrinterDC();

Valor de retorno

Identificador para o contexto de dispositivo de impressora que acaba de ser criado.

Comentários

Supõe-se que esse DC seja o DC da impressora atual e todos os outros DCs de impressora obtidos anteriormente devem ser excluídos pelo usuário. Essa função pode ser chamada e o DC resultante pode ser usado sem nunca exibir a caixa de diálogo Imprimir.

Exemplo

// Display the Windows Print dialog box with "All" radio button 
// initially selected. All other radio buttons are disabled.
CPrintDialog dlg(FALSE);
if (dlg.DoModal() == IDOK)
{
   // Create a printer device context (DC) based on the information
   // selected from the Print dialog.
   HDC hdc = dlg.CreatePrinterDC();
   ASSERT(hdc);
}

CPrintDialog::DoModal

Exibe a caixa de diálogo de impressão comum do Windows e permite que o usuário selecione várias opções de impressão, como o número de cópias, o intervalo de páginas e se as cópias devem ser agrupadas.

virtual INT_PTR DoModal();

Valor de retorno

IDOK ou IDCANCEL. Se IDCANCEL for retornado, chame a função CommDlgExtendedError do Windows para determinar se ocorreu um erro.

IDOK e IDCANCEL são constantes que indicam se o usuário selecionou o botão OK ou Cancelar.

Comentários

Se você quiser inicializar as várias opções de diálogo de impressão definindo membros da estrutura m_pd, faça isso antes de chamar DoModal, mas depois que o objeto de caixa de diálogo tiver sido construído.

Depois de chamar DoModal, você poderá chamar outras funções de membro para recuperar as configurações ou a entrada de informações do usuário na caixa de diálogo.

Observe que, quando você chama o construtor com bPrintSetupOnly definido como FALSE, o sinalizador PD_RETURNDC é usado automaticamente. Depois de chamar DoModal, GetDefaults ou GetPrinterDC, um DC de impressora será retornado em m_pd.hDC. Este DC deve ser liberado com uma chamada para DeleteDC pelo chamador de CPrintDialog.

Exemplo

Confira o exemplo de CPrintDialog::CreatePrinterDC.

CPrintDialog::GetCopies

Recupera o número de cópias solicitadas.

int GetCopies() const;

Valor de retorno

O número de cópias solicitadas.

Comentários

Chame essa função depois de chamar DoModal para recuperar o número de cópias solicitadas.

Exemplo

Confira o exemplo de CPrintDialog::PrintCollate.

CPrintDialog::GetDefaults

Recupera os padrões do dispositivo da impressora padrão sem exibir uma caixa de diálogo.

BOOL GetDefaults();

Valor de retorno

Diferente de zero se a função foi bem-sucedida, caso contrário, 0.

Comentários

Os valores recuperados são colocados na estrutura m_pd.

Em alguns casos, uma chamada para essa função chamará o construtor para CPrintDialog com bPrintSetupOnly definido como FALSE. Nesses casos, um DC da impressora e hDevNames e hDevMode (dois identificadores localizados no membro de dados m_pd) são alocados automaticamente.

Se o construtor para CPrintDialog for chamado com bPrintSetupOnly definido como FALSE, essa função não retornará apenas hDevNames e hDevMode localizados em m_pd.hDevNames e m_pd.hDevMode) para o chamador, mas também retornará um DC de impressora em m_pd.hDC. É responsabilidade do chamador excluir o DC da impressora e chamar a função GlobalFree do Windows nos identificadores quando terminar de usar o objeto CPrintDialog.

Exemplo

Esse fragmento de código obtém o contexto do dispositivo da impressora padrão e relata ao usuário a resolução da impressora em pontos por polegada. (Esse atributo dos recursos da impressora geralmente é chamado de DPI.)

CPrintDialog dlg(FALSE);

if (!dlg.GetDefaults())
{
   AfxMessageBox(_T("You have no default printer!"));
}
else
{
   // attach to the DC we were given
   CDC dc;
   dc.Attach(dlg.m_pd.hDC);

   // ask for the measurements
   int nHorz = dc.GetDeviceCaps(LOGPIXELSX);
   int nVert = dc.GetDeviceCaps(LOGPIXELSY);

   // almost always the same in both directions, but sometimes not!
   CString str;
   if (nHorz == nVert)
   {
      str.Format(_T("Your printer supports %d pixels per inch"), nHorz);
   }
   else
   {
      str.Format(_T("Your printer supports %d pixels per inch ")
         _T("horizontal resolution, and %d pixels per inch vertical ")
         _T("resolution"), nHorz, nVert);
   }

   // tell the user
   AfxMessageBox(str);

   // Note: no need to call Detach() because we want the CDC destructor
   // to call FreeDC() on the DC we borrowed from the common dialog
}

CPrintDialog::GetDeviceName

Recupera o nome do dispositivo de impressora selecionado no momento.

CString GetDeviceName() const;

Valor de retorno

O nome da impressora selecionada no momento.

Comentários

Chame essa função depois de chamar DoModal para recuperar o nome da impressora selecionada no momento ou depois de chamar GetDefaults para recuperar os padrões atuais do dispositivo da impressora padrão. Use um ponteiro para o objeto CString retornado por GetDeviceName como o valor de lpszDeviceName em uma chamada para CDC::CreateDC.

Exemplo

Esse fragmento de código mostra o nome padrão da impressora do usuário e a porta à qual ele está conectado, além do nome do spooler usado pela impressora. O código pode mostrar uma caixa de mensagem que diz: "Sua impressora padrão é HP LaserJet IIIP em \\server\share using winspool.", por exemplo.

CPrintDialog dlg(FALSE);

if (!dlg.GetDefaults())
{
   AfxMessageBox(_T("You have no default printer!"));
}
else
{
   CString strDescription;

   strDescription.Format(_T("Your default printer is %s on %s using %s."),
      (LPCTSTR)dlg.GetDeviceName(),
      (LPCTSTR)dlg.GetPortName(),
      (LPCTSTR)dlg.GetDriverName());

   AfxMessageBox(strDescription);
}

CPrintDialog::GetDevMode

Recupera a estrutura DEVMODE.

LPDEVMODE GetDevMode() const;

Valor de retorno

A estrutura de dados DEVMODE, que contém informações sobre a inicialização do dispositivo e o ambiente de um driver de impressão. Você deve desbloquear a memória obtida por essa estrutura com a função GlobalUnlock do Windows, que é descrita no SDK do Windows.

Comentários

Chame essa função depois de chamar DoModal ou GetDefaults para recuperar informações sobre o dispositivo de impressão.

Exemplo

Confira o exemplo de CPrintDialog::PrintCollate.

CPrintDialog::GetDriverName

Recupera o nome do driver de impressora selecionado no momento.

CString GetDriverName() const;

Valor de retorno

Um CString especificando o nome do driver definido pelo sistema.

Comentários

Chame essa função depois de chamar DoModal ou GetDefaults para recuperar o nome do driver de dispositivo de impressora definido pelo sistema. Use um ponteiro para o objeto CString retornado por GetDriverName como o valor de lpszDriverName em uma chamada para CDC::CreateDC.

Exemplo

Confira o exemplo de CPrintDialog::GetDeviceName.

CPrintDialog::GetFromPage

Recupera a página inicial do intervalo de impressão.

int GetFromPage() const;

Valor de retorno

O número da página inicial no intervalo de páginas a serem impressas.

Comentários

Chame essa função depois de chamar DoModal para recuperar o número da página inicial no intervalo de páginas a serem impressas.

Exemplo

Confira o exemplo de CPrintDialog::m_pd.

CPrintDialog::GetPortName

Recupera o nome da porta da impressora selecionada no momento.

CString GetPortName() const;

Valor de retorno

O nome da porta da impressora selecionada no momento.

Comentários

Chame essa função depois de chamar DoModal ou GetDefaults para recuperar o nome da porta da impressora selecionada no momento.

Exemplo

Confira o exemplo de CPrintDialog::GetDeviceName.

CPrintDialog::GetPrinterDC

Recupera um identificador para o contexto do dispositivo de impressora.

HDC GetPrinterDC() const;

Valor de retorno

Um identificador para o contexto do dispositivo da impressora, se for bem-sucedido; caso contrário NULL.

Comentários

Se o parâmetro bPrintSetupOnly do construtor CPrintDialog for FALSE (indicando que a caixa de diálogo Imprimir é exibida), GetPrinterDC retornará um identificador para o contexto do dispositivo da impressora. Você deve chamar a função DeleteDC do Windows para excluir o contexto do dispositivo quando terminar de usá-lo.

Exemplo

CPrintDialog dlg(FALSE);
CPrintDialog dlg(FALSE);
if (dlg.DoModal() == IDOK)
{
   // Get a handle to the printer device context (DC).
   HDC hdc = dlg.GetPrinterDC();
   ASSERT(hdc);

   // Do something with the HDC...

   // Clean up.
   CDC::FromHandle(hdc)->DeleteDC();
}

CPrintDialog::GetToPage

Recupera a página final do intervalo de impressão.

int GetToPage() const;

Valor de retorno

O número da página final no intervalo de páginas a serem impressas.

Comentários

Chame essa função depois de chamar DoModal para recuperar o número de página final no intervalo de páginas a serem impressas.

Exemplo

Confira o exemplo de CPrintDialog::m_pd.

CPrintDialog::m_pd

Uma estrutura cujos membros armazenam as características do objeto de caixa de diálogo.

PRINTDLG& m_pd;

Comentários

Depois de construir um objeto CPrintDialog, você pode usar m_pd para definir vários aspectos da caixa de diálogo antes de chamar a função de membro DoModal. Para mais informações sobre a estrutura m_pd, confira PRINTDLG no SDK do Windows.

Se você modificar o membro de dados m_pd diretamente, substituirá qualquer comportamento padrão.

Exemplo

// Display the Windows Print dialog box with "Pages" radio button
// initially selected. "All" and "Pages" radio buttons are
// enabled as well.
CPrintDialog dlg(FALSE, PD_PAGENUMS | PD_USEDEVMODECOPIES);
dlg.m_pd.nMinPage = dlg.m_pd.nFromPage = 1;
dlg.m_pd.nMaxPage = dlg.m_pd.nToPage = 10;
if (dlg.DoModal() == IDOK)
{
   // Determine the starting and ending page numbers for the range 
   // of pages to be printed.

   int from_page = -1, to_page = -1;
   if (dlg.PrintAll())              // print all pages in the document
   {
      from_page = dlg.m_pd.nMinPage;
      to_page = dlg.m_pd.nMaxPage;
   }
   else if (dlg.PrintRange())       // print only a range of pages 
   {                                // in the document 
      from_page = dlg.GetFromPage();
      to_page = dlg.GetToPage();
   }
   else if (dlg.PrintSelection())   // print only the currently selected 
                                    // items
   {
      from_page = to_page = -1;     // -1 to denote unknown yet
   }

   TRACE(_T("Print from %d to %d\n"), from_page, to_page);
}

CPrintDialog::PrintAll

Determina se todas as páginas do documento devem ser impressas.

BOOL PrintAll() const;

Valor de retorno

Não zero se todas as páginas no documento forem impressas; caso contrário, 0.

Comentários

Chame essa função depois de chamar DoModal para determinar se todas as páginas devem ser impressas no documento.

Exemplo

Confira o exemplo de CPrintDialog::m_pd.

CPrintDialog::PrintCollate

Determina se as cópias agrupadas são solicitadas.

BOOL PrintCollate() const;

Valor de retorno

Não zero se o usuário marcar caixa de seleção de ordenação na caixa de diálogo; caso contrário, 0.

Comentários

Chame essa função depois de chamar DoModal para determinar se a impressora deve reunir todas as cópias impressas do documento.

Exemplo

// Display the Windows Print dialog box with Collate check box checked.
CPrintDialog dlg(FALSE, PD_ALLPAGES | PD_COLLATE | PD_NOPAGENUMS |
   PD_HIDEPRINTTOFILE);
if (dlg.DoModal() == IDOK)
{
   // If the collate check box is selected, then GetCopies() will return
   // the number of copies printed. Otherwise, GetCopies() always 
   // returns 1. Then, the number of copies printed can be found from the
   // DEVMODE structure of the printing device.
   if (dlg.PrintCollate())
   {
      int num = dlg.GetCopies();
      TRACE(_T("Number of copies printed = %d\n"), num);
   }
   else
   {
      LPDEVMODE devmode = dlg.GetDevMode();
      TRACE(_T("Number of copies printed = %d\n"), devmode->dmCopies);
   }
}

CPrintDialog::PrintRange

Determina se é necessário imprimir apenas um intervalo de páginas especificado.

BOOL PrintRange() const;

Valor de retorno

Não zero se apenas um intervalo de páginas no documento for impresso; caso contrário, 0.

Comentários

Chame essa função depois de chamar DoModal para determinar se deseja imprimir apenas um intervalo de páginas no documento.

Exemplo

Confira o exemplo de CPrintDialog::m_pd.

CPrintDialog::PrintSelection

Determina se os itens selecionados no momento devem ser impressos.

BOOL PrintSelection() const;

Valor de retorno

Não zero se apenas os itens selecionados forem impressos; caso contrário, 0.

Comentários

Chame essa função depois de chamar DoModal para determinar se você deseja imprimir apenas os itens selecionados no momento.

Exemplo

Confira o exemplo de CPrintDialog::m_pd.

Confira também

Exemplo de MFC DIBLOOK
Classe CCommonDialog
Gráfico da hierarquia
Estrutura CPrintInfo