X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/fc2171bd4c660b8554dae2a1cbf34ff09f3032a6..066f3611df971be93b2ec46b82c2f05f3ff9a422:/docs/latex/wx/tprint.tex?ds=sidebyside diff --git a/docs/latex/wx/tprint.tex b/docs/latex/wx/tprint.tex index df5a703f3e..db064e4927 100644 --- a/docs/latex/wx/tprint.tex +++ b/docs/latex/wx/tprint.tex @@ -4,34 +4,40 @@ Classes: \helpref{wxPrintout}{wxprintout}, \helpref{wxPrinter}{wxprinter}, \helpref{wxPrintPreview}{wxprintpreview}, \helpref{wxPrinterDC}{wxprinterdc}, +\helpref{wxPostScriptDC}{wxpostscriptdc}, \helpref{wxPrintDialog}{wxprintdialog}, \helpref{wxPrintData}{wxprintdata}, \helpref{wxPrintDialogData}{wxprintdialogdata}, \helpref{wxPageSetupDialog}{wxpagesetupdialog}, \helpref{wxPageSetupDialogData}{wxpagesetupdialogdata} -The printing framework relies on the application to provide classes -whose member functions can respond to particular requests, such -as `print this page' or `does this page exist in the document?'. -This method allows wxWidgets to take over the housekeeping duties of -turning preview pages, calling the print dialog box, creating -the printer device context, and so on: the application can concentrate +The printing framework relies on the application to provide classes whose member +functions can respond to particular requests, such as `print this page' or `does +this page exist in the document?'. This method allows wxWidgets to take over the +housekeeping duties of turning preview pages, calling the print dialog box, +creating the printer device context, and so on: the application can concentrate on the rendering of the information onto a device context. -The \helpref{document/view framework}{docviewoverview} creates a default wxPrintout -object for every view, calling wxView::OnDraw to achieve a -prepackaged print/preview facility. +In most cases, the only class you will need to derive from is +\helpref{wxPrintout}{wxprintout}; all others will be used as-is. + +A brief description of each class's role and how they work together follows. + +For the special case of printing under Unix, where various different +printing backends have to be offered, please have a look at the +\helpref{Unix printing overview}{unixprinting}. -A document's printing ability is represented in an application by a -derived wxPrintout class. This class prints a page on request, and can -be passed to the Print function of a wxPrinter object to actually print -the document, or can be passed to a wxPrintPreview object to initiate -previewing. The following code (from the printing sample) shows how easy -it is to initiate printing, previewing and the print setup dialog, once the wxPrintout -functionality has been defined. Notice the use of MyPrintout for -both printing and previewing. All the preview user interface functionality -is taken care of by wxWidgets. For details on how MyPrintout is defined, -please look at the printout sample code. +\subsection{\helpref{wxPrintout}{wxprintout}} + +A document's printing ability is represented in an application by a derived +wxPrintout class. This class prints a page on request, and can be passed to the +Print function of a wxPrinter object to actually print the document, or can be +passed to a wxPrintPreview object to initiate previewing. The following code +(from the printing sample) shows how easy it is to initiate printing, previewing +and the print setup dialog, once the wxPrintout functionality has been defined. +Notice the use of MyPrintout for both printing and previewing. All the preview +user interface functionality is taken care of by wxWidgets. For more details on how +MyPrintout is defined, please look at the printout sample code. \begin{verbatim} case WXPRINT_PRINT: @@ -45,18 +51,183 @@ please look at the printout sample code. { // Pass two printout objects: for preview, and possible printing. wxPrintPreview *preview = new wxPrintPreview(new MyPrintout, new MyPrintout); - wxPreviewFrame *frame = new wxPreviewFrame(preview, this, "Demo Print Preview", 100, 100, 600, 650); + wxPreviewFrame *frame = new wxPreviewFrame(preview, this, "Demo Print Preview", wxPoint(100, 100), wxSize(600, 650)); frame->Centre(wxBOTH); frame->Initialize(); frame->Show(true); break; } - case WXPRINT_PRINT_SETUP: - { - wxPrintDialog printerDialog(this); - printerDialog.GetPrintData().SetSetupDialog(true); - printerDialog.Show(true); - break; - } \end{verbatim} +Class \helpref{wxPrintout}{wxprintout} assembles the printed page and (using +your subclass's overrides) writes requested pages to a \helpref{wxDC}{wxdc} that +is passed to it. This wxDC could be a \helpref{wxMemoryDC}{wxmemorydc} (for +displaying the preview image on-screen), a \helpref{wxPrinterDC}{wxprinterdc} +(for printing under MSW and Mac), or a \helpref{wxPostScriptDC}{wxpostscriptdc} +(for printing under GTK or generating PostScript output). + +The \helpref{document/view framework}{docviewoverview} creates a default +wxPrintout object for every view, calling wxView::OnDraw to achieve a +prepackaged print/preview facility. + +If your window classes have a Draw(wxDC *dc) routine to do screen rendering, +your wxPrintout subclass will typically call those routines to create portions +of the image on your printout. Your wxPrintout subclass can also make its own +calls to its wxDC to draw headers, footers, page numbers, etc. + +The scaling of the drawn image typically differs from the screen to the preview +and printed images. This class provides a set of routines named +FitThisSizeToXXX(), MapScreenSizeToXXX(), and GetLogicalXXXRect, which can be +used to set the user scale and origin of the wxPrintout's DC so that your class +can easily map your image to the printout withough getting into the details of +screen and printer PPI and scaling. See the printing sample for examples of how +these routines are used. + +\subsection{\helpref{wxPrinter}{wxprinter}} + +Class wxPrinter encapsulates the platform-dependent print function with a common +interface. In most cases, you will not need to derive a class from wxPrinter; +simply create a wxPrinter object in your Print function as in the example above. + +\subsection{\helpref{wxPrintPreview}{wxprintpreview}} + +Class wxPrintPreview manages the print preview process. Among other things, it +constructs the wxDCs that get passed to your wxPrintout subclass for printing +and manages the display of multiple pages, a zoomable preview image, and so +forth. In most cases you will use this class as-is, but you can create your own +subclass, for example, to change the layout or contents of the preview window. + + +\subsection{\helpref{wxPrinterDC}{wxprinterdc}} + +Class wxPrinterDC is the wxDC that represents the actual printed page under MSW +and Mac. During printing, an object of this class will be passed to your derived +wxPrintout object to draw upon. The size of the wxPrinterDC will depend on the +paper orientation and the resolution of the printer. + +There are two important rectangles in printing: the \em{page rectangle} defines +the printable area seen by the application, and under MSW and Mac, it is the +printable area specified by the printer. (For PostScript printing, the page +rectangle is the entire page.) The inherited function +\helpref{wxDC::GetSize}{wxdcgetsize} returns the page size in device pixels. The +point (0,0) on the wxPrinterDC represents the top left corner of the page +rectangle; that is, the page rect is given by wxRect(0, 0, w, h), where (w,h) +are the values returned by GetSize. + +The \em{paper rectangle}, on the other hand, represents the entire paper area +including the non-printable border. Thus, the coordinates of the top left corner +of the paper rectangle will have small negative values, while the width and +height will be somewhat larger than that of the page rectangle. The +wxPrinterDC-specific function +\helpref{wxPrinterDC::GetPaperRect}{wxprinterdcgetpaperrect} returns the paper +rectangle of the given wxPrinterDC. + +\subsection{\helpref{wxPostScriptDC}{wxpostscriptdc}} + +Class wxPostScriptDC is the wxDC that represents the actual printed page under +GTK and other PostScript printing. During printing, an object of this class will +be passed to your derived wxPrintout object to draw upon. The size of the +wxPostScriptDC will depend upon the \helpref{wxPrintData}{wxprintdata} used to +construct it. + +Unlike a wxPrinterDC, there is no distinction between the page rectangle and the +paper rectangle in a wxPostScriptDC; both rectangles are taken to represent the +entire sheet of paper. + +\subsection{\helpref{wxPrintDialog}{wxprintdialog}} + +Class wxPrintDialog puts up the standard print dialog, which allows you to +select the page range for printing (as well as many other print settings, which +may vary from platform to platform). You provide an object of type +\helpref{wxPrintDialogData}{wxprintdialogdata} to the wxPrintDialog at +construction, which is used to populate the dialog. + +\subsection{\helpref{wxPrintData}{wxprintdata}} + +Class wxPrintData is a subset of wxPrintDialogData that is used (internally) to +initialize a wxPrinterDC or wxPostScriptDC. (In fact, a wxPrintData is a data +member of a wxPrintDialogData and a wxPageSetupDialogData). Essentially, +wxPrintData contains those bits of information from the two dialogs necessary to +configure the wxPrinterDC or wxPostScriptDC (e.g., size, orientation, etc.). You +might wish to create a global instance of this object to provide call-to-call +persistence to your application's print settings. + +\subsection{\helpref{wxPrintDialogData}{wxprintdialogdata}} + +Class wxPrintDialogData contains the settings entered by the user in the print +dialog. It contains such things as page range, number of copies, and so forth. +In most cases, you won't need to access this information; the framework takes +care of asking your wxPrintout derived object for the pages requested by the +user. + +\subsection{\helpref{wxPageSetupDialog}{wxpagesetupdialog}} + +Class wxPageSetupDialog puts up the standard page setup dialog, which allows you +to specify the orientation, paper size, and related settings. You provide it +with a wxPageSetupDialogData object at intialization, which is used to populate +the dialog; when the dialog is dismissed, this object contains the settings +chosen by the user, including orientation and/or page margins. + +Note that on Macintosh, the native page setup dialog does not contain entries +that allow you to change the page margins. You can use the Mac-specific class +wxMacPageMarginsDialog (which, like wxPageSetupDialog, takes a +wxPageSetupDialogData object in its constructor) to provide this capability; see +the printing sample for an example. + +\subsection{\helpref{wxPageSetupDialogData}{wxpagesetupdialogdata}} + +Class wxPageSetupDialogData contains settings affecting the page size (paper +size), orientation, margins, and so forth. Note that not all platforms populate +all fields; for example, the MSW page setup dialog lets you set the page margins +while the Mac setup dialog does not. + +You will typically create a global instance of each of a wxPrintData and +wxPageSetupDialogData at program initiation, which will contain the default +settings provided by the system. Each time the user calls up either the +wxPrintDialog or the wxPageSetupDialog, you pass these data structures to +initialize the dialog values and to be updated by the dialog. The framework then +queries these data structures to get information like the printed page range +(from the wxPrintDialogData) or the paper size and/or page orientation (from the +wxPageSetupDialogData). + + +\section{Printing under Unix (GTK+)}\label{unixprinting} + +Printing under Unix has always been a cause of problems as Unix +does not provide a standard way to display text and graphics +on screen and print it to a printer using the same application +programming interface - instead, displaying on screen is done +via the X11 library while printing has to be done with using +PostScript commands. This was particularly difficult to handle +for the case of fonts with the result that only a selected +number of application could offer WYSIWYG under Unix. Equally, +wxWidgets offered its own printing implementation using PostScript +which never really matched the screen display. + +Starting with version 2.8.X, the GNOME project provides printing +support through the libgnomeprint and libgnomeprintui libraries +by which especially the font problem is mostly solved. Beginning +with version 2.5.4, the GTK+ port of wxWidgets can make use of +these libraries if wxWidgets is configured accordingly and if the +libraries are present. You need to configure wxWidgets with the +{\it configure --with-gnomeprint} switch and your application will +then search for the GNOME print libraries at runtime. If they +are found, printing will be done through these, otherwise the +application will fall back to the old PostScript printing code. +Note that the application will not require the GNOME print libraries +to be installed in order to run (there will be no dependency on +these libraries). + +In version GTK+ 2.10, support for printing has been added to GTK+ +itself. Beginning with version wxWidgets 2.9.X, the GTK+ port of +wxWidgets can make use of this feature +if wxWidgets is configured accordingly and if the GTK+ version is >= 2.10. +You need to configure wxWidgets with the {\it configure --with-gtkprint} +switch and your application will then search for the GTK+ print support +at runtime. If it is found, printing will be done through GTK+, otherwise the +application will fall back to GNOME printing support if it is available or, +if it isn't, to the old PostScript printing code. +Note that the application will not require a GTK+ version >= 2.10 +to be installed in order to run (there will be no dependency on +this version). +