A Drawing Area Example

Listing 13-1 implements a simple drawing program using the Gtk.DrawingArea widget. Since the introduction of GTK+ 3 the Cairo drawing library has replaced the old drawing primitives used in earlier versions of GTK+. This library differs from the old primitives in that it use vector graphics to draw shapes instead of using freehand techniques. Vector graphics are interesting because they don’t lose clarity when resized or transformed.

Figure 13-1 is a screenshot of this application.

The best way to understand how to use Cairo is to imagine that you are an artist using a paintbrush to draw out a shape on canvas.

To begin, you can choose a few characteristics of your brush. You can choose the thickness of your brush and the color you want to paint with. You can also choose the shape of your brush tip. You can choose either a circle or a square.

Once you have chosen your brush, you are ready to start painting. You have to be quite precise when describing what you want to appear.

First, decide where you want to place your brush on the canvas. You do this by supplying an x and a y coordinate. Next, you define how you want your brush stroke to look—an arc, a straight line, and so forth. Finally, you define the point where you want your stroke to end, again by supplying an x and a y coordinate. Triangles and squares are very easy to do!

More complex graphics are generated using variations of the above theme with a few additions, such as Fills (coloring in), transformations (zooming in, moving), and so forth, using the Python interface to Cairo.

Nearly all the work revolves around using the cairo.Context (or cairo_t in the Cairo C API). This is the object that you send your drawing commands to. There are a few options available to initialize this object in different ways.

It is very important to know that there is a difference between the coordinates that you are describing your graphics on and the coordinates that you are displaying your graphics on. When giving a presentation, you draw on your transparent acetate beforehand, and then display it on your overhead projector. Cairo calls the transparent acetate that the user space coordinates and the projected image that the device space coordinates.

When initializing the Cairo context object, we tell it how our description should be displayed. To do this, we supply a transformation matrix. Modifying the transformation matrix can lead to some very interesting results.

One of Cairo’s most powerful features is that it can output graphics in many different formats (it can use multiple back ends). For printing, we can have Cairo translate our graphics into postscript to send to the printer. For onscreen display, Cairo can translate our graphics into something gtk can understand for hardware-accelerated rendering! It has many more important and useful target back ends. On initializing the cairo.Context, we set its target back end, supplying a few details (such as color depth and size), as seen in the next example.

The Layout Widget

In addition to Gtk.DrawingArea, GTK+ provides another drawing widget called Gtk.Layout. This widget is actually a container and differs from Gtk.DrawingArea in that it supports not only drawing primitives but also child widgets. In addition, Gtk.Layout provides scrolling support natively, so it does not need a viewport when added to a scrolled window.

New Gtk.Layout widgets are created with Gtk.Layout.new(), which accepts horizontal and vertical adjustments. Adjustments are created for you if you pass None to both function parameters. Since Gtk.Layout has native scrolling support, it can be much more useful than Gtk.DrawingArea when you need to use it with a scrolled window.

However, Gtk.Layout does add some overhead, since it is capable of containing widgets as well. Because of this, Gtk.DrawingArea is a better choice if you only need to draw on the widget’s Gdk.Window.

A call to layout.move()can be used later to relocate the child widget to another location in the Gtk.Layout container.

Also, unlike size requests, the layout sizing function requires unsigned numbers. This means that you must specify an absolute size for the layout widget. This size should be the total size of the layout, including portions of the widget that are not visible on the screen because they are beyond the bounds of the scrolling area! The size of a Gtk.Layout widget defaults to 100×100 pixels.

Print Operations

The next step is to implement the print_file callback method that runs when the Print button is clicked. This method is implemented in Listing 13-2. It takes care of creating the PrintData, connecting all the necessary signals, and creating the print operation.

The first step in printing is to create a new print operation, which is done by calling Gtk.PrintOperation.new(). What makes Gtk.PrintOperation unique is that it uses the platform’s native print dialog if there is one available. On platforms like UNIX, which do not provide such a dialog, Gtk.PrintUnixDialog or the GNOME dialog is used.

The next step is to call operation.set_print_settings() to apply print settings to the operation. In this application, the Gtk.PrintSettings object is stored as an attribute in the Widgets class instance. If the print operation is successful, you should store the current print settings so that these same settings can be applied to future print jobs.

You then set up the PrintData class by allocating a new instance. The file name is set to the currently selected file in the Gtk.FileChooserButton , which was already confirmed to exist. The print font size is also set to 10.0 points. In text editing applications, you would usually retrieve this font from Gtk.TextView’s current font. In more complex printing applications, the font size may vary throughout a document, but this is a simple example meant only to get you started.

Next, we connect to three Gtk.PrintOperation signals, which are discussed in detail later in this section. In short, begin_print is called before the pages are rendered and can be used for setting the number of pages and doing necessary preparation. The draw_page signal is called for every page in the print job so that it can be rendered. Lastly, the end_print signal is called after the print operation has completed, regardless of whether it succeeded or failed. This callback method cleans up after the print job. A number of other signals can be used throughout the print operation. A full list is in Appendix B.

The last two parameters of operation.run() allow you to define a parent window to use for the print dialog to use None to ignore this parameter. This function does not return until all of the pages have been rendered and are sent to the printer.

It is possible to run the print operation asynchronously, which means that operation.run() may return before the pages have been rendered. This is set with operation.set_allow_async(). You should note that not all platforms allow this operation, so you should be prepared for this not to work!

If you run the print operation asynchronously, you can use the done signal to retrieve notification when the printing has completed. At this point, you are given the print operation results, and you need to handle it accordingly.

After handling the print operation result, you should also handle the resulting error if it was set and if it exists.

A full list of possible errors under the Gtk.PrintError domain can be found in Appendix E.

It is also possible to give a unique name to the print job, which identifies it within an external print monitoring application. Print jobs are given names with operation.set_job_name(). If this is not set, GTK+ automatically designates a name for the print job and numbers consecutive print jobs accordingly.

The value returned by operation.get_status() can be used within applications, since it is a numerical value. However, GTK+ also provides the ability to retrieve a string with operation.get_status_string(), which is a human-readable description of the print job status. It is used for debugging output or displaying more information to the user about the print job. For example, it could be displayed on a status bar or in a message dialog.

Beginning the Print Operation

Now that the print operation is set up, it is time to implement the necessary signal callback methods. The “begin-print” signal is emitted when the user initiates printing, which means that all settings have been finalized from the user’s point of view.

In Listing 13-2, the begin_print callback method first retrieves the contents of the file and splits it into the number of lines. The total number of lines is then calculated, which can retrieve the number of pages.

To calculate the number of pages required by the print operation, you need to figure out how many lines can be rendered on every page. The total height of every page is retrieved with context.get_height(), which is stored in a Gtk.PrintContext object. Gtk.PrintContext stores information about how to draw the page. For example, it stores the page setup, width and height dimensions, and dots per inch in both directions. We go into more detail in the draw_page callback method later in this chapter.

Once you have the total height of the page that is available for rendering text, the next step is to divide that height by the font size of the text plus 3 pixels of spacing to be added between each line. The floor() function rounds down the number of lines per page so that clipping does not occur along the bottom of every full page.

Once you have the number of lines per page, you can calculate the number of pages. Then, you must send this value to operation.set_n_pages() by the end of this callback method. The number of pages are used so that GTK+ knows how many times to call the draw_page callback method. This must be set to a positive value so that rendering does not begin until it is changed from its default –1 value.

Rendering Pages

The next step is to implement the draw_page callback method, which is called once for every page that needs to be rendered. This callback method requires the introduction of a library called Cairo. It is a vector graphics library that renders print operations, among other things.

Listing 13-2 begins by retrieving the Cairo drawing context for the current Gtk.PrintContext with context.get_cairo_context(). The returned context object renders print content and then applies it to the PangoLayout.

At the beginning of this callback method, we also need to retrieve two other values from the Gtk.PrintContext. The first is context.get_width(), which returns the width of the document. Notice that we do not need to retrieve the height of the page, since we have already calculated the number of lines that fit on each page. If the text is wider than the page, it is clipped. You have to alter this example to avoid clipping the document.

The next step is to create a PangoLayout with context.create_pango_layout(), which is used for the print context. You should create Pango layouts in this manner for print operations, because the print context already has the correct font metrics applied.

The next operation performed by this function is to add the file name to the top-left corner of the page. To start, layout.set_text() sets the current text stored by the layout to the file name. The width of the layout is set to –1 so that the file name does not wrap at forward slash characters. The text is also aligned to the left of the layout with layout.set_alignment().

After rendering the file name, the same method adds the page count to the top-right corner of each page. You should again note that the width returned by the PangoLayout had to be scaled down by Pango.SCALE so that it would be in the same units as other Cairo values.

This function moves the current position relative to the previous position. Therefore, after a line is rendered, the current position is moved down one line, which is equal to the font size of the text since the font is monospace.

When developing with GTK+, you have the whole Cairo library available to you. More basics are covered in the “Cairo Drawing Context” section of this chapter; however, if you are implementing printing in your own applications, you should take the time to learn more about this library from the Cairo API documentation.

Finalizing the Print Operation

After all of the pages have been rendered, the "end-print" signal is emitted. Listing 13-2 shows the end_print callback method, which is used for the signal. It resets modified attributes of the PrintData instance.

Drawing Paths

When you are finished with a subpath, you can close it with cairo.path_close(). This encloses the current path so that it can be filled with a color if necessary.

Rendering Options

The current color used for drawing operations on a source is cairo.set_source_rgb(). The color is used until a new color is set. In addition to choosing a color, you can use cairo.set_source_rgba(), which accepts a fifth alpha parameter. Each of the color parameters is a floating-point number between 0.0 and 1.0.

This is simply a short introduction to Cairo drawing contexts. For further information about Cairo, you should reference its API documentation at www.cairographics.org .

Recent Chooser Menu

You have just learned about the Gtk.RecentChooserMenu widget. Listing 13-3 implements the "selection-done" callback method that was connected to it. This function retrieves the selected URI and opens the file if it exists.

After the prefix is removed, we attempt to open the file. If the file was successfully opened, the window title is set to the file name and the file is opened; otherwise, a warning is presented to the user that the file could not be opened.

Adding Recent Files

When the Open button is pressed, we want to allow the user to select a file to open from a Gtk.FileChooserDialog . If the file is opened, it is added to the default Gtk.RecentManager.

Secondly, you need an instance of the Gtk.RecentData class. The content of this class are a set of attributes that describe the data needed to store the file information to the Gtk.RecentManager. display_name displays a shortened name instead of the file name, and description is a short description of the file. Both of these values can safely be set to None.

You then have to specify a MIME type for the file, the name of your application, and the command line used to open the file. The name of your application can be retrieved by calling the Python library method os.path.basename(__file__). There a number of ways to get the program name but you can also safely set this to None.

Next, groups is a list of strings that designate what groups the resource belongs to. You are able to use this to filter out files that do not belong to a specific group.

The last member, is_private, specifies whether this resource is available to applications that did not register it. By setting this to True, you can prevent other applications that use the Gtk.RecentManager API from displaying this recent file.

Once you construct the Gtk.RecentData instance, it can be added along with the recent file URI as a new resource with recentmanager.add_full(). You can also add a new recent item with recentmanager.add_item(), which creates a Gtk.RecentData object for you.

Recent Chooser Dialog

GTK+ also provides a widget called Gtk.RecentChooserDialog, which displays recent files in a convenient dialog. This widget implements the Gtk.RecentChooser interface, so it is very similar in functionality to Gtk.RecentChooserMenu. In Listing 13-3, open_recent_file shows how to allow the user to open a recent file with this widget.

New Gtk.RecentChooserDialog widgets are created in a similar way to dialogs with Gtk.RecentChooserDialog(). This function accepts a title for the dialog, a parent window, a Gtk.RecentManager widget to display, and pairs of buttons and response identifiers.

The next step is to set the name of the filter. This name is displayed in the combo box where the user chooses which filter to use. There are many ways to create filters, including with filter. add_pattern() , which finds filters with matching patterns. The asterisk character can be used as the wildcard. There are also functions for matching MIME types, image file types, application names, group names, and ages in days. Next, use recentchooser.add_filter() to add the Gtk.RecentFilter to the recent chooser.

This function also returns the number of elements in the list of strings.

Exercise 1: Creating a Full Text Editor

In this exercise, you complete the text editor that you have been creating in the last few chapters. You add three new features to the application.

First, add the automatic completion feature, which should be implemented to remember past searches in the search toolbar. The application has to remember the past searches for only the current instance of the application runtimes. Next, add printing support, which includes printing and print preview abilities. Printing support can be easily implemented with the high-level Gtk.PrintOperation class. Lastly, instruct the text editor to remember the last five files loaded using the Gtk.RecentManager class.

So that you do not have to rewrite previous aspects of the application, you should use the solution to a Chapter 11 exercise or download that solution from this book’s official web site.