Consideration requested for merging of kdelibs-action branch
Hamish Rodda
rodda at kde.org
Sun Mar 12 15:37:07 GMT 2006
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>
More information about the kde-core-devel
mailing list