d54cf7ff13
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52014 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
205 lines
9.4 KiB
C
205 lines
9.4 KiB
C
/////////////////////////////////////////////////////////////////////////////
|
|
// Name: printing
|
|
// Purpose: topic overview
|
|
// Author: wxWidgets team
|
|
// RCS-ID: $Id$
|
|
// Licence: wxWindows license
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*!
|
|
|
|
@page overview_printing Printing overview
|
|
|
|
Classes: #wxPrintout,
|
|
#wxPrinter,
|
|
#wxPrintPreview,
|
|
#wxPrinterDC,
|
|
#wxPostScriptDC,
|
|
#wxPrintDialog,
|
|
#wxPrintData,
|
|
#wxPrintDialogData,
|
|
#wxPageSetupDialog,
|
|
#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
|
|
on the rendering of the information onto a device context.
|
|
In most cases, the only class you will need to derive from is
|
|
#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
|
|
@ref unixprinting_overview.
|
|
@ref topic9_overview
|
|
@ref topic10_overview
|
|
@ref topic11_overview
|
|
@ref topic12_overview
|
|
@ref topic13_overview
|
|
@ref topic14_overview
|
|
@ref topic15_overview
|
|
@ref topic16_overview
|
|
@ref topic17_overview
|
|
@ref topic18_overview
|
|
|
|
|
|
@section topic9 #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.
|
|
|
|
@code
|
|
case WXPRINT_PRINT:
|
|
{
|
|
wxPrinter printer;
|
|
MyPrintout printout("My printout");
|
|
printer.Print(this, , @true);
|
|
break;
|
|
}
|
|
case WXPRINT_PREVIEW:
|
|
{
|
|
// 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", wxPoint(100, 100), wxSize(600, 650));
|
|
frame-Centre(wxBOTH);
|
|
frame-Initialize();
|
|
frame-Show(@true);
|
|
break;
|
|
}
|
|
@endcode
|
|
|
|
Class #wxPrintout assembles the printed page and (using
|
|
your subclass's overrides) writes requested pages to a #wxDC that
|
|
is passed to it. This wxDC could be a #wxMemoryDC (for
|
|
displaying the preview image on-screen), a #wxPrinterDC
|
|
(for printing under MSW and Mac), or a #wxPostScriptDC
|
|
(for printing under GTK or generating PostScript output).
|
|
The @ref docview_overview 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.
|
|
|
|
@section topic10 #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.
|
|
|
|
@section topic11 #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.
|
|
|
|
|
|
@section topic12 #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 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
|
|
wxDC::GetSize 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 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
|
|
wxPrinterDC::GetPaperRect returns the paper
|
|
rectangle of the given wxPrinterDC.
|
|
|
|
@section topic13 #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 #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.
|
|
|
|
@section topic14 #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
|
|
#wxPrintDialogData to the wxPrintDialog at
|
|
construction, which is used to populate the dialog.
|
|
|
|
@section topic15 #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.
|
|
|
|
@section topic16 #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.
|
|
|
|
@section topic17 #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.
|
|
|
|
@section topic18 #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).
|
|
|
|
*/
|
|
|
|
|