proposed KAction/KActionCollection API changes

[Simon Hausmann]

Hi,

as you may have noticed Kevin and I have been doing some mysterious commits to 
branches/work/kaction-cleanup-branch. We would like to propose a change in 
the API that affects a lot of code. Let me first briefly outline the existing 
KDE 2/3 style API:

KAction and its subclasses are created using single constructor calls that 
combine multiple method calls into one:

KAction *a = new KAction(i18n("&Reload"), "reload", CTRL + Key_F5, this, 
SLOT(reload()), actionCollection(), "view_reload");

This sets the action's text, icon and shortcut, connects the triggered 
(activated) slot, makes the action a child of the passed actionCollection and 
registers it as "view_reload" at the same time.

KAction and KActionCollection are tightly coupled. KActionCollection does not 
support putting QAction objects into it, which however can be a useful thing 
as Qt provides action objects sometimes, for example for dockwidgets or the 
undo-redo stack. One may want to provide KActionCollection's features such as 
the saving/loading of configurable shortcuts for these actions, too.

To developers KActionCollection acts as associative container that maps from a 
name to the action itself. Very often actions are extracted from 
KActionCollection with the name that was passed to the KAction constructor.

In KDE 4 KAction inherits from QAction (finally) and as part of the work in 
the recent weeks we've been able to get rid of quite a bit of cruft in 
KAction to bring the two closer together.

Unfortunately KAction's constructors are right now incompatible with QAction. 
KAction is not a drop-in replacement, it is different because one has to pass 
the name to the constructor along with a KActionCollection as parent. QAction 
on the other hand has only three constructors.

We would like to propose the following changes:

1) KAction and its subclasses get the same 3 (compatible) constructors as 
QAction.

2) Actions need to be explicitly added to the actioncollection. The name used 
for extraction from the actioncollection (and with xmlgui) is specified when 
adding the action to the collection, for symmetry. We would like to use 
KActionCollection::addAction(const QString &name, QAction *action) for that.

3) KActionCollection supports QActions and also provides configurable 
shortcuts for them, through the use of dynamic properties.

[ 4) Get rid of the ugly setObjectName() hiding in KAction ]

The result for application code is that it becomes a lot more verbose:

KAction *a = new KAction(i18n("&Reload"), "reload", CTRL + Key_F5, this, 
SLOT(reload()), actionCollection(), "view_reload");

becomes

KAction *a = new KAction(KIcon("reload"), i18n("&Reload"), this);
a->setShortcut(Qt::ControlModifier + Qt::Key_F5);
connect(a, SIGNAL(triggered()), this, SLOT(reload());
actionCollection()->addAction("view_reload", a);

Or alternatively:

KAction *a = actionCollection()->addAction("view_reload");
a->setShortcut(Qt::ControlModifier + Qt::Key_F5);
connect(a, SIGNAL(triggered()), this, SLOT(reload());


What do people think about this?


Simon
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20070102/85540535/attachment.sig>