/////////////////////////////////////////////////////////////////////////////
-// Name: printing
+// Name: printing.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
-/*!
-
- @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).
-
- */
+/**
+
+@page overview_printing Printing Framework Overview
+
+Classes:
+@li wxPrintout
+@li wxPrinter
+@li wxPrintPreview
+@li wxPrinterDC
+@li wxPostScriptDC
+@li wxPrintDialog
+@li wxPrintData
+@li wxPrintDialogData
+@li wxPageSetupDialog
+@li wxPageSetupDialogData
+
+
+@li @ref overview_printing_printout
+@li @ref overview_printing_printer
+@li @ref overview_printing_printpreview
+@li @ref overview_printing_printerdc
+@li @ref overview_printing_postscriptdc
+@li @ref overview_printing_printdialog
+@li @ref overview_printing_printdata
+@li @ref overview_printing_printdialogdata
+@li @ref overview_printing_pagesetupdialog
+@li @ref overview_printing_pagesetupdialogdata
+
+
+<hr>
+
+
+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 @ref overview_unixprinting.
+
+
+@section overview_printing_printout 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, &printout, 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
+
+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 overview_docview "document/view framework" 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 overview_printing_printer 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 overview_printing_printpreview 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 overview_printing_printerdc 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</em>
+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 <em>paper rectangle</em>, 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 overview_printing_postscriptdc 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 overview_printing_printdialog 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 overview_printing_printdata 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 overview_printing_printdialogdata 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 overview_printing_pagesetupdialog 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 overview_printing_pagesetupdialogdata 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).
+
+*/
projects / wxWidgets.git / blobdiff