\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:
}
\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
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 you application will
+{\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.
to be installed in order to run (there will be no dependency on
these libraries).
-It is expected that the printing code that is currently implemented
-in the GNOME print libraries will be moved into GTK+ later.
+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).
projects / wxWidgets.git / blobdiff