Development/Tutorials/Calligra Overview

Warning

This page needs a review and probably holds information that needs to be fixed.

Parts to be reviewed:

Port to KF5

Calligra has gotten more and more configurable through plugins over time, which is a really good thing as 3rd party developers can extend Calligra using dedicated code for their purpose.

You will learn what functionality you can place in each plugin type so you can choose wisely. There is a general guide to writing plugins and each type has a tutorial showing how to create a new plugin of that type.

well, not all required info is there yet; but this is the idea :) Anyone want to help?

Generic Information

Plugins are a design technique with a series of steps that will lead you to a loadable plugin. If you want to know more its is interresting to read an overview at Generic Calligra Plugin Creation

Shapes

In Calligra shapes are document content. This content can be manipulated by the user and can be shown on screen or printed. The fact that they are plugins means that a new content types can be added to documents by just installing the plugin and starting your favorite Calligra application. To get a feel for what a shape is, here are some examples of existing shapes, sometimes referred to as Flake shapes because shapes are one of the two main parts of the Flake library.

We have a PathShape which is a generic vector shape capable of showing and printing any sort of vector art like SVG vector graphics.

There is a Text plugin that is capable of showing marked up text with a huge feature set including HTML capabilities and a big part of the more extensive OpenDocument format.

KCells exports a tableShape, to allow a spread-sheet table to be embedded in other Calligra applications.

API docs start at; KoShapeRegistry

The tutorial on how to write your own shape plugins can be found at Write a Flake Plugin

Tools

A tool is a plugin that handles user input and can manipulate either the general application data, or can manipulate a specific shape. All user input mouse and keyboard events that are send to the document area (canvas), will be passed to the active tool. The active tool can use them to, for example, move shapes around or rotate them. If you combine a tool with a shape plugin you can make the tool manipulate the data of the shape. A good example is the text tool which is bundled with the text shape. The text tool takes all keyboard events and thereby lets the user type text in the text shape.

This gives a clear separation of control and content. The shape holds the content and a tool is required to control that content.

In general there are two types of Tools;

• generic tools that are not associated with a shape plugin. Its rare that you will create such plugins, though we still need a 'measure' tool that falls in that category.
• bundled tools that come with a specific flake shape and is made to manipulate that shapes data.

API docs start at; KoToolRegistry

The tutorial on how to write your own shape plugins can be found at Write a Flake Plugin

Dockers

Plugins that provide a docker are basically plugins that provide a graphical user interface element for Calligra applications. In Calligra the focus on toolbars and dialogs will be less as they have been proven to be confusing to users because they clutter the interface. Instead the focus is shifted to widgets that can be docked along the sides of a document window but also moved to be a separate window. The real change is that, unlike dialogs, they don't have an 'Ok' button but instead change the content life and immediately. Examples of dockers are; the toolbox, the shape selector and the tool-options but also the color selector.

API docs start at; KoDockRegistry

Within Calligra dockers could also be written in a scripting language like Python or Ruby. The KCells Scripting Docker tutorial shows how it was done within KCells.

Considerations

Dockers should never be passed a document or a view in the constructor. The reasons for that is simple; the lifetime of the docker is longer then the lifetime of the document and also of the view.

The proper way to do this is to let the application tell you there is a new document or a new image, etc. And listen on that. This involves a couple of steps;

• The application should use the KCanvasResourceProvider to put content on. Like the current layer, the current document etc.
• The docker should (also) inherit from KCanvasObserver which means it will get notified when its canvas changes.
• Using the KCanvasBase received from the KCanvasObserver it can fetch the document from the KCanvasResourceProvider. It can also connect to the provider to be informed about any changes.

An extra tip is to use the KCanvasResource::DocumentIsLoading boolean, dockers should listen to it to avoid doing work while the document is loading.

Text Plugins

The text component used in all Calligra applications has a set of plugins itself. These plugins allow the possibility to enhance the content as well as allow to enhance the editing experience. Use Inline object plugins to write content such as inline variables and bookmarks. Use Text Editing plugins to be able to replace the text a user types while he types it. For example for autocorrection.

Inline Objects

The plugins of this type effectively become a character in the text document. What this means is that a user can insert an inline object and the plugin can decide the size and content of the character inserted. A good example of inline objects are variables. A variable can have a name and a value and altering the value of a variable will then change the value in the text all over the document. This is done by an inline object that shows the full text of the variable, but in the document it behaves as it is one big character that can't be split over lines or otherwise edited.

An inline object does not have to have content, it can just be a placeholder as well. Which makes it ideal for things like in-text comments/annotations and Bookmarks.

API docs start at; KoInlineObjectRegistry

Text Editing

The text editing plugins are all about handling user input while (s)he is editing the text. A plugin can do near everything with the typed text, including altering it and adding markup. The plugin gives events when a word and when a paragraph has been finished. Which is ideal for autocorrection and autoreplacement of text.

Examples of usages of this plugin type are; a word count in a docker updated continuesly, auto correction of text, replacing formatted text with calculated values or custom shape plugins.

API docs start at; KoTextEditingRegistry