← Back to branch summary

~oif-team/ubuntu/natty/qt4-x11/xi2.1

« back to all changes in this revision

Viewing changes to src/gui/kernel/qshortcut.cpp

  • Committer: Bazaar Package Importer
  • Author(s): Adam Conrad
  • Date: 2005-08-24 04:09:09 UTC
  • Revision ID: james.westby@ubuntu.com-20050824040909-xmxe9jfr4a0w5671
Tags: upstream-4.0.0
Import upstream version 4.0.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/gui/kernel/qshortcut.cpp
 
1
/****************************************************************************
 
2
**
 
3
** Copyright (C) 1992-2005 Trolltech AS. All rights reserved.
 
4
**
 
5
** This file is part of the gui module of the Qt Toolkit.
 
6
**
 
7
** This file may be distributed under the terms of the Q Public License
 
8
** as defined by Trolltech AS of Norway and appearing in the file
 
9
** LICENSE.QPL included in the packaging of this file.
 
10
**
 
11
** This file may be distributed and/or modified under the terms of the
 
12
** GNU General Public License version 2 as published by the Free Software
 
13
** Foundation and appearing in the file LICENSE.GPL included in the
 
14
** packaging of this file.
 
15
**
 
16
** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
 
17
**   information about Qt Commercial License Agreements.
 
18
** See http://www.trolltech.com/qpl/ for QPL licensing information.
 
19
** See http://www.trolltech.com/gpl/ for GPL licensing information.
 
20
**
 
21
** Contact info@trolltech.com if any conditions of this licensing are
 
22
** not clear to you.
 
23
**
 
24
** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
 
25
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 
26
**
 
27
****************************************************************************/
 
28
 
 
29
#include "qshortcut.h"
 
30
#include "private/qwidget_p.h"
 
31
 
 
32
#include <qevent.h>
 
33
#include <qwhatsthis.h>
 
34
#include <qmenu.h>
 
35
#include <qapplication.h>
 
36
#include <private/qapplication_p.h>
 
37
#include <private/qshortcutmap_p.h>
 
38
 
 
39
/*!
 
40
    \class QShortcut
 
41
    \brief The QShortcut class is used to create keyboard shortcuts.
 
42
 
 
43
    \ingroup events
 
44
    \mainclass
 
45
 
 
46
    The QShortcut class provides a way of connecting keyboard
 
47
    shortcuts to Qt's \l{signals and slots} mechanism, so that
 
48
    objects can be informed when a shortcut is executed. The shortcut
 
49
    can be set up to contain all the key presses necessary to
 
50
    describe a keyboard shortcut, including the states of modifier
 
51
    keys such as \gui Shift, \gui Ctrl, and \gui Alt.
 
52
 
 
53
    For applications that use menus, it may be more convenient to
 
54
    use the convenience functions provided in the QMenu class to
 
55
    assign keyboard shortcuts to menu items as they are created.
 
56
    Alternatively, shortcuts may be associated with other types of
 
57
    actions in the QAction class.
 
58
 
 
59
    The simplest way to create a shortcut for a particular widget is
 
60
    to construct the shortcut with a key sequence. For example:
 
61
 
 
62
    \code
 
63
        shortcut = QShortcut(QKeySequence(tr("Ctrl+O", "File|Open")),
 
64
                             parent);
 
65
    \endcode
 
66
 
 
67
    When the user types the \l{QKeySequence}{key sequence}
 
68
    for a given shortcut, the shortcut's activated() signal is
 
69
    emitted. (In the case of ambiguity, the activatedAmbiguously()
 
70
    signal is emitted.) A shortcut is "listened for" by Qt's event
 
71
    loop when the shortcut's parent widget is receiving events.
 
72
 
 
73
    A shortcut's key sequence can be set with setKey() and retrieved
 
74
    with key(). A shortcut can be enabled or disabled with
 
75
    setEnabled(), and can have "What's This?" help text set with
 
76
    setWhatsThis().
 
77
 
 
78
    \sa QShortcutEvent, QKeySequence, QAction
 
79
*/
 
80
 
 
81
/*!
 
82
    \fn QWidget *QShortcut::parentWidget() const
 
83
 
 
84
    Returns the shortcut's parent widget.
 
85
*/
 
86
 
 
87
/*!
 
88
    \fn void QShortcut::activated()
 
89
 
 
90
    This signal is emitted when the user types the shortcut's key
 
91
    sequence.
 
92
 
 
93
    \sa activatedAmbiguously()
 
94
*/
 
95
 
 
96
/*!
 
97
    \fn void QShortcut::activatedAmbiguously()
 
98
 
 
99
    This signal is emitted when the user types a shortcut key
 
100
    sequence that is ambiguous. For example, if one key sequence is a
 
101
    "prefix" for another and the user types these keys it isn't clear
 
102
    if they want the shorter key sequence, or if they're about to type
 
103
    more to complete the longer key sequence.
 
104
 
 
105
    \sa activated()
 
106
*/
 
107
 
 
108
/*
 
109
    \internal
 
110
    Private data accessed through d-pointer.
 
111
*/
 
112
class QShortcutPrivate : public QObjectPrivate
 
113
{
 
114
    Q_DECLARE_PUBLIC(QShortcut)
 
115
public:
 
116
    QShortcutPrivate() : sc_context(Qt::WindowShortcut), sc_enabled(true), sc_id(0) {}
 
117
    QKeySequence sc_sequence;
 
118
    Qt::ShortcutContext sc_context;
 
119
    bool sc_enabled;
 
120
    int sc_id;
 
121
    QString sc_whatsthis;
 
122
    void redoGrab(QShortcutMap &map);
 
123
};
 
124
 
 
125
void QShortcutPrivate::redoGrab(QShortcutMap &map)
 
126
{
 
127
    Q_Q(QShortcut);
 
128
    QWidget *parent = q->parentWidget();
 
129
    if (!parent) {
 
130
        qWarning("QShortcut: no widget parent defined");
 
131
        return;
 
132
    }
 
133
 
 
134
    if (sc_id)
 
135
        map.removeShortcut(sc_id, q);
 
136
    if (sc_sequence.isEmpty())
 
137
        return;
 
138
    sc_id = map.addShortcut(q, sc_sequence, sc_context);
 
139
    if (!sc_enabled)
 
140
        map.setShortcutEnabled(false, sc_id, q);
 
141
}
 
142
 
 
143
/*!
 
144
    Constructs a QShortcut object for the \a parent widget. Since no
 
145
    shortcut key sequence is specified, the shortcut will not emit any
 
146
    signals.
 
147
 
 
148
    \sa setKey()
 
149
*/
 
150
QShortcut::QShortcut(QWidget *parent)
 
151
    : QObject(*new QShortcutPrivate, parent)
 
152
{
 
153
    Q_ASSERT(parent != 0);
 
154
}
 
155
 
 
156
/*!
 
157
    Constructs a QShortcut object for the \a parent widget. The shortcut
 
158
    operates on its parent, listening for \l{QShortcutEvent}s that
 
159
    match the \a key sequence. Depending on the ambiguity of the
 
160
    event, the shortcut will call the \a member function, or the \a
 
161
    ambiguousMember function, if the key press was in the shortcut's
 
162
    \a context.
 
163
*/
 
164
QShortcut::QShortcut(const QKeySequence &key, QWidget *parent,
 
165
                     const char *member, const char *ambiguousMember,
 
166
                     Qt::ShortcutContext context)
 
167
    : QObject(*new QShortcutPrivate, parent)
 
168
{
 
169
    Q_D(QShortcut);
 
170
    Q_ASSERT(parent != 0);
 
171
    d->sc_context = context;
 
172
    d->sc_sequence = key;
 
173
    d->redoGrab(qApp->d_func()->shortcutMap);
 
174
    if (member)
 
175
        connect(this, SIGNAL(activated()), parent, member);
 
176
    if (ambiguousMember)
 
177
        connect(this, SIGNAL(activatedAmbiguously()), parent, ambiguousMember);
 
178
}
 
179
 
 
180
/*!
 
181
    Destroys the shortcut.
 
182
*/
 
183
QShortcut::~QShortcut()
 
184
{
 
185
    Q_D(QShortcut);
 
186
    if (qApp)
 
187
        qApp->d_func()->shortcutMap.removeShortcut(d->sc_id, this);
 
188
}
 
189
 
 
190
/*!
 
191
    \property QShortcut::key
 
192
    \brief the shortcut's key sequence
 
193
 
 
194
    This is a key sequence with an optional combination of Shift, Ctrl,
 
195
    and Alt. The key sequence may be supplied in a number of ways:
 
196
 
 
197
    \code
 
198
        setKey(0);                  // no signal emitted
 
199
        setKey(QKeySequence());     // no signal emitted
 
200
        setKey(0x3b1);              // Greek letter alpha
 
201
        setKey(Qt::Key_D);              // 'd', e.g. to delete
 
202
        setKey('q');                // 'q', e.g. to quit
 
203
        setKey(Qt::CTRL + Qt::Key_P);       // Ctrl+P, e.g. to print document
 
204
        setKey("Ctrl+P");           // Ctrl+P, e.g. to print document
 
205
    \endcode
 
206
*/
 
207
void QShortcut::setKey(const QKeySequence &key)
 
208
{
 
209
    Q_D(QShortcut);
 
210
    if (d->sc_sequence == key)
 
211
        return;
 
212
    d->sc_sequence = key;
 
213
    d->redoGrab(qApp->d_func()->shortcutMap);
 
214
}
 
215
 
 
216
QKeySequence QShortcut::key() const
 
217
{
 
218
    Q_D(const QShortcut);
 
219
    return d->sc_sequence;
 
220
}
 
221
 
 
222
/*!
 
223
    \property QShortcut::enabled
 
224
    \brief whether the shortcut is enabled
 
225
 
 
226
    An enabled shortcut emits the activated() or activatedAmbiguously()
 
227
    signal when a QShortcutEvent occurs that matches the shortcut's
 
228
    key() sequence.
 
229
 
 
230
    If the application is in \c WhatsThis mode the shortcut will not emit
 
231
    the signals, but will show the "What's This?" text instead.
 
232
 
 
233
    \sa whatsThis
 
234
*/
 
235
void QShortcut::setEnabled(bool enable)
 
236
{
 
237
    Q_D(QShortcut);
 
238
    if (d->sc_enabled == enable)
 
239
        return;
 
240
    d->sc_enabled = enable;
 
241
    qApp->d_func()->shortcutMap.setShortcutEnabled(enable, d->sc_id, this);
 
242
}
 
243
 
 
244
bool QShortcut::isEnabled() const
 
245
{
 
246
    Q_D(const QShortcut);
 
247
    return d->sc_enabled;
 
248
}
 
249
 
 
250
/*!
 
251
    \property QShortcut::context
 
252
    \brief the context in which the shortcut is valid
 
253
 
 
254
    A shortcut's context decides in which circumstances a shortcut is
 
255
    allowed to be triggered. The normal context is Qt::WindowShortcut,
 
256
    which allows the shortcut to trigger if the parent (the widget
 
257
    containing the shortcut) is a subwidget of the active top-level
 
258
    window.
 
259
*/
 
260
void QShortcut::setContext(Qt::ShortcutContext context)
 
261
{
 
262
    Q_D(QShortcut);
 
263
    if(d->sc_context == context)
 
264
        return;
 
265
    d->sc_context = context;
 
266
    d->redoGrab(qApp->d_func()->shortcutMap);
 
267
}
 
268
 
 
269
Qt::ShortcutContext QShortcut::context()
 
270
{
 
271
    Q_D(QShortcut);
 
272
    return d->sc_context;
 
273
}
 
274
 
 
275
/*!
 
276
    \property QShortcut::whatsThis
 
277
    \brief the shortcut's "What's This?" help text
 
278
 
 
279
    The text will be shown when the application is in "What's
 
280
    This?" mode and the user types the shortcut key() sequence.
 
281
 
 
282
    To set "What's This?" help on a menu item (with or without a
 
283
    shortcut key), set the help on the item's action.
 
284
 
 
285
    \sa QWhatsThis::inWhatsThisMode(), QAction::setWhatsThis()
 
286
*/
 
287
void QShortcut::setWhatsThis(const QString &text)
 
288
{
 
289
    Q_D(QShortcut);
 
290
    d->sc_whatsthis = text;
 
291
}
 
292
 
 
293
QString QShortcut::whatsThis() const
 
294
{
 
295
    Q_D(const QShortcut);
 
296
    return d->sc_whatsthis;
 
297
}
 
298
 
 
299
/*!
 
300
    Returns the shortcut's ID.
 
301
 
 
302
    \sa QShortcutEvent::shortcutId()
 
303
*/
 
304
int QShortcut::id() const
 
305
{
 
306
    Q_D(const QShortcut);
 
307
    return d->sc_id;
 
308
}
 
309
 
 
310
/*!
 
311
    \internal
 
312
*/
 
313
bool QShortcut::event(QEvent *e)
 
314
{
 
315
    Q_D(QShortcut);
 
316
    bool handled = false;
 
317
    if (d->sc_enabled && e->type() == QEvent::Shortcut) {
 
318
        QShortcutEvent *se = static_cast<QShortcutEvent *>(e);
 
319
        if (se->shortcutId() == d->sc_id && se->key() == d->sc_sequence){
 
320
#ifndef QT_NO_WHATSTHIS
 
321
            if (QWhatsThis::inWhatsThisMode()) {
 
322
                QWhatsThis::showText(QCursor::pos(), d->sc_whatsthis);
 
323
                handled = true;
 
324
            } else
 
325
#endif
 
326
            if (se->isAmbiguous())
 
327
                emit activatedAmbiguously();
 
328
            else
 
329
                emit activated();
 
330
            handled = true;
 
331
        }
 
332
    }
 
333
    return handled;
 
334
}