Development/Tutorials/Calligra Overview: Difference between revisions
(Mark for updating) |
|||
| (11 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
{{Review|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. | 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. | ||
| Line 8: | Line 10: | ||
== Generic Information == | == 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 [[Development/Tutorials/Generic | 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 [[Development/Tutorials/Generic Calligra Plugin Creation|Generic Calligra Plugin Creation]] | ||
== Shapes == | == Shapes == | ||
In | 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. | 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 | 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. | 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; [http:// | API docs start at; [http://api.kde.org/bundled-apps-api/calligra-apidocs/libs/flake/html/classKoShapeRegistry.html KoShapeRegistry] | ||
The tutorial on how to write your own shape plugins can be found at [[Development/Tutorials/Write a Flake Plugin|Write a Flake Plugin]] | The tutorial on how to write your own shape plugins can be found at [[Development/Tutorials/Write a Flake Plugin|Write a Flake Plugin]] | ||
| Line 29: | Line 31: | ||
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. | 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. | 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; | In general there are two types of Tools; | ||
| Line 35: | Line 37: | ||
* bundled tools that come with a specific flake shape and is made to manipulate that shapes data. | * bundled tools that come with a specific flake shape and is made to manipulate that shapes data. | ||
API docs start at; [http:// | API docs start at; [http://api.kde.org/bundled-apps-api/calligra-apidocs/libs/flake/html/classKoToolRegistry.html KoToolRegistry] | ||
The tutorial on how to write your own shape plugins can be found at [[Development/Tutorials/Write a Flake Plugin|Write a Flake Plugin]] | The tutorial on how to write your own shape plugins can be found at [[Development/Tutorials/Write a Flake Plugin|Write a Flake Plugin]] | ||
| Line 41: | Line 43: | ||
== Dockers == | == Dockers == | ||
Plugins that provide a docker are basically plugins that provide a graphical user interface element for | 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. | 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. | Examples of dockers are; the toolbox, the shape selector and the tool-options but also the color selector. | ||
API docs start at; [http:// | API docs start at; [http://api.kde.org/bundled-apps-api/calligra-apidocs/libs/flake/html/classKoDockRegistry.html KoDockRegistry] | ||
Within | Within Calligra dockers could also be written in a scripting language like Python or Ruby. The [[Development/Tutorials/KSpread_Scripting#Scripting_Docker_Widgets|KCells Scripting Docker]] tutorial shows how it was done within KCells. | ||
=== Considerations === | === Considerations === | ||
Dockers should never be passed a document or a view in the constructor. | 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 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 | 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. | ||
new document or a new image, etc. And listen on that. | This involves a couple of steps; | ||
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 application should use the | * The docker should (also) inherit from KCanvasObserver which means it will get notified when its canvas changes. | ||
on. Like the current layer, the current document etc. | * 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. | ||
* The docker should (also) inherit from | |||
will get notified when its canvas changes. | |||
* Using the | |||
the document from the | |||
the provider to be informed about any changes. | |||
An extra tip is to use the | An extra tip is to use the KCanvasResource::DocumentIsLoading boolean, dockers should listen to it to avoid doing work while the document is loading. | ||
is loading. | |||
== Colorspaces == | == Colorspaces == | ||
| Line 77: | Line 68: | ||
== Text Plugins == | == Text Plugins == | ||
The text component used in all | 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 === | === Inline Objects === | ||
| Line 86: | Line 77: | ||
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. | 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; [http:// | API docs start at; [http://api.kde.org/bundled-apps-api/calligra-apidocs/libs/kotext/html/classKoInlineObjectRegistry.html KoInlineObjectRegistry] | ||
=== Text Editing === | === Text Editing === | ||
| Line 95: | Line 86: | ||
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. | 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; [http:// | API docs start at; [http://api.kde.org/bundled-apps-api/calligra-apidocs/libs/kotext/html/classKoTextEditingRegistry.html KoTextEditingRegistry] | ||
Latest revision as of 08:36, 31 May 2019
Parts to be reviewed:
Port to KF5Calligra 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.
Colorspaces
File Filters
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