kdeui/kkeydialog.h

   1 /* This file is part of the KDE libraries
   2     Copyright (C) 1997 Nicolas Hadacek <hadacek@kde.org>
   3     Copyright (C) 2001,2001 Ellis Whitehead <ellis@kde.org>
   4
   5     This library is free software; you can redistribute it and/or
   6     modify it under the terms of the GNU Library General Public
   7     License as published by the Free Software Foundation; either
   8     version 2 of the License, or (at your option) any later version.
   9
  10     This library is distributed in the hope that it will be useful,
  11     but WITHOUT ANY WARRANTY; without even the implied warranty of
  12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13     Library General Public License for more details.
  14
  15     You should have received a copy of the GNU Library General Public License
  16     along with this library; see the file COPYING.LIB.  If not, write to
  17     the Free Software Foundation, Inc., 51 Franklin Steet, Fifth Floor,
  18     Boston, MA 02110-1301, USA.
  19 */
  20
  21 #ifndef __KKEYDIALOG_H__
  22 #define __KKEYDIALOG_H__
  23
  24 #include <qdict.h>
  25 #include <kdialogbase.h>
  26 #include <klistview.h>
  27
  28 class QButtonGroup;
  29 class QCheckBox;
  30 class QGroupBox;
  31 class QLabel;
  32 class QLineEdit;
  33 class QRadioButton;
  34 class KAccel;
  35 class KAccelActions;
  36 class KActionCollection;
  37 class KConfigBase;
  38 class KGlobalAccel;
  39 class KKeySequence;
  40 class KShortcut;
  41 class KShortcutList;
  42 class KKeyChooserItem;
  43
  44 /**
  45  * @short Widget for configuration of KAccel and KGlobalAccel.
  46  *
  47  * Configure dictionaries of key/action associations for KAccel and
  48  * KGlobalAccel.
  49  *
  50  * The class takes care of all aspects of configuration, including
  51  * handling key conflicts internally. Connect to the allDefault()
  52  * slot if you want to set all configurable shortcuts to their
  53  * default values.
  54  *
  55  * @see KKeyDialog
  56  * @author Nicolas Hadacek <hadacek@via.ecp.fr>
  57  */
  58 class KDEUI_EXPORT KKeyChooser : public QWidget
  59 {
  60         Q_OBJECT
  61  public:
  62         enum ActionType { Application, ApplicationGlobal, Standard, Global };
  63
  64         /**
  65          * Constructor.
  66          *
  67          * @param parent the parent widget for this widget
  68          * @param type the ActionType for this KKeyChooser
  69          * @param bAllowLetterShortcuts Set to false if unmodified alphanumeric
  70          *  keys ('A', '1', etc.) are not permissible shortcuts.
  71          **/
  72         KKeyChooser( QWidget* parent, ActionType type = Application, bool bAllowLetterShortcuts = true );
  73         /**
  74          * \overload
  75          * @param parent parent widget
  76          * @param coll the KActionCollection to configure
  77          * @param bAllowLetterShortcuts Set to false if unmodified alphanumeric
  78      *  keys ('A', '1', etc.) are not permissible shortcuts.
  79      */
  80         KKeyChooser( KActionCollection* coll, QWidget* parent, bool bAllowLetterShortcuts = true );
  81
  82     KKeyChooser( KAccel* actions, QWidget* parent, bool bAllowLetterShortcuts = true );
  83         KKeyChooser( KGlobalAccel* actions, QWidget* parent );
  84         KKeyChooser( KShortcutList*, QWidget* parent, ActionType type = Application, bool bAllowLetterShortcuts = true );
  85
  86         virtual ~KKeyChooser();
  87
  88         /**
  89          * Insert an action collection, i.e. add all its actions to the ones
  90          * already associated with the KKeyChooser object.
  91          */
  92         bool insert( KActionCollection* ); // #### KDE4 : remove me
  93     /**
  94          * Insert an action collection, i.e. add all its actions to the ones
  95          * already associated with the KKeyChooser object.
  96          * @param title subtree title of this collection of shortcut.
  97          * @since 3.1
  98          */
  99     bool insert( KActionCollection *, const QString &title);
 100
 101         void syncToConfig( const QString& sConfigGroup, KConfigBase* pConfig, bool bClearUnset );
 102
 103         /**
 104          * This function writes any shortcut changes back to the original
 105          * action set(s).
 106          */
 107         void commitChanges();
 108
 109         /**
 110          * This commits and then saves the actions to disk.
 111          * Any KActionCollection objects with the xmlFile() value set
 112          * will be written to an XML file.  All other will be written
 113          * to the application's rc file.
 114          */
 115         void save();
 116
 117         /**
 118          * Checks whether the given shortcut conflicts with global keyboard shortcuts.
 119          * If yes, and the warnUser argument is true, warns the user and gives them a chance
 120          * to reassign the shortcut from the global shortcut.
 121          *
 122          * @return true if there was conflict (and the user didn't reassign the shortcut)
 123          * @param cut the shortcut that will be checked for conflicts
 124          * @param warnUser if true, the user will be warned about a conflict and given a chance
 125          *        to reassign the shortcut
 126          * @param parent parent widget for the warning dialog
 127          *
 128          * @since 3.2
 129          */
 130         static bool checkGlobalShortcutsConflict( const KShortcut& cut, bool warnUser, QWidget* parent );
 131
 132         /**
 133          * Checks whether the given shortcut conflicts with standard keyboard shortcuts.
 134          * If yes, and the warnUser argument is true, warns the user and gives them a chance
 135          * to reassign the shortcut from the standard shortcut.
 136          *
 137          * @return true if there was conflict (and the user didn't reassign the shortcut)
 138          * @param cut the shortcut that will be checked for conflicts
 139          * @param warnUser if true, the user will be warned about a conflict and given a chance
 140          *        to reassign the shortcut
 141          * @param parent parent widget for the warning dialog
 142          *
 143          * @since 3.2
 144          */
 145         static bool checkStandardShortcutsConflict( const KShortcut& cut, bool warnUser, QWidget* parent );
 146
 147  signals:
 148         /**
 149          * Emitted when an action's shortcut has been changed.
 150          **/
 151         void keyChange();
 152
 153  public slots:
 154         /**
 155          * Set all keys to their default values (bindings).
 156          **/
 157         void allDefault();
 158
 159         /**
 160          * Specifies whether to use the 3 or 4 modifier key scheme.
 161          * This determines which default is used when the 'Default' button is
 162          * clicked.
 163          */
 164         void setPreferFourModifierKeys( bool preferFourModifierKeys );
 165
 166  // KDE4 a lot of stuff in this class should be probably private:
 167  protected:
 168         enum { NoKey = 1, DefaultKey, CustomKey };
 169
 170         void initGUI( ActionType type, bool bAllowLetterShortcuts );
 171         bool insert( KAccel* );
 172         bool insert( KGlobalAccel* );
 173         bool insert( KShortcutList* );
 174         /// @since 3.1
 175         void buildListView( uint iList, const QString &title = QString::null );
 176
 177         void readGlobalKeys();
 178
 179         void updateButtons();
 180         void fontChange( const QFont& _font );
 181         void setShortcut( const KShortcut& cut );
 182         bool isKeyPresent( const KShortcut& cut, bool warnuser = true );
 183         bool isKeyPresentLocally( const KShortcut& cut, KKeyChooserItem* ignoreItem, const QString& warnText );
 184         void _warning( const KKeySequence& seq, QString sAction, QString sTitle );
 185
 186  protected slots:
 187         void slotNoKey();
 188         void slotDefaultKey();
 189         void slotCustomKey();
 190         void slotListItemSelected( QListViewItem *item );
 191         void capturedShortcut( const KShortcut& cut );
 192         void slotSettingsChanged( int );
 193         void slotListItemDoubleClicked ( QListViewItem * ipoQListViewItem, const QPoint & ipoQPoint, int c );
 194
 195  protected:
 196         ActionType m_type;
 197         bool m_bAllowLetterShortcuts;
 198         bool m_bAllowWinKey; // unused KDE4 remove
 199         // When set, pressing the 'Default' button will select the aDefaultKeycode4,
 200         //  otherwise aDefaultKeycode.
 201         bool m_bPreferFourModifierKeys;
 202
 203         QRadioButton* m_prbNone;
 204         QRadioButton* m_prbDef;
 205         QRadioButton* m_prbCustom;
 206
 207  private:
 208         bool isKeyPresentLocally( const KShortcut& cut, KKeyChooserItem* ignoreItem, bool bWarnUser );
 209         static bool promptForReassign( const KKeySequence& cut, const QString& sAction, ActionType action, QWidget* parent );
 210         // Remove the key sequences contained in cut from the standard shortcut @p name
 211         // which currently has @p origCut as shortcut.
 212         static void removeStandardShortcut( const QString& name, KKeyChooser* chooser, const KShortcut &origCut, const KShortcut &cut );
 213         // Remove the key sequences contained in cut from the global shortcut @p name
 214         // which currently has @p origCut as shortcut.
 215         static void removeGlobalShortcut( const QString& name, KKeyChooser* chooser, const KShortcut &origCut, const KShortcut &cut );
 216         static void readGlobalKeys( QMap< QString, KShortcut >& map );
 217         static bool checkGlobalShortcutsConflict( const KShortcut& cut, bool bWarnUser, QWidget* parent,
 218             const QMap< QString, KShortcut >& map, const QString& ignoreAction );
 219         // Remove the key sequences contained in cut from this item
 220         bool removeShortcut( const QString& name, const KShortcut &cut );
 221
 222 private slots:
 223         void captureCurrentItem();
 224
 225 #ifndef KDE_NO_COMPAT
 226  public:
 227         /**
 228          * @obsolete
 229          */
 230         KKeyChooser( KAccel* actions, QWidget* parent,
 231                         bool bCheckAgainstStdKeys,
 232                         bool bAllowLetterShortcuts,
 233                         bool bAllowWinKey = false );
 234         /**
 235          * @obsolete
 236          */
 237         KKeyChooser( KGlobalAccel* actions, QWidget* parent,
 238                         bool bCheckAgainstStdKeys,
 239                         bool bAllowLetterShortcuts,
 240                         bool bAllowWinKey = false );
 241
 242  public slots:
 243         /**
 244          * Rebuild list entries based on underlying map.
 245          * Use this if you changed the underlying map.
 246          */
 247         void listSync();
 248
 249 #endif
 250  protected:
 251         virtual void virtual_hook( int id, void* data );
 252  private:
 253         class KKeyChooserPrivate *d;
 254         friend class KKeyDialog;
 255 };
 256 typedef KKeyChooser KKeyChooser;
 257
 258 /**
 259  * @short Dialog for configuration of KActionCollection, KAccel, and KGlobalAccel.
 260  *
 261  * The KKeyDialog class is used for configuring dictionaries of key/action
 262  * associations for KActionCollection, KAccel, and KGlobalAccel. It uses the KKeyChooser widget
 263  * and offers buttons to set all keys to defaults and invoke on-line help.
 264  *
 265  * Three static methods are supplied which provide the most convienient interface
 266  * to the dialog. The most common and most encouraged use is with KActionCollection.
 267  *
 268  * \code
 269  * KKeyDialog::configure( actionCollection() );
 270  * \endcode
 271  *
 272  * @author Nicolas Hadacek <hadacek@via.ecp.fr>
 273  */
 274 class KDEUI_EXPORT KKeyDialog : public KDialogBase
 275 {
 276         Q_OBJECT
 277
 278 public:
 279         /**
 280          * Constructs a KKeyDialog called @p name as a child of @p parent.
 281          * Set @p bAllowLetterShortcuts to false if unmodified alphanumeric
 282          * keys ('A', '1', etc.) are not permissible shortcuts.
 283          */
 284         KKeyDialog( bool bAllowLetterShortcuts = true, QWidget* parent = 0, const char* name = 0 );
 285
 286         /**
 287          * Destructor. Deletes all resources used by a KKeyDialog object.
 288          */
 289         virtual ~KKeyDialog();
 290
 291         /**
 292          * Insert an action collection, i.e. add all its actions to the ones
 293          * displayed by the dialog.
 294          * This method can be useful in applications following the document/view
 295          * design, with actions in both the document and the view.
 296          * Simply call insert with the action collections of each one in turn.
 297          * @return true :)
 298          */
 299         bool insert( KActionCollection* ); // #### KDE4: remove me
 300
 301         /**
 302          * Insert an action collection, i.e. add all its actions to the ones
 303          * displayed by the dialog.
 304          * This method can be useful in applications following the document/view
 305          * design, with actions in both the document and the view.
 306          * Simply call insert with the action collections of each one in turn.
 307          *
 308          * @param title the title associated with the collection (if null, the
 309          * KAboutData::progName() of the collection's instance is used)
 310          * @return true :)
 311          * @since 3.1
 312          */
 313         bool insert(KActionCollection *, const QString &title);
 314
 315         /**
 316          * Run the dialog and call commitChanges() if @p bSaveSettings
 317          * is true.
 318          */
 319         bool configure( bool bSaveSettings = true );
 320
 321         /**
 322          * Commit key setting changes so that changed settings actually become active.
 323          * This method is implicitly called from configure(bool) if
 324          * @p bSaveSettings is true.
 325          */
 326         void commitChanges();
 327
 328         /**
 329          * Pops up a modal dialog for configuring key settings. The new
 330          * shortcut settings will be active if the user presses OK.  If
 331          * @p bSaveSettings if true, the settings will also be saved back to
 332          * the *uirc file which they were intially read from.
 333          * @return Accept if the dialog was closed with OK, Reject otherwise.
 334          */
 335         static int configure( KActionCollection* coll, QWidget* parent = 0, bool bSaveSettings = true );
 336
 337         /**
 338          * This is an overloaded member function, provided for convenience.
 339          * It behaves essentially like the above function, except that settings
 340          * are saved to a *.rc file using KConfig.
 341          */
 342         static int configure( KAccel* keys, QWidget* parent = 0, bool bSaveSettings = true );
 343
 344         /**
 345          * This is an overloaded member function, provided for convenience.
 346          * It behaves essentially like the above function.
 347          */
 348         static int configure( KGlobalAccel* keys, QWidget* parent = 0, bool bSaveSettings = true );
 349
 350
 351         /**
 352          * This is an overloaded member function, provided for convenience.
 353          * It behaves essentially like the above function.
 354          *
 355          * @param coll the KActionCollection to configure
 356          * @param bAllowLetterShortcuts Set to false if unmodified alphanumeric
 357          *  keys ('A', '1', etc.) are not permissible shortcuts.
 358          * @param parent the parent widget to attach to
 359          * @param bSaveSettings if true, the settings will also be saved back to
 360          * the *uirc file which they were intially read from.
 361          */
 362         static int configure( KActionCollection* coll, bool bAllowLetterShortcuts, QWidget* parent = 0, bool bSaveSettings = true ); // BCI: merge with bAllowLetterShortcuts = true
 363
 364         /**
 365          * This is an overloaded member function, provided for convenience.
 366          * It behaves essentially like the above function.
 367          **/
 368         static int configure( KAccel* keys, bool bAllowLetterShortcuts, QWidget* parent = 0, bool bSaveSettings = true ); // BCI: merge with bAllowLetterShortcuts = true
 369
 370         /**
 371          * This is an overloaded member function, provided for convenience.
 372          * It behaves essentially like the above function.
 373          **/
 374         static int configure( KGlobalAccel* keys, bool bAllowLetterShortcuts, QWidget* parent = 0, bool bSaveSettings = true ); // BCI: merge with bAllowLetterShortcuts = true
 375
 376         /**
 377          * @deprecated Obsolete.
 378          * Please use KKeyDialog::configure instead
 379          */
 380         static KDE_DEPRECATED int configureKeys( KAccel* keys, bool save_settings = true, QWidget* parent = 0 )
 381                 { return configure( keys, parent, save_settings ); }
 382         /**
 383          * @deprecated Obsolete.
 384          * Please use KKeyDialog::configure instead
 385          */
 386         static KDE_DEPRECATED int configureKeys( KGlobalAccel* keys, bool save_settings = true, QWidget* parent = 0 )
 387                 { return configure( keys, parent, save_settings ); }
 388         /**
 389          * @deprecated Obsolete.
 390          * Please use KKeyDialog::configure instead
 391          */
 392         static KDE_DEPRECATED int configureKeys( KActionCollection* coll, const QString& /*xmlfile*/,
 393                 bool save_settings = true, QWidget* parent = 0 )
 394                 { return configure( coll, parent, save_settings ); }
 395
 396 private:
 397         KKeyDialog( KKeyChooser::ActionType, bool bAllowLetterShortcuts = true, QWidget* parent = 0, const char* name = 0 );
 398
 399  protected:
 400         virtual void virtual_hook( int id, void* data );
 401
 402  private:
 403         class KKeyDialogPrivate* d;
 404         KKeyChooser* m_pKeyChooser;
 405 };
 406
 407 #endif // __KKEYDIALOG_H__