Most of the time you won't have to do anything to get basic printing support in your PyGUI application. There are default implementations of the Page Setup command in the Application class, and the Print command in the View and ScrollableView classes. The generic printing system uses the same code for printing a view as is used for drawing to the screen, so once you've written a draw() method for your view, you can also print it.

While the default printing system works well enough, it is fairly rudimentary and won't always do exactly what you want. However, you can customise and build upon it in various ways to provide more advanced features. This section explains how the printing support in PyGUI works and how you can extend it.

Page Setup

Page setup information is represented by an instance of the PageSetup class. This class holds all of the information typically specified by a "Page Setup" dialog. For PyGUI's purposes, the most important of these are the paper size (the physical size of the sheet of paper) and the margins (the distances from the edge of the paper to the region that will be printed on). Together these determine the page size (the size of the printed area). The following diagram illustrates the relationships between these attributes.

The Application object has a page_setup attribute that holds a default PageSetup instance, and an implementation of the Page Setup command that presents a dialog for editing it. The Document class also has a page_setup attribute and a corresponding Page Setup command handler. Thus, in a document-oriented application, each document has its own set of page setup information. If a view is associated with a document, it will use that document's PageSetup when printed; otherwise, it will use the application-wide one.

None of these PageSetup objects are automatically saved anywhere. If you want them to persist, you will need to save them along with your document data, or if you're not using documents, write the application-wide one to a preferences file. To facilitate this, PageSetup objects are designed to be pickled. They also have to_string() and from_string() methods, in case you don't want to use pickle.

You can customise the way page setup information is edited by overriding the page_setup_cmd() method of a view, a document or the application. You may want to make use of the utility function present_page_setup_dialog(), which displays the platform's standard page setup dialog for a given PageSetup instance.

Printing Views

The Print command is handled by the print_cmd() method of the View and ScrollableView classes. First, the view attempts to find a PageSetup instance. If the view's model attribute refers to a Document, and the document's page_setup attribute is not None, then it is used. Otherwise, the application-wide PageSetup is used. If you want the PageSetup to be located some other way, you can override the get_page_setup() method of the view.

Next, the view's print_view() method is called, with the PageSetup object as a parameter. This method does most of the hard work. First it determines the total size of the area to be printed. For a View, this is the same as the size of the view on the screen; for a ScrollableView, it is the view's extent.

Then the printed area is divided into pages. with the size of each page equal to the page_size attribute of the PageSetup. The view's draw() method is called once for each page, with a special canvas object that draws to the printer instead of the screen. In place of the update_rect parameter, a rectangle is passed representing the bounds of the page currently being drawn.

The following diagram illustrates a view with a large extent being divided into pages for printing. Note that the origin of the coordinate system as seen by the draw() method is always at the top left corner of the extent, regardless of which page is being printed. So the view doesn't need to know whether it's drawing to a screen or a printer (although it can find out if it wants to, as we will see below).

Customising Printing

Often you won't want to print a view exactly the same way as it appears on the screen. For example, things like selection highlighting and page boundaries should only be shown on the screen and not on the printed page. The Canvas object passed to the draw() method has a printing attribute that is true when printing and false when drawing to the screen. You can use this to determine which elements of the view should be drawn.

This technique is sufficient to accommodate minor differences between screen drawing and printing. Sometimes, however, you may want to lay out the document quite differently when printing. An example would be a word processor where you want to display the text in a continuous "galley" view on the screen, without any page breaks. When printed, however, you want to add headers and footers to each page. This presents a problem, because the extent of the view has to be increased when printing in order to accommodate the headers and footers.

The solution to this kind of problem is to use a different view subclass for printing. When you come to print, instead of printing the view that you use on the screen, create an off-screen instance of the printing view and call its print_view() method. The printing view can then calculate its extent appropriately and generally do things in as different a way as needed from the on-screen one.

An example of the use of this technique can be seen in PyGUI's TextEditor class. When printed, it wraps to the width of the page instead of the width of the view on the screen. It also figures out how many lines will fit on a page and avoids splitting a line between two pages. To accomplish this, it uses a separate View subclass behind the scenes (TextEditorPrintingView). It's implemented in pure Python, so you can examine it if you want to see how it works.

There are a couple of ways you can intervene in order to introduce your custom printing view into the printing process. One way is to override the print_view() method of the on-screen view to instantiate a printing view and then call its print_view() method instead. (This is the technique used by TextEditor.)

The other way, applicable in a document-oriented application, is to handle printing at the document level instead of the view level. This may make more sense if you have a number of different kinds of on-screen view of the document, but only one way of printing it. Whichever view is active when the user gives the Print command, you want the same printing code to be invoked.

To do it this way, you will first need to disable handling of the Print command in the view, otherwise it will never get as far as the document. You can do this by setting the printable property of the view to false. The view will then ignore the Print command and pass it on to the next handler.

Then you can give your Document subclass a print_cmd() method that creates an instance of your printing view and calls its print_view() method, passing it the document's page_setup. Remember to enable the Print command in the document's setup_menus() method.