Digikam/GSoC2012/KipiPluginInterfaceToolbarAccess: Difference between revisions

From KDE Community Wiki
(Created page with "== 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 exi...")
 
(→‎More Details & Steps: added note about projects.kde.org > quickgit)
 
(3 intermediate revisions by one other user not shown)
Line 14: Line 14:
plugin interface. This last one uses KDE XML GUI API. libkipi,NO.
plugin interface. This last one uses KDE XML GUI API. libkipi,NO.


Typically, image editor plug tools in GUI use KDE XML features,
Typically, image editor plug tools in GUI use [http://en.wikipedia.org/wiki/XMLGUI KDE XML features],
which is very flexible and automatize very well plugins mechanism and
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
plugin host interface but Kipi plugin interface plug tool uses a hardcoded way, which is not
Line 21: Line 21:


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.  
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
To be more powerful, KIPI interface must be re-implemented using [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKXMLGUIClient.html XML GUI API for client application].
GUI API.


= More Details & Steps =
= More Details & Steps =
{{Note | 1=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
1/ Libkipi shared library
Line 73: Line 74:
https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/show/utilities/kipiiface
https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/show/utilities/kipiiface


all is there, EXCEPTED... the famous plugin loader, which need to be
all is there, including the famous plugin loader. This last one must be
implmented into the class which host action collections. This must be
patched in your project to group this loader with other kipi classes.
patched in your project to group this loader with other kipi classes.
Typically a new plugin loader class must be created from libkipi
Typically a new plugin loader class must be created from libkipi
parent class and must support KDE XML GUI architecture.
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 :
The plugin loader implementation is here :
Line 83: Line 84:
plugins loaded at startup :
plugins loaded at startup :


https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/entry/digikam/main/digikamapp.cpp#L288
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#L2541
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/digikam/main/digikamapp.cpp#L2582
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,
...look the puzzle to plug actions at the right place in menu,
Line 92: Line 93:
The simple way to pass plugin actions to KDE shortcuts edit dialog...
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#L2424
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
The puzzle to pass plugin action to KDE toolbar edit dialog (which
don't work of course)
don't work of course)


https://projects.kde.org/projects/extragear/graphics/digikam/repository/revisions/master/entry/digikam/main/digikamapp.cpp#L2438
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
To enable kipi plugin action in menu, it's another big puzzle. We get
Line 107: Line 108:


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


As in libkipi, there are 2 classes :
As in libkipi, there are 2 classes :
Line 180: Line 181:


https://projects.kde.org/projects/extragear/graphics/kphotoalbum/repository/revisions/master/show/Plugins
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
5/ Plan
Line 186: Line 189:
Your plan must be to patch libkipi, kipi-plugins and digiKam in first,
Your plan must be to patch libkipi, kipi-plugins and digiKam in first,
and proposal patches for Gwenview and KSnapshot to work. These last
and proposal patches for Gwenview and KSnapshot to work. These last
one must be doen before KPhotoAlbum as they are released through KDE
one must be done before KPhotoAlbum as they are released through KDE
plan, as libkipi. At end proposal for KPhotoAlbum can be proposed. It
plan, as libkipi. At end proposal for KPhotoAlbum can be proposed. It
will be recommended to contact Gwenview, KSnapshoot, and KPhotoAlbum
will be recommended to contact Gwenview, KSnapshoot, and KPhotoAlbum
Line 192: Line 195:
ready.
ready.


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


{|
{|

Latest revision as of 05:51, 18 May 2016

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.