Printing Dialogs

You use wxPageSetupDialog and wxPrintDialog in applications that print documents. If you use the printing framework (including wxPrintout, wxPrinter, and other classes), you won't need to invoke these dialogs explicitly in your code. For more on printing, refer to Chapter 5, "Drawing and Printing."

wxPageSetupDialog

wxPageSetupDialog contains controls for paper size such as A4 and letter, orientation (landscape or portrait), and controls for setting left, top, right, and bottom margin sizes in millimeters. The user can also set printer-specific options by invoking a further dialog from this one.

Figure 8-27 shows the wxPageSetupDialog dialog under Windows.

Figure 8-27. wxPageSetupDialog under Windows

Figure 8-28 shows wxPageSetupDialog using the generic implementation under GTK+. If the GNOME printing libraries are installed, wxWidgets will instead use a native GNOME page setup dialog, as shown in Figure 8-29.

Figure 8-28. wxPageSetupDialog under GTK+ without GNOME printing

Figure 8-29. wxPageSetupDialog under GTK+ with GNOME printing

The Mac OS X version of wxPageSetupDialog is shown in Figure 8-30.

Figure 8-30. wxPageSetupDialog under Mac OS X

To use this dialog, pass to the constructor a parent window and a pointer to a wxPageSetupDialogData object, which contains settings to pass to and retrieve from the dialog. You can create the dialog on the stack or dynamically. The page setup data will be copied to the dialog's own data; use GetPageSetupData to return a reference to the dialog's data.

wxPageSetupData Functions

wxPageSetupDialogData has the following functions.

Ok returns true if the print data associated with the object is valid. This can return false on Windows if the current printer is not set, for example. On all other platforms, it returns true.

SetMarginTopLeft takes a wxPoint object and sets the left and top margins in millimeters. Call GetMarginTopLeft to retrieve this value.

SetMarginBottomRight takes a wxPoint object and sets the bottom and right margins in millimeters. Call GetMarginBottomRight to retrieve this value.

SetPaperId sets the paper identifier to select the current paper size, instead of using SetPaperSize. See the documentation for this function for the symbols that are available. GetPaperId retrieves the paper identifier.

SetPaperSize takes a wxSize object and sets the paper size in millimeters. Use GetPaperSize to retrieve the current paper size.

EnableMargins enables or disables the margin controls (Windows only). Call GetEnableMargins to test the value of this setting.

EnableOrientation enables or disables the orientation control (Windows only). Call GetEnableOrientation to test the value of this setting.

EnablePaper enables or disables the paper size control (Windows only). Call GetEnablePaper to test the value of this setting.

EnablePrinter enables or disables the Printer button, which invokes a print setup dialog. Call GetEnablePrinter to test the value of this setting.

wxPageSetupDialog Example

Here's an example of using wxPageSetupDialog:

 #include "wx/printdlg.h" void MyFrame::OnPageSetup(wxCommandEvent& event) {     wxPageSetupDialog pageSetupDialog(this, & m_pageSetupData);     if (pageSetupDialog.ShowModal() == wxID_OK)         m_pageSetupData = pageSetupDialog.GetPageSetupData(); } 

wxPrintDialog

This class represents the print and print setup standard dialogs. You may obtain a wxPrinterDC device context from a successfully dismissed print dialog.

Figure 8-31 shows wxPrintDialog under Windows.

Figure 8-31. wxPrintDialog under Windows

Figure 8-32 shows wxPrintDialog under GTK+ without the GNOME printing libraries, and Figure 8-33 shows the dialog shown when the GNOME printing libraries are installed.

Figure 8-32. wxPrintDialog under GTK+ without GNOME printing

Figure 8-33. wxPrintDialog under GTK+ with GNOME printing

Figure 8-34 shows wxPrintDialog under Mac OS X. As you can see from the buttons along the bottom, Mac OS X gives you the added advantage of saving your document as a PDF file, and you can use the Mac OS X previewer as an alternative to the application's preview window.

Figure 8-34. wxPrintDialog under Mac OS X

To use wxPrintDialog, create it on the stack or dynamically and pass the parent window and a pointer to a wxPrintDialogData object, whose contents will be copied to internal data in the dialog object. Call wxPrintDialogData:: SetSetupDialog with true before passing the data to the dialog if you want to show the print setup dialog instead of the print dialog. Following Microsoft's conventions, the print setup dialog has been replaced by the wxPageSetupDialog, but for compatibility, some applications may still need to use the setup dialog.

When the dialog returns successfully, you can retrieve the wxPrintDialogData using the GetPrintDialogData function.

Call GetPrintDC on the dialog to get a printer device context based on the settings the user has chosen. If the function returns a non-null pointer, the application is then responsible for deleting the device context.

Ok returns true if the print data associated with the dialog is valid. This can return false on Windows if the current printer is not set, for example. On all other platforms, it returns true.

wxPrintDialogData Functions

These are the functions you can use with wxPrintDialogData.

EnableHelp enables or disables the Help button. Use GetEnableHelp to return the value of this setting.

EnablePageNumbers enables or disables the page number controls, and GetEnablePageNumbers returns the value of this setting.

EnablePrintToFile enables or disables the Print to File check box. Use GetEnablePrintToFile to return the value of this setting.

EnableSelection enables or disables the Selection radio button that lets the user specify that the current selection should be printed. Use GetEnableSelection to return the value of this setting.

SetCollate sets the Collate check box to be TRue or false. Use GetCollate to return the value of this setting.

SetFromPage and SetToPage set the page range to print. Use GetFromPage and GetToPage to return this range.

SetMinPage and SetMaxPage set the minimum and maximum page numbers that can be printed. Use GetMinPage and GetMaxPage to return these values.

SetNoCopies sets the default number of copies that will be printed. Use GetNoCopies to return the value of this setting.

SetPrintToFile sets the Print to File check box to TRue or false. Use GetPrintToFile to return the value of this setting.

SetSelection sets the Selection radio button. Use GetSelection to return the value of this setting.

SetSetupDialog determines whether the print setup dialog is shown (TRue) or the normal print dialog is shown (false). Use GetSetupDialog to return the value of this setting.

SetPrintData sets the internal wxPrintData object. GetPrintData returns a reference to the internal wxPrintData object.

wxPrintDialog Example

The following example shows wxPrintDialog being used to return a suitable printer device context:

 #include "wx/printdlg.h" void MyFrame::OnPrint(wxCommandEvent& event) {     wxPrintDialogData dialogData;     dialogData.SetFromPage(0);     dialogData.SetToPage(10);     wxPrintDialog printDialog(this, & m_dialogData);     if (printDialog.ShowModal() == wxID_OK)     {         // After calling GetPrintDC(), the application         // owns the DC         wxDC* dc = printDialog.GetPrintDC();         // Draw on the device context         ...         // Destroy it         delete dc;     } } 

However, usually you can avoid invoking the print dialog directly. Instead, use the higher-level printing framework (refer to Chapter 5). The print dialog will be shown as a side effect of calling wxPrinter::Print.