CPrintDialog Classe

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

Métodos Públicos

Membros de Dados Públicos

Observações

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

CPrintDialogé substituída pela CPageSetupDialogde , que foi concebida para lhe fornecer uma caixa de diálogo comum tanto para a configuração de impressão como para a configuração da página.

Pode confiar no framework para tratar de muitos aspetos do processo de impressão para a sua aplicação. Neste caso, o framework mostra automaticamente a caixa de diálogo comum do Windows para impressão. Também podes fazer com que o framework trate da impressão para a tua aplicação, mas sobrepor a caixa de diálogo comum de Imprimir com a tua própria caixa de diálogo de impressão. Para mais informações sobre a utilização da estrutura para lidar com tarefas de impressão, consulte o artigo Impressão.

Se quiseres que a tua aplicação trate da impressão sem o envolvimento do framework, podes usar a CPrintDialog classe "como está" com o construtor fornecido, ou podes derivar a tua própria classe CPrintDialog de diálogo e escrever um construtor para satisfazer as tuas necessidades. Em qualquer dos casos, estas caixas de diálogo vão comportar-se como caixas de diálogo padrão do MFC porque derivam da classe CCommonDialog.

Para usar um CPrintDialog objeto, primeiro cria-o usando o CPrintDialog construtor. Depois de construída a caixa de diálogo, pode definir ou modificar quaisquer valores na m_pd estrutura para inicializar os valores dos controlos da caixa de diálogo. A m_pd estrutura é do tipo PRINTDLG. Para obter mais informações sobre essa estrutura, consulte o SDK do Windows.

Se não forneceres os teus próprios m_pd handles para os hDevMode membros and hDevNames , certifica-te de chamar a função GlobalFree Windows para esses handles quando terminares a caixa de diálogo. Ao usar a implementação Print Setup do framework fornecida por CWinApp::OnFilePrintSetup, não é necessário libertar estes handles. As alavancas são mantidas e CWinApp libertadas em CWinApp's destructor. Só é necessário libertar estas pegas quando usas CPrintDialog stand-alone.

Após inicializar os controlos da caixa de diálogo, chame a DoModal função membro para mostrar a caixa de diálogo e permitir que o utilizador selecione opções de impressão. DoModal retorna se o utilizador selecionou o botão OK (IDOK) ou Cancelar (IDCANCEL).

Se DoModal devolver IDOK, pode usar uma das CPrintDialogfunções membros de , para recuperar a informação introduzida pelo utilizador.

A CPrintDialog::GetDefaults função membro é útil para recuperar os valores predefinidos atuais da impressora sem apresentar uma caixa de diálogo. Esta função membro não requer interação do utilizador.

Pode usar a função Windows CommDlgExtendedError para determinar se ocorreu um erro durante a inicialização da caixa de diálogo e para saber mais sobre o erro. Para mais informações sobre esta função, consulte o SDK do Windows.

CPrintDialog depende do COMMDLG.DLL ficheiro que vem com as versões 3.1 do Windows e posteriores.

Para personalizar a caixa de diálogo, derive uma classe a partir de CPrintDialog, forneça um modelo de diálogo personalizado e adicione um mapa de mensagens para processar as mensagens de notificação a partir dos controlos estendidos. Quaisquer mensagens não processadas devem ser passadas para a classe base. Não é necessário personalizar a função de gancho.

Para processar a mesma mensagem de forma diferente dependendo se a caixa de diálogo é Imprimir ou Imprimir Setup, deve derivar uma classe para cada caixa de diálogo. Também deve sobrescrever a função Windows AttachOnSetup , que gere a criação de uma nova caixa de diálogo quando o botão Imprimir Configuração está selecionado numa caixa de diálogo Imprimir.

Para mais informações sobre a utilização CPrintDialogde , veja Classes Comuns de Diálogo.

Hierarquia de herança

CObject

CCmdTarget

CWnd

CDialog

CCommonDialog

CPrintDialog

Requerimentos

Cabeçalho:afxdlgs.h

CPrintDialog::CPrintDialog

Constrói um objeto de diálogo Windows Print ou Print Setup.

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 de Imprimir ou de Configuração de Imprimir é apresentada. Defina este parâmetro para TRUE mostrar a caixa de diálogo padrão de Configuração de Impressão do Windows. Defina para FALSE mostrar a caixa de diálogo Imprimir do Windows. Se bPrintSetupOnly for FALSE, um botão de opção Configuração de Impressão continua a ser exibido na caixa de diálogo Imprimir.

dwFlags
Uma ou mais flags podes usar para personalizar as definições da caixa de diálogo, combinados com o operador OR bit a bit. Por exemplo, o PD_ALLPAGES flag define o intervalo de impressão padrão para todas as páginas do documento. Consulte a PRINTDLG estrutura no SDK do Windows para mais informações sobre estas bandeiras.

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

Observações

Esta função membro apenas constrói o objeto. Use a DoModal função de membro para mostrar a caixa de diálogo.

Note que quando chama o construtor com bPrintSetupOnly definido como FALSE, a PD_RETURNDC flag é usada automaticamente. Após chamar DoModal, GetDefaults, ou GetPrinterDC, um DC de impressora será devolvido em m_pd.hDC. Este DC deve ser libertado com uma chamada para DeleteDC pelo chamador de CPrintDialog.

Example

// 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 contexto de dispositivo de impressora (DC) a partir das DEVMODE estruturas e.DEVNAMES

HDC CreatePrinterDC();

Valor de retorno

Handle para o contexto do dispositivo de impressora recém-criado.

Observações

Assume-se que este DC é o DC atual da impressora, e quaisquer outros DCs de impressora previamente obtidos devem ser eliminados pelo utilizador. Esta função pode ser chamada, e o DC resultante usado, sem nunca mostrar a caixa de diálogo Imprimir.

Example

// 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

Apresenta a caixa de diálogo comum de impressão do Windows e permite ao utilizador selecionar 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 devolvido, chame a função Windows CommDlgExtendedError para determinar se ocorreu um erro.

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

Observações

Se quiseres inicializar as várias opções de diálogo de impressão definindo membros da m_pd estrutura, deves fazê-lo antes de chamar DoModal, mas depois de o objeto de diálogo estar construído.

Depois de chamar DoModal, pode chamar outras funções membros para recuperar as definições ou informações introduzidas pelo utilizador na caixa de diálogo.

Note que quando chama o construtor com bPrintSetupOnly definido como FALSE, a PD_RETURNDC flag é usada automaticamente. Após chamar DoModal, GetDefaults, ou GetPrinterDC, um DC de impressora será devolvido em m_pd.hDC. Este DC deve ser libertado com uma chamada para DeleteDC pelo chamador de CPrintDialog.

Example

Veja o exemplo para 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.

Observações

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

Example

Veja o exemplo para CPrintDialog::PrintCollate.

CPrintDialog::GetDefaults

Recupera os valores predefinidos do dispositivo da impressora predefinida sem mostrar uma caixa de diálogo.

BOOL GetDefaults();

Valor de retorno

Não nula se a função fosse bem-sucedida; caso contrário, 0.

Observações

Os valores recuperados são colocados na m_pd estrutura.

Em alguns casos, uma chamada a esta função chamará o construtor para CPrintDialog com bPrintSetupOnly o conjunto em FALSE. Nestes casos, uma DC da impressora e hDevNames e hDevMode (duas alavancas localizadas no m_pd membro de dados) são automaticamente atribuídas.

Se o construtor for CPrintDialog for chamado com bPrintSetupOnly definido como FALSE, esta função não só devolverá hDevNames e hDevMode localizado em m_pd.hDevNames e m_pd.hDevMode) ao chamador, como também devolverá um DC de impressora em m_pd.hDC. É responsabilidade do chamador apagar o DC da impressora e chamar a função Windows GlobalFree nos handles quando terminares com o CPrintDialog objeto.

Example

Este fragmento de código recebe o contexto padrão do dispositivo da impressora e reporta ao utilizador a resolução da impressora em pontos por polegada. (Esta característica das capacidades da impressora é frequentemente referida como 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 atualmente selecionado.

CString GetDeviceName() const;

Valor de retorno

O nome do impressor atualmente selecionado.

Observações

Chame esta função depois de chamar DoModal para recuperar o nome da impressora atualmente selecionada, ou depois de chamar GetDefaults para recuperar os valores predefinidos atuais do dispositivo da impressora predefinida. Use um ponteiro para o CString objeto devolvido por GetDeviceName como valor de lpszDeviceName numa chamada para CDC::CreateDC.

Example

Este fragmento de código mostra o nome padrão da impressora do utilizador e a porta a que está ligado, juntamente com o nome do spooler que a impressora utiliza. O código pode mostrar uma caixa de mensagem que diz: "A sua impressora padrão é a HP LaserJet IIIP em \\servidor\partilhar usando 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 DEVMODE estrutura.

LPDEVMODE GetDevMode() const;

Valor de retorno

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

Observações

Ligue para esta função após chamar DoModal ou GetDefaults para obter informações sobre o dispositivo de impressão.

Example

Veja o exemplo para CPrintDialog::PrintCollate.

CPrintDialog::GetDriverName

Recupera o nome do driver da impressora atualmente selecionado.

CString GetDriverName() const;

Valor de retorno

A CString especificar o nome do driver definido pelo sistema.

Observações

Chame esta função após chamar DoModal ou GetDefaults para recuperar o nome do driver do dispositivo de impressora definido pelo sistema. Use um ponteiro para o CString objeto devolvido por GetDriverName como valor de lpszDriverName numa chamada para CDC::CreateDC.

Example

Veja o exemplo para CPrintDialog::GetDeviceName.

CPrintDialog::GetFromPage

Recupera a página inicial da gama de impressão.

int GetFromPage() const;

Valor de retorno

O número inicial da página dentro do intervalo de páginas a imprimir.

Observações

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

Example

Veja o exemplo para CPrintDialog::m_pd.

CPrintDialog::GetPortName

Recupera o nome da porta da impressora atualmente selecionada.

CString GetPortName() const;

Valor de retorno

O nome da porta da impressora atualmente selecionada.

Observações

Chame esta função após chamar DoModal ou GetDefaults para recuperar o nome da porta da impressora atualmente selecionada.

Example

Veja o exemplo para CPrintDialog::GetDeviceName.

CPrintDialog::GetPrinterDC

Recupera um handle para o contexto do dispositivo da impressora.

HDC GetPrinterDC() const;

Valor de retorno

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

Observações

Se o bPrintSetupOnly parâmetro do CPrintDialog construtor for FALSE (indicando que a caixa de diálogo Imprimir é exibida), então GetPrinterDC devolve um handle ao contexto do dispositivo de impressora. Tens de chamar a função Windows DeleteDC para apagar o contexto do dispositivo quando terminares de o usar.

Example

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 da gama de impressão.

int GetToPage() const;

Valor de retorno

O número da página final está no intervalo de páginas a imprimir.

Observações

Chame esta função após chamar DoModal para recuperar o número da página final no intervalo de páginas a imprimir.

Example

Veja o exemplo para CPrintDialog::m_pd.

CPrintDialog::m_pd

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

PRINTDLG& m_pd;

Observações

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

Se modificar diretamente o m_pd membro dos dados, irá sobrepor qualquer comportamento padrão.

Example

// 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 deve imprimir todas as páginas do documento.

BOOL PrintAll() const;

Valor de retorno

Diferente de zero se todas as páginas do documento devem ser impressas; caso contrário, 0.

Observações

Chame esta função após a chamada DoModal para determinar se deve imprimir todas as páginas do documento.

Example

Veja o exemplo para CPrintDialog::m_pd.

CPrintDialog::PrintCollate

Determina se são solicitadas cópias compiladas.

BOOL PrintCollate() const;

Valor de retorno

Diferente de zero se o utilizador selecionar a caixa de seleção de colar na caixa de diálogo; caso contrário, 0.

Observações

Chame esta função após a chamada DoModal para determinar se a impressora deve compilar todas as cópias impressas do documento.

Example

// 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 deve imprimir apenas um intervalo especificado de páginas.

BOOL PrintRange() const;

Valor de retorno

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

Observações

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

Example

Veja o exemplo para CPrintDialog::m_pd.

CPrintDialog::PrintSelection

Determina se deve imprimir apenas os itens atualmente selecionados.

BOOL PrintSelection() const;

Valor de retorno

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

Observações

Chame esta função depois de chamar DoModal para determinar se deve imprimir apenas os itens atualmente selecionados.

Example

Veja o exemplo para CPrintDialog::m_pd.

Consulte também

Exemplo MFC DIBLOOK
CCommonDialog Classe
Gráfico de Hierarquia
CPrintInfo Estrutura