Development/Tutorials/Calligra Overview: Difference between revisions
m (Add link to the userbase docker install page.) |
No edit summary |
||
| Line 14: | Line 14: | ||
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 KOffice applications. | |||
API docs start at; [http://www.koffice.org/developer/apidocs/libs-flake/ | API docs start at; [http://www.koffice.org/developer/apidocs/libs-flake/classKShapeRegistry.html KShapeRegistry] | ||
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 29: | ||
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 35: | ||
* 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://www.koffice.org/developer/apidocs/libs-flake/ | API docs start at; [http://www.koffice.org/developer/apidocs/libs-flake/classKToolRegistry.html KToolRegistry] | ||
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 41: | ||
== Dockers == | == Dockers == | ||
Plugins that provide a docker are basically plugins that provide a graphical user interface element for KOffice applications. In | Plugins that provide a docker are basically plugins that provide a graphical user interface element for KOffice applications. In KOffice 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://www.koffice.org/developer/apidocs/libs-flake/ | API docs start at; [http://www.koffice.org/developer/apidocs/libs-flake/classKDockRegistry.html KDockRegistry] | ||
Within KOffice dockers could also be written in a scripting language like Python or Ruby. The [[Development/Tutorials/KSpread_Scripting#Scripting_Docker_Widgets|KSpread Scripting Docker]] tutorial shows how it was done within | Within KOffice dockers could also be written in a scripting language like Python or Ruby. The [[Development/Tutorials/KSpread_Scripting#Scripting_Docker_Widgets|KSpread Scripting Docker]] tutorial shows how it was done within KCells. | ||
=== Considerations === | === Considerations === | ||
| Line 54: | Line 54: | ||
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. | 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; | This involves a couple of steps; | ||
* The application should use the | * The application should use the KCanvasResourceProvider to put content on. Like the current layer, the current document etc. | ||
* The docker should (also) inherit from | * The docker should (also) inherit from KCanvasObserver which means it will get notified when its canvas changes. | ||
* Using the | * 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 | 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 == | == Colorspaces == | ||
| Line 75: | Line 75: | ||
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://www.koffice.org/developer/apidocs/libs-kotext/ | API docs start at; [http://www.koffice.org/developer/apidocs/libs-kotext/classKInlineObjectRegistry.html KInlineObjectRegistry] | ||
=== Text Editing === | === Text Editing === | ||
| Line 84: | Line 84: | ||
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://www.koffice.org/developer/apidocs/libs-kotext/ | API docs start at; [http://www.koffice.org/developer/apidocs/libs-kotext/classKTextEditingRegistry.html KTextEditingRegistry] | ||
== Installing Plugins == | == Installing Plugins == | ||
Userbase has a short guide [http://userbase.kde.org/KOffice/Building_Dockers] to installing custom/third-party plugins. | Userbase has a short guide [http://userbase.kde.org/KOffice/Building_Dockers] to installing custom/third-party plugins. | ||
Revision as of 09:54, 15 November 2011
KOffice has gotten more and more configurable through plugins over time, which is a really good thing as 3rd party developers can extend KOffice 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 KOffice Plugin Creation
Shapes
In KOffice 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 KOffice 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 KOffice applications.
API docs start at; KShapeRegistry
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; KToolRegistry
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 KOffice applications. In KOffice 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; KDockRegistry
Within KOffice dockers could also be written in a scripting language like Python or Ruby. The KSpread 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 KOffice 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; KInlineObjectRegistry
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; KTextEditingRegistry
Installing Plugins
Userbase has a short guide [1] to installing custom/third-party plugins.