summaryrefslogtreecommitdiffstats
path: root/kdeui/kactioncollection.h
blob: cf3c88e81e478275e8ecdc97bbd934d60bb2270c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
/* This file is part of the KDE libraries
    Copyright (C) 1999 Reginald Stadlbauer <reggie@kde.org>
              (C) 1999 Simon Hausmann <hausmann@kde.org>
              (C) 2000 Nicolas Hadacek <haadcek@kde.org>
              (C) 2000 Kurt Granroth <granroth@kde.org>
              (C) 2000 Michael Koch <koch@kde.org>
              (C) 2001 Holger Freyther <freyther@kde.org>
              (C) 2002 Ellis Whitehead <ellis@kde.org>

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Library General Public
    License version 2 as published by the Free Software Foundation.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Library General Public License for more details.

    You should have received a copy of the GNU Library General Public License
    along with this library; see the file COPYING.LIB.  If not, write to
    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
    Boston, MA 02110-1301, USA.
*/

#ifndef __kactioncollection_h__
#define __kactioncollection_h__

#include <kaction.h>

#include <qkeysequence.h>
#include <qobject.h>
#include <qvaluelist.h>
#include <qguardedptr.h>
#include <kguiitem.h>
#include <kshortcut.h>
#include <kstdaction.h>
#include <kicontheme.h>

class QMenuBar;
class QPopupMenu;
class QComboBox;
class QPoint;
class QIconSet;
class QString;
class KToolBar;

class KAccel;
class KAccelActions;
class KConfig;
class KConfigBase;
class KURL;
class KInstance;
class KToolBar;
class KActionCollection;
class KPopupMenu;
class KMainWindow;
class KXMLGUIClient;

typedef QValueList<KAction *> KActionPtrList;

/**
 * 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:
 *
 * \code
 * actionCollection()->setHighlightingEnabled(true);  
 * connect(actionCollection(), SIGNAL( actionStatusText( const QString & ) ),
 *           statusBar(), SLOT( message( const QString & ) ) );
 * connect(actionCollection(), SIGNAL( clearStatusText() ),
 *           statusBar(), SLOT( clear() ) );
 * \endcode
 */
class KDEUI_EXPORT KActionCollection : public QObject
{
  friend class KAction;
  friend class KXMLGUIClient;

  Q_OBJECT

public:
  KActionCollection( QWidget *parent, const char *name = 0, KInstance *instance = 0 );
  /**
   * Use this constructor if you want the collection's actions to restrict
   * their accelerator keys to @p watch rather than the @p parent.  If
   * you don't require shortcuts, you can pass a null to the @p watch parameter.
   */
  KActionCollection( QWidget *watch, QObject* parent, const char *name = 0, KInstance *instance = 0 );
#ifndef KDE_NO_COMPAT
  KActionCollection( const KActionCollection &copy );
#endif
  virtual ~KActionCollection();

  /**
   * 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.
   */
  virtual void setWidget( QWidget *widget );

  /**
   * 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 isAutoConnectShortcuts()
   */
  void setAutoConnectShortcuts( bool );

  /**
   * This indicates whether new actions which are created in this collection
   * have their keyboard shortcuts automatically connected on
   * construction.
   * @see setAutoConnectShortcuts()
   */
  bool isAutoConnectShortcuts();

  /**
   * This sets the default shortcut scope for new actions created in this
   * collection.  The default is ScopeUnspecified.  Ideally the default
   * would have been ScopeWidget, but that would cause some backwards
   * compatibility problems.
   */
  //void setDefaultScope( KAction::Scope );

  /**
   * Doc/View model.  This lets you add the action collection of a document
   * to a view's action collection.
   */
  bool addDocCollection( KActionCollection* pDoc );

  /** Returns the number of widgets which this collection is associated with. */
  //uint widgetCount() const;

  /**
   * Returns true if the collection has its own KAccel object.  This will be
   * the case if it was constructed with a valid widget ptr or if setWidget()
   * was called.
   */
  //bool ownsKAccel() const;

  /** @deprecated  Deprecated because of ambiguous name.  Use kaccel() */
  virtual KAccel* accel() KDE_DEPRECATED;
  /** @deprecated  Deprecated because of ambiguous name.  Use kaccel() */
  virtual const KAccel* accel() const KDE_DEPRECATED;

  /** Returns the KAccel object of the most recently set widget. */
  KAccel* kaccel();
  /** Returns the KAccel object of the most recently set widget. Const version for convenience. */
  const KAccel* kaccel() const;

  /** @internal, for KAction::kaccelCurrent() */
  KAccel* builderKAccel() const;
  /** Returns the KAccel object associated with widget #. */
  //KAccel* widgetKAccel( uint i );
  //const KAccel* widgetKAccel( uint i ) const;

  /** Returns the number of actions in the collection */
  virtual uint count() const;
  bool isEmpty() const { return (count() == 0); }
  /**
   * Return the KAction* at position "index" in the action collection.
   * @see count()
   */
  virtual KAction* action( int index ) const;
  /**
   * Find an action (optionally, of a given subclass of KAction) in the action collection.
   * @param name Name of the KAction.
   * @param classname Name of the KAction subclass.
   * @return A pointer to the first KAction in the collection which matches the parameters or
   * null if nothing matches.
   */
  virtual KAction* action( const char* name, const char* classname = 0 ) const;

  /** Returns a list of all the groups of all the KActions in this action collection.
   * @see KAction::group()
   * @see KAction::setGroup()
   */
  virtual QStringList groups() const;
  /**
   * Returns the list of actions in a particular group managed by this action collection.
   * @param group The name of the group.
   */
  virtual KActionPtrList actions( const QString& group ) const;
  /** Returns the list of actions managed by this action collection. */
  virtual KActionPtrList actions() const;

  /**
   * Used for reading shortcut configuration from a non-XML rc file.
   */
  bool readShortcutSettings( const QString& sConfigGroup = QString::null, KConfigBase* pConfig = 0 );
  /**
   * Used for writing shortcut configuration to a non-XML rc file.
   */
  bool writeShortcutSettings( const QString& sConfigGroup = QString::null, KConfigBase* pConfig = 0 ) const;

  void setInstance( KInstance *instance );
  /** The instance with which this class is associated. */
  KInstance *instance() const;

  /**
   * @deprecated
   */
  void setXMLFile( const QString& );
  /**
   * @deprecated
   */
  const QString& xmlFile() const;

  //TODO FOR KDE4 make this default true
  /**
   * Enable highlighting notification for specific KActions.
   * This is false by default, so, by default, the highlighting
   * signals will not be emitted.
   * 
   * @see connectHighlight()
   * @see disconnectHighlight()
   * @see actionHighlighted()
   * @see actionHighlighted()
   * @see highlightingEnabled()
   */
  void setHighlightingEnabled( bool enable );
  /**
   * Return whether highlighting notifications are enabled.
   * @see connectHighlight()
   * @see disconnectHighlight()
   * @see actionHighlighted()
   * @see setHighlightingEnabled()
   * @see actionHighlighted()
   */
  bool highlightingEnabled() const;

  /**
   * 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.
   * 
   * @param container A container in which the KAction is plugged (must inherit QPopupMenu or KToolBar)
   * @param action The action you are interested in
   * @see disconnectHighlight()
   * @see actionHighlighted()
   * @see setHighlightingEnabled()
   * @see highlightingEnabled()
   * @see actionHighlighted()
   */
  void connectHighlight( 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.
   * 
   * @param container A container in which the KAction is plugged (must inherit QPopupMenu or KToolBar)
   * @param action The action you are interested in
   * @see connectHighlight()
   * @see actionHighlighted()
   * @see setHighlightingEnabled()
   * @see highlightingEnabled()
   * @see actionHighlighted()
   */
  void disconnectHighlight( QWidget *container, KAction *action );

  /**
   * The parent KXMLGUIClient, return 0L if not available.
   */
  const KXMLGUIClient *parentGUIClient() const;

signals:
  void inserted( KAction* );
  void removed( KAction* );

  /** Emitted when @p action is highlighted.
   *  This is only emitted if you have setHighlightingEnabled()
   * @see connectHighlight()
   * @see disconnectHighlight()
   * @see actionHighlighted()
   * @see setHighlightingEnabled()
   * @see highlightingEnabled()
   */
  void actionHighlighted( KAction *action );
  /** Emitted when @p action is highlighed or loses highlighting.
   *  This is only emitted if you have setHighlightingEnabled()
   * @see connectHighlight()
   * @see disconnectHighlight()
   * @see actionHighlighted()
   * @see setHighlightingEnabled()
   * @see highlightingEnabled()
   */
  void actionHighlighted( KAction *action, bool highlight );
  /** 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 setHighlightingEnabled()
   */
  void actionStatusText( const QString &text );
  /** Emitted when an action loses highlighting.
   *  This is only emitted if you have setHighlightingEnabled()
   *  
   * @see setHighlightingEnabled()
   */
  void clearStatusText();

private:
  /**
   * @internal Only to be called by KXMLGUIFactory::addClient().
   * When actions are being connected, KAction needs to know what
   * widget it should connect widget-scope actions to, and what
   * main window it should connect
   */
  void beginXMLPlug( QWidget *widget );
  void endXMLPlug();
  /** @internal.  Only to be called by KXMLGUIFactory::removeClient() */
  void prepareXMLUnplug();
  void unplugShortcuts( KAccel* kaccel );

  void _clear();
  void _insert( KAction* );
  void _remove( KAction* );
  KAction* _take( KAction* );

private slots:
   void slotMenuItemHighlighted( int id );
   void slotToolBarButtonHighlighted( int id, bool highlight );
   void slotMenuAboutToHide();
   void slotDestroyed();

private:
   KAction *findAction( QWidget *container, int id );

#ifndef KDE_NO_COMPAT
public:
  KActionCollection( QObject *parent, const char *name = 0, KInstance *instance = 0 );
#endif

public:
  /**
   * 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.
   * @param action The KAction to add.
   */
  void insert( 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.
   * @param action The KAction to remove.
   */
  void remove( 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.
   * @return NULL if not found else returns action.
   * @param action the KAction to remove.
   */
  KAction* take( KAction* action );

#ifndef KDE_NO_COMPAT
  KActionCollection operator+ ( const KActionCollection& ) const;
  KActionCollection& operator= ( const KActionCollection& );
  KActionCollection& operator+= ( const KActionCollection& );
#endif // !KDE_NO_COMPAT

  // KDE4: clear() doesn't need to be a slot
public slots:
  /**
   * Clears the entire actionCollection, deleting all actions.
   * @see remove
   */
  void clear();

protected:
    virtual void virtual_hook( int id, void* data );
private:
    KActionCollection( const char* name, const KXMLGUIClient* parent );
    class KActionCollectionPrivate;
    KActionCollectionPrivate *d;
};

#endif