Robert Lang's patch [ 1583183 ] Fixes printing/print preview inconsistencies

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@42522 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/tprint.tex

@@ -4,34 +4,36 @@ 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 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.
+A brief description of each class's role and how they work together follows.
+
+\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:
@@ -53,6 +55,139 @@ please look at the printout sample code.
     }
 \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