org.kde.koala

Class KAction

public class KAction extends QObject

The KAction class (and derived and super classes) 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 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 );
 }
 
  • 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).
  • "Plug" the Action into whatever GUI element you want. Typically, this will be a menu or toolbar.
  • Detailed Example:
  • Here is an example of enabling a "New [document]" action
     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.
  • Usage Within the XML Framework:
  • If you are using KAction within the context of the XML menu and toolbar building framework, then there are a few tiny changes. The first is that you must insert your new action into an action collection. The action collection (a KActionCollection) is, logically enough, a central collection of all of the actions defined in your application. The XML UI framework code in KXMLGUI classes needs access to this collection in order to build up the GUI (it's how the builder code knows which actions are valid and which aren't). Also, if you use the XML builder framework, then you do not ever have to plug your actions into containers manually. The framework does that for you. See KActionSignals for signals emitted by KAction

    See Also: KStdAction

    UNKNOWN: Class to encapsulate user-driven action or event.

    Field Summary
    static intAccelActivation
    static intEmulatedActivation
    static intPopupMenuActivation
    static intToolBarActivation
    static intUnknownActivation
    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
    voidactivate()
    Emulate user's interaction programmatically, by activating the action.
    protected voidaddContainer(QWidget parent, int id)
    protected voidaddContainer(QWidget parent, QWidget representative)
    StringclassName()
    QWidgetcontainer(int index)
    intcontainerCount()
    voiddispose()
    Delete the wrapped C++ instance ahead of finalize()
    protected voidfinalize()
    Deletes the wrapped C++ instance
    protected intfindContainer(QWidget widget)
    protected intfindContainer(int id)
    static intgetToolButtonID()
    Generate a toolbar button id.
    Stringgroup()
    protected KGuiItemguiItem()
    Return the underlying KGuiItem
    booleanhasIcon()
    booleanhasIconSet()
    Stringicon()
    QIconSeticonSet(int group, int size)
    Get the QIconSet from which the icons used to display this action will be chosen.
    QIconSeticonSet(int group)
    QIconSeticonSet()
    Remove in KDE4
    booleanisDisposed()
    Has the wrapped C++ instance been deleted?
    booleanisEnabled()
    Returns true if this action is enabled.
    booleanisPlugged()
    returns whether the action is plugged into any container widget or not.
    booleanisPlugged(QWidget container)
    returns whether the action is plugged into the given container
    booleanisPlugged(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 ) .
    booleanisPlugged(QWidget container, QWidget _representative)
    returns whether the action is plugged into the given container with the given, container specific, representative container widget item.
    booleanisShortcutConfigurable()
    Returns true if this action's shortcut is configurable.
    intitemId(int index)
    intkaccelCount()
    QMetaObjectmetaObject()
    KActionCollectionparentCollection()
    StringplainText()
    intplug(QWidget widget, int index)
    "Plug" or insert this action into a given widget.
    intplug(QWidget widget)
    protected voidplugMainWindowAccel(QWidget w)
    protected QPopupMenupopupMenu(int index)
    protected voidremoveContainer(int index)
    QWidgetrepresentative(int index)
    voidsetDisabled(boolean disable)
    Calls setEnabled( !
    voidsetEnabled(boolean enable)
    Enables or disables this action.
    voidsetGroup(String arg1)
    voidsetIcon(String icon)
    voidsetIconSet(QIconSet iconSet)
    Sets the QIconSet from which the icons used to display this action will be chosen.
    booleansetShortcut(KShortcut arg1)
    Sets the keyboard shortcut associated with this action.
    voidsetShortcutConfigurable(boolean arg1)
    Indicate whether the user may configure the action's shortcut.
    voidsetShortcutText(String arg1)
    voidsetText(String text)
    Sets the text associated with this action.
    voidsetToolTip(String arg1)
    Sets the tooltip text for the action.
    voidsetWhatsThis(String text)
    Sets the What's this text for the action.
    KShortcutshortcut()
    Get the keyboard shortcut associated with this action.
    KShortcutshortcutDefault()
    Get the default shortcut for this action.
    StringshortcutText()
    protected voidslotActivated()
    protected voidslotButtonClicked(int arg1, int state)
    protected voidslotDestroyed()
    protected voidslotKeycodeChanged()
    protected voidslotPopupActivated()
    StringstatusText()
    Stringtext()
    Get the text associated with this action.
    protected KToolBartoolBar(int index)
    StringtoolTip()
    Get the tooltip text for the action.
    voidunplug(QWidget w)
    "Unplug" or remove this action from a given widget.
    voidunplugAll()
    protected voidupdateEnabled(int i)
    protected voidupdateGroup(int id)
    protected voidupdateIcon(int i)
    protected voidupdateIconSet(int i)
    protected voidupdateShortcut(int i)
    protected voidupdateShortcut(QPopupMenu menu, int id)
    protected voidupdateText(int i)
    protected voidupdateToolTip(int id)
    protected voidupdateWhatsThis(int i)
    StringwhatsThis()
    Get the What's this text for the action.
    protected StringwhatsThisWithIcon()

    Field Detail

    AccelActivation

    public static final int AccelActivation

    EmulatedActivation

    public static final int EmulatedActivation

    PopupMenuActivation

    public static final int PopupMenuActivation

    ToolBarActivation

    public static final int ToolBarActivation

    UnknownActivation

    public static final int UnknownActivation

    UNKNOWN:

    Constructor Detail

    KAction

    protected KAction(Class dummy)

    KAction

    public 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. If you do not want or have a keyboard shortcut, set the 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.

    KAction

    public 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. If you do not want or have a keyboard shortcut, set the 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.

    KAction

    public 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. The icon is loaded on demand later based on where it is plugged in. If you do not want or have a keyboard shortcut, set the 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.

    KAction

    public 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.

    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.

    Method Detail

    activate

    public void activate()
    Emulate user's interaction programmatically, by activating the action. The implementation simply emits activated().

    UNKNOWN: Emulate user's interaction programmatically, by activating the action.

    addContainer

    protected void addContainer(QWidget parent, int id)

    addContainer

    protected void addContainer(QWidget parent, QWidget representative)

    className

    public String className()

    container

    public QWidget container(int index)

    containerCount

    public int containerCount()

    dispose

    public void dispose()
    Delete the wrapped C++ instance ahead of finalize()

    finalize

    protected void finalize()
    Deletes the wrapped C++ instance

    findContainer

    protected int findContainer(QWidget widget)

    findContainer

    protected int findContainer(int id)

    getToolButtonID

    public static int getToolButtonID()
    Generate a toolbar button id. Made public for reimplementations.

    UNKNOWN:

    group

    public String group()

    guiItem

    protected KGuiItem guiItem()
    Return the underlying KGuiItem

    UNKNOWN: Return the underlying KGuiItem

    hasIcon

    public boolean hasIcon()

    hasIconSet

    public boolean hasIconSet()

    icon

    public String icon()

    iconSet

    public QIconSet iconSet(int group, int size)
    Get the QIconSet from which the icons used to display this action will be chosen. In KDE4 set group default to KIcon.Small while removing the other iconSet() function.

    UNKNOWN: Get the QIconSet from which the icons used to display this action will be chosen.

    iconSet

    public QIconSet iconSet(int group)

    iconSet

    public QIconSet iconSet()
    Remove in KDE4

    UNKNOWN: Remove in KDE4

    isDisposed

    public boolean isDisposed()
    Has the wrapped C++ instance been deleted?

    isEnabled

    public boolean isEnabled()
    Returns true if this action is enabled.

    UNKNOWN: Returns true if this action is enabled.

    isPlugged

    public boolean isPlugged()
    returns whether the action is plugged into any container widget or not.

    UNKNOWN: returns whether the action is plugged into any container widget or not.

    isPlugged

    public boolean isPlugged(QWidget container)
    returns whether the action is plugged into the given container

    UNKNOWN: returns whether the action is plugged into the given container

    isPlugged

    public 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 ) .

    UNKNOWN: returns whether the action is plugged into the given container with the given, container specific, id (often menu or toolbar id ) .

    isPlugged

    public 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.

    UNKNOWN: returns whether the action is plugged into the given container with the given, container specific, representative container widget item.

    isShortcutConfigurable

    public boolean isShortcutConfigurable()
    Returns true if this action's shortcut is configurable.

    UNKNOWN: Returns true if this action's shortcut is configurable.

    itemId

    public int itemId(int index)

    kaccelCount

    public int kaccelCount()

    metaObject

    public QMetaObject metaObject()

    parentCollection

    public KActionCollection parentCollection()

    plainText

    public String plainText()

    plug

    public int plug(QWidget widget, int index)
    "Plug" or insert this action into a given widget. This will typically be a menu or a toolbar. From this point on, you will never need to directly manipulate the item in the menu or toolbar. You do all enabling/disabling/manipulation directly with your KAction object.

    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.

    plug

    public int plug(QWidget widget)

    plugMainWindowAccel

    protected void plugMainWindowAccel(QWidget w)

    popupMenu

    protected QPopupMenu popupMenu(int index)

    removeContainer

    protected void removeContainer(int index)

    representative

    public QWidget representative(int index)

    setDisabled

    public void setDisabled(boolean disable)
    Calls setEnabled( !disable ).

    UNKNOWN: Calls setEnabled( !disable ).

    setEnabled

    public void setEnabled(boolean enable)
    Enables or disables this action. All uses of this action (eg. in menus or toolbars) will be updated to reflect the state of the action.

    UNKNOWN: Enables or disables this action.

    setGroup

    public void setGroup(String arg1)

    setIcon

    public void setIcon(String icon)

    setIconSet

    public void setIconSet(QIconSet iconSet)
    Sets the QIconSet from which the icons used to display this action will be chosen.

    UNKNOWN: Sets the QIconSet from which the icons used to display this action will be chosen.

    setShortcut

    public boolean setShortcut(KShortcut arg1)
    Sets the keyboard shortcut associated with this action.

    UNKNOWN: Sets the keyboard shortcut associated with this action.

    setShortcutConfigurable

    public void setShortcutConfigurable(boolean arg1)
    Indicate whether the user may configure the action's shortcut.

    UNKNOWN: Indicate whether the user may configure the action's shortcut.

    setShortcutText

    public void setShortcutText(String arg1)

    setText

    public void setText(String text)
    Sets the text associated with this action. The text is used for menu and toolbar labels etc.

    UNKNOWN: Sets the text associated with this action.

    setToolTip

    public void setToolTip(String arg1)
    Sets the tooltip text for the action. This will be used as a tooltip for a toolbar button, as a statusbar help-text for a menu item, and it also appears in the toolbar editor, to describe the action. For the tooltip to show up on the statusbar you will need to connect a couple of the actionclass signals to the toolbar. The easiest way of doing this is in your main window class, when you create a statusbar. See the KActionCollection class for more details.

    See Also: KActionCollection

    UNKNOWN: Sets the tooltip text for the action.

    setWhatsThis

    public void setWhatsThis(String text)
    Sets the What's this text for the action. This text will be displayed when a widget that has been created by plugging this action into a container is clicked on in What's this mode. The What's this text can include QML markup as well as raw text.

    UNKNOWN: Sets the What's this text for the action.

    shortcut

    public KShortcut shortcut()
    Get the keyboard shortcut associated with this action.

    UNKNOWN: Get the keyboard shortcut associated with this action.

    shortcutDefault

    public KShortcut shortcutDefault()
    Get the default shortcut for this action.

    UNKNOWN: Get the default shortcut for this action.

    shortcutText

    public String shortcutText()

    slotActivated

    protected void slotActivated()

    slotButtonClicked

    protected void slotButtonClicked(int arg1, int state)

    slotDestroyed

    protected void slotDestroyed()

    slotKeycodeChanged

    protected void slotKeycodeChanged()

    slotPopupActivated

    protected void slotPopupActivated()

    statusText

    public String statusText()

    text

    public String text()
    Get the text associated with this action.

    UNKNOWN: Get the text associated with this action.

    toolBar

    protected KToolBar toolBar(int index)

    toolTip

    public String toolTip()
    Get the tooltip text for the action.

    UNKNOWN: Get the tooltip text for the action.

    unplug

    public void unplug(QWidget w)
    "Unplug" or remove this action from a given widget. This will typically be a menu or a toolbar. This is rarely used in "normal" application. Typically, it would be used if your application has several views or modes, each with a completely different menu structure. If you simply want to disable an action for a given period, use setEnabled() instead.

    Parameters: w Remove the action from this GUI element.

    UNKNOWN: "Unplug" or remove this action from a given widget.

    unplugAll

    public void unplugAll()

    updateEnabled

    protected void updateEnabled(int i)

    updateGroup

    protected void updateGroup(int id)

    updateIcon

    protected void updateIcon(int i)

    updateIconSet

    protected void updateIconSet(int i)

    updateShortcut

    protected void updateShortcut(int i)

    updateShortcut

    protected void updateShortcut(QPopupMenu menu, int id)

    updateText

    protected void updateText(int i)

    updateToolTip

    protected void updateToolTip(int id)

    updateWhatsThis

    protected void updateWhatsThis(int i)

    whatsThis

    public String whatsThis()
    Get the What's this text for the action.

    UNKNOWN: Get the What's this text for the action.

    whatsThisWithIcon

    protected String whatsThisWithIcon()