Warning, /graphics/libkipi/src/Mainpage.dox is written in an unsupported language. File is not indexed.

 /**
    \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).
 
    This documentation has been writen by Gilles Caulier and has been updated
    and improved by Victor Dodon.
 
    <h1>General information about libkipi 2.0.0</h1>
 
    Starting with 2.0.0 version of libkipi shared library, Plugin class
    inherits KXMLGUIClient class. This means that if your application uses
    KDE-XML GUI, you can add plugin actions to the toolbar(if you add plugins to
    the guiFactory of you KXmlGuiWindow). For more documentation about KDE-XML
    GUI you can look <a href="http://techbase.kde.org/Development/Architecture/KDE4/XMLGUI_Technology">here</a>.
 
    <h2>Developing a new KIPI plugin</h2>
 
    The easiest way to start a new plugin, is to copy the
    <a href="https://commits.kde.org/libkipi?path=tests/plugins/kxmlhelloworld">
    KXMLHelloWorld</a> plugin, which you may find in <a
    href="https://commits.kde.org/libkipi">
    libkipi</a> project from KDE git repository. Please also read <a
    href="http://www.ukuug.org/events/linux2004/programme/paper-JPedersen-2/index.html">
    this tutorial</a> 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.
 
 
 
 
 
    <h2>General things to do to implement a KIPI plugin</h2>
 
    Here is a list of things to do.
    <ul>
    <li> Create a class that inherits KIPI::Plugin. In the constructor you
    must create instances of QAction for your application. The topmost
    actions should be given to the Plugin super class using KIPI::Plugin::addAction().
    <li> As described in the tutorial <a href="http://www.ukuug.org/events/linux2004/programme/paper-JPedersen-2/index.html#understanding_loading">here</a>, you must call KDE macros
    <tt>K_PLUGIN_FACTORY</tt> and <tt>K_EXPORT_PLUGIN</tt>.
    <li> You also need to create a desktop file, as described <a href="http://www.ukuug.org/events/linux2004/programme/paper-JPedersen-2/index.html#makefile_am_client">here</a>
    <li> You must write a rc file describing the gui of your plugin. For an
    example look at the <a href="https://commits.kde.org/libkipi?path=tests/plugins/kxmlhelloworld/kipiplugin_kxmlhelloworldui.rc">rc
    file</a> of the KXMLHelloWorld plugin.
    </ul>
 
 
 
 
 
    <h2>Retrieving information from the KIPI host application</h2>
 
    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, or, beginning with libkipi
    2.0.0, by calling interface() method from KIPI::Plugin class.
 
    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. Note that Kipi-plugins provide a dedicated wrapper around KIPI::ImageInfo
    to simplify item attribute management with host application. See
    <a href="https://commits.kde.org/kipi-plugins?path=common/libkipiplugins/tools/kpimageinfo.h">
    here</a> for details.
 
    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(). See also extra settings that can be shared
    by KIPI host application. Kipi-plugins provide a dedicated wrapper around KIPI::Interface to
    simplify host settings management.
 
 
 
    <h2>Utilities for Plugins</h2>
 
    KIPI has a number of utilities useful when developing plugins:
    <ul>
    <li> use KIPI::ImageCollectionSelector to ask the user for a collection.
    <li> use KIPI::UploadWidget when the user should specify a directory to
    write images into.
    <li> KIPI::Interface::thumbnail() helps you load thumbnails of images from KIPI host thumbnail manager.
    <li> KIPI::Interface::progress*() helps you dispatch progress information to KIPI host progress manager.
    <li> <a href="https://commits.kde.org/libkipi?path=tests/kipicmd">
    kipicmd command line program</a> helps you to test your plugin without to have a KIPI host application available.
    It emulates a simplified KIPI interface and can run plugin as stand-alone application.
    Look kipicmd command line documentation for details.
    <li> Beginning with libkipi 2.0.0 you have a simple gui program,
    <a href="https://commits.kde.org/libkipi?path=tests/kxmlkipicmd">kxmlkipicmd</a>,
    which emulates a simplified KIPI interface with a menubar and a toolbar. This
    way you can test the gui of your plugin.
    </ul>
 
 
 
 
    <h1>Adding KIPI support to a new host application.</h1>
 
    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 "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.
 */