Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@42522 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Julian Smart
2006-10-27 13:07:40 +00:00
parent ea28077683
commit f415cab9ef
32 changed files with 1308 additions and 294 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
docs/latex/wx/pagedlg.tex
View File

@@ -1,18 +1,26 @@
\section{\class{wxPageSetupDialog}}\label{wxpagesetupdialog}
This class represents the page setup common dialog. The page setup dialog is standard from
Windows 95 on, replacing the print setup dialog (which is retained in Windows and wxWidgets
for backward compatibility). On Windows 95 and NT 4.0 and above, the page setup dialog is
native to the windowing system, otherwise it is emulated.
This class represents the page setup common dialog. In MSW, the page setup
dialog is standard from Windows 95 on, replacing the print setup dialog (which
is retained in Windows and wxWidgets for backward compatibility). On Windows 95
and NT 4.0 and above, the page setup dialog is native to the windowing system,
otherwise it is emulated.
The page setup dialog contains controls for paper size (A4, A5 etc.), orientation (landscape
or portrait), and controls for setting left, top, right and bottom margin sizes in millimetres.
The page setup dialog contains controls for paper size (A4, A5 etc.),
orientation (landscape or portrait), and controls for setting left, top, right
and bottom margin sizes in millimetres.
When the dialog has been closed, you need to query the \helpref{wxPageSetupDialogData}{wxpagesetupdialogdata} object
associated with the dialog.
On Macintosh, the native page setup dialog is used, which lets you select paper
size and orientation but it does not let you change the page margins.
Note that the OK and Cancel buttons do not destroy the dialog; this must be done by the
application.
On other platforms, a generic dialog is used.
When the dialog has been closed, you need to query the
\helpref{wxPageSetupDialogData}{wxpagesetupdialogdata} object associated with
the dialog.
Note that the OK and Cancel buttons do not destroy the dialog; this must be done
by the application.
\wxheading{Derived from}
@@ -27,7 +35,9 @@ application.
\wxheading{See also}
\helpref{wxPrintDialog}{wxprintdialog}, \helpref{wxPageSetupDialogData}{wxpagesetupdialogdata}
\helpref{Printing framework overview}{printingoverview},
\helpref{wxPrintDialog}{wxprintdialog},
\helpref{wxPageSetupDialogData}{wxpagesetupdialogdata}
\latexignore{\rtfignore{\wxheading{Members}}}
@@ -82,6 +92,7 @@ user-interface configuration settings stored by wxPageSetupDialogData).
\wxheading{See also}
\helpref{Printing framework overview}{printingoverview},
\helpref{wxPageSetupDialog}{wxpagesetupdialog}
\latexignore{\rtfignore{\wxheading{Members}}}

269
docs/latex/wx/print.tex
View File

@@ -16,6 +16,7 @@ between the print dialogs and the application.
\wxheading{See also}
\helpref{Printing framework overview}{printingoverview},
\helpref{wxPrintDialog}{wxprintdialog},
\helpref{wxPageSetupDialog}{wxpagesetupdialog},
\helpref{wxPrintDialogData}{wxprintdialogdata},
@@ -371,6 +372,7 @@ a successfully dismissed print dialog.
\wxheading{See also}
\helpref{Printing framework overview}{printingoverview},
\helpref{wxPrintDialog Overview}{wxprintdialogoverview}
\latexignore{\rtfignore{\wxheading{Members}}}
@@ -436,7 +438,9 @@ It contains a wxPrintData object with underlying printing settings.
\wxheading{See also}
\helpref{wxPrintDialog}{wxprintdialog}, \helpref{wxPrintDialog Overview}{wxprintdialogoverview}
\helpref{Printing framework overview}{printingoverview},
\helpref{wxPrintDialog}{wxprintdialog},
\helpref{wxPrintDialog Overview}{wxprintdialogoverview}
\latexignore{\rtfignore{\wxheading{Members}}}
@@ -672,8 +676,11 @@ method of printing.
\wxheading{See also}
\helpref{Printing framework overview}{printingoverview}, \helpref{wxPrinterDC}{wxprinterdc}, \helpref{wxPrintDialog}{wxprintdialog},\rtfsp
\helpref{wxPrintout}{wxprintout}, \helpref{wxPrintPreview}{wxprintpreview}.
\helpref{Printing framework overview}{printingoverview},
\helpref{wxPrinterDC}{wxprinterdc},
\helpref{wxPrintDialog}{wxprintdialog},
\helpref{wxPrintout}{wxprintout},
\helpref{wxPrintPreview}{wxprintpreview}.
\latexignore{\rtfignore{\wxheading{Members}}}
@@ -775,10 +782,10 @@ Windows 95, though retained for backward compatibility.
\section{\class{wxPrinterDC}}\label{wxprinterdc}
A printer device context is specific to Windows, and allows access to
any printer with a Windows driver. See \helpref{wxDC}{wxdc} for further information
on device contexts, and \helpref{wxDC::GetSize}{wxdcgetsize} for advice on
achieving the correct scaling for the page.
A printer device context is specific to MSW and Mac, and allows access to any
printer with a Windows or Macintosh driver. See \helpref{wxDC}{wxdc} for further
information on device contexts, and \helpref{wxDC::GetSize}{wxdcgetsize} for
advice on achieving the correct scaling for the page.
\wxheading{Derived from}
@@ -791,7 +798,8 @@ achieving the correct scaling for the page.
\wxheading{See also}
\helpref{wxDC}{wxdc}, \helpref{Printing framework overview}{printingoverview}
\helpref{Printing framework overview}{printingoverview},
\helpref{wxDC}{wxdc}
\latexignore{\rtfignore{\wxheading{Members}}}
@@ -800,7 +808,7 @@ achieving the correct scaling for the page.
\func{}{wxPrinterDC}{\param{const wxPrintData\& }{printData}}
Pass a \helpref{wxPrintData}{wxprintdata} object with information
Constructor. Pass a \helpref{wxPrintData}{wxprintdata} object with information
necessary for setting up a suitable printer device context. This
is the recommended way to construct a wxPrinterDC. Make sure you
specify a reference to a \helpref{wxPrintData}{wxprintdata} object,
@@ -818,13 +826,43 @@ constructor was successful in creating a usable device context.
This constructor is deprecated and retained only for backward compatibility.
\membersection{wxPrinterDC::GetPaperRect}\label{wxprinterdcgetpaperrect}
\func{wxRect}{wxPrinterDC::GetPaperRect}{}
Return the rectangle in device coordinates that corresponds to the full paper
area, including the nonprinting regions of the paper. The point (0,0) in device
coordinates is the top left corner of the page rectangle, which is the printable
area on MSW and Mac. The coordinates of the top left corner of the paper
rectangle will therefore have small negative values, while the bottom right
coordinates will be somewhat larger than the values returned by
\helpref{wxDC::GetSize}{wxdcgetsize}.
\section{\class{wxPrintout}}\label{wxprintout}
This class encapsulates the functionality of printing out an
application document. A new class must be derived and members
overridden to respond to calls such as OnPrintPage and HasPage.
Instances of this class are passed to wxPrinter::Print or a
wxPrintPreview object to initiate printing or previewing.
This class encapsulates the functionality of printing out an application
document. A new class must be derived and members overridden to respond to calls
such as OnPrintPage and HasPage and to render the print image onto an associated
\helpref{wxDC}{wxdc}. Instances of this class are passed to wxPrinter::Print or
to a wxPrintPreview object to initiate printing or previewing.
Your derived wxPrintout is responsible for drawing both the preview image and
the printed page. If your windows' drawing routines accept an arbitrary DC as an
argument, you can re-use those routines within your wxPrintout subclass to draw
the printout image. You may also add additional drawing elements within your
wxPrintout subclass, like headers, footers, and/or page numbers. However, the
image on the printed page will often differ from the image drawn on the screen,
as will the print preview image -- not just in the presence of headers and
footers, but typically in scale. A high-resolution printer presents a much
larger drawing surface (i.e., a higher-resolution DC); a zoomed-out preview
image presents a much smaller drawing surface (lower-resolution DC). By using
the routines FitThisSizeToXXX() and/or MapScreenSizeToXXX() within your
wxPrintout subclass to set the user scale and origin of the associated DC, you
can easily use a single drawing routine to draw on your application's windows,
to create the print preview image, and to create the printed paper image, and
achieve a common appearance to the preview image and the printed page.
\wxheading{Derived from}
@@ -836,8 +874,12 @@ wxPrintPreview object to initiate printing or previewing.
\wxheading{See also}
\helpref{Printing framework overview}{printingoverview}, \helpref{wxPrinterDC}{wxprinterdc}, \helpref{wxPrintDialog}{wxprintdialog},\rtfsp
\helpref{wxPrinter}{wxprinter}, \helpref{wxPrintPreview}{wxprintpreview}
\helpref{Printing framework overview}{printingoverview},
\helpref{wxPrinterDC}{wxprinterdc},
\helpref{wxPrintDialog}{wxprintdialog},
\helpref{wxPageSetupDialog}{wxpagesetupdialog},
\helpref{wxPrinter}{wxprinter},
\helpref{wxPrintPreview}{wxprintpreview}
\latexignore{\rtfignore{\wxheading{Members}}}
@@ -862,7 +904,7 @@ Destructor.
\func{wxDC *}{GetDC}{\void}
Returns the device context associated with the printout (given to the printout at start of
printing or previewing). This will be a wxPrinterDC if printing under Windows,
printing or previewing). This will be a wxPrinterDC if printing under Windows or Mac,
a wxPostScriptDC if printing on other platforms, and a wxMemoryDC if previewing.
@@ -870,9 +912,10 @@ a wxPostScriptDC if printing on other platforms, and a wxMemoryDC if previewing.
\func{void}{GetPageInfo}{\param{int *}{minPage}, \param{int *}{maxPage}, \param{int *}{pageFrom}, \param{int *}{pageTo}}
Called by the framework to obtain information from the application about minimum and maximum page values that
the user can select, and the required page range to be printed. By default this
returns 1, 32000 for the page minimum and maximum values, and 1, 1 for the required page range.
Called by the framework to obtain information from the application about minimum
and maximum page values that the user can select, and the required page range to
be printed. By default this returns 1, 32000 for the page minimum and maximum
values, and 1, 1 for the required page range.
If {\it minPage} is zero, the page number controls in the print dialog will be disabled.
@@ -902,12 +945,13 @@ Returns the size of the printer page in millimetres.
\func{void}{GetPageSizePixels}{\param{int *}{w}, \param{int *}{h}}
Returns the size of the printer page in pixels. These may not be the
same as the values returned from \helpref{wxDC::GetSize}{wxdcgetsize} if
the printout is being used for previewing, since in this case, a
memory device context is used, using a bitmap size reflecting the current
preview zoom. The application must take this discrepancy into account if
previewing is to be supported.
Returns the size of the printer page in pixels, called the \em{page rectangle}.
The page rectangle has a top left corner at (0,0) and a bottom right corner at
(w,h). These values may not be the same as the values returned from
\helpref{wxDC::GetSize}{wxdcgetsize}; if the printout is being used for
previewing, a memory device context is used, which uses a bitmap size reflecting
the current preview zoom. The application must take this discrepancy into
account if previewing is to be supported.
\pythonnote{This method returns the output-only parameters as a tuple.}
@@ -915,14 +959,37 @@ previewing is to be supported.
2-element list {\tt ( w, h )}}
\membersection{wxPrintout::GetPaperRectPixels}\label{wxprintoutgetpaperrectpixels}
\func{wxRect}{GetPaperRectPixels}{}
Returns the rectangle that corresponds to the entire paper in pixels, called the
\em{paper rectangle}. This distinction between paper rectangle and page
rectangle reflects the fact that most printers cannot print all the way to the
edge of the paper. The page rectangle is a rectangle whose top left corner is at
(0,0) and whose width and height are given by
\helpref{wxDC::GetPageSizePixels}{wxprintoutgetpagesizepixels}. On MSW and Mac,
the page rectangle gives the printable area of the paper, while the paper
rectangle represents the entire paper, including non-printable borders. Thus,
the rectangle returned by GetPaperRectPixels will have a top left corner whose
coordinates are small negative numbers and the bottom right corner will have
values somewhat larger than the width and height given by
\helpref{wxDC::GetPageSizePixels}{wxprintoutgetpagesizepixels}. On other
platforms and for PostScript printing, the paper is treated as if its entire
area were printable, so this function will return the same rectangle as the page
rectangle.
\membersection{wxPrintout::GetPPIPrinter}\label{wxprintoutgetppiprinter}
\func{void}{GetPPIPrinter}{\param{int *}{w}, \param{int *}{h}}
Returns the number of pixels per logical inch of the printer device context.
Dividing the printer PPI by the screen PPI can give a suitable scaling
factor for drawing text onto the printer. Remember to multiply
this by a scaling factor to take the preview DC size into account.
Dividing the printer PPI by the screen PPI can give a suitable scaling factor
for drawing text onto the printer. Remember to multiply this by a scaling factor
to take the preview DC size into account. Or you can just use the
FitThisSizeToXXX() and MapScreenSizeToXXX routines below, which do most of the
scaling calculations for you.
\pythonnote{This method returns the output-only parameters as a tuple.}
@@ -935,9 +1002,9 @@ this by a scaling factor to take the preview DC size into account.
\func{void}{GetPPIScreen}{\param{int *}{w}, \param{int *}{h}}
Returns the number of pixels per logical inch of the screen device context.
Dividing the printer PPI by the screen PPI can give a suitable scaling
factor for drawing text onto the printer. Remember to multiply
this by a scaling factor to take the preview DC size into account.
Dividing the printer PPI by the screen PPI can give a suitable scaling factor
for drawing text onto the printer. If you are doing your own scaling, remember
to multiply this by a scaling factor to take the preview DC size into account.
\membersection{wxPrintout::GetTitle}\label{wxprintoutgettitle}
@@ -968,6 +1035,134 @@ HasPage behaves as if the document has only one page.
Returns true if the printout is currently being used for previewing.
\membersection{wxPrintout::FitThisSizeToPaper}\label{wxprintoutfitthissizetopaper}
\func{void}{FitThisSizeToPaper}{\param{const wxSize\& }{imageSize}}
Set the user scale and device origin of the wxDC associated with this wxPrintout
so that the given image size fits entirely within the paper and the origin is at
the top left corner of the paper. Note that with most printers, the region
around the edges of the paper are not printable so that the edges of the image
could be cut off. Use this if you're managing your own page margins.
\membersection{wxPrintout::FitThisSizeToPage}\label{wxprintoutfitthissizetopage}
\func{void}{FitThisSizeToPage}{\param{const wxSize\& }{imageSize}}
Set the user scale and device origin of the wxDC associated with this wxPrintout
so that the given image size fits entirely within the page rectangle and the
origin is at the top left corner of the page rectangle. On MSW and Mac, the page
rectangle is the printable area of the page. On other platforms and PostScript
printing, the page rectangle is the entire paper. Use this if you want your
printed image as large as possible, but with the caveat that on some platforms,
portions of the image might be cut off at the edges.
\membersection{wxPrintout::FitThisSizeToPageMargins}\label{wxprintoutfitthissizetopagemargins}
\func{void}{FitThisSizeToPageMargins}{\param{const wxSize\& }{imageSize}, \param{const wxPageSetupDialogData\& }{pageSetupData}}
Set the user scale and device origin of the wxDC associated with this wxPrintout
so that the given image size fits entirely within the page margins set in the
given wxPageSetupDialogData object. This function provides the greatest
consistency across all platforms because it does not depend on having access to
the printable area of the paper. Note that on Mac, the native wxPageSetupDialog
does not let you set the page margins; you'll have to provide your own mechanism,
or you can use the Mac-only class wxMacPageMarginsDialog.
\membersection{wxPrintout::MapScreenSizeToPaper}\label{wxprintoutmapscreensizetopaper}
\func{void}{MapScreenSizeToPaper}{}
Set the user scale and device origin of the wxDC associated with this wxPrintout
so that the printed page matches the screen size as closely as possible
and the logical origin is in the top left corner of the paper rectangle.
That is,
a 100-pixel object on screen should appear at the same size on the printed page. (It
will, of course, be larger or smaller in the preview image, depending on the zoom
factor.) Use this if you want WYSIWYG behavior, e.g., in a text editor.
\membersection{wxPrintout::MapScreenSizeToPage}\label{wxprintoutmapscreensizetopage}
\func{void}{MapScreenSizeToPage}{}
This sets the user scale of the wxDC assocated with this wxPrintout to the same
scale as \helpref{MapScreenSizeToPaper}{wxprintoutmapscreensizetopaper} but sets
the logical origin to the top left corner of the page rectangle.
\membersection{wxPrintout::MapScreenSizeToPageMargins}\label{wxprintoutmapscreensizetopagemargins}
\func{void}{MapScreenSizeToPageMargins}{\param{const wxPageSetupDialogData\& }{pageSetupData}}
This sets the user scale of the wxDC assocated with this wxPrintout to the same
scale as
\helpref{MapScreenSizeToPageMargins}{wxprintoutmapscreensizetopagemargins} but
sets the logical origin to the top left corner of the page margins specified by
the given wxPageSetupDialogData object.
\membersection{wxPrintout::MapScreenSizeToDevice}\label{wxprintoutmapscreensizetodevice}
\func{void}{MapScreenSizeToDevice}{}
Set the user scale and device origin of the wxDC associated with this wxPrintout
so that one screen pixel maps to one device pixel on the DC. That is, the user
scale is set to (1,1) and the device origin is set to (0,0). Use this if you
want to do your own scaling prior to calling wxDC drawing calls, for example, if
your underlying model is floating-point and you want to achieve maximum drawing
precision on high-resolution printers. (Note that while the underlying drawing
model of Mac OS X is floating-point, wxWidgets's drawing model scales from integer
coordinates.) You can use the GetLogicalXXXRect() routines below to obtain the
paper rectangle, page rectangle, or page margins rectangle to perform your own scaling.
\membersection{wxPrintout::GetLogicalPaperRect}\label{wxprintoutgetlogicalpaperrect}
\func{wxRect}{GetLogicalPaperRect}{}
Return the rectangle corresponding to the paper in the associated wxDC's
logical coordinates for the current user scale and device origin.
\membersection{wxPrintout::GetLogicalPageRect}\label{wxprintoutgetlogicalpagerect}
\func{wxRect}{GetLogicalPageRect}{}
Return the rectangle corresponding to the page in the associated wxDC's
logical coordinates for the current user scale and device origin.
On MSW and Mac, this will be the printable area of the paper. On other platforms
and PostScript printing, this will be the full paper rectangle.
\membersection{wxPrintout::GetLogicalPageMarginsRect}\label{wxprintoutgetlogicalpagemarginsrect}
\func{wxRect}{GetLogicalPageMarginsRect}{\param{const wxPageSetupDialogData\& }{pageSetupData}}
Return the rectangle corresponding to the page margins specified by the given
wxPageSetupDialogData object in the associated wxDC's logical coordinates for the
current user scale and device origin. The page margins are specified
with respect to the edges of the paper on all platforms.
\membersection{wxPrintout::SetLogicalOrigin}\label{wxprintoutsetlogicalorigin}
\func{void}{SetLogicalOrigin}{\param{wxCoord }{x}, \param{wxCoord }{y}}
Set the device origin of the associated wxDC so that the current logical point
becomes the new logical origin.
\membersection{wxPrintout::OffsetLogicalOrigin}\label{wxprintoutoffsetlogicalorigin}
\func{void}{OffsetLogicalOrigin}{\param{wxCoord }{xoff}, \param{wxCoord }{yoff}}
Shift the device origin by an amount specified in logical coordinates.
\membersection{wxPrintout::OnBeginDocument}\label{wxprintoutonbegindocument}
\func{bool}{OnBeginDocument}{\param{int}{ startPage}, \param{int}{ endPage}}
@@ -1046,9 +1241,13 @@ immediately after the frame is shown.
\wxheading{See also}
\overview{Printing framework overview}{printingoverview}, \helpref{wxPrinterDC}{wxprinterdc}, \helpref{wxPrintDialog}{wxprintdialog},\rtfsp
\helpref{wxPrintout}{wxprintout}, \helpref{wxPrinter}{wxprinter},\rtfsp
\helpref{wxPreviewCanvas}{wxpreviewcanvas}, \helpref{wxPreviewControlBar}{wxpreviewcontrolbar},\rtfsp
\overview{Printing framework overview}{printingoverview},
\helpref{wxPrinterDC}{wxprinterdc},
\helpref{wxPrintDialog}{wxprintdialog},
\helpref{wxPrintout}{wxprintout},
\helpref{wxPrinter}{wxprinter},
\helpref{wxPreviewCanvas}{wxpreviewcanvas},
\helpref{wxPreviewControlBar}{wxpreviewcontrolbar},
\helpref{wxPreviewFrame}{wxpreviewframe}.
\latexignore{\rtfignore{\wxheading{Members}}}

173
docs/latex/wx/tprint.tex
View File

@@ -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