1
/* This file is part of the KDE libraries
2
Copyright (C) 2001,2002 Ellis Whitehead <ellis@kde.org>
4
This library is free software; you can redistribute it and/or
5
modify it under the terms of the GNU Library General Public
6
License as published by the Free Software Foundation; either
7
version 2 of the License, or (at your option) any later version.
9
This library is distributed in the hope that it will be useful,
10
but WITHOUT ANY WARRANTY; without even the implied warranty of
11
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12
Library General Public License for more details.
14
You should have received a copy of the GNU Library General Public License
15
along with this library; see the file COPYING.LIB. If not, write to
16
the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17
Boston, MA 02110-1301, USA.
20
#ifndef _KACCELACTION_H
21
#define _KACCELACTION_H
24
#include <qptrvector.h>
26
#include <qvaluevector.h>
28
#include <kshortcut.h>
38
* A KAccelAction prepresents an action that can be executed using
39
* an accelerator key. Each KAccelAction has a name, a label, a
40
* "What's this" string and a KShortcut. The user can configure and
41
* enable/disable them using KKeyDialog.
44
* 1) KAccelAction = "Run Command"
46
* Default4 = "Meta+Enter;Alt+F2"
47
* 1) KShortcut = "Meta+Enter"
48
* 1) KKeySequence = "Meta+Enter"
49
* 1) KKey = "Meta+Enter"
51
* 2) Meta+Keypad_Enter
52
* 2) KShortcut = "Alt+F2"
53
* 1) KKeySequence = "Alt+F2"
55
* 2) KAccelAction = "Something"
58
* 1) KShortcut = "Meta+X,Asterisk"
59
* 1) KKeySequence = "Meta+X,Asterisk"
62
* 2) KKey = "Asterisk"
63
* 1) Shift+8 (English layout)
66
* @short An accelerator action
72
class KDECORE_EXPORT KAccelAction
76
* Creates an empty KAccelAction.
84
KAccelAction( const KAccelAction& );
87
* Creates a new KAccelAction.
88
* @param sName the name of the accelerator
89
* @param sLabel the label of the accelerator (i18n!)
90
* @param sWhatsThis the What's This text (18n!)
91
* @param cutDef3 the default shortcut for 3 modifier systems
92
* @param cutDef4 the default shortcut for 4 modifier systems
93
* @param pObjSlot the receiver of a signal when the key has been
95
* @param psMethodSlot the slot to connect for key presses. Receives
96
* an int, as set by setID(), as only argument
97
* @param bConfigurable if true the user can configure the shortcut
98
* @param bEnabled true if the accelerator should be enabled
100
KAccelAction( const QString& sName, const QString& sLabel, const QString& sWhatsThis,
101
const KShortcut& cutDef3, const KShortcut& cutDef4,
102
const QObject* pObjSlot, const char* psMethodSlot,
103
bool bConfigurable, bool bEnabled );
107
* Clears the accelerator.
112
* Re-initialized the KAccelAction.
113
* @param sName the name of the accelerator
114
* @param sLabel the label of the accelerator (i18n!)
115
* @param sWhatsThis the What's This text (18n!)
116
* @param cutDef3 the default shortcut for 3 modifier systems
117
* @param cutDef4 the default shortcut for 4 modifier systems
118
* @param pObjSlot the receiver of a signal when the key has been
120
* @param psMethodSlot the slot to connect for key presses. Receives
121
* an int, as set by setID(), as only argument
122
* @param bConfigurable if true the user can configure the shortcut
123
* @param bEnabled true if the accelerator should be enabled
124
* @return true if successful, false otherwise
126
bool init( const QString& sName, const QString& sLabel, const QString& sWhatsThis,
127
const KShortcut& cutDef3, const KShortcut& cutDef4,
128
const QObject* pObjSlot, const char* psMethodSlot,
129
bool bConfigurable, bool bEnabled );
132
* Copies this KAccelAction.
134
KAccelAction& operator=( const KAccelAction& );
137
* Returns the name of the accelerator action.
138
* @return the name of the accelerator action, can be null if not
141
const QString& name() const { return m_sName; }
144
* Returns the label of the accelerator action.
145
* @return the label of the accelerator action, can be null if
148
const QString& label() const { return m_sLabel; }
151
* Returns the What's This text of the accelerator action.
152
* @return the What's This text of the accelerator action, can be
155
const QString& whatsThis() const { return m_sWhatsThis; }
158
* The shortcut that is actually used (may be used configured).
159
* @return the shortcut of the KAccelAction, can be null if not set
160
* @see shortcutDefault()
162
const KShortcut& shortcut() const { return m_cut; }
165
* The default shortcut for this system.
166
* @return the default shortcut on this system, can be null if not set
168
* @see shortcutDefault3()
169
* @see shortcutDefault4()
171
const KShortcut& shortcutDefault() const;
174
* The default shortcut for 3 modifier systems.
175
* @return the default shortcut for 3 modifier systems, can be null
177
* @see shortcutDefault()
178
* @see shortcutDefault4()
179
* @see useFourModifierKeys()
181
const KShortcut& shortcutDefault3() const { return m_cutDefault3; }
184
* The default shortcut for 4 modifier systems.
185
* @return the default shortcut for 4 modifier systems, can be null
187
* @see shortcutDefault()
188
* @see shortcutDefault3()
189
* @see useFourModifierKeys()
191
const KShortcut& shortcutDefault4() const { return m_cutDefault4; }
194
* Returns the receiver of signals.
195
* @return the receiver of signals (can be 0 if not set)
197
const QObject* objSlotPtr() const { return m_pObjSlot; }
200
* Returns the slot for the signal.
201
* @return the slot for the signal
203
const char* methodSlotPtr() const { return m_psMethodSlot; }
206
* Checks whether the user can configure the action.
207
* @return true if configurable, false otherwise
209
bool isConfigurable() const { return m_bConfigurable; }
212
* Checks whether the action is enabled.
213
* @return true if enabled, false otherwise
215
bool isEnabled() const { return m_bEnabled; }
218
* Sets the name of the accelerator action.
219
* @param name the new name
221
void setName( const QString& name );
224
* Sets the user-readable label of the accelerator action.
225
* @param label the new label (i18n!)
227
void setLabel( const QString& label );
230
* Sets the What's This text for the accelerator action.
231
* @param whatsThis the new What's This text (i18n!)
233
void setWhatsThis( const QString& whatsThis );
236
* Sets the new shortcut of the accelerator action.
237
* @param rgCuts the shortcut to set
238
* @return true if successful, false otherwise
240
bool setShortcut( const KShortcut& rgCuts );
243
* Sets the slot of the accelerator action.
244
* @param pObjSlot the receiver object of the signal
245
* @param psMethodSlot the slot for the signal
247
void setSlot( const QObject* pObjSlot, const char* psMethodSlot );
250
* Enables or disabled configuring the action.
251
* @param configurable true to enable configurability, false to disable
253
void setConfigurable( bool configurable );
256
* Enables or disabled the action.
257
* @param enable true to enable the action, false to disable
259
void setEnabled( bool enable );
262
* Retrieves the id set using setID.
263
* @return the id of the accelerator action
265
int getID() const { return m_nIDAccel; }
268
* Allows you to set an id that will be used as the action
271
* @param n the new id
274
void setID( int n ) { m_nIDAccel = n; }
277
* Checkes whether the action is connected (emits signals).
278
* @return true if connected, false otherwise
280
bool isConnected() const;
283
* Sets a key sequence of the action's shortcut.
284
* @param i the position of the sequence
285
* @param keySeq the new new sequence
286
* @return true if successful, false otherwise
287
* @see KShortcut::setSeq()
289
bool setKeySequence( uint i, const KKeySequence &keySeq );
292
* Clears the action's shortcut. It will not contain any sequences after
293
* calling this method.
294
* @see KShortcut::clear()
296
void clearShortcut();
299
* Checks whether the action's shortcut contains the given key sequence.
300
* @param keySeq the key sequence to check
301
* @return true if the shortcut contains the given sequence
302
* @see KShortcut::contains()
304
bool contains( const KKeySequence &keySeq );
307
* Returns the string representation of the action's shortcut.
308
* @return the string representation of the action's shortcut.
309
* @see KShortcut::toString()
311
QString toString() const;
316
QString toStringInternal() const;
319
* Returns true if four modifier keys will be used.
320
* @return true if four modifier keys will be used.
322
static bool useFourModifierKeys();
325
* Selects 3 or 4 modifier default shortcuts.
326
* @param use true to use 4 modifier shortcuts, false to use
327
* 3 modifier shortcuts
329
static void useFourModifierKeys( bool use );
332
QString m_sName /**< Name of accel. @sa setName() */,
333
m_sLabel /**< Label of accel. User-visible. */,
334
m_sWhatsThis /**< WhatsThis help for accel. User-visible. */;
335
KShortcut m_cut /**< Shortcut actually assigned. */;
336
KShortcut m_cutDefault3 /**< Default shortcut in 3-modifier layout */,
337
m_cutDefault4 /**< Default shortcur in 4-modifier layout */;
338
const QObject* m_pObjSlot /**< Object we will send signals to. */;
339
const char* m_psMethodSlot /**< Slot we send signals to, in m_pObjSlot */;
340
bool m_bConfigurable /**< Can this accel be configured by the user? */,
341
m_bEnabled /**< Is this accel enabled? */;
342
int m_nIDAccel /**< Id of this accel, from the list of IDs */;
343
uint m_nConnections /**< Number of connections to this accel. */ ;
345
/** @internal Increment the number of connections to this accel. */
346
void incConnections();
347
/** @internal Decrement the number of connections to this accel (bouded by zero). */
348
void decConnections();
351
static int g_bUseFourModifierKeys;
352
class KAccelActionPrivate* d;
354
friend class KAccelActions;
355
friend class KAccelBase;
358
//---------------------------------------------------------------------
360
//---------------------------------------------------------------------
364
* This class represents a collection of KAccelAction objects.
366
* @short A collection of accelerator actions
369
class KDECORE_EXPORT KAccelActions
373
* Creates a new, empty KAccelActions object.
378
* Copy constructor (deep copy).
380
KAccelActions( const KAccelActions& );
381
virtual ~KAccelActions();
384
* Removes all items from this collection.
389
* Initializes this object with the given actions.
390
* It will make a deep copy of all actions.
391
* @param actions the actions to copy
392
* @return true if successful, false otherwise
394
bool init( const KAccelActions &actions );
397
* Loads the actions from the given configuration file.
399
* @param config the configuration file to load from
400
* @param sGroup the group in the configuration file
401
* @return true if successful, false otherwise
403
bool init( KConfigBase& config, const QString& sGroup );
406
* Updates the shortcuts of all actions in this object
407
* with the shortcuts from the given object.
408
* @param shortcuts the collection that contains the new
411
void updateShortcuts( KAccelActions &shortcuts );
414
* Retrieves the index of the action with the given name.
415
* @param sAction the action to search
416
* @return the index of the action, or -1 if not found
418
int actionIndex( const QString& sAction ) const;
421
* Returns the action with the given @p index.
422
* @param index the index of an action. You must not
423
* use an index that is too high.
424
* @return the KAccelAction with the given index
427
KAccelAction* actionPtr( uint index );
430
* Returns the action with the given @p index.
431
* @param index the index of an action. You must not
432
* use an index that is too high.
433
* @return the KAccelAction with the given index
436
const KAccelAction* actionPtr( uint index ) const;
439
* Returns the action with the given name.
440
* @param sAction the name of the action to search
441
* @return the KAccelAction with the given name, or 0
444
KAccelAction* actionPtr( const QString& sAction );
447
* Returns the action with the given name.
448
* @param sAction the name of the action to search
449
* @return the KAccelAction with the given name, or 0
452
const KAccelAction* actionPtr( const QString& sAction ) const;
455
* Returns the action with the given key sequence.
456
* @param cut the sequence to search for
457
* @return the KAccelAction with the given sequence, or 0
460
KAccelAction* actionPtr( KKeySequence cut );
463
* Returns the action with the given @p index.
464
* @param index the index of an action. You must not
465
* use an index that is too high.
466
* @return the KAccelAction with the given index
470
KAccelAction& operator []( uint index );
473
* Returns the action with the given @p index.
474
* @param index the index of an action. You must not
475
* use an index that is too high.
476
* @return the KAccelAction with the given index
480
const KAccelAction& operator []( uint index ) const;
483
* Inserts an action into the collection.
484
* @param sAction the name of the accelerator
485
* @param sLabel the label of the accelerator (i18n!)
486
* @param sWhatsThis the What's This text (18n!)
487
* @param rgCutDefaults3 the default shortcut for 3 modifier systems
488
* @param rgCutDefaults4 the default shortcut for 4 modifier systems
489
* @param pObjSlot the receiver of a signal when the key has been
491
* @param psMethodSlot the slot to connect for key presses. Receives
492
* an int, as set by setID(), as only argument
493
* @param bConfigurable if true the user can configure the shortcut
494
* @param bEnabled if true the accelerator should be enabled
495
* @return the new action
497
KAccelAction* insert( const QString& sAction, const QString& sLabel, const QString& sWhatsThis,
498
const KShortcut& rgCutDefaults3, const KShortcut& rgCutDefaults4,
499
const QObject* pObjSlot = 0, const char* psMethodSlot = 0,
500
bool bConfigurable = true, bool bEnabled = true );
503
* Inserts an action into the collection.
504
* @param sName the name of the accelerator
505
* @param sLabel the label of the accelerator (i18n!)
506
* @return the new action
508
KAccelAction* insert( const QString& sName, const QString& sLabel );
511
* Removes the given action.
512
* @param sAction the name of the action.
513
* @return true if successful, false otherwise
515
bool remove( const QString& sAction );
518
* Loads the actions from the given configuration file.
520
* @param sConfigGroup the group in the configuration file
521
* @param pConfig the configuration file to load from
522
* @return true if successful, false otherwise
524
bool readActions( const QString& sConfigGroup = "Shortcuts", KConfigBase* pConfig = 0 );
527
* Writes the actions to the given configuration file.
529
* @param sConfigGroup the group in the configuration file
530
* @param pConfig the configuration file to save to
531
* @param bWriteAll true to write all actions
532
* @param bGlobal true to write to the global configuration file
533
* @return true if successful, false otherwise
535
bool writeActions( const QString& sConfigGroup = "Shortcuts", KConfigBase* pConfig = 0,
536
bool bWriteAll = false, bool bGlobal = false ) const;
539
* Emit a keycodeChanged signal.
541
void emitKeycodeChanged();
544
* Returns the number of actions in the collection.
545
* @return the number of actions
550
/** Base object that proxies signals from us. */
551
KAccelBase* m_pKAccelBase;
552
/** Array of actions we're hanging on to. */
553
KAccelAction** m_prgActions;
554
uint m_nSizeAllocated /**< Allocated size of the array. */,
555
m_nSize /**< Amount in use. */ ;
558
* Resize the list to the given number @p new_size of entries.
559
* @todo Can you make it smaller?
560
* @todo Implementation seems to break m_nSize.
562
void resize( uint new_size );
563
/** Add a action to this collection. @todo Document ownership. */
564
void insertPtr( KAccelAction* );
567
class KAccelActionsPrivate* d;
569
KAccelActions( KAccelBase* );
570
void initPrivate( KAccelBase* );
571
KAccelActions& operator =( KAccelActions& );
573
friend class KAccelBase;
576
#endif // _KACCELACTION_H
added
removed
extra/kde353/kaccelaction.h
