White Paper: The GNOME Canvas

Introduction

The GNOME canvas is a high-level engine for creating structured graphics. This means the programmer can insert graphical items like lines, rectangles, and text into the canvas, and refer to them later for further manipulation. The programmer does not need to worry about repainting these items or generating events for them; the canvas automatically takes care of these operations.

The canvas provides several predefined item types, including lines, rectangles, and text. However, the canvas is designed to serve as a general-purpose display engine. Applications can define their own custom item types that integrate with the rest of the canvas framework. This lets them have a flicker-free display engine with proper event management and propagation.

The canvas supports two rendering models. One is based directly on Xlib (used via GDK), which provides an extremely fast and lean display that runs well over networks. The second rendering model is based on Libart, a sophisticated library for manipulating and rendering vector paths using antialiasing and alpha compositing. Libart provides a superset of the PostScript imaging model, allowing for extremely high-quality displays.

Simple applications can use the predefined canvas item types to create interactive graphics displays. For example, theGNOME Calendarprogram uses the canvas to display and manipulate monthly calendars. It only needs simple graphical items like rectangles and text to display its information. Please look at Figure 1 for an example of the use of the canvas in theGNOME Calendar.

Figure 1. Use of the canvas in the GNOME Calendar

(1)

The whole month view is a single big canvas. Stock canvas items like rectangles and text are used to display an easily-customizable calendar.

(2)

The little monthly calendars are custom canvas groups based on the stock item types. The calendar program implements different behavior for each place in which the monthly calendar item is used.

Applications with more sophisticated requirements can define their custom canvas item types. The Gnumeric spreadsheet defines a large ‘Sheet’ item that takes care of painting the sheet's grid and the cell contents. It also defines an item to handle the complex cursor object in the spreadsheet, which must handle the current selection, the current cell, and the border items to drag and extend selections. Please look at Figure 2 for an example of the use of the canvas in the Gnumeric spreadsheet.

Figure 2. Use of the canvas in the Gnumeric spreadsheet

(1)

Gnumeric uses a custom "Sheet" item to display the spreadsheet contents. This item is responsible for drawing grid lines and cell contents.

(2)

The cursor is another custom item. In Figure 2 it is shown as a 42-cell selection with the current cell being G13. The cursor item handles all aspects of a spreadsheet's cursor, including the current cell, the selection range, and the clickable areas that let the user drag and fill cells automatically.

(3)

The column and row headers are two modes of a single custom item. This item draws the button-like headers and highlights them as appropriate when cells are selected.

(4)

Gnumericuses the stock canvas items (like lines, rectangles, and ellipses) for the graphic elements that the user may want to overlay on the spreadsheet. Here the user has inserted an arrow, and the canvas takes care of repainting everything automatically.

This white paper describes the architecture of the GNOME canvas and Libart. It gives examples on why application writers may want to use these technologies.