1\section{Printing overview}\label{printingoverview} 2 3Classes: \helpref{wxPrintout}{wxprintout}, 4\helpref{wxPrinter}{wxprinter}, 5\helpref{wxPrintPreview}{wxprintpreview}, 6\helpref{wxPrinterDC}{wxprinterdc}, 7\helpref{wxPostScriptDC}{wxpostscriptdc}, 8\helpref{wxPrintDialog}{wxprintdialog}, 9\helpref{wxPrintData}{wxprintdata}, 10\helpref{wxPrintDialogData}{wxprintdialogdata}, 11\helpref{wxPageSetupDialog}{wxpagesetupdialog}, 12\helpref{wxPageSetupDialogData}{wxpagesetupdialogdata} 13 14The printing framework relies on the application to provide classes whose member 15functions can respond to particular requests, such as `print this page' or `does 16this page exist in the document?'. This method allows wxWidgets to take over the 17housekeeping duties of turning preview pages, calling the print dialog box, 18creating the printer device context, and so on: the application can concentrate 19on the rendering of the information onto a device context. 20 21In most cases, the only class you will need to derive from is 22\helpref{wxPrintout}{wxprintout}; all others will be used as-is. 23 24A brief description of each class's role and how they work together follows. 25 26For the special case of printing under Unix, where various different 27printing backends have to be offered, please have a look at the 28\helpref{Unix printing overview}{unixprinting}. 29 30\subsection{\helpref{wxPrintout}{wxprintout}} 31 32A document's printing ability is represented in an application by a derived 33wxPrintout class. This class prints a page on request, and can be passed to the 34Print function of a wxPrinter object to actually print the document, or can be 35passed to a wxPrintPreview object to initiate previewing. The following code 36(from the printing sample) shows how easy it is to initiate printing, previewing 37and the print setup dialog, once the wxPrintout functionality has been defined. 38Notice the use of MyPrintout for both printing and previewing. All the preview 39user interface functionality is taken care of by wxWidgets. For more details on how 40MyPrintout is defined, please look at the printout sample code. 41 42\begin{verbatim} 43 case WXPRINT_PRINT: 44 { 45 wxPrinter printer; 46 MyPrintout printout("My printout"); 47 printer.Print(this, &printout, true); 48 break; 49 } 50 case WXPRINT_PREVIEW: 51 { 52 // Pass two printout objects: for preview, and possible printing. 53 wxPrintPreview *preview = new wxPrintPreview(new MyPrintout, new MyPrintout); 54 wxPreviewFrame *frame = new wxPreviewFrame(preview, this, "Demo Print Preview", wxPoint(100, 100), wxSize(600, 650)); 55 frame->Centre(wxBOTH); 56 frame->Initialize(); 57 frame->Show(true); 58 break; 59 } 60\end{verbatim} 61 62Class \helpref{wxPrintout}{wxprintout} assembles the printed page and (using 63your subclass's overrides) writes requested pages to a \helpref{wxDC}{wxdc} that 64is passed to it. This wxDC could be a \helpref{wxMemoryDC}{wxmemorydc} (for 65displaying the preview image on-screen), a \helpref{wxPrinterDC}{wxprinterdc} 66(for printing under MSW and Mac), or a \helpref{wxPostScriptDC}{wxpostscriptdc} 67(for printing under GTK or generating PostScript output). 68 69The \helpref{document/view framework}{docviewoverview} creates a default 70wxPrintout object for every view, calling wxView::OnDraw to achieve a 71prepackaged print/preview facility. 72 73If your window classes have a Draw(wxDC *dc) routine to do screen rendering, 74your wxPrintout subclass will typically call those routines to create portions 75of the image on your printout. Your wxPrintout subclass can also make its own 76calls to its wxDC to draw headers, footers, page numbers, etc. 77 78The scaling of the drawn image typically differs from the screen to the preview 79and printed images. This class provides a set of routines named 80FitThisSizeToXXX(), MapScreenSizeToXXX(), and GetLogicalXXXRect, which can be 81used to set the user scale and origin of the wxPrintout's DC so that your class 82can easily map your image to the printout withough getting into the details of 83screen and printer PPI and scaling. See the printing sample for examples of how 84these routines are used. 85 86\subsection{\helpref{wxPrinter}{wxprinter}} 87 88Class wxPrinter encapsulates the platform-dependent print function with a common 89interface. In most cases, you will not need to derive a class from wxPrinter; 90simply create a wxPrinter object in your Print function as in the example above. 91 92\subsection{\helpref{wxPrintPreview}{wxprintpreview}} 93 94Class wxPrintPreview manages the print preview process. Among other things, it 95constructs the wxDCs that get passed to your wxPrintout subclass for printing 96and manages the display of multiple pages, a zoomable preview image, and so 97forth. In most cases you will use this class as-is, but you can create your own 98subclass, for example, to change the layout or contents of the preview window. 99 100 101\subsection{\helpref{wxPrinterDC}{wxprinterdc}} 102 103Class wxPrinterDC is the wxDC that represents the actual printed page under MSW 104and Mac. During printing, an object of this class will be passed to your derived 105wxPrintout object to draw upon. The size of the wxPrinterDC will depend on the 106paper orientation and the resolution of the printer. 107 108There are two important rectangles in printing: the \em{page rectangle} defines 109the printable area seen by the application, and under MSW and Mac, it is the 110printable area specified by the printer. (For PostScript printing, the page 111rectangle is the entire page.) The inherited function 112\helpref{wxDC::GetSize}{wxdcgetsize} returns the page size in device pixels. The 113point (0,0) on the wxPrinterDC represents the top left corner of the page 114rectangle; that is, the page rect is given by wxRect(0, 0, w, h), where (w,h) 115are the values returned by GetSize. 116 117The \em{paper rectangle}, on the other hand, represents the entire paper area 118including the non-printable border. Thus, the coordinates of the top left corner 119of the paper rectangle will have small negative values, while the width and 120height will be somewhat larger than that of the page rectangle. The 121wxPrinterDC-specific function 122\helpref{wxPrinterDC::GetPaperRect}{wxprinterdcgetpaperrect} returns the paper 123rectangle of the given wxPrinterDC. 124 125\subsection{\helpref{wxPostScriptDC}{wxpostscriptdc}} 126 127Class wxPostScriptDC is the wxDC that represents the actual printed page under 128GTK and other PostScript printing. During printing, an object of this class will 129be passed to your derived wxPrintout object to draw upon. The size of the 130wxPostScriptDC will depend upon the \helpref{wxPrintData}{wxprintdata} used to 131construct it. 132 133Unlike a wxPrinterDC, there is no distinction between the page rectangle and the 134paper rectangle in a wxPostScriptDC; both rectangles are taken to represent the 135entire sheet of paper. 136 137\subsection{\helpref{wxPrintDialog}{wxprintdialog}} 138 139Class wxPrintDialog puts up the standard print dialog, which allows you to 140select the page range for printing (as well as many other print settings, which 141may vary from platform to platform). You provide an object of type 142\helpref{wxPrintDialogData}{wxprintdialogdata} to the wxPrintDialog at 143construction, which is used to populate the dialog. 144 145\subsection{\helpref{wxPrintData}{wxprintdata}} 146 147Class wxPrintData is a subset of wxPrintDialogData that is used (internally) to 148initialize a wxPrinterDC or wxPostScriptDC. (In fact, a wxPrintData is a data 149member of a wxPrintDialogData and a wxPageSetupDialogData). Essentially, 150wxPrintData contains those bits of information from the two dialogs necessary to 151configure the wxPrinterDC or wxPostScriptDC (e.g., size, orientation, etc.). You 152might wish to create a global instance of this object to provide call-to-call 153persistence to your application's print settings. 154 155\subsection{\helpref{wxPrintDialogData}{wxprintdialogdata}} 156 157Class wxPrintDialogData contains the settings entered by the user in the print 158dialog. It contains such things as page range, number of copies, and so forth. 159In most cases, you won't need to access this information; the framework takes 160care of asking your wxPrintout derived object for the pages requested by the 161user. 162 163\subsection{\helpref{wxPageSetupDialog}{wxpagesetupdialog}} 164 165Class wxPageSetupDialog puts up the standard page setup dialog, which allows you 166to specify the orientation, paper size, and related settings. You provide it 167with a wxPageSetupDialogData object at intialization, which is used to populate 168the dialog; when the dialog is dismissed, this object contains the settings 169chosen by the user, including orientation and/or page margins. 170 171Note that on Macintosh, the native page setup dialog does not contain entries 172that allow you to change the page margins. You can use the Mac-specific class 173wxMacPageMarginsDialog (which, like wxPageSetupDialog, takes a 174wxPageSetupDialogData object in its constructor) to provide this capability; see 175the printing sample for an example. 176 177\subsection{\helpref{wxPageSetupDialogData}{wxpagesetupdialogdata}} 178 179Class wxPageSetupDialogData contains settings affecting the page size (paper 180size), orientation, margins, and so forth. Note that not all platforms populate 181all fields; for example, the MSW page setup dialog lets you set the page margins 182while the Mac setup dialog does not. 183 184You will typically create a global instance of each of a wxPrintData and 185wxPageSetupDialogData at program initiation, which will contain the default 186settings provided by the system. Each time the user calls up either the 187wxPrintDialog or the wxPageSetupDialog, you pass these data structures to 188initialize the dialog values and to be updated by the dialog. The framework then 189queries these data structures to get information like the printed page range 190(from the wxPrintDialogData) or the paper size and/or page orientation (from the 191wxPageSetupDialogData). 192 193 194\section{Printing under Unix (GTK+)}\label{unixprinting} 195 196Printing under Unix has always been a cause of problems as Unix 197does not provide a standard way to display text and graphics 198on screen and print it to a printer using the same application 199programming interface - instead, displaying on screen is done 200via the X11 library while printing has to be done with using 201PostScript commands. This was particularly difficult to handle 202for the case of fonts with the result that only a selected 203number of application could offer WYSIWYG under Unix. Equally, 204wxWidgets offered its own printing implementation using PostScript 205which never really matched the screen display. 206 207Starting with version 2.8.X, the GNOME project provides printing 208support through the libgnomeprint and libgnomeprintui libraries 209by which especially the font problem is mostly solved. Beginning 210with version 2.5.4, the GTK+ port of wxWidgets can make use of 211these libraries if wxWidgets is configured accordingly and if the 212libraries are present. You need to configure wxWidgets with the 213{\it configure --with-gnomeprint} switch and your application will 214then search for the GNOME print libraries at runtime. If they 215are found, printing will be done through these, otherwise the 216application will fall back to the old PostScript printing code. 217Note that the application will not require the GNOME print libraries 218to be installed in order to run (there will be no dependency on 219these libraries). 220 221In version GTK+ 2.10, support for printing has been added to GTK+ 222itself. Support for this has been added to wxWidgets in the 223development branch and it will be available for wxWidgets 3.0. 224 225