org.kde.koala
public class KAction extends QObject
paste
the contents of
the clipboard or scroll
down
a document or quit
the
application. These are all actions
-- events that the
user causes to happen. The KAction class allows the developer to
deal with these actions in an easy and intuitive manner.
Specifically, the KAction class encapsulated the various attributes
to an event/action. For instance, an action might have an icon
that goes along with it (a clipboard for a "paste" action or
scissors for a "cut" action). The action might have some text to
describe the action. It will certainly have a method or function
that actually executes
the action! All these attributes
are contained within the KAction object.
The advantage of dealing with Actions is that you can manipulate
the Action without regard to the GUI representation of it. For
instance, in the "normal" way of dealing with actions like "cut",
you would manually insert a item for Cut into a menu and a button
into a toolbar. If you want to disable the cut action for a moment
(maybe nothing is selected), you would have to hunt down the pointer
to the menu item and the toolbar button and disable both
individually. Setting the menu item and toolbar item up uses very
similar code - but has to be done twice!
With the Action concept, you simply "plug" the Action into whatever
GUI element you want. The KAction class will then take care of
correctly defining the menu item (with icons, accelerators, text,
etc) or toolbar button.. or whatever. From then on, if you
manipulate the Action at all, the effect will propogate through all
GUI representations of it. Back to the "cut" example: if you want
to disable the Cut Action, you would simply do
'cutAction.setEnabled(false)' and the menuitem and button would
instantly be disabled!
This is the biggest advantage to the Action concept -- there is a
one-to-one relationship between the "real" action and all
GUI representations of it.
KAction emits the activated() signal if the user activated the
corresponding GUI element ( menu item, toolbar button, etc. )
If you are in the situation of wanting to map the activated()
signal of multiple action objects to one slot, with a special
argument bound to each action, then you might consider using
QSignalMapper . A tiny example:
QSignalMapper desktopNumberMapper = new QSignalMapper( this ); connect( desktopNumberMapper, SIGNAL("mapped( int )"), this, SLOT("moveWindowToDesktop( int )") ); for ( uint i = 0; i < numberOfDesktops; ++i ) { KAction desktopAction = new KAction( i18n( "Move Window to Desktop %i" ).arg( i ), ... ); connect( desktopAction, SIGNAL("activated()"), desktopNumberMapper, SLOT("map()") ); desktopNumberMapper.setMapping( desktopAction, i ); }
KAction newAct = new KAction(i18n("&New"), "filenew", KStdAccel.shortcut(KStdAccel.New), this, SLOT("fileNew()"), actionCollection(), "new");This line creates our action. It says that wherever this action is displayed, it will use "&New" as the text, the standard icon, and the standard shortcut. It further says that whenever this action is invoked, it will use the fileNew() slot to execute it.
QPopupMenu file = new QPopupMenu; newAct.plug(file);That just inserted the action into the File menu. The point is, it's not important in which menu it is: all manipulation of the item is done through the newAct object.
newAct.plug(toolBar());And this inserted the Action into the main toolbar as a button. That's it! If you want to disable that action sometime later, you can do so with
newAct.setEnabled(false)and both the menuitem in File and the toolbar button will instantly be disabled. Do not delete a KAction object without unplugging it from all its containers. The simplest way to do that is to use the unplugAll() as in the following example:
newAct.unplugAll(); delete newAct;Normally you will not need to do this as KActionCollection manages everything for you. Note: if you are using a "standard" action like "new", "paste", "quit", or any other action described in the KDE UI Standards, please use the methods in the KStdAction class rather than defining your own.
See Also: KStdAction
UNKNOWN: Class to encapsulate user-driven action or event.
Field Summary | |
---|---|
static int | AccelActivation |
static int | EmulatedActivation |
static int | PopupMenuActivation |
static int | ToolBarActivation |
static int | UnknownActivation |
Constructor Summary | |
---|---|
protected | KAction(Class dummy) |
KAction(String text, KShortcut cut, QObject receiver, String slot, KActionCollection parent, String name)
Constructs an action with text, potential keyboard
shortcut, and a SLOT to call when this action is invoked by
the user.
| |
KAction(String text, QIconSet pix, KShortcut cut, QObject receiver, String slot, KActionCollection parent, String name)
Constructs an action with text, icon, potential keyboard
shortcut, and a SLOT to call when this action is invoked by
the user.
| |
KAction(String text, String pix, KShortcut cut, QObject receiver, String slot, KActionCollection parent, String name)
Constructs an action with text, icon, potential keyboard
shortcut, and a SLOT to call when this action is invoked by
the user. | |
KAction(KGuiItem item, KShortcut cut, QObject receiver, String slot, KActionCollection parent, String name)
The same as the above constructor, but with a KGuiItem providing
the text and icon. |
Method Summary | |
---|---|
void | activate()
Emulate user's interaction programmatically, by activating the action.
|
protected void | addContainer(QWidget parent, int id) |
protected void | addContainer(QWidget parent, QWidget representative) |
String | className() |
QWidget | container(int index) |
int | containerCount() |
void | dispose() Delete the wrapped C++ instance ahead of finalize() |
protected void | finalize() Deletes the wrapped C++ instance |
protected int | findContainer(QWidget widget) |
protected int | findContainer(int id) |
static int | getToolButtonID()
Generate a toolbar button id. |
String | group() |
protected KGuiItem | guiItem()
Return the underlying KGuiItem |
boolean | hasIcon() |
boolean | hasIconSet() |
String | icon() |
QIconSet | iconSet(int group, int size)
Get the QIconSet from which the icons used to display this action will
be chosen.
|
QIconSet | iconSet(int group) |
QIconSet | iconSet()
Remove in KDE4 |
boolean | isDisposed() Has the wrapped C++ instance been deleted? |
boolean | isEnabled()
Returns true if this action is enabled. |
boolean | isPlugged()
returns whether the action is plugged into any container widget or not. |
boolean | isPlugged(QWidget container)
returns whether the action is plugged into the given container |
boolean | isPlugged(QWidget container, int id)
returns whether the action is plugged into the given container with the given, container specific, id (often
menu or toolbar id ) . |
boolean | isPlugged(QWidget container, QWidget _representative)
returns whether the action is plugged into the given container with the given, container specific, representative
container widget item. |
boolean | isShortcutConfigurable()
Returns true if this action's shortcut is configurable. |
int | itemId(int index) |
int | kaccelCount() |
QMetaObject | metaObject() |
KActionCollection | parentCollection() |
String | plainText() |
int | plug(QWidget widget, int index)
"Plug" or insert this action into a given widget.
|
int | plug(QWidget widget) |
protected void | plugMainWindowAccel(QWidget w) |
protected QPopupMenu | popupMenu(int index) |
protected void | removeContainer(int index) |
QWidget | representative(int index) |
void | setDisabled(boolean disable)
Calls setEnabled( ! |
void | setEnabled(boolean enable)
Enables or disables this action. |
void | setGroup(String arg1) |
void | setIcon(String icon) |
void | setIconSet(QIconSet iconSet)
Sets the QIconSet from which the icons used to display this action will
be chosen. |
boolean | setShortcut(KShortcut arg1)
Sets the keyboard shortcut associated with this action. |
void | setShortcutConfigurable(boolean arg1)
Indicate whether the user may configure the action's shortcut. |
void | setShortcutText(String arg1) |
void | setText(String text)
Sets the text associated with this action. |
void | setToolTip(String arg1)
Sets the tooltip text for the action.
|
void | setWhatsThis(String text)
Sets the What's this text for the action. |
KShortcut | shortcut()
Get the keyboard shortcut associated with this action. |
KShortcut | shortcutDefault()
Get the default shortcut for this action. |
String | shortcutText() |
protected void | slotActivated() |
protected void | slotButtonClicked(int arg1, int state) |
protected void | slotDestroyed() |
protected void | slotKeycodeChanged() |
protected void | slotPopupActivated() |
String | statusText() |
String | text()
Get the text associated with this action. |
protected KToolBar | toolBar(int index) |
String | toolTip()
Get the tooltip text for the action. |
void | unplug(QWidget w)
"Unplug" or remove this action from a given widget.
|
void | unplugAll() |
protected void | updateEnabled(int i) |
protected void | updateGroup(int id) |
protected void | updateIcon(int i) |
protected void | updateIconSet(int i) |
protected void | updateShortcut(int i) |
protected void | updateShortcut(QPopupMenu menu, int id) |
protected void | updateText(int i) |
protected void | updateToolTip(int id) |
protected void | updateWhatsThis(int i) |
String | whatsThis()
Get the What's this text for the action. |
protected String | whatsThisWithIcon() |
UNKNOWN:
cut
param to 0.
This is the most common KAction used when you do not have a
corresponding icon (note that it won't appear in the current version
of the "Edit ToolBar" dialog, because an action needs an icon to be
plugged in a toolbar...).Parameters: text The text that will be displayed. cut The corresponding keyboard shortcut. receiver The SLOT's parent. slot The SLOT to invoke to execute this action. parent This action's parent. name An internal name for this action.
UNKNOWN: Constructs an action with text, potential keyboard shortcut, and a SLOT to call when this action is invoked by the user.
cut
param to 0.
This is the other common KAction used. Use it when you
do
have a corresponding icon.Parameters: text The text that will be displayed. pix The icon to display. cut The corresponding keyboard shortcut. receiver The SLOT's parent. slot The SLOT to invoke to execute this action. parent This action's parent. name An internal name for this action.
UNKNOWN: Constructs an action with text, icon, potential keyboard shortcut, and a SLOT to call when this action is invoked by the user.
cut
param to 0.
This is the other common KAction used. Use it when you
do
have a corresponding icon.Parameters: text The text that will be displayed. pix The icon to display. cut The corresponding keyboard shortcut (shortcut). receiver The SLOT's parent. slot The SLOT to invoke to execute this action. parent This action's parent. name An internal name for this action.
UNKNOWN: Constructs an action with text, icon, potential keyboard shortcut, and a SLOT to call when this action is invoked by the user.
Parameters: item The KGuiItem with the label and (optional) icon. cut The corresponding keyboard shortcut (shortcut). receiver The SLOT's parent. slot The SLOT to invoke to execute this action. parent This action's parent. name An internal name for this action.
UNKNOWN: The same as the above constructor, but with a KGuiItem providing the text and icon.
UNKNOWN: Emulate user's interaction programmatically, by activating the action.
UNKNOWN:
UNKNOWN: Return the underlying KGuiItem
UNKNOWN: Get the QIconSet from which the icons used to display this action will be chosen.
UNKNOWN: Remove in KDE4
UNKNOWN: Returns true if this action is enabled.
UNKNOWN: returns whether the action is plugged into any container widget or not.
UNKNOWN: returns whether the action is plugged into the given container
UNKNOWN: returns whether the action is plugged into the given container with the given, container specific, id (often menu or toolbar id ) .
UNKNOWN: returns whether the action is plugged into the given container with the given, container specific, representative container widget item.
UNKNOWN: Returns true if this action's shortcut is configurable.
Parameters: widget The GUI element to display this action index The position into which the action is plugged. If this is negative, the action is inserted at the end.
UNKNOWN: "Plug" or insert this action into a given widget.
UNKNOWN: Calls setEnabled( !disable ).
UNKNOWN: Enables or disables this action.
UNKNOWN: Sets the QIconSet from which the icons used to display this action will be chosen.
UNKNOWN: Sets the keyboard shortcut associated with this action.
UNKNOWN: Indicate whether the user may configure the action's shortcut.
UNKNOWN: Sets the text associated with this action.
See Also: KActionCollection
UNKNOWN: Sets the tooltip text for the action.
UNKNOWN: Sets the What's this text for the action.
UNKNOWN: Get the keyboard shortcut associated with this action.
UNKNOWN: Get the default shortcut for this action.
UNKNOWN: Get the text associated with this action.
UNKNOWN: Get the tooltip text for the action.
Parameters: w Remove the action from this GUI element.
UNKNOWN: "Unplug" or remove this action from a given widget.
UNKNOWN: Get the What's this text for the action.