Consideration requested for merging of kdelibs-action branch

[Hamish Rodda]

Hi all,

I've been having increasing interest from various people as to the state of my 
port of KAction to be a subclass of QAction.  Recently I've been motivated to 
make it merge ready, and I think the time has come.

Making KAction a subclass of QAction brings KDE more into line with the Qt way 
of creating user interfaces, and (for the most part) removes code 
duplication.  It also removes the compatibility layer existing previously 
(for many uses of the old KAction, there was at least one QAction object 
hidden behind the scenes)

QAction in Qt4 is a true 1st class citizen - all QWidgets now have a list of 
associated actions, and QToolBar, QMenu etc. all use this list directly to 
show the graphical items (widgets, entries in the menu, etc).  This has 
replaced all usage of integers as "id"s.  There is also a new
QEvent (QActionEvent), and the corresponding virtual protected function in 
QWidget, actionEvent().

This branch also ports KMainWindow over to QMainWindow, and KToolBar to 
QToolBar.  As a consequence of the change to QAction, KAccel is no longer 
used for capturing shortcut presses (although I haven't removed the unused 
parts yet, that's for later) - that is all within Qt now (QShortcutMap, a 
private class).  K3MDI was deleted because it would take much work to port 
over to the new QMainWindow, and there is a replacement being worked on by 
Adam Treat.

This branch does not alter XMLGui in any way other than direct porting.  I've 
had several people express their concern re. moving to another system, and 
I'd like to keep that as a separate discussion.

I've succeeded in porting konqueror and kate over to the branch.  The 
konqueror port took about an hour;  I find most of the difficult parts are in 
adapting to QMainWindow, not the KAction changes, unless the app has its own 
custom actions.  Konqueror runs, with a few minor regressions, and one crash 
bug which I will fix tomorrow (KWidgetActions don't work with the new 
ownership model for widgets placed in toolbars, so when they are re-plugged, 
the widget gets deleted).

If this branch (which is a 16k+ line diff, btw) gets the go ahead, I expect it 
will not be an entirely smooth transition, but hopefully things will settle 
quickly.

To test the branch, you'll need a qt-copy with patches 0113, 0115, 0116, and 
0119 (the last in patches/notsafe) applied.  Checkout 
branches/work/kdelibs-action + build with unsermake.  Then with a checkout of 
kdebase, svn switch both libkonq and konqueror over to the respective subdirs 
of branches/work/kdebase-action/.  You'll have to remove DONTPORT from 
include/kdeversion.h to bypass the configure check.  Compile + enjoy.

Patch 0119 deserves special mention because it provides the mechanism by which 
custom widgets are inserted into a toolbar.  Although Simon Hausmann + I have 
discussed the principle behind it, I haven't heard whether it's a likely 
candidate for Qt 4.2.  Without it, this branch would be severely crippled; 
however, I don't anticipate that there will be substantial issues having it 
applied for 4.2.


Porting specifics by class
==========================

KAction
* Now a subclass of QAction.
* New constructors more closely model QAction (old constructors deprecated)
* You should never rename the objectName() of a KAction - as KActionCollection 
holds a map, and it is not told of name changes (thus the setObjectName() 
functions are made private)
* "icon" property is now a QIcon, use iconName() / setIconName() for KDE named 
icons
* KShortcuts supported by shortcut/setShortcut (hides QAction's 
shortcut/setShortcut). Automatically sets alternateShortcuts() in QAction.
* plug(), unplug() deprecated - use QWidget::addAction() and 
QWidget::removeAction() instead
  * To provide custom widgets for toolbars, provide a QActionWidgetFactory to 
setToolBarWidgetFactory() (i use multiple inheritance on that action)
* containerCount(), container() deprecated - use associatedWidgets() instead
* activated(), activated(int) signals deprecated - use triggered() signal 
instead
* activate() is now trigger(), as in QAction
* there is a replacement for activation providing keyboard + mouse states, see 
triggered(Qt::MouseButtons buttons, Qt::KeyboardModifiers modifiers)
* plugAccel(), unplugAccel(), kaccelCount() removed - they have no use now 
(accelerator management is inside Qt)
* itemId(), getToolButtonID() removed - actions no longer have ids, basically 
the QAction* is its replacement
* setGroup() / group() removed
  * use QActionGroup in stead (setActionGroup() / actionGroup())
* ActivationReason has been removed
  * not supported by Qt
  * for a surrogate, you can connect to QMenu::triggered(QAction*), 
QToolBar::actionTriggered(QAction*), etc.
* setters are no longer slots; where they were used as such, an intermediary 
will be required

KActionCollection
* constructor (QWidget* watch, ..) and setWidget() replaced by {set|add|
remove}AssociatedWidget() - allows actions to respond to matching key presses 
on a widget level (basically a convenience method to have all actions in the 
collection added to the associated widget(s) and their shortcut scopes set to 
Qt::WidgetShortcut).
* *AutoConnectShortcuts removed - irrelevant
* *accel() removed - irrelevant (KAccel no longer handles keypresses)
* New functions setConfigGroup(), setConfigGlobal(), configGroup(), 
configIsGlobal() - the action collection now stores the group whether the 
config is global. referenced in readSettings() / writeSettings()
* readShortcutSettings() and writeShortcutSettings() renamed without the 
"Shortcut" (no particular reason - could revert)
* {set}HighlightingEnabled(), {connect|disconnect}Highlight() removed - 
highlighting is always enabled now
  * actionHighlighted(), actionStatusText(), clearStatusText() removed - use 
QAction::hovered() as replacement
* groups() removed (now using QActionGroups) - see actionGroups() (and 
actionsWithoutGroup()) for replacement
* actions( const QString& group ) removed - use actionGroups() instead, and 
then QActionGroup::actions()

KToggleAction
* setExclusiveGroup() / exclusiveGroup() removed, use setActionGroup() and 
QActionGroup::setExclusive() for exclusivity (imitates the deleted 
KRadioAction class)
* in comparison with KAction, only adds setCheckedState(), so if you don't 
need that, just use KAction

KSelectAction
* now allows for combo box or button with popup menu when inserted to a 
toolbar
* popupMenu() removed, use menu() instead
* {set|}removeAmpersandsInCombo() removed - was deprecated

KRecentFilesAction
* clearURLList() removed, use clear() instead
* *URL* -> *Url* as per KDE naming policy

KWidgetAction
* deprecated, instead assign a QActionWidgetFactory to a {K|Q}Action so the 
action can be plugged into mutiple toolbars.

KToolBar
* Ported to QToolBar
* IconText, iconText(), setIconText() replaced by QToolBar::toolButtonStyle() 
et. al.
* BarPosition, barPos(), setBarPos() replaced by Qt::ToolBarArea settings in 
QMainWindow
  * Unmanaged, Floating, and Flat are no longer supported (use QDockWidget if 
you need floating toolbars)
* fullSize(), setFullSize() removed as not supported by Qt - best estimation 
is to add a QAction with a widget requesting maximum available width, and to 
insert a tool bar break after the toolbar using 
QMainWindow::insertToolBarBreak()
* iconSize(), setIconSize() now a QToolBar property, and a QSize instead of an 
int - convenience function setIconDimensions() takes an int instead
* insert*() and all associated item-manipulation methods removed - all done 
through actions now. Compatibility layer possible however so far I haven't 
found the functions to be used much in KDE programs (mostly it's taken care 
of by xmlgui instead)
* setFlat() only partially working - you can't remove a toolbar's handle, but 
you can make it unmovable
* layout-related methods removed (done by QToolBar's layout)

KMainWindow
* Ported to QMainWindow
* accel() removed - KAccel no longer needed


Deleted classes:
* KToolBarButton - all done by QToolButton now
* KToolBarRadioGroup - all done by QToolButton now
* KRadioAction - use KAction (or KToggleAction if you need different 
text/icons for the selected state) instead, in combination with an exclusive 
QActionGroup
* KListAction - as per comments, did not add anything to KSelectAction
* KToolBarSeparator - use QAction::setSeparator()

KMDI
* Removed from compile - significant effort would be required to port it to 
QMainWindow.

Remaining issues (in my opinion, can all be fixed after merging of the 
branch):

* Should we be emitting QAction::changed() when our K*Action properties 
change? [probably yes therefore @todo]

* KSelectAction / isEditable() doesn't fit in well with the action-based 
principle (rethink probably needed, perhaps a separate action subclass 
required)

* Review which constructors are supplied for KAction.  The new constructors 
impersonate QAction - appropriate?

* Fix the issue with icon loading:

"The icon name we should be able to solve nicely through QIconEngine. Instead
of passing the QString iconName around we can pass around a QIcon that was
constructed with an internal KIconEngine. Then we call addFile on it so that
the icon engine can remember it. That's it, from then on we can pass the
QIcon around and whenever someone needs the actual pixmap he can request it
through QIcon or (more likely) call QIcon's paint method directly. That way
we can also implement svg icons."

There are some icon group and size hacks at the moment which I'd like to 
remove.

* KShortcutDialog is pretty tightly bound to KAccel, needs porting over
to Qt keycodes / classes.

* Removal of unused parts of KAccel et. al.

* Cleanup of KMainWindow and KToolBar, once the necessary info is exported by 
QMainWindow
  * create patch for exporting toolbar position, toolbarbreaks, etc.

* Fix remaining "FIXME KAction" comments / issues

* Kiosk settings not yet honoured.  Best way will probably be to look the 
setting up in the KAction constructor, and disable + hide + block signals 
from actions which are not authorized.

Qt Issues:
1) QToolButton does not reverse it's down state when clicking from one button 
to another

2) Disabled checkbox actions can be checked/unchecked!!

3) Actions whose plugged widgets are hidden have their shortcuts disabled :(


And with that, I'm looking forward to your comments/questions etc...

Cheers,
Hamish.
-------------- 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/20060313/38a229f6/attachment.sig>