class KAction


Module kdeui
Namespace
Class KAction
Inherits QWidgetAction
Class to encapsulate user-driven action or event

The KAction class (and derived and super classes) extends QAction, which provides a way to easily encapsulate a "real" user-selected action or event in your program.

For instance, a user may want to paste the contents of the clipboard, 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, and conforms to KDE's extended functionality requirements - including supporting multiple user-configurable shortcuts, and KDE named icons. Actions also improve accessibility.

Specifically, QAction (and thus KAction) encapsulates the various attributes of an event/action. For instance, an action might have an icon() that provides a visual representation (a clipboard for a "paste" action or scissors for a "cut" action). The action should also be described by some text(). It will certainly be connected to a method that actually executes the action! All these attributes are contained within the action 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 add the action to whatever GUI element you want. The KAction class will then take care of correctly defining the menu item (with icons, accelerators, text, etc), toolbar button, or other. From then on, if you manipulate the action at all, the effect will propagate through all GUI representations of it. Back to the "cut" example: if you want to disable the Cut Action, you would simply call 'cutAction->setEnabled(false)' and both 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 hovered() signal on mouseover, and the triggered(bool checked) signal on activation of a corresponding GUI element ( menu item, toolbar button, etc. )

If you are in the situation of wanting to map the triggered() signal of multiple action objects to one slot, with a special argument bound to each action, you have several options:

Using QActionGroup:

  • Create a QActionGroup and assign it to each of the actions with setActionGroup(), then
  • Connect the QActionGroup.triggered(QAction*) signal to your slot.
  • Using QSignalMapper:

    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( triggered(bool) ), desktopNumberMapper, SLOT( map() ) ); desktopNumberMapper->setMapping( desktopAction, i ); }

    General Usage

    The steps to using actions are roughly as follows:

  • Decide which attributes you want to associate with a given
  • action (icons, text, keyboard shortcut, etc)
  • Create the action using KAction (or derived or super class).
  • Add the action into whatever GUI element you want. Typically,
  • this will be a menu or toolbar.

    The kinds of shortcuts

    Local shortcuts are active in their context, global shortcus are active everywhere, usually even if another program has focus.

  • Active shortcuts trigger a KAction if activated.
  • Default shortcuts are what the active shortcuts revert to if the user chooses
  • to reset shortcuts to default.

    Detailed Example

    Here is an example of enabling a "New [document]" action

    KAction *newAct = actionCollection()->addAction(
    KStandardAction.New, //< see KStandardAction
    this, //< Receiver
    SLOT(fileNew()) ); //< SLOT
    

    This section creates our action. Text, Icon and Shortcut will be set from KStandardAction. KStandardAction ensures your application complies to the platform standards. When triggered the fileNew() slot will be called.

    See also KStandardAction for more information.

    If you want to create your own non standard action use

    KAction *newAct = actionCollection()->addAction("quick-connect");
    newAct->setText(i18n("Quick Connect"))
    newAct->setIcon(KIcon("quick-connect"));
    newAct->setShortcut(Qt.Key_F6);
    connect(newAct, SIGNAL(triggered()), this, SLOT(quickConnect()));
    

    This section creates our action. It will display the text "Quick Connect" and use the Icon "quick-connect". F6 will trigger the action. It further says that whenever this action is invoked, it will use the quickConnect() slot to execute it.

    QMenu *file = new QMenu;
    file->addAction(newAct);
    
    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.

    toolBar()->addAction(newAct);
    
    And this added 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.

    Unlike with previous versions of KDE, the action can simply be deleted when you have finished with it - the destructor takes care of all of the cleanup.

    calling QAction.setShortcut() on a KAction may lead to unexpected behavior. There is nothing we can do about it because QAction.setShortcut() is not virtual.

    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 KStandardAction class rather than defining your own.

    Usage Within the XML Framework

    If you are using KAction within the context of the XML menu and toolbar building framework, you do not ever have to add your actions to containers manually. The framework does that for you.

    See also KStandardAction



    enums

    enum details

    methods