Clase CPrintDialog

Encapsula los servicios proporcionados por el cuadro de diálogo común de Windows para imprimir.

Sintaxis

class CPrintDialog : public CCommonDialog

Miembros

Constructores públicos

Nombre	Descripción
CPrintDialog::CPrintDialog	Construye un objeto CPrintDialog.

Métodos públicos

Nombre	Descripción
CPrintDialog::CreatePrinterDC	Crea un contexto de dispositivos de impresora sin mostrar el cuadro de diálogo Imprimir.
CPrintDialog::DoModal	Muestra el cuadro de diálogo y permite al usuario realizar selecciones.
CPrintDialog::GetCopies	Recupera el número de copias solicitadas.
CPrintDialog::GetDefaults	Recupera los valores predeterminados del dispositivo sin mostrar un cuadro de diálogo.
CPrintDialog::GetDeviceName	Recupera el nombre del dispositivo de impresora seleccionado actualmente.
CPrintDialog::GetDevMode	Recupera la estructura DEVMODE.
CPrintDialog::GetDriverName	Recupera el nombre del controlador de impresora seleccionado actualmente.
CPrintDialog::GetFromPage	Recupera la página inicial del intervalo de impresión.
CPrintDialog::GetPortName	Recupera el nombre del puerto de impresora seleccionado actualmente.
CPrintDialog::GetPrinterDC	Recupera un identificador para el contexto del dispositivo de impresora.
CPrintDialog::GetToPage	Recupera la página final del intervalo de impresión.
CPrintDialog::PrintAll	Determina si se van a imprimir todas las páginas del documento.
CPrintDialog::PrintCollate	Determina si se solicitan copias intercaladas.
CPrintDialog::PrintRange	Determina si se va a imprimir solo un intervalo de páginas especificado.
CPrintDialog::PrintSelection	Determina si se van a imprimir solo los elementos seleccionados actualmente.

Miembros de datos públicos

Nombre	Descripción
CPrintDialog::m_pd	Estructura utilizada para personalizar un objeto CPrintDialog.

Comentarios

Los cuadros de diálogo de impresión comunes proporcionan una manera sencilla de implementar los cuadros de diálogo Imprimir y Configurar impresión de forma coherente con los estándares de Windows.

Nota:

La clase CPrintDialogEx encapsula los servicios proporcionados por la hoja de propiedades de impresión de Windows. Para más información, consulte el tema de información general de CPrintDialogEx.

La funcionalidad de CPrintDialog se sustituye por la de CPageSetupDialog, que está diseñada para proporcionarle un cuadro de diálogo común tanto para la configuración de impresión como para la configuración de las páginas.

Puede confiar en el marco para controlar muchos aspectos del proceso de impresión de la aplicación. En este caso, el marco muestra automáticamente el cuadro de diálogo común de Windows para imprimir. También puede hacer que el marco se encargue de imprimir para la aplicación, pero invalidando el cuadro de diálogo Imprimir común con su propio cuadro de diálogo de impresión. Para más información sobre el uso del marco para controlar las tareas de impresión, consulte el artículo Impresión.

Si quiere que la aplicación controle la impresión sin la participación del marco, puede usar la clase CPrintDialog "tal cual" con el constructor proporcionado, o puede derivar su propia clase de cuadro de diálogo de CPrintDialog y escribir un constructor que se adapte a sus necesidades. En cualquier caso, estos cuadros de diálogo se comportarán como cuadros de diálogo de MFC estándar porque se derivan de la clase CCommonDialog.

Para usar un objeto CPrintDialog, cree primero el objeto mediante el constructor CPrintDialog. Una vez se ha construido el cuadro de diálogo, puede establecer o modificar los valores de la estructura m_pd para inicializar los valores de los controles del cuadro de diálogo. La estructura m_pd es de tipo PRINTDLG. Para más información sobre esta estructura, consulte Windows SDK.

Si no proporciona sus propios identificadores en m_pd para los miembros hDevMode y hDevNames, asegúrese de llamar a la función GlobalFree de Windows con estos identificadores cuando haya terminado con el cuadro de diálogo. Cuando se usa la implementación del programa de instalación de impresión del marco proporcionada por CWinApp::OnFilePrintSetup, no es necesario liberar estos identificadores. Los identificadores se mantienen con CWinApp y se liberan en el destructor de CWinApp. Solo es necesario liberar estos identificadores al usar la función CPrintDialog independiente.

Después de inicializar los controles del cuadro de diálogo, llame a la función miembro DoModal para mostrar el cuadro de diálogo y permitir que el usuario seleccionar opciones de impresión. DoModal se devuelve si el usuario seleccionó el botón Aceptar (IDOK) o Cancelar (IDCANCEL).

Si DoModal devuelve IDOK, puede usar una de las funciones miembro de CPrintDialog para recuperar la entrada de información por parte del usuario.

La función miembro CPrintDialog::GetDefaults es útil para recuperar los valores predeterminados de la impresora actual sin mostrar un cuadro de diálogo. Esta función miembro no requiere ninguna interacción del usuario.

Puede usar la función CommDlgExtendedError de Windows para determinar si se produjo un error durante la inicialización del cuadro de diálogo y obtener más información sobre el error. Para más información sobre esta función, consulte Windows SDK.

CPrintDialog se basa en el archivo COMMDLG.DLL que se incluye con las versiones 3.1 y posteriores de Windows.

Para personalizar el cuadro de diálogo, derive una clase de CPrintDialog, proporcione una plantilla de diálogo personalizada y agregue un mapa de mensajes para procesar los mensajes de notificación de los controles extendidos. Los mensajes no procesados deben pasarse a la clase base. No es necesario personalizar la función de enlace.

Para procesar el mismo mensaje de forma diferente en función de si el cuadro de diálogo es Imprimir o Configurar impresión, debe derivar una clase para cada cuadro de diálogo. También debe invalidar la función AttachOnSetup de Windows que controla la creación de un cuadro de diálogo nuevo cuando se selecciona el botón Configurar impresión dentro del cuadro de diálogo Imprimir.

Para más información sobre el uso de CPrintDialog, consulte Clases de cuadros de diálogo comunes.

Jerarquía de herencia

CObject

CCmdTarget

CWnd

CDialog

CCommonDialog

CPrintDialog

Requisitos

Encabezado: afxdlgs.h

CPrintDialog::CPrintDialog

Construye un objeto de cuadro de diálogo Imprimir o Configurar impresión de Windows.

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

Parámetros

bPrintSetupOnly
Especifica si se muestra el cuadro de diálogo Imprimir estándar de Windows o el cuadro de diálogo Configurar impresión. Establezca este parámetro en TRUE para mostrar el cuadro de diálogo de configuración de impresión estándar de Windows. Establézcalo en FALSE para mostrar el cuadro de diálogo Imprimir de Windows. Si bPrintSetupOnly es FALSE, se sigue mostrando un botón de opción Configurar impresión en el cuadro de diálogo Imprimir.

dwFlags
Puede usar una o varias marcas para personalizar la configuración del cuadro de diálogo, en combinación con el operador OR bit a bit. Por ejemplo, la marca PD_ALLPAGES establece el intervalo de impresión predeterminado en todas las páginas del documento. Consulte la estructura PRINTDLG en Windows SDK para más información sobre estas marcas.

pParentWnd
Puntero a la ventana principal o propietaria del cuadro de diálogo.

Comentarios

Esta función miembro solo construye el objeto. Use la función miembro DoModal para mostrar el cuadro de diálogo.

Tenga en cuenta que cuando se llama al constructor con bPrintSetupOnly establecido en FALSE, se usa automáticamente la marca PD_RETURNDC. Después de llamar a DoModal, GetDefaults o GetPrinterDC, se devolverá un contexto de dispositivo de impresora en m_pd.hDC. Este contexto de dispositivo debe liberarlo con una llamada a DeleteDC por el autor de la llamada de CPrintDialog.

Ejemplo

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

Crea un contexto de dispositivo (DC) de impresora a partir de las DEVMODE estructuras y DEVNAMES.

HDC CreatePrinterDC();

Valor devuelto

Identificador del contexto del dispositivo de impresora recién creado.

Comentarios

Se supone que este contexto de dispositivo es el contexto de dispositivo actual de la impresora y el usuario debe eliminar cualquier otro contexto de dispositivo de impresora obtenido anteriormente. Se puede llamar a esta función y usar el controlador de dominio resultante, sin mostrar nunca el cuadro de diálogo Imprimir.

Ejemplo

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

Muestra el cuadro de diálogo de impresión común de Windows y permite al usuario seleccionar varias opciones de impresión, como el número de copias, el intervalo de páginas y si se deben intercalar las copias.

virtual INT_PTR DoModal();

Valor devuelto

IDOK o IDCANCEL. Si se devuelve IDCANCEL, llame a la función CommDlgExtendedError de Windows para determinar si se ha producido un error.

IDOK y IDCANCEL son constantes que indican si el usuario seleccionó el botón Aceptar o Cancelar.

Comentarios

Si quiere inicializar las distintas opciones del cuadro de diálogo de impresión estableciendo miembros de la estructura m_pd, debe hacerlo antes de llamar a DoModal, pero después de construir el objeto de cuadro de diálogo.

Después de llamar a DoModal, puede llamar a otras funciones miembro para recuperar la configuración o la información de entrada del usuario en el cuadro de diálogo.

Tenga en cuenta que cuando se llama al constructor con bPrintSetupOnly establecido en FALSE, se usa automáticamente la marca PD_RETURNDC. Después de llamar a DoModal, GetDefaults o GetPrinterDC, se devolverá un contexto de dispositivo de impresora en m_pd.hDC. Este contexto de dispositivo debe liberarlo con una llamada a DeleteDC por el autor de la llamada de CPrintDialog.

Ejemplo

Vea el ejemplo de CPrintDialog::CreatePrinterDC.

CPrintDialog::GetCopies

Recupera el número de copias solicitadas.

int GetCopies() const;

Valor devuelto

Número de copias solicitadas.

Comentarios

Llame a esta función después de llamar a DoModal para recuperar el número de copias solicitadas.

Ejemplo

Vea el ejemplo de CPrintDialog::PrintCollate.

CPrintDialog::GetDefaults

Recupera los valores predeterminados del dispositivo de la impresora predeterminada sin mostrar un cuadro de diálogo.

BOOL GetDefaults();

Valor devuelto

Distinto de cero si la función se realizó correctamente; de lo contrario, 0.

Comentarios

Los valores recuperados se colocan en la estructura m_pd.

En algunos casos, una llamada a esta función llamará al constructor de CPrintDialog con bPrintSetupOnly establecido en FALSE. En estos casos, se asigna automáticamente un contexto de dispositivo de impresora y hDevNames y hDevMode (dos identificadores ubicados en el miembro de datos m_pd).

Si se llamó al constructor de CPrintDialog con bPrintSetupOnly establecido en FALSE, esta función no solo devolverá hDevNames y hDevMode (ubicados en m_pd.hDevNames y m_pd.hDevMode) al autor de la llamada, sino que también devolverá un contexto de dispositivo de impresora en m_pd.hDC. Es responsabilidad del autor de la llamada eliminar el contexto de dispositivo de la impresora y llamar a la función GlobalFree de Windows en los identificadores cuando haya terminado con el objeto CPrintDialog.

Ejemplo

Este fragmento de código obtiene el contexto del dispositivo de la impresora predeterminada e informa al usuario de la resolución de la impresora en puntos por pulgada. (Este atributo de las funcionalidades de la impresora se conoce a menudo como PPP).

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 el nombre del dispositivo de impresora seleccionado actualmente.

CString GetDeviceName() const;

Valor devuelto

Nombre de la impresora actualmente seleccionada.

Comentarios

Llame a esta función después de llamar a DoModal para recuperar el nombre de la impresora seleccionada actualmente o después de llamar a GetDefaults para recuperar los valores predeterminados del dispositivo actual de la impresora predeterminada. Use un puntero al objeto CString devuelto por GetDeviceName como valor de lpszDeviceName en una llamada a CDC::CreateDC.

Ejemplo

Este fragmento de código muestra el nombre de impresora predeterminado del usuario y el puerto al que está conectada, junto con el nombre que usa la impresora en el administrador de trabajos de impresión. El código puede mostrar un cuadro de mensaje que dice: "Your default printer is HP LaserJet IIIP on \\server\share using winspool" (La impresora predeterminada es HP LaserJet IIIP en \\server\share con winspool), por ejemplo.

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 la estructura DEVMODE.

LPDEVMODE GetDevMode() const;

Valor devuelto

La estructura de datos DEVMODE, que contiene información sobre la inicialización del dispositivo y el entorno de un controlador de impresión. Debe desbloquear la memoria ocupada por esta estructura con la función GlobalUnlock de Windows, que se describe en Windows SDK.

Comentarios

Llame a esta función después de llamar a DoModal o GetDefaults para recuperar información sobre el dispositivo de impresión.

Ejemplo

Vea el ejemplo de CPrintDialog::PrintCollate.

CPrintDialog::GetDriverName

Recupera el nombre del controlador de impresora seleccionado actualmente.

CString GetDriverName() const;

Valor devuelto

Un objeto CString que especifica el nombre del controlador definido por el sistema.

Comentarios

Llame a esta función después de llamar a DoModal o GetDefaults para recuperar el nombre del controlador de dispositivo de impresora definido por el sistema. Use un puntero al objeto CString devuelto por GetDriverName como valor de lpszDriverName en una llamada a CDC::CreateDC.

Ejemplo

Vea el ejemplo de CPrintDialog::GetDeviceName.

CPrintDialog::GetFromPage

Recupera la página inicial del intervalo de impresión.

int GetFromPage() const;

Valor devuelto

Número de página inicial del intervalo de páginas que se va a imprimir.

Comentarios

Llame a esta función después de llamar a DoModal para recuperar el número de página inicial en el intervalo de páginas que se va a imprimir.

Ejemplo

Vea el ejemplo de CPrintDialog::m_pd.

CPrintDialog::GetPortName

Recupera el nombre del puerto de impresora seleccionado actualmente.

CString GetPortName() const;

Valor devuelto

Nombre del puerto de impresora seleccionado actualmente.

Comentarios

Llame a esta función después de llamar a DoModal o GetDefaults para recuperar el nombre del puerto de la impresora seleccionado actualmente.

Ejemplo

Vea el ejemplo de CPrintDialog::GetDeviceName.

CPrintDialog::GetPrinterDC

Recupera un identificador para el contexto del dispositivo de impresora.

HDC GetPrinterDC() const;

Valor devuelto

Identificador del contexto del dispositivo de impresora si se realiza correctamente; de lo contrario, NULL.

Comentarios

Si el parámetro bPrintSetupOnly del constructor CPrintDialog era FALSE (lo que indica que se muestra el cuadro de diálogo Imprimir), GetPrinterDC devuelve un identificador al contexto del dispositivo de impresora. Debe llamar a la función DeleteDC de Windows para eliminar el contexto del dispositivo cuando haya terminado de usarlo.

Ejemplo

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 la página final del intervalo de impresión.

int GetToPage() const;

Valor devuelto

Número de página final del intervalo de páginas que se va a imprimir.

Comentarios

Llame a esta función después de llamar a DoModal para recuperar el número de página final en el intervalo de páginas que se va a imprimir.

Ejemplo

Vea el ejemplo de CPrintDialog::m_pd.

CPrintDialog::m_pd

Estructura cuyos miembros almacenan las características del objeto de cuadro de diálogo.

PRINTDLG& m_pd;

Comentarios

Después de construir un objeto CPrintDialog, puede usar m_pd para establecer varios aspectos del cuadro de diálogo antes de llamar a la función miembro DoModal. Para más información sobre la estructura m_pd, consulte PRINTDLG en Windows SDK.

Si modifica el miembro de datos m_pd directamente, invalidará cualquier comportamiento predeterminado.

Ejemplo

// 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 si se van a imprimir todas las páginas del documento.

BOOL PrintAll() const;

Valor devuelto

Distinto a cero si se van a imprimir todas las páginas del documento; en caso contrario, 0.

Comentarios

Llame a esta función después de llamar a DoModal para determinar si se van a imprimir todas las páginas del documento.

Ejemplo

Vea el ejemplo de CPrintDialog::m_pd.

CPrintDialog::PrintCollate

Determina si se solicitan copias intercaladas.

BOOL PrintCollate() const;

Valor devuelto

Distinto a cero si el usuario activa la casilla de intercalación en el cuadro de diálogo; en caso contrario, 0.

Comentarios

Llame a esta función después de llamar a DoModal para determinar si la impresora debe intercalar todas las copias impresas del documento.

Ejemplo

// 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 si se va a imprimir solo un intervalo de páginas especificado.

BOOL PrintRange() const;

Valor devuelto

Distinto a cero si solo se va a imprimir un intervalo de páginas del documento; en caso contrario, 0.

Comentarios

Llame a esta función después de llamar a DoModal para determinar si se va a imprimir solo un intervalo de páginas del documento.

Ejemplo

Vea el ejemplo de CPrintDialog::m_pd.

CPrintDialog::PrintSelection

Determina si se van a imprimir solo los elementos seleccionados actualmente.

BOOL PrintSelection() const;

Valor devuelto

Distinto a cero si solo se van a imprimir los elementos seleccionados; en caso contrario, 0.

Comentarios

Llame a esta función después de llamar a DoModal para determinar si se van a imprimir solo los elementos seleccionados actualmente.

Ejemplo

Vea el ejemplo de CPrintDialog::m_pd.

Consulte también

Ejemplo de MFCDIBLOOK
CCommonDialog (clase)
Gráfico de jerarquías
CPrintInfo (Estructura)