# kdeui Library API Documentation

Overview | Class Hierarchy | Classes | Classes (annotated) | Members | Namespaces | Source Files

# KActionCollection Class Reference

A managed set of KAction objects. More...

`#include <kactioncollection.h>`

Inheritance diagram for KActionCollection:

[legend]
Collaboration diagram for KActionCollection:

[legend]
List of all members.

## Public Slots

void | clear ()

## Signals

void | inserted (KAction *)
void | removed (KAction *)
void | actionHighlighted (KAction *action)
void | actionHighlighted (KAction *action, bool highlight)
void | actionStatusText (const QString &text)
void | clearStatusText ()

## Public Member Functions

| KActionCollection (QWidget *parent, const char *name=0, KInstance *instance=0)
| KActionCollection (QWidget *watch, QObject *parent, const char *name=0, KInstance *instance=0)
| KActionCollection (const KActionCollection &copy)
virtual void | setWidget (QWidget *widget)
void | setAutoConnectShortcuts (bool)
bool | isAutoConnectShortcuts ()
bool | addDocCollection (KActionCollection *pDoc)
virtual KAccel * | accel () KDE_DEPRECATED
virtual const KAccel * | accel () const KDE_DEPRECATED
KAccel * | kaccel ()
const KAccel * | kaccel () const
KAccel * | builderKAccel () const
virtual uint | count () const
bool | isEmpty () const
virtual KAction * | action (int index) const
virtual KAction * | action (const char *name, const char *classname=0) const
virtual QStringList | groups () const
virtual KActionPtrList | actions (const QString &group) const
virtual KActionPtrList | actions () const
bool | readShortcutSettings (const QString &sConfigGroup=QString::null, KConfigBase *pConfig=0)
bool | writeShortcutSettings (const QString &sConfigGroup=QString::null, KConfigBase *pConfig=0) const
void | setInstance (KInstance *instance)
KInstance * | instance () const
void | setXMLFile (const QString &)
const QString & | xmlFile () const
void | setHighlightingEnabled (bool enable)
bool | highlightingEnabled () const
void | connectHighlight (QWidget *container, KAction *action)
void | disconnectHighlight (QWidget *container, KAction *action)
const KXMLGUIClient * | parentGUIClient () const
| KActionCollection (QObject *parent, const char *name=0, KInstance *instance=0)
void | insert (KAction *action)
void | remove (KAction *action)
KAction * | take (KAction *action)
KActionCollection | operator+ (const KActionCollection &) const
KActionCollection & | operator= (const KActionCollection &)
KActionCollection & | operator+= (const KActionCollection &)

## Protected Member Functions

virtual void | virtual_hook (int id, void *data)

## Friends

class | KAction
class | KXMLGUIClient

## Detailed Description

A managed set of KAction objects.

If you set the tooltips on KActions and want the tooltip to show in statusbar (recommended) then you will need to connect a couple of the actionclass signals to the toolbar. The easiest way of doing this is in your KMainWindow subclass, where you create a statusbar, do:

     actionCollection()->setHighlightingEnabled(true);
     connect(actionCollection(), SIGNAL( actionStatusText( const QString & ) ),
               statusBar(), SLOT( message( const QString & ) ) );
     connect(actionCollection(), SIGNAL( clearStatusText() ),
               statusBar(), SLOT( clear() ) );

Definition at line 78 of file kactioncollection.h.

## Constructor & Destructor Documentation

KActionCollection::KActionCollection | ( | QWidget * | watch,
|  | QObject * | parent,
|  | const char * | name = `0`,
|  | KInstance * | instance = `0`
| ) |

| Use this constructor if you want the collection's actions to restrict their accelerator keys to `watch` rather than the `parent`. If you don't require shortcuts, you can pass a null to the `watch` parameter. Definition at line 92 of file kactioncollection.cpp. References endl(), instance(), kdDebug(), and setWidget().

## Member Function Documentation

void KActionCollection::setWidget | ( | QWidget * | widget | ) | `[virtual]`

| This sets the widget to which the keyboard shortcuts should be attached. You only need to call this if a null pointer was passed in the constructor. Definition at line 152 of file kactioncollection.cpp. References endl(), and kdWarning(). Referenced by KActionCollection().

void KActionCollection::setAutoConnectShortcuts | ( | bool |  | ) |

This indicates whether new actions which are created in this collection should have their keyboard shortcuts automatically connected on construction.

Set to 'false' if you will be loading XML-based settings. This is automatically done by KParts. The default is 'true'.

See also:
  isAutoConnectShortcuts()

Definition at line 167 of file kactioncollection.cpp.

bool KActionCollection::isAutoConnectShortcuts | ( |  | ) |

This indicates whether new actions which are created in this collection have their keyboard shortcuts automatically connected on construction.

See also:
  setAutoConnectShortcuts()

Definition at line 172 of file kactioncollection.cpp.

bool KActionCollection::addDocCollection | ( | KActionCollection * | pDoc | ) |

| Doc/View model. This lets you add the action collection of a document to a view's action collection. Definition at line 177 of file kactioncollection.cpp.

KAccel * KActionCollection::accel | ( |  | ) | `[virtual]`

Deprecated:
  Deprecated because of ambiguous name. Use kaccel()

Definition at line 369 of file kactioncollection.cpp.

References kaccel().

const KAccel * KActionCollection::accel | ( |  | ) | const`[virtual]`

Deprecated:
  Deprecated because of ambiguous name. Use kaccel()

Definition at line 370 of file kactioncollection.cpp.

References kaccel().

KAccel * KActionCollection::kaccel | ( |  | ) |

| Returns the KAccel object of the most recently set widget. Definition at line 282 of file kactioncollection.cpp. Referenced by accel().

const KAccel * KActionCollection::kaccel | ( |  | ) | const

| Returns the KAccel object of the most recently set widget. Const version for convenience. Definition at line 291 of file kactioncollection.cpp.

uint KActionCollection::count | ( |  | ) | const`[virtual]`

| Returns the number of actions in the collection. Definition at line 418 of file kactioncollection.cpp. Referenced by KAction::plug().

KAction * KActionCollection::action | ( | int | index | ) | const`[virtual]`

Return the KAction* at position "index" in the action collection.

See also:
  count()

Definition at line 400 of file kactioncollection.cpp.

Referenced by KXMLGUIClient::action(), connectHighlight(), disconnectHighlight(), insert(), remove(), KXMLGUIClient::stateChanged(), and take().

KAction * KActionCollection::action | ( | const char * | name,
|  | const char * | classname = `0`
| ) | const`[virtual]`

Find an action (optionally, of a given subclass of KAction) in the action collection.

Parameters:

  | name | Name of the KAction.
  | classname | Name of the KAction subclass.

Returns:
  A pointer to the first KAction in the collection which matches the parameters or null if nothing matches.

Definition at line 373 of file kactioncollection.cpp.

QStringList KActionCollection::groups | ( |  | ) | const`[virtual]`

Returns a list of all the groups of all the KActions in this action collection.

See also:
  KAction::group()

  KAction::setGroup()

Definition at line 423 of file kactioncollection.cpp.

KActionPtrList KActionCollection::actions | ( | const QString & | group | ) | const`[virtual]`

Returns the list of actions in a particular group managed by this action collection.

Parameters:

  | group | The name of the group.

Definition at line 435 of file kactioncollection.cpp.

KActionPtrList KActionCollection::actions | ( |  | ) | const`[virtual]`

| Returns the list of actions managed by this action collection. Definition at line 449 of file kactioncollection.cpp.

bool KActionCollection::readShortcutSettings | ( | const QString & | sConfigGroup = `QString::null`,
|  | KConfigBase * | pConfig = `0`
| ) |

| Used for reading shortcut configuration from a non-XML rc file. Definition at line 408 of file kactioncollection.cpp.

bool KActionCollection::writeShortcutSettings | ( | const QString & | sConfigGroup = `QString::null`,
|  | KConfigBase * | pConfig = `0`
| ) | const

| Used for writing shortcut configuration to a non-XML rc file. Definition at line 413 of file kactioncollection.cpp.

KInstance * KActionCollection::instance | ( |  | ) | const

| The instance with which this class is associated. Definition at line 468 of file kactioncollection.cpp. Referenced by KActionCollection(), KPasteTextAction::plug(), KToolBarPopupAction::plug(), KActionMenu::plug(), KRecentFilesAction::plug(), and KAction::plug().

void KActionCollection::setXMLFile | ( | const QString & |  | ) |

Deprecated:

Definition at line 473 of file kactioncollection.cpp.

Referenced by KXMLGUIClient::setXMLFile().

const QString & KActionCollection::xmlFile | ( |  | ) | const

Deprecated:

Definition at line 478 of file kactioncollection.cpp.

void KActionCollection::setHighlightingEnabled | ( | bool | enable | ) |

Enable highlighting notification for specific KActions.

This is false by default, so, by default, the highlighting signals will not be emitted.

See also:
  connectHighlight()

  disconnectHighlight()

  actionHighlighted()

  actionHighlighted()

  highlightingEnabled()

Definition at line 483 of file kactioncollection.cpp.

bool KActionCollection::highlightingEnabled | ( |  | ) | const

Return whether highlighting notifications are enabled.

See also:
  connectHighlight()

  disconnectHighlight()

  actionHighlighted()

  setHighlightingEnabled()

  actionHighlighted()

Definition at line 488 of file kactioncollection.cpp.

void KActionCollection::connectHighlight | ( | QWidget * | container,
|  | KAction * | action
| ) |

Call this function if you want to receive a signal whenever a KAction is highlighted in a menu or a toolbar.

This is only needed if you do not add this action to this container. You will generally not need to call this function.

Parameters:

  | container | A container in which the KAction is plugged (must inherit QPopupMenu or KToolBar)
  | action | The action you are interested in

See also:
  disconnectHighlight()

  actionHighlighted()

  setHighlightingEnabled()

  highlightingEnabled()

  actionHighlighted()

Definition at line 493 of file kactioncollection.cpp.

References action(), QPtrList::append(), QObject::connect(), QObject::destroyed(), and QPtrList::insert().

Referenced by KActionMenu::plug(), and KAction::plug().

void KActionCollection::disconnectHighlight | ( | QWidget * | container,
|  | KAction * | action
| ) |

Disconnect highlight notifications for a particular pair of contianer and action.

This is only needed if you do not add this action to this container. You will generally not need to call this function.

Parameters:

  | container | A container in which the KAction is plugged (must inherit QPopupMenu or KToolBar)
  | action | The action you are interested in

See also:
  connectHighlight()

  actionHighlighted()

  setHighlightingEnabled()

  highlightingEnabled()

  actionHighlighted()

Definition at line 526 of file kactioncollection.cpp.

References action(), QPtrList::isEmpty(), QPtrList::remove(), and QPtrList::removeRef().

Referenced by KAction::unplug().

const KXMLGUIClient * KActionCollection::parentGUIClient | ( |  | ) | const

| The parent KXMLGUIClient, return 0L if not available. Definition at line 627 of file kactioncollection.cpp.

void KActionCollection::actionHighlighted | ( | KAction * | action | ) | `[signal]`

Emitted when "action" is highlighted.

This is only emitted if you have setHighlightingEnabled()

See also:
  connectHighlight()

  disconnectHighlight()

  actionHighlighted()

  setHighlightingEnabled()

  highlightingEnabled()

void KActionCollection::actionHighlighted | ( | KAction * | action,
|  | bool | highlight
| ) | `[signal]`

Emitted when "action" is highlighed or loses highlighting.

This is only emitted if you have setHighlightingEnabled()

See also:
  connectHighlight()

  disconnectHighlight()

  actionHighlighted()

  setHighlightingEnabled()

  highlightingEnabled()

void KActionCollection::actionStatusText | ( | const QString & | text | ) | `[signal]`

Emitted when an action is highlighted, with text being the tooltip for the action.

This is only emitted if you have setHighlightingEnabled()

This is useful to connect to KStatusBar::message(). See this class overview for more information.

See also:
  setHighlightingEnabled()

void KActionCollection::clearStatusText | ( |  | ) | `[signal]`

Emitted when an action loses highlighting.

This is only emitted if you have setHighlightingEnabled()

See also:
  setHighlightingEnabled()

void KActionCollection::insert | ( | KAction * | action | ) |

Add an action to the collection.

Generally you don't have to call this. The action inserts itself automatically into its parent collection. This can be useful however for a short-lived collection (e.g. for a popupmenu, where the signals from the collection are needed too). (don't forget that in the simple case, a list of actions should be a simple KActionPtrList). If you manually insert actions into a 2nd collection, don't forget to take them out again before destroying the collection.

Parameters:

  | action | The KAction to add.

Definition at line 365 of file kactioncollection.cpp.

References action().

void KActionCollection::remove | ( | KAction * | action | ) |

Removes an action from the collection and deletes it.

Since the KAction destructor removes the action from the collection, you generally don't have to call this.

Parameters:

  | action | The KAction to remove.

Definition at line 366 of file kactioncollection.cpp.

References action().

KAction * KActionCollection::take | ( | KAction * | action | ) |

Removes an action from the collection.

Since the KAction destructor removes the action from the collection, you generally don't have to call this.

Returns:
  NULL if not found else returns action.

Parameters:

  | action | the KAction to remove.

Definition at line 367 of file kactioncollection.cpp.

References action().

Referenced by KAction::~KAction().

void KActionCollection::clear | ( |  | ) | `[slot]`

Clears the entire actionCollection, deleting all actions.

See also:
  remove

Definition at line 368 of file kactioncollection.cpp.

The documentation for this class was generated from the following files:

- kactioncollection.h
- kactioncollection.cpp

This file is part of the documentation for kdeui Library Version 3.4.1.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Sat Jun 11 20:20:35 2005 by doxygen 1.4.1 written by Dimitri van Heesch, © 1997-2003