Development/Tutorials/Calligra Overview: Difference between revisions

    From KDE TechBase
    (4 intermediate revisions by 4 users not shown)
    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 or EPS vector graphics.
    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.


    KSpread exports a tableShape, to allow a spread-sheet table to be embedded in other KOffice applications.
    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/classKoShapeRegistry.html KoShapeRegistry]
    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. The shape holds the content and a tool is required to control that 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/classKoToolRegistry.html KoToolRegistry]
    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 KOffice2 the focus on toolbars and dialogs will be less as they have been proven to be confusing to users because they clutter the interface.
    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/classKoDockRegistry.html KoDockRegistry]
    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 KSpread.
    Within KOffice 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 ===
    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 KoCanvasResourceProvider to put content on. Like the current layer, the current document etc.
    * The application should use the KCanvasResourceProvider to put content on. Like the current layer, the current document etc.
    * The docker should (also) inherit from KoCanvasObserver which means it will get notified when its canvas changes.
    * The docker should (also) inherit from KCanvasObserver which means it will get notified when its canvas changes.
    * Using the KoCanvasBase received from the KoCanvasObserver it can fetch the document from the KoCanvasResourceProvider.  It can also connect to the provider to be informed about any 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 KoCanvasResource::DocumentIsLoading boolean, dockers should listen to it to avoid doing work while the document is loading.
    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/classKoVariableRegistry.html KoInlineObjectRegistry]
    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/classKoTextEditingRegistry.html KoTextEditingRegistry]
    API docs start at; [http://www.koffice.org/developer/apidocs/libs-kotext/classKTextEditingRegistry.html KTextEditingRegistry]


    == Krita's plugins ==
    == Installing Plugins ==
    * filters (effects)
     
    * paintop (plugin that are in charge of painting when the user uses a drawing tool)
    Userbase has a short guide [http://userbase.kde.org/KOffice/Building_Dockers] to installing custom/third-party plugins.
    * viewplugin (aka misc)
    See [http://docs.kde.org/development/en/koffice/krita/developers-plugins.html Krita's handbook]

    Revision as of 09:55, 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 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 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.