Architecture and Design of Calligra 2.4

The links below document specific areas of the Calligra Architecture.

It is my (ingwa) intention to enhance this with more subsystems like:

General Overview
Code Overview
Shapes
Filters

Old Contents Follows

The rest of this page is old and does not give a very good overview of the architecture of Calligra. It should be rewritten IMHO. /ingwa

This document is intended to present a general, high-level overview of software architecture and user interface design of Calligra 2.4. Note that because of different workflow not all Calligra applications are fully integrated into this design: notably Kexi and Calligra Plan. The Calligra Sheets integration with the Calligra 2.4 design has not progressed very far at the time of writing, although there are plenty of opportunities.

Also note that Calligra consists of two "wings" a creative wing and a productive wing, with calligra Words as the join. The first contains Krita, Karbon and Kivio, the second contains Calligra Stage, Calligra Sheets, Calligra Plan, Kexi, KChart and KFormula.

A second division is between the big, document-oriented stand-alone applications and the smaller applications that are more like really big shapes: kformula and kchart.

The Applications

Calligra consists of several applications that offer a specialized interface for a certain task to a generic set of content components. For instance, the word processor is optimized for the creating of paged text documents with a certain layout. The drawing application is optimized for creating single page vector images. The presentation application is optimized for making slideshows. But all the applications use the text component, the same vector graphics components and the same chart components.

Applications are specialized through their canvas and document and their menu structure:

A multi-page document needs a different canvas and document from a single-page document, which again is different from a slideshow. Thus, every Calligra application needs to implement a particular document type and a specific KoCanvasBase-based canvas for displaying the document. The document contents consist mainly of shapes. The scrollbars around the canvas are provided by Calligra, by the way. Some applications contain more than one canvas implementation: Krita for instance has both a QPainter and an OpenGL canvas. (Which could be useful for Karbon, too.)

The menu structure contains additional user actions that extend the basic functionality provided by the shape tools with document-specific functionality.

Shapes and Tools

Similar to Gobe Productive and Apple's iWorks, Calligra documents are composed from fine-grained components, shapes. A shape can contain text, vector graphics, a table, a chart, raster graphics, music -- the possibilities are infinite.

Shapes can be selected in a gui element called the "shape selector". A particular shape, say a vector shape, can come in many different forms: think Calligra Flow stencils. We are still developing a shape selector that can handle and organize many different shape types and shape templates.

Shapes contain data and know how to draw themselves using Qt's painting code, load themselves from a chunk of (odf-compliant) XML and save themselves to XML. Shapes can be moved, rotated, scaled, added and deleted using the pointer tool. Vector shapes can also contain gradient or other fills, nodes and lines: there are generic tools for setting these. It is the intention to make fill and line tools also work on, for instance, the borders of other shape types.

The data contained in the shape is edited using tools. As soon as a shape is selected the associated tools are added to a special area in the toolbox. Selecting a tool shows the the tool option page in a docking window. The tool receives all keyboard, mouse and tablet events from the canvas and is supposed to use these events to mess with the data contained in the shape. There is one tool instance for each pointing device attached to the computer: mouse, stylus, airbrush, eraser, art pen.

User Interface

The basic design of a Calligra application contains the following components:

toolbox
shape selector
dock windows
menus and toolbars
canvas

Here, we have the toolbox top-left, shape selector at the bottom, tool option page top-right, other dockers on the right, menu on top and the canvas with some shapes in the middle.

The use of toolbar buttons in Calligra is closer to the Apple example of only few very useful buttons rather than the Microsoft example of tens of toolbars stuffed with buttons.

There is still a lot of work to be done to make our user interfaces more useful and pleasant to use. The functionality is ready, the basic order of things (i.e., the list above) is pretty sound, but the actual implementation is not done at all.

The Libraries

Calligra contains a set of base libraries that provide the common functionality:

Flake: the canvas interface, the tool interface and the shape definitions
Main: the document and view base classes, support for import/export filters
GuiUtils: zooming, widgets, document section browser
kokross: support for scripting in many scripting languages, with some gui components for managing scripts
kopageapp: the base for applications that have multiple pages but without text running from one page to another (Calligra Stage and Calligra Flow)
kopainter: common graphics stuff like gradients
kotext: text handling
pigment: professional color handling including color correction
resources: handling of resources like clipart, brushes etc. (needs a refactor!)
store: odf and old-style native file handling. May be extracted from Calligra in the future and provided to all of KDE.

The Plugins

As discussed at Developing Calligra Plugins, Calligra is very extensible. You can add new file import/export filters, content types (for example, a music notation shape was developed as a plugin), tools, dockers, text plugins and application specific plugins like Krita's image filters.