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 */
69class KDEUI_EXPORT KShortcutsDialog : public KDialog
70{
71 Q_OBJECT
72
73public:
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
127Q_SIGNALS:
128 /**
129 * emitted after ok is clicked and settings are saved
130 */
131 void saved();
132
133private:
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