Convenience methods to access all standard KDE actions.
These actions should be used instead of hardcoding menubar and
toolbar items. Using these actions helps your application easily
conform to the KDE UI Style Guide
See also http://developer.kde.org/documentation/standards/kde/style/basics/index.html .
All of the documentation for KAction holds for KStandardAction
also. When in doubt on how things work, check the KAction
documention first.
Please note that calling any of these methods automatically adds the action
to the actionCollection() of the QObject given by the 'parent' parameter.
Simple Example:\n
In general, using standard actions should be a drop in replacement
for regular actions. For example, if you previously had:
KAction *newAct = new KAction(i18n("&New"), KIcon("document-new"),
KStandardShortcut.shortcut(KStandardShortcut.New), this,
SLOT(fileNew()), actionCollection());
You could drop that and replace it with:
KAction *newAct = KStandardAction.openNew(this, SLOT(fileNew()),
actionCollection());
Non-standard Usages\n
It is possible to use the standard actions in various
non-recommended ways. Say, for instance, you wanted to have a
standard action (with the associated correct text and icon and
accelerator, etc) but you didn't want it to go in the standard
place (this is not recommended, by the way). One way to do this is
to simply not use the XML UI framework and plug it into wherever
you want. If you do want to use the XML UI framework (good!), then
it is still possible.
Basically, the XML building code matches names in the XML code with
the internal names of the actions. You can find out the internal
names of each of the standard actions by using the stdName
action like so: KStandardAction.stdName(KStandardAction.Cut) would return
'edit_cut'. The XML building code will match 'edit_cut' to the
attribute in the global XML file and place your action there.
However, you can change the internal name. In this example, just
do something like:
(void)KStandardAction.cut(this, SLOT(editCut()), actionCollection(), "my_cut");
Now, in your local XML resource file (e.g., yourappui.rc), simply
put 'my_cut' where you want it to go.
Another non-standard usage concerns getting a pointer to an
existing action if, say, you want to enable or disable the action.
You could do it the recommended way and just grab a pointer when
you instantiate it as in the the 'openNew' example above... or you
could do it the hard way:
KAction *cut = actionCollection()->action(KStandardAction.stdName(KStandardAction.Cut));
Another non-standard usage concerns instantiating the action in the
first place. Usually, you would use the member functions as
shown above (e.g., KStandardAction.cut(this, SLOT, parent)). You
may, however, do this using the enums provided. This author can't
think of a reason why you would want to, but, hey, if you do,
here's how:
(void)KStandardAction.action(KStandardAction.New, this, SLOT(fileNew()), actionCollection());
(void)KStandardAction.action(KStandardAction.Cut, this, SLOT(editCut()), actionCollection());
Author Kurt Granroth
|