summaryrefslogtreecommitdiffstats log msg author committer range
path: root/libkipi/libkipi/mainpage.cpp
blob: d4e30fe8bdc4e8681da85bd0849002c7b74df174 (plain)
 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100  /** \mainpage libkipi reference page. This page will tell you both how to develop a new plugin for KIPI, and how to add KIPI support to a new application (referred to as host application). You can find more information about KIPI at this url. This documentation has been writen by Renchi Raju, Gilles Caulier, Jesper K. Pedersen, and Aurelien Gateau.

Developing a new Plugin

The easiest way to start a new plugin, is to copy the hello world plugin, which you may find in kdeextragear-libs-1/kipi-plugins. Please also read this tutorial which tells in general about developing a plugin structure for an application, but it also gives some background information on how plugins are loaded, and especially on the macros involved. The tutorial has been written by one of the KIPI authors, so it matches fairly good the model of KIPI (except the part on merging GUI's from plugins).

General things to do to implement a plugin

Here is a list of things to do.
• Create a class that inherits KIPI::Plugin. In the constructor you must create instances of TDEAction for your application. The topmost actions should be given to the Plugin super class using KIPI::Plugin::addAction().
• As described in the tutorial here, you must call the macro K_EXPORT_COMPONENT_FACTORY.
• You also need to create a desktop file, as described here

Retrieving information from the host application

The above was the required step to build the plugin. The following will tell you about the functions with which you communicate with the host application. The origin of all your communication with the host application is \ref KIPI::Interface. You obtain a pointer to this by casting the parent pointer given to your plugin during construction. Selection of images can be obtained using KIPI::Interface::currentSelection(), KIPI::Interface::currentAlbum() and KIPI::Interface::allAlbums(). These methods uses KIPI::ImageCollection to wrap a selection of images. Finally to obtain information about individual images, call KIPI::Interface::info(), which returns a KIPI::ImageInfo, with the information. When developing plugins, you should pay special attention to the fact the different host applications may have different feature sets they support. Information about what the host application support can be obtained from KIPI::Interface::hasFeature().

Utilities for Plugins

KIPI has a number of utilities useful when developing plugins:
• use KIPI::ImageCollectionDialog to ask the user for an image.
• use KIPI::UploadWidget when the user should specify a directory to write images into.
• KIPI::ThumbnailJob helps you load thumb nails of images.

Adding KIPI support to a new host application.

To add KIPI support to your application you must inherit KIPI::Interface, and give an instance of this class to KIPI::PluginLoader. See \ref KIPI::PluginLoader for details on loading plugins. To be able to create an instance of your subclass of KIPI::Interface, you must of course implement all the pure virtual method of the super class, among others this requires you to create and return instances of KIPI::ImageCollection and KIPI::ImageInfo. The only way you can do so are by giving the classes a pointer to a subclass of KIPI::ImageCollectionShared and KIPI::ImageInfoShared. These sub classes are also your responsibility to implement. The reason why things are that complicated, are to solve the problem of ownership of pointers to the classes in question. The KIPI::ImageCollectionShared pointer you give to KIPI::ImageCollection constructor will be the owned by the ImageCollection instance. */