1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>wxWidgets: Printing Framework Overview</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra_stylesheet.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="page_container">
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0" style="width: 100%;">
<tbody>
<tr>
<td id="projectlogo">
<a href="http://www.wxwidgets.org/" target="_new">
<img alt="wxWidgets" src="logo.png"/>
</a>
</td>
<td style="padding-left: 0.5em; text-align: right;">
<span id="projectnumber">Version: 3.0.2</span>
</td>
</tr>
</tbody>
</table>
</div>
<!-- Generated by Doxygen 1.8.2 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Categories</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="index.html">Documentation</a></li><li class="navelem"><a class="el" href="page_topics.html">Programming Guides</a></li> </ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Printing Framework Overview </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#overview_printing_printout">wxPrintout</a></li>
<li class="level1"><a href="#overview_printing_printer">wxPrinter</a></li>
<li class="level1"><a href="#overview_printing_printpreview">wxPrintPreview</a></li>
<li class="level1"><a href="#overview_printing_printerdc">wxPrinterDC</a></li>
<li class="level1"><a href="#overview_printing_postscriptdc">wxPostScriptDC</a></li>
<li class="level1"><a href="#overview_printing_printdialog">wxPrintDialog</a></li>
<li class="level1"><a href="#overview_printing_printdata">wxPrintData</a></li>
<li class="level1"><a href="#overview_printing_printdialogdata">wxPrintDialogData</a></li>
<li class="level1"><a href="#overview_printing_pagesetupdialog">wxPageSetupDialog</a></li>
<li class="level1"><a href="#overview_printing_pagesetupdialogdata">wxPageSetupDialogData</a></li>
</ul>
</div>
<div class="textblock"><p>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?'.</p>
<p>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.</p>
<p>In most cases, the only class you will need to derive from is <a class="el" href="classwx_printout.html" title="This class encapsulates the functionality of printing out an application document.">wxPrintout</a>; all others will be used as-is.</p>
<p>A brief description of each class's role and how they work together follows.</p>
<p>For the special case of printing under Unix, where various different printing backends have to be offered, please have a look at <a class="el" href="overview_unixprinting.html">Printing Under Unix (GTK+)</a>.</p>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="group__group__class__printing.html">Printing Framework</a></dd></dl>
<h1><a class="anchor" id="overview_printing_printout"></a>
wxPrintout</h1>
<p>A document's printing ability is represented in an application by a derived <a class="el" href="classwx_printout.html" title="This class encapsulates the functionality of printing out an application document.">wxPrintout</a> class. This class prints a page on request, and can be passed to the Print function of a <a class="el" href="classwx_printer.html" title="This class represents the Windows or PostScript printer, and is the vehicle through which printing ma...">wxPrinter</a> object to actually print the document, or can be passed to a <a class="el" href="classwx_print_preview.html" title="Objects of this class manage the print preview process.">wxPrintPreview</a> 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 <a class="el" href="classwx_printout.html" title="This class encapsulates the functionality of printing out an application document.">wxPrintout</a> 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.</p>
<div class="fragment"><div class="line"><span class="keywordflow">case</span> WXPRINT_PRINT:</div>
<div class="line">{</div>
<div class="line"> <a class="code" href="classwx_printer.html" title="This class represents the Windows or PostScript printer, and is the vehicle through which printing ma...">wxPrinter</a> printer;</div>
<div class="line"> MyPrintout printout(<span class="stringliteral">"My printout"</span>);</div>
<div class="line"> printer.<a class="code" href="classwx_printer.html#a59e6d69be017dfa033e116bdf749bab3" title="Starts the printing process.">Print</a>(<span class="keyword">this</span>, &printout, <span class="keyword">true</span>);</div>
<div class="line"> <span class="keywordflow">break</span>;</div>
<div class="line">}</div>
<div class="line"><span class="keywordflow">case</span> WXPRINT_PREVIEW:</div>
<div class="line">{</div>
<div class="line"> <span class="comment">// Pass two printout objects: for preview, and possible printing.</span></div>
<div class="line"> <a class="code" href="classwx_print_preview.html" title="Objects of this class manage the print preview process.">wxPrintPreview</a> *preview = <span class="keyword">new</span> <a class="code" href="classwx_print_preview.html" title="Objects of this class manage the print preview process.">wxPrintPreview</a>(<span class="keyword">new</span> MyPrintout, <span class="keyword">new</span> MyPrintout);</div>
<div class="line"> <a class="code" href="classwx_preview_frame.html" title="This class provides the default method of managing the print preview interface.">wxPreviewFrame</a> *frame = <span class="keyword">new</span> <a class="code" href="classwx_preview_frame.html" title="This class provides the default method of managing the print preview interface.">wxPreviewFrame</a>(preview, <span class="keyword">this</span>,</div>
<div class="line"> <span class="stringliteral">"Demo Print Preview"</span>,</div>
<div class="line"> <a class="code" href="classwx_point.html" title="A wxPoint is a useful data structure for graphics operations.">wxPoint</a>(100, 100),</div>
<div class="line"> <a class="code" href="classwx_size.html" title="A wxSize is a useful data structure for graphics operations.">wxSize</a>(600, 650));</div>
<div class="line"> frame-><a class="code" href="classwx_frame.html#a39b18ed552aabaf2a1bc4af7cc924a0f" title="Centres the frame on the display.">Centre</a>(<a class="code" href="defs_8h.html#a1e6994f40bd9cb140e292afb165af971a31055fdab980125bf5a575f776066097" title="A mask value to indicate both vertical and horizontal orientations.">wxBOTH</a>);</div>
<div class="line"> frame-><a class="code" href="classwx_preview_frame.html#a3906d261e406fb21c4bdff861063fb31" title="Initializes the frame elements and prepares for showing it.">Initialize</a>();</div>
<div class="line"> frame-><a class="code" href="classwx_window.html#a7fbc92ce240a8d4f6956b6e0276ef07f" title="Shows or hides the window.">Show</a>(<span class="keyword">true</span>);</div>
<div class="line"> <span class="keywordflow">break</span>;</div>
<div class="line">}</div>
</div><!-- fragment --><p><a class="el" href="classwx_printout.html" title="This class encapsulates the functionality of printing out an application document.">wxPrintout</a> assembles the printed page and (using your subclass's overrides) writes requested pages to a <a class="el" href="classwx_d_c.html" title="A wxDC is a "device context" onto which graphics and text can be drawn.">wxDC</a> that is passed to it. This <a class="el" href="classwx_d_c.html" title="A wxDC is a "device context" onto which graphics and text can be drawn.">wxDC</a> could be a <a class="el" href="classwx_memory_d_c.html" title="A memory device context provides a means to draw graphics onto a bitmap.">wxMemoryDC</a> (for displaying the preview image on-screen), a <a class="el" href="classwx_printer_d_c.html" title="A printer device context is specific to MSW and Mac, and allows access to any printer with a Windows ...">wxPrinterDC</a> (for printing under MSW and Mac), or a <a class="el" href="classwx_post_script_d_c.html" title="This defines the wxWidgets Encapsulated PostScript device context, which can write PostScript files o...">wxPostScriptDC</a> (for printing under GTK or generating PostScript output).</p>
<p>The <a class="el" href="overview_docview.html">document/view framework</a> creates a default <a class="el" href="classwx_printout.html" title="This class encapsulates the functionality of printing out an application document.">wxPrintout</a> object for every view, calling <a class="el" href="classwx_view.html#ab4b046b3cf4280fd35ed6fb711c35a94" title="Override this function to render the view on the given device context.">wxView::OnDraw()</a> to achieve a prepackaged print/preview facility.</p>
<p>If your window classes have a Draw(wxDC *dc) routine to do screen rendering, your <a class="el" href="classwx_printout.html" title="This class encapsulates the functionality of printing out an application document.">wxPrintout</a> subclass will typically call those routines to create portions of the image on your printout. Your <a class="el" href="classwx_printout.html" title="This class encapsulates the functionality of printing out an application document.">wxPrintout</a> subclass can also make its own calls to its <a class="el" href="classwx_d_c.html" title="A wxDC is a "device context" onto which graphics and text can be drawn.">wxDC</a> to draw headers, footers, page numbers, etc.</p>
<p>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 <a class="el" href="classwx_printout.html" title="This class encapsulates the functionality of printing out an application document.">wxPrintout</a>'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.</p>
<h1><a class="anchor" id="overview_printing_printer"></a>
wxPrinter</h1>
<p>Class <a class="el" href="classwx_printer.html" title="This class represents the Windows or PostScript printer, and is the vehicle through which printing ma...">wxPrinter</a> encapsulates the platform-dependent print function with a common interface. In most cases, you will not need to derive a class from <a class="el" href="classwx_printer.html" title="This class represents the Windows or PostScript printer, and is the vehicle through which printing ma...">wxPrinter</a>; simply create a <a class="el" href="classwx_printer.html" title="This class represents the Windows or PostScript printer, and is the vehicle through which printing ma...">wxPrinter</a> object in your Print function as in the example above.</p>
<h1><a class="anchor" id="overview_printing_printpreview"></a>
wxPrintPreview</h1>
<p>Class <a class="el" href="classwx_print_preview.html" title="Objects of this class manage the print preview process.">wxPrintPreview</a> manages the print preview process. Among other things, it constructs the wxDCs that get passed to your <a class="el" href="classwx_printout.html" title="This class encapsulates the functionality of printing out an application document.">wxPrintout</a> 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.</p>
<h1><a class="anchor" id="overview_printing_printerdc"></a>
wxPrinterDC</h1>
<p>Class <a class="el" href="classwx_printer_d_c.html" title="A printer device context is specific to MSW and Mac, and allows access to any printer with a Windows ...">wxPrinterDC</a> is the <a class="el" href="classwx_d_c.html" title="A wxDC is a "device context" onto which graphics and text can be drawn.">wxDC</a> that represents the actual printed page under MSW and Mac. During printing, an object of this class will be passed to your derived <a class="el" href="classwx_printout.html" title="This class encapsulates the functionality of printing out an application document.">wxPrintout</a> object to draw upon. The size of the <a class="el" href="classwx_printer_d_c.html" title="A printer device context is specific to MSW and Mac, and allows access to any printer with a Windows ...">wxPrinterDC</a> will depend on the paper orientation and the resolution of the printer.</p>
<p>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 <a class="el" href="classwx_d_c.html#ab4c22c7c7490a4aabc13dfd9e7a285a3" title="Gets the horizontal and vertical extent of this device context in device units.">wxDC::GetSize()</a> returns the page size in device pixels. The point (0,0) on the <a class="el" href="classwx_printer_d_c.html" title="A printer device context is specific to MSW and Mac, and allows access to any printer with a Windows ...">wxPrinterDC</a> 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.</p>
<p>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 <a class="el" href="classwx_printer_d_c.html#aa859b4ff7a00c8648e12647f962b2678" title="Return the rectangle in device coordinates that corresponds to the full paper area, including the nonprinting regions of the paper.">wxPrinterDC::GetPaperRect()</a> returns the paper rectangle of the given <a class="el" href="classwx_printer_d_c.html" title="A printer device context is specific to MSW and Mac, and allows access to any printer with a Windows ...">wxPrinterDC</a>.</p>
<h1><a class="anchor" id="overview_printing_postscriptdc"></a>
wxPostScriptDC</h1>
<p>Class <a class="el" href="classwx_post_script_d_c.html" title="This defines the wxWidgets Encapsulated PostScript device context, which can write PostScript files o...">wxPostScriptDC</a> is the <a class="el" href="classwx_d_c.html" title="A wxDC is a "device context" onto which graphics and text can be drawn.">wxDC</a> 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 <a class="el" href="classwx_printout.html" title="This class encapsulates the functionality of printing out an application document.">wxPrintout</a> object to draw upon. The size of the <a class="el" href="classwx_post_script_d_c.html" title="This defines the wxWidgets Encapsulated PostScript device context, which can write PostScript files o...">wxPostScriptDC</a> will depend upon the <a class="el" href="classwx_print_data.html" title="This class holds a variety of information related to printers and printer device contexts.">wxPrintData</a> used to construct it.</p>
<p>Unlike a <a class="el" href="classwx_printer_d_c.html" title="A printer device context is specific to MSW and Mac, and allows access to any printer with a Windows ...">wxPrinterDC</a>, there is no distinction between the page rectangle and the paper rectangle in a <a class="el" href="classwx_post_script_d_c.html" title="This defines the wxWidgets Encapsulated PostScript device context, which can write PostScript files o...">wxPostScriptDC</a>; both rectangles are taken to represent the entire sheet of paper.</p>
<h1><a class="anchor" id="overview_printing_printdialog"></a>
wxPrintDialog</h1>
<p>Class <a class="el" href="classwx_print_dialog.html" title="This class represents the print and print setup common dialogs.">wxPrintDialog</a> 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 <a class="el" href="classwx_print_dialog_data.html" title="This class holds information related to the visual characteristics of wxPrintDialog.">wxPrintDialogData</a> to the <a class="el" href="classwx_print_dialog.html" title="This class represents the print and print setup common dialogs.">wxPrintDialog</a> at construction, which is used to populate the dialog.</p>
<h1><a class="anchor" id="overview_printing_printdata"></a>
wxPrintData</h1>
<p>Class <a class="el" href="classwx_print_data.html" title="This class holds a variety of information related to printers and printer device contexts.">wxPrintData</a> is a subset of <a class="el" href="classwx_print_dialog_data.html" title="This class holds information related to the visual characteristics of wxPrintDialog.">wxPrintDialogData</a> that is used (internally) to initialize a <a class="el" href="classwx_printer_d_c.html" title="A printer device context is specific to MSW and Mac, and allows access to any printer with a Windows ...">wxPrinterDC</a> or <a class="el" href="classwx_post_script_d_c.html" title="This defines the wxWidgets Encapsulated PostScript device context, which can write PostScript files o...">wxPostScriptDC</a>. (In fact, a <a class="el" href="classwx_print_data.html" title="This class holds a variety of information related to printers and printer device contexts.">wxPrintData</a> is a data member of a <a class="el" href="classwx_print_dialog_data.html" title="This class holds information related to the visual characteristics of wxPrintDialog.">wxPrintDialogData</a> and a <a class="el" href="classwx_page_setup_dialog_data.html" title="This class holds a variety of information related to wxPageSetupDialog.">wxPageSetupDialogData</a>). Essentially, <a class="el" href="classwx_print_data.html" title="This class holds a variety of information related to printers and printer device contexts.">wxPrintData</a> contains those bits of information from the two dialogs necessary to configure the <a class="el" href="classwx_printer_d_c.html" title="A printer device context is specific to MSW and Mac, and allows access to any printer with a Windows ...">wxPrinterDC</a> or <a class="el" href="classwx_post_script_d_c.html" title="This defines the wxWidgets Encapsulated PostScript device context, which can write PostScript files o...">wxPostScriptDC</a> (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.</p>
<h1><a class="anchor" id="overview_printing_printdialogdata"></a>
wxPrintDialogData</h1>
<p>Class <a class="el" href="classwx_print_dialog_data.html" title="This class holds information related to the visual characteristics of wxPrintDialog.">wxPrintDialogData</a> 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 <a class="el" href="classwx_printout.html" title="This class encapsulates the functionality of printing out an application document.">wxPrintout</a> derived object for the pages requested by the user.</p>
<h1><a class="anchor" id="overview_printing_pagesetupdialog"></a>
wxPageSetupDialog</h1>
<p>Class <a class="el" href="classwx_page_setup_dialog.html" title="This class represents the page setup common dialog.">wxPageSetupDialog</a> puts up the standard page setup dialog, which allows you to specify the orientation, paper size, and related settings. You provide it with a <a class="el" href="classwx_page_setup_dialog_data.html" title="This class holds a variety of information related to wxPageSetupDialog.">wxPageSetupDialogData</a> 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.</p>
<p>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 <a class="el" href="classwx_page_setup_dialog.html" title="This class represents the page setup common dialog.">wxPageSetupDialog</a>, takes a <a class="el" href="classwx_page_setup_dialog_data.html" title="This class holds a variety of information related to wxPageSetupDialog.">wxPageSetupDialogData</a> object in its constructor) to provide this capability; see the printing sample for an example.</p>
<h1><a class="anchor" id="overview_printing_pagesetupdialogdata"></a>
wxPageSetupDialogData</h1>
<p>Class <a class="el" href="classwx_page_setup_dialog_data.html" title="This class holds a variety of information related to wxPageSetupDialog.">wxPageSetupDialogData</a> 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.</p>
<p>You will typically create a global instance of each of a <a class="el" href="classwx_print_data.html" title="This class holds a variety of information related to printers and printer device contexts.">wxPrintData</a> and <a class="el" href="classwx_page_setup_dialog_data.html" title="This class holds a variety of information related to wxPageSetupDialog.">wxPageSetupDialogData</a> at program initiation, which will contain the default settings provided by the system. Each time the user calls up either the <a class="el" href="classwx_print_dialog.html" title="This class represents the print and print setup common dialogs.">wxPrintDialog</a> or the <a class="el" href="classwx_page_setup_dialog.html" title="This class represents the page setup common dialog.">wxPageSetupDialog</a>, 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 <a class="el" href="classwx_print_dialog_data.html" title="This class holds information related to the visual characteristics of wxPrintDialog.">wxPrintDialogData</a>) or the paper size and/or page orientation (from the <a class="el" href="classwx_page_setup_dialog_data.html" title="This class holds a variety of information related to wxPageSetupDialog.">wxPageSetupDialogData</a>). </p>
</div></div><!-- contents -->
<address class="footer">
<small>
Generated on Thu Nov 27 2014 13:46:42 for wxWidgets by <a href="http://www.doxygen.org/index.html" target="_new">Doxygen</a> 1.8.2
</small>
</address>
<script src="wxwidgets.js" type="text/javascript"></script>
</div><!-- #page_container -->
</body>
</html>
|
