1 /****************************************************************************
3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/legal
6 ** This file is part of the documentation of the Qt Toolkit.
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.
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.
26 ****************************************************************************/
33 \brief Classes used to create and handle events.
35 These classes are used to create and handle events.
37 For more information see the \link object.html Object model\endlink
38 and \link signalsandslots.html Signals and Slots\endlink.
42 \page eventsandfilters.html
43 \title The Event System
44 \ingroup qt-basic-concepts
45 \brief A guide to event handling in Qt.
47 \ingroup frameworks-technologies
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
57 \section1 How Events are Delivered
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.
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.
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}).
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.
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.
90 Some classes support more than one actual event type. QMouseEvent
91 supports mouse button presses, double-clicks, moves, and other
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
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.nokia.com/qq/qq11-events.html}{Another Look at Events}
104 rehashes it less concisely. Here we will explain enough for 95%
107 \section1 Event Handlers
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.
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:
120 \snippet events/events.cpp 0
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.
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
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()}
141 \snippet events/events.cpp 1
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
148 \section1 Event Filters
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.
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.
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.
171 \snippet eventfilters/filterobject.cpp 0
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.
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.
187 \section1 Sending Events
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().
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.
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.
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.
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.