← Back to branch summary

~ubuntu-branches/ubuntu/trusty/digikam/trusty

« back to all changes in this revision

Viewing changes to extra/libkipi/libkipi/Mainpage.dox

  • Committer: Package Import Robot
  • Author(s): Rohan Garg
  • Date: 2012-11-26 18:24:20 UTC
  • mfrom: (1.9.1) (3.1.23 experimental)
  • Revision ID: package-import@ubuntu.com-20121126182420-qoy6z0nx4ai0wzcl
Tags: 4:3.0.0~beta3-0ubuntu1
https://launchpad.net/bugs/890059
https://launchpad.net/bugs/1011211
https://launchpad.net/bugs/658047
* New upstream release
  - Add build-deps :  libhupnp-dev, libqtgstreamer-dev, libmagickcore-dev
* Merge from debian, remaining changes:
  - Make sure libqt4-opengl-dev, libgl1-mesa-dev and libglu1-mesa-dev only
    install on i386,amd64 and powerpc
  - Depend on libtiff-dev instead of libtiff4-dev
  - Drop digikam breaks/replaces kipi-plugins-common since we're past the
    LTS release now
  - digikam to recommend mplayerthumbs | ffmpegthumbs. We currently only
    have latter in the archives, even though former is also supposed to
    be part of kdemultimedia. (LP: #890059)
  - kipi-plugins to recommend www-browser rather than konqueror directly
    since 2.8 no direct usage of konqueror is present in the flickr
    plugin anymore (LP: #1011211)
  - Keep kubuntu_mysqld_executable_name.diff
  - Don't install libkipi translations
  - Keep deps on libcv-dev, libcvaux-dev
  - Keep split packaging of libraries
  - Replace icons from KDE 3 time in debian/xpm.d/*.xpm with the new
    versions (LP: #658047)
* Update debian/not-installed

Show diffs side-by-side

added added

removed removed

Lines of Context:
extra/libkipi/libkipi/Mainpage.dox
5
5
   plugin for KIPI, and how to add KIPI support to a new
6
6
   application (referred to as host application).
7
7
 
8
 
   You can find more information about KIPI at this <a
9
 
   href="http://wwww.digikam.org/docs">url</a>.
10
 
 
11
 
   This documentation has been writen by Gilles Caulier.
12
 
 
13
 
   <h1>Developing a New Plugin</h1>
14
 
 
15
 
   The easiest way to start a new plugin, is to copy the 
16
 
   <a href="https://projects.kde.org/projects/extragear/graphics/kipi-plugins/repository/revisions/master/show/tests/helloworld">
17
 
   HelloWorld</a> plugin, which you may find in <a
18
 
   href="https://projects.kde.org/projects/extragear/graphics/kipi-plugins">
19
 
   kipi-plugins</a> project from KDE git repository. Please also read <a
 
8
   This documentation has been writen by Gilles Caulier and has been updated
 
9
   and improved by Victor Dodon.
 
10
 
 
11
   <h1>General information about libkipi 2.0.0</h1>
 
12
 
 
13
   Starting with 2.0.0 version of libkipi shared library, Plugin class
 
14
   inherits KXMLGUIClient class. This means that if your application uses
 
15
   KDE-XML GUI, you can add plugin actions to the toolbar(if you add plugins to
 
16
   the guiFactory of you KXMLGuiWindow). For more documentation about KDE-XML
 
17
   GUI you can look <a href="http://techbase.kde.org/Development/Architecture/KDE4/XMLGUI_Technology">here</a>.
 
18
 
 
19
   <h2>Developing a new KIPI plugin</h2>
 
20
 
 
21
   The easiest way to start a new plugin, is to copy the
 
22
   <a href="https://projects.kde.org/projects/kde/kdegraphics/libs/libkipi/repository/show/tests/kxmlhelloworld?rev=development%2F2.0.0">
 
23
   KXMLHelloWorld</a> plugin, which you may find in <a
 
24
   href="https://projects.kde.org/projects/kde/kdegraphics/libs/libkipi">
 
25
   libkipi</a> project from KDE git repository. Please also read <a
20
26
   href="http://www.ukuug.org/events/linux2004/programme/paper-JPedersen-2/index.html">
21
27
   this tutorial</a> which tells in general about developing a plugin
22
28
   structure for an application, but it also gives some background
23
29
   information on how plugins are loaded, and especially on the macros
24
30
   involved. The tutorial has been written by one of the KIPI authors, so
25
 
   it matches fairly good the model of KIPI (except the part on merging
26
 
   GUI's from plugins).
27
 
 
28
 
 
29
 
 
30
 
 
31
 
   <h2>General Things to do to Implement a Plugin</h2>
 
31
   it matches fairly good the model of KIPI.
 
32
 
 
33
 
 
34
 
 
35
 
 
36
 
 
37
   <h2>General things to do to implement a KIPI plugin</h2>
32
38
 
33
39
   Here is a list of things to do.
34
40
   <ul>
35
41
   <li> Create a class that inherits KIPI::Plugin. In the constructor you
36
42
   must create instances of KAction for your application. The topmost
37
 
   actions should be given to the Plugin super class using 
38
 
   KIPI::Plugin::addAction().
 
43
   actions should be given to the Plugin super class using KIPI::Plugin::addAction().
39
44
   <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
40
45
   <tt>K_PLUGIN_FACTORY</tt> and <tt>K_EXPORT_PLUGIN</tt>.
41
46
   <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>
 
47
   <li> You must write a rc file describing the gui of your plugin. For an
 
48
   example look at the <a href="https://projects.kde.org/projects/kde/kdegraphics/libs/libkipi/repository/entry/tests/kxmlhelloworld/plugin/kipiplugin_kxmlhelloworldui.rc?rev=development%2F2.0.0">rc
 
49
   file</a> of the KXMLHelloWorld plugin.
42
50
   </ul>
43
51
 
44
52
 
45
53
 
46
54
 
47
55
 
48
 
   <h2>Retrieving Information from the Host Application</h2>
 
56
   <h2>Retrieving information from the KIPI host application</h2>
49
57
 
50
58
   The above was the required step to build the plugin. The following will
51
59
   tell you about the functions with which you communicate with the host
53
61
 
54
62
   The origin of all your communication with the host application is
55
63
   \ref KIPI::Interface. You obtain a pointer to this by casting the parent
56
 
   pointer given to your plugin during construction.
 
64
   pointer given to your plugin during construction, or, beginning with libkipi
 
65
   2.0.0, by calling interface() method from KIPI::Plugin class.
57
66
 
58
67
   Selection of images can be obtained using
59
68
   KIPI::Interface::currentSelection(), KIPI::Interface::currentAlbum() and
62
71
 
63
72
   Finally to obtain information about individual images, call
64
73
   KIPI::Interface::info(), which returns a KIPI::ImageInfo, with the
65
 
   information. Note that Kipi-plugins provide a dedicated wrapper around KIPI::ImageInfo 
66
 
   to simplify item attribute management with host application. See 
 
74
   information. Note that Kipi-plugins provide a dedicated wrapper around KIPI::ImageInfo
 
75
   to simplify item attribute management with host application. See
67
76
   <a href="https://projects.kde.org/projects/extragear/graphics/kipi-plugins/repository/revisions/master/entry/common/libkipiplugins/tools/kpimageinfo.h">
68
77
   here</a> for details.
69
78
 
70
79
   When developing plugins, you should pay special attention to the fact the different
71
80
   host applications may have different feature sets they
72
81
   support. Information about what the host application support can be
73
 
   obtained from KIPI::Interface::hasFeature(). See also extra settings that can be shared 
74
 
   by KIPI host application. Kipi-plugins provide a dedicated wrapper around KIPI::Interface to 
75
 
   simplify host settings management. See 
 
82
   obtained from KIPI::Interface::hasFeature(). See also extra settings that can be shared
 
83
   by KIPI host application. Kipi-plugins provide a dedicated wrapper around KIPI::Interface to
 
84
   simplify host settings management. See
76
85
   <a href="https://projects.kde.org/projects/extragear/graphics/kipi-plugins/repository/revisions/master/entry/common/libkipiplugins/tools/kphostsettings.h">
77
 
   here</a> and <a href="https://projects.kde.org/projects/extragear/graphics/kipi-plugins/repository/revisions/master/entry/common/libkipiplugins/tools/kpmetasettings.h">
78
 
   here</a> for details.
 
86
   KPHostSettings</a> and <a href="https://projects.kde.org/projects/extragear/graphics/kipi-plugins/repository/revisions/master/entry/common/libkipiplugins/tools/kpmetasettings.h">
 
87
   KPMetaSettings</a> for details.
79
88
 
80
89
 
81
90
 
90
99
   <li> KIPI::Interface::thumbnail() helps you load thumbnails of images from KIPI host thumbnail manager.
91
100
   <li> KIPI::Interface::progress*() helps you dispatch progress information to KIPI host progress manager.
92
101
   <li> <a href="https://projects.kde.org/projects/extragear/graphics/kipi-plugins/repository/revisions/master/show/tests">
93
 
   kipicmd command line program</a> helps you to test your plugin without to have a KIPI host application available. 
94
 
   It emule a simplified KIPI interface and can run plugin as stand-alone application. 
 
102
   kipicmd command line program</a> helps you to test your plugin without to have a KIPI host application available.
 
103
   It emulates a simplified KIPI interface and can run plugin as stand-alone application.
95
104
   Look kipicmd command line documentation for details.
 
105
   <li> Beginning with libkipi 2.0.0 you have a simple gui program,
 
106
   <a href="https://projects.kde.org/projects/kde/kdegraphics/libs/libkipi/repository/show/tests?rev=development%2F2.0.0">kxmlkipicmd</a>,
 
107
   which emulates a simplified KIPI interface with a menubar and a toolbar. This
 
108
   way you can test the gui of your plugin.
96
109
   </ul>
97
110
 
98
111