← Back to branch summary

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

« back to all changes in this revision

Viewing changes to doc/src/frameworks-technologies/eventsandfilters.qdoc

  • Committer: Bazaar Package Importer
  • Author(s): Alessandro Ghersi
  • Date: 2009-11-02 18:30:08 UTC
  • mfrom: (1.2.2 upstream)
  • mto: (15.2.5 experimental)
  • mto: This revision was merged to the branch mainline in revision 88.
  • Revision ID: james.westby@ubuntu.com-20091102183008-b6a4gcs128mvfb3m
Tags: upstream-4.6.0~beta1
Import upstream version 4.6.0~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/frameworks-technologies/eventsandfilters.qdoc
 
1
/****************************************************************************
 
2
**
 
3
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
 
4
** All rights reserved.
 
5
** Contact: Nokia Corporation (qt-info@nokia.com)
 
6
**
 
7
** This file is part of the documentation of the Qt Toolkit.
 
8
**
 
9
** $QT_BEGIN_LICENSE:LGPL$
 
10
** No Commercial Usage
 
11
** This file contains pre-release code and may not be distributed.
 
12
** You may use this file in accordance with the terms and conditions
 
13
** contained in the Technology Preview License Agreement accompanying
 
14
** this package.
 
15
**
 
16
** GNU Lesser General Public License Usage
 
17
** Alternatively, this file may be used under the terms of the GNU Lesser
 
18
** General Public License version 2.1 as published by the Free Software
 
19
** Foundation and appearing in the file LICENSE.LGPL included in the
 
20
** packaging of this file.  Please review the following information to
 
21
** ensure the GNU Lesser General Public License version 2.1 requirements
 
22
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
 
23
**
 
24
** In addition, as a special exception, Nokia gives you certain additional
 
25
** rights.  These rights are described in the Nokia Qt LGPL Exception
 
26
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
 
27
**
 
28
** If you have questions regarding the use of this file, please contact
 
29
** Nokia at qt-info@nokia.com.
 
30
**
 
31
**
 
32
**
 
33
**
 
34
**
 
35
**
 
36
**
 
37
**
 
38
** $QT_END_LICENSE$
 
39
**
 
40
****************************************************************************/
 
41
 
 
42
/*!
 
43
    \group events
 
44
    \title Event Classes
 
45
    \ingroup groups
 
46
 
 
47
    \brief Classes used to create and handle events.
 
48
 
 
49
    These classes are used to create and handle events.
 
50
 
 
51
    For more information see the \link object.html Object model\endlink
 
52
    and \link signalsandslots.html Signals and Slots\endlink.
 
53
*/
 
54
 
 
55
/*!
 
56
    \page eventsandfilters.html
 
57
    \title Events and Event Filters
 
58
    \brief A guide to event handling in Qt.
 
59
 
 
60
    \ingroup frameworks-technologies
 
61
 
 
62
    In Qt, events are objects, derived from the abstract QEvent class,
 
63
    that represent things that have happened either within an application
 
64
    or as a result of outside activity that the application needs to know
 
65
    about. Events can be received and handled by any instance of a
 
66
    QObject subclass, but they are especially relevant to widgets. This
 
67
    document describes how events are delivered and handled in a typical
 
68
    application.
 
69
 
 
70
    \tableofcontents
 
71
 
 
72
    \section1 How Events are Delivered
 
73
 
 
74
    When an event occurs, Qt creates an event object to represent it by
 
75
    constructing an instance of the appropriate QEvent subclass, and
 
76
    delivers it to a particular instance of QObject (or one of its
 
77
    subclasses) by calling its \l{QObject::}{event()} function.
 
78
 
 
79
    This function does not handle the event itself; based on the type
 
80
    of event delivered, it calls an event handler for that specific
 
81
    type of event, and sends a response based on whether the event
 
82
    was accepted or ignored.
 
83
 
 
84
    \omit
 
85
    Event delivery means that an
 
86
    event has occurred, the QEvent indicates precisely what, and the
 
87
    QObject needs to respond. Most events are specific to QWidget and its
 
88
    subclasses, but there are important events that aren't related to
 
89
    graphics (e.g., \l{QTimer}{timer events}).
 
90
    \endomit
 
91
 
 
92
    Some events, such as QMouseEvent and QKeyEvent, come from the
 
93
    window system; some, such as QTimerEvent, come from other sources;
 
94
    some come from the application itself.
 
95
 
 
96
    \section1 Event Types
 
97
 
 
98
    Most events types have special classes, notably QResizeEvent,
 
99
    QPaintEvent, QMouseEvent, QKeyEvent, and QCloseEvent. Each class
 
100
    subclasses QEvent and adds event-specific functions. For example,
 
101
    QResizeEvent adds \l{QResizeEvent::}{size()} and
 
102
    \l{QResizeEvent::}{oldSize()} to enable widgets to discover how
 
103
    their dimensions have been changed.
 
104
 
 
105
    Some classes support more than one actual event type. QMouseEvent
 
106
    supports mouse button presses, double-clicks, moves, and other
 
107
    related operations.
 
108
 
 
109
    Each event has an associated type, defined in QEvent::Type, and this
 
110
    can be used as a convenient source of run-time type information to
 
111
    quickly determine which subclass a given event object was constructed
 
112
    from.
 
113
 
 
114
    Since programs need to react in varied and complex ways, Qt's
 
115
    event delivery mechanisms are flexible. The documentation for
 
116
    QCoreApplication::notify() concisely tells the whole story; the
 
117
    \e{Qt Quarterly} article
 
118
    \l{http://qt.nokia.com/doc/qq/qq11-events.html}{Another Look at Events}
 
119
    rehashes it less concisely. Here we will explain enough for 95%
 
120
    of applications.
 
121
 
 
122
    \section1 Event Handlers
 
123
 
 
124
    The normal way for an event to be delivered is by calling a virtual
 
125
    function. For example, QPaintEvent is delivered by calling
 
126
    QWidget::paintEvent(). This virtual function is responsible for
 
127
    reacting appropriately, normally by repainting the widget. If you
 
128
    do not perform all the necessary work in your implementation of the
 
129
    virtual function, you may need to call the base class's implementation.
 
130
 
 
131
    For example, the following code handles left mouse button clicks on
 
132
    a custom checkbox widget while passing all other button clicks to the
 
133
    base QCheckBox class:
 
134
 
 
135
    \snippet doc/src/snippets/events/events.cpp 0
 
136
 
 
137
    If you want to replace the base class's function, you must
 
138
    implement everything yourself. However, if you only want to extend
 
139
    the base class's functionality, then you implement what you want and
 
140
    call the base class to obtain the default behavior for any cases you
 
141
    do not want to handle.
 
142
 
 
143
    Occasionally, there isn't such an event-specific function, or the
 
144
    event-specific function isn't sufficient. The most common example
 
145
    involves \key Tab key presses. Normally, QWidget intercepts these to
 
146
    move the keyboard focus, but a few widgets need the \key{Tab} key for
 
147
    themselves.
 
148
 
 
149
    These objects can reimplement QObject::event(), the general event
 
150
    handler, and either do their event handling before or after the usual
 
151
    handling, or they can replace the function completely. A very unusual
 
152
    widget that both interprets \key Tab and has an application-specific
 
153
    custom event might contain the following \l{QObject::event()}{event()}
 
154
    function:
 
155
 
 
156
    \snippet doc/src/snippets/events/events.cpp 1
 
157
 
 
158
    Note that QWidget::event() is still called for all of the cases not
 
159
    handled, and that the return value indicates whether an event was
 
160
    dealt with; a \c true value prevents the event from being sent on
 
161
    to other objects.
 
162
 
 
163
    \section1 Event Filters
 
164
 
 
165
    Sometimes an object needs to look at, and possibly intercept, the
 
166
    events that are delivered to another object. For example, dialogs
 
167
    commonly want to filter key presses for some widgets; for example,
 
168
    to modify \key{Return}-key handling.
 
169
 
 
170
    The QObject::installEventFilter() function enables this by setting
 
171
    up an \e{event filter}, causing a nominated filter object to receive
 
172
    the events for a target object in its QObject::eventFilter()
 
173
    function. An event filter gets to process events before the target
 
174
    object does, allowing it to inspect and discard the events as
 
175
    required. An existing event filter can be removed using the
 
176
    QObject::removeEventFilter() function.
 
177
 
 
178
    When the filter object's \l{QObject::}{eventFilter()} implementation
 
179
    is called, it can accept or reject the event, and allow or deny
 
180
    further processing of the event. If all the event filters allow
 
181
    further processing of an event (by each returning \c false), the event
 
182
    is sent to the target object itself. If one of them stops processing
 
183
    (by returning \c true), the target and any later event filters do not
 
184
    get to see the event at all.
 
185
 
 
186
    \snippet doc/src/snippets/eventfilters/filterobject.cpp 0
 
187
 
 
188
    The above code shows another way to intercept \key{Tab} key press
 
189
    events sent to a particular target widget. In this case, the filter
 
190
    handles the relevant events and returns \c true to stop them from
 
191
    being processed any further. All other events are ignored, and the
 
192
    filter returns \c false to allow them to be sent on to the target
 
193
    widget, via any other event filters that are installed on it.
 
194
 
 
195
    It is also possible to filter \e all events for the entire application,
 
196
    by installing an event filter on the QApplication or QCoreApplication
 
197
    object. Such global event filters are called before the object-specific
 
198
    filters. This is very powerful, but it also slows down event delivery
 
199
    of every single event in the entire application; the other techniques
 
200
    discussed should generally be used instead.
 
201
 
 
202
    \section1 Sending Events
 
203
 
 
204
    Many applications want to create and send their own events. You can
 
205
    send events in exactly the same ways as Qt's own event loop by
 
206
    constructing suitable event objects and sending them with
 
207
    QCoreApplication::sendEvent() and QCoreApplication::postEvent().
 
208
 
 
209
    \l{QCoreApplication::}{sendEvent()} processes the event immediately.
 
210
    When it returns, the event filters and/or the object itself have
 
211
    already processed the event. For many event classes there is a function
 
212
    called isAccepted() that tells you whether the event was accepted
 
213
    or rejected by the last handler that was called.
 
214
 
 
215
    \l{QCoreApplication::}{postEvent()} posts the event on a queue for
 
216
    later dispatch. The next time Qt's main event loop runs, it dispatches
 
217
    all posted events, with some optimization. For example, if there are
 
218
    several resize events, they are are compressed into one. The same
 
219
    applies to paint events: QWidget::update() calls
 
220
    \l{QCoreApplication::}{postEvent()}, which eliminates flickering and
 
221
    increases speed by avoiding multiple repaints.
 
222
 
 
223
    \l{QCoreApplication::}{postEvent()} is also used during object
 
224
    initialization, since the posted event will typically be dispatched
 
225
    very soon after the initialization of the object is complete.
 
226
    When implementing a widget, it is important to realise that events
 
227
    can be delivered very early in its lifetime so, in its constructor,
 
228
    be sure to initialize member variables early on, before there's any
 
229
    chance that it might receive an event.
 
230
 
 
231
    To create events of a custom type, you need to define an event
 
232
    number, which must be greater than QEvent::User, and you may need to
 
233
    subclass QEvent in order to pass specific information about your
 
234
    custom event. See the QEvent documentation for further details.
 
235
*/