← Back to branch summary

~ubuntu-branches/ubuntu/wily/qtbase-opensource-src/wily

« back to all changes in this revision

Viewing changes to src/corelib/doc/src/eventsandfilters.qdoc

  • Committer: Package Import Robot
  • Author(s): Timo Jyrinki
  • Date: 2013-02-05 12:46:17 UTC
  • Revision ID: package-import@ubuntu.com-20130205124617-c8jouts182j002fx
Tags: upstream-5.0.1+dfsg
Import upstream version 5.0.1+dfsg

Show diffs side-by-side

added added

removed removed

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