Digikam/GSoC2012/KipiPluginInterfaceToolbarAccess

From KDE Community Wiki

Digikam GSoC 2012 Kipi Plugin Interface Toolbar Access

This page is meant to gather information about the project idea which aims to provide an easy toolbar access for existing Kipi Plugin interface.

Requirements and Considerations

Summary

In digiKam we have 2 plugin architectures : one for Album Gui, as kipi-plugins, shared through libkipi with all kipi host applications, and one for image editor, not shared with the rest of the world.

kipi plugin interface have been written 1 year before image editor plugin interface. This last one uses KDE XML GUI API. libkipi,NO.

Typically, image editor plug tools in GUI use KDE XML features, which is very flexible and automatize very well plugins mechanism and plugin host interface but Kipi plugin interface plug tool uses a hardcoded way, which is not flexible. That is the action from tool can be plugged into menu, toolbar easily, action can be edited through KDE configuration shortcuts dialog, action can be added/removed from menu and toolbar KDE configuration edit dialog, etc.

With kipi interface, we can only plug tool in menu and that too only through code. Using KDE XML GUI way, we will only need to change XML files of KDE application. When KIPI interface was written, KDE XML GUI API was still under development. To be more powerful, KIPI interface must be re-implemented using XML GUI API for client application.

More Details & Steps

Note

The projects.kde.org links below are dead; however clicking them should transfer you to the up-to-date links on quickgit.kde.org. If this page is still being used, updating those links would be useful.


1/ Libkipi shared library


Libkipi is the main interface between plugin and kipi host application. This library is hosted in KDE core, into KDEGraphics component. This is another brick in the puzzle : this lib is released through KDE release. It will be important to mention in your GSoC proposal a release plan following KDE release plan. Note that Gwenview and ksnapshot, which use libkipi, are also hosted into kdegraphics is released with KDE. It's not the case of digiKam and KPhotoAlbum. So take a care about the plan to fix this host application.

Libkipi interface contain a definition of plugin class for kipi-plugins :

https://projects.kde.org/projects/kde/kdegraphics/libs/libkipi/repository/revisions/master/entry/libkipi/plugin.h

there is also a plugin loader which is used by kipi host applications :

https://projects.kde.org/projects/kde/kdegraphics/libs/libkipi/repository/revisions/master/entry/libkipi/pluginloader.h

Both classes must be patched in this project.

To study how work these classes, in kipi-plugins, there is a very simple "hello world" plugin :

https://projects.kde.org/projects/extragear/graphics/kipi-plugins/repository/revisions/master/entry/tests/helloworld/plugin_helloworld.h

... and a stand alone plugin loader that you can invoke by command line. It re-implement a simple loader :

https://projects.kde.org/projects/extragear/graphics/kipi-plugins/repository/revisions/master/entry/tests/main.cpp#L150

Look like code sound like complex, not very comprehensive at the first read.

You can use this command line tool to load and test plugin as stand alone application. Look README for details.

Note that this test application must be also fixed to support KDE XML GUI plugin loader architecture.

2/ digiKam Kipi interface


digiKam has a collection of classes re-implemented from libkipi here :

https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/show/utilities/kipiiface

all is there, including the famous plugin loader. This last one must be patched in your project to group this loader with other kipi classes. Typically a new plugin loader class must be created from libkipi parent class and must support KDE XML GUI architecture. In parallele, the older one must be preserve for compatibility reason with older libkipi release.

The plugin loader implementation is here :

plugins loaded at startup :

https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/entry/digikam/main/digikamapp.cpp#L287 https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/entry/digikam/main/digikamapp.cpp#L2511 https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/entry/utilities/kipiiface/kipipluginloader.cpp#L169

...look the puzzle to plug actions at the right place in menu, accordingly to plugin type (batch, image, import, export, etc...)...

The simple way to pass plugin actions to KDE shortcuts edit dialog...

https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/entry/digikam/main/digikamapp.cpp#L2397

The puzzle to pass plugin action to KDE toolbar edit dialog (which don't work of course)

https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/entry/digikam/main/digikamapp.cpp#L2412

To enable kipi plugin action in menu, it's another big puzzle. We get list of plugin actions accordingly with plugin types. this is done outside this class...

3/ digiKam image editor plugin interface


This point is VERY important ! This code must be used as reference to re-implement kipi plugin interface based on KDE XML GUI.

As in libkipi, there are 2 classes :

- the plugin class based on KXMLGUIClient :

https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/entry/utilities/imageeditor/canvas/imageplugin.h#L47

- the plugin loader :

https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/entry/utilities/imageeditor/canvas/imagepluginloader.h#L44

All image editor plugins are here :

https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/show/imageplugins

Lead class of Image editor is based on KXmlGuiWindow of course :

https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/entry/utilities/imageeditor/editor/editorwindow.cpp#L162

Similar to kipi, editor plugin actions are passed to KDE shortcuts edit dialog :

https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/entry/utilities/imageeditor/editor/editorwindow.cpp#L753

Plugins are loaded by this method :

https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/entry/utilities/imageeditor/editor/editorwindow.cpp#L866

...called from derivated classes here :

https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/entry/utilities/imageeditor/editor/imagewindow.cpp#L313

https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/entry/showfoto/main/showfoto.cpp#L230

Plugins are unloaded from GUI if necessary by this method (not used anymore, since there is no more editor plugin config dialog as KIPI)

https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/entry/utilities/imageeditor/editor/editorwindow.cpp#L914

We manage plugin action activation through menu and toolbar here :

https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/entry/utilities/imageeditor/editor/editorwindow.cpp#L1161

Look like it's more simple than kipi way...

The XML GUI configuration is done here for editor :

https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/entry/utilities/imageeditor/editor/digikamimagewindowui.rc

Each plugin has an XML GUI configuration file which is merged with editor XML file. There is 5 plugins :

https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/entry/imageplugins/color/digikamimageplugin_color_ui.rc

https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/entry/imageplugins/decorate/digikamimageplugin_decorate_ui.rc

https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/entry/imageplugins/enhance/digikamimageplugin_enhance_ui.rc

https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/entry/imageplugins/filters/digikamimageplugin_fxfilters_ui.rc

https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/entry/imageplugins/transform/digikamimageplugin_transform_ui.rc

4/ Others kipi host application


Here my knowledge are limited. I don't manage this code of course. KIPI interface are there :

https://projects.kde.org/projects/kde/kdegraphics/gwenview/repository/revisions/master/show/app

https://projects.kde.org/projects/kde/kdegraphics/ksnapshot/repository

https://projects.kde.org/projects/extragear/graphics/kphotoalbum/repository/revisions/master/show/Plugins

IMPORTANT : Using KDEXML-GUI architecture, all kipi-plugins will provide default XML files to plug tool action in menu and toolbar. These XML content must be adapted to digiKam Album GUI menu structure. But as all others KIPI host application use a different menu structure than digiKam, a way must be found to be able to customize XML content by KIPI host application.

5/ Plan


Your plan must be to patch libkipi, kipi-plugins and digiKam in first, and proposal patches for Gwenview and KSnapshot to work. These last one must be done before KPhotoAlbum as they are released through KDE plan, as libkipi. At end proposal for KPhotoAlbum can be proposed. It will be recommended to contact Gwenview, KSnapshoot, and KPhotoAlbum team at the right time when libkipi/kipi-plugins/digiKam will be ready.

You must include in your patch a way to customize XML content accordingly with KIPI host application. See point 4/ for details.

Creation Date 7-March-2012
Status Proposal
Maintainers Gilles Caulier - Development Supreet Pal Singh - Development

Project Timeline

TODO

Milestone name Milestone description Assigned to Status
Supreet Pal Singh In Progress

Completed

Milestone name Milestone description Assigned to Status


Note

Please use the talk page to discuss this proposal.