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 | Copyright (C) 2006 Hamish Rodda <rodda@kde.org> |
5 | Copyright (C) 2007 Roberto Raggi <roberto@kdevelop.org> |
6 | Copyright (C) 2007 Andreas Hartmetz <ahartmetz@gmail.com> |
7 | Copyright (C) 2008 Michael Jansen <kde@michael-jansen.biz> |
8 | |
9 | This library is free software; you can redistribute it and/or |
10 | modify it under the terms of the GNU Library General Public |
11 | License as published by the Free Software Foundation; either |
12 | version 2 of the License, or (at your option) any later version. |
13 | |
14 | This library is distributed in the hope that it will be useful, |
15 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
17 | Library General Public License for more details. |
18 | |
19 | You should have received a copy of the GNU Library General Public License |
20 | along with this library; see the file COPYING.LIB. If not, write to |
21 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
22 | Boston, MA 02110-1301, USA. |
23 | */ |
24 | |
25 | |
26 | #ifndef KSHORTCUTSDIALOG_H |
27 | #define KSHORTCUTSDIALOG_H |
28 | |
29 | #include <kdialog.h> |
30 | |
31 | #include "kshortcutseditor.h" |
32 | |
33 | /** |
34 | * @short Dialog for configuration of KActionCollection and KGlobalAccel. |
35 | * |
36 | * The KShortcutsDialog class is used for configuring dictionaries of key/action |
37 | * associations for KActionCollection and KGlobalAccel. It uses the KShortcutsEditor widget |
38 | * and offers buttons to set all keys to defaults and invoke on-line help. |
39 | * |
40 | * Several static methods are supplied which provide the most convenient interface |
41 | * to the dialog. The most common and most encouraged use is with KActionCollection. |
42 | * |
43 | * \code |
44 | * KShortcutsDialog::configure( actionCollection() ); |
45 | * \endcode |
46 | * |
47 | * @since 4.3 |
48 | * By default this dialog is modal. If you don't want that, setModal(false) and then the non-static |
49 | * configure() will show the dialog. If you want to do anything extra when the dialog is done, |
50 | * connect to okClicked() and/or cancelClicked(). However, if your extra stuff depends on the |
51 | * changed settings already being saved, connect to saved() instead to be safe; if you connect to |
52 | * okClicked() your function might be called before the save happens. |
53 | * |
54 | * example: |
55 | * \code |
56 | * KShortcutsDialog dlg; |
57 | * dlg.addCollection(myActions); |
58 | * dlg.setModal(false); |
59 | * connect(&dlg, SIGNAL(saved()), this, SLOT(doExtraStuff())); |
60 | * dlg.configure(); |
61 | * \endcode |
62 | * |
63 | * \image html kshortcutsdialog.png "KDE Shortcuts Dialog" |
64 | * |
65 | * @author Nicolas Hadacek <hadacek@via.ecp.fr> |
66 | * @author Hamish Rodda <rodda@kde.org> (KDE 4 porting) |
67 | * @author Michael Jansen <kde@michael-jansen.biz> |
68 | */ |
69 | class KDEUI_EXPORT KShortcutsDialog : public KDialog |
70 | { |
71 | Q_OBJECT |
72 | |
73 | public: |
74 | /** |
75 | * Constructs a KShortcutsDialog as a child of @p parent. |
76 | * Set @p allowLetterShortcuts to false if unmodified alphanumeric |
77 | * keys ('A', '1', etc.) are not permissible shortcuts. |
78 | */ |
79 | explicit KShortcutsDialog(KShortcutsEditor::ActionTypes types = KShortcutsEditor::AllActions, |
80 | KShortcutsEditor::LetterShortcuts allowLetterShortcuts = KShortcutsEditor::LetterShortcutsAllowed, |
81 | QWidget *parent = 0); |
82 | |
83 | /** |
84 | * Destructor. Deletes all resources used by a KShortcutsDialog object. |
85 | */ |
86 | virtual ~KShortcutsDialog(); |
87 | |
88 | /** |
89 | * Add all actions of the collection to the ones displayed and configured |
90 | * by the dialog. |
91 | * |
92 | * @param title the title associated with the collection (if null, the |
93 | * KAboutData::progName() of the collection's componentData is used) |
94 | */ |
95 | void addCollection(KActionCollection *, const QString &title = QString()); |
96 | |
97 | /** |
98 | * @return the list of action collections that are available for configuration in the dialog. |
99 | */ |
100 | QList<KActionCollection*> actionCollections() const; |
101 | |
102 | /** |
103 | * Run the dialog and call writeSettings() on the action collections |
104 | * that were added if @p bSaveSettings is true. |
105 | */ |
106 | bool configure(bool saveSettings = true); |
107 | |
108 | /** @see QWidget::sizeHint() */ |
109 | virtual QSize sizeHint() const; |
110 | |
111 | /** |
112 | * Pops up a modal dialog for configuring key settings. The new |
113 | * shortcut settings will become active if the user presses OK. |
114 | * |
115 | * @param collection the KActionCollection to configure |
116 | * @param allowLetterShortcuts set to KShortcutsEditor::LetterShortcutsDisallowed if unmodified alphanumeric |
117 | * keys ('A', '1', etc.) are not permissible shortcuts. |
118 | * @param parent the parent widget to attach to |
119 | * @param bSaveSettings if true, the settings will also be saved back |
120 | * by calling writeSettings() on the action collections that were added. |
121 | * |
122 | * @return Accept if the dialog was closed with OK, Reject otherwise. |
123 | */ |
124 | static int configure( KActionCollection *collection, KShortcutsEditor::LetterShortcuts allowLetterShortcuts = |
125 | KShortcutsEditor::LetterShortcutsAllowed, QWidget* parent = 0, bool bSaveSettings = true); |
126 | |
127 | Q_SIGNALS: |
128 | /** |
129 | * emitted after ok is clicked and settings are saved |
130 | */ |
131 | void saved(); |
132 | |
133 | private: |
134 | Q_PRIVATE_SLOT(d, void changeShortcutScheme(const QString &)) |
135 | Q_PRIVATE_SLOT(d, void save()) |
136 | Q_PRIVATE_SLOT(d, void undoChanges()) |
137 | |
138 | class KShortcutsDialogPrivate; |
139 | friend class KShortcutsDialogPrivate; |
140 | class KShortcutsDialogPrivate *const d; |
141 | |
142 | Q_DISABLE_COPY(KShortcutsDialog) |
143 | }; |
144 | |
145 | #endif // KSHORTCUTSDIALOG_H |
146 | |
147 | //kate: space-indent off; indent-width 4; replace-tabs off;tab-width 4; |
148 | |