1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
9 \brief Classes used to create and handle events.
11 These \l{Qt Core} classes are used to create and handle events.
13 For more information see the \l{The Event System}{Event System} page.
18 \page eventsandfilters.html
19 \title The Event System
20 \ingroup qt-basic-concepts
21 \brief A guide to event handling in Qt.
23 \ingroup frameworks-technologies
25 In Qt, events are objects, derived from the abstract QEvent class,
26 that represent things that have happened either within an application
27 or as a result of outside activity that the application needs to know
28 about. Events can be received and handled by any instance of a
29 QObject subclass, but they are especially relevant to widgets. This
30 document describes how events are delivered and handled in a typical
33 \section1 How Events are Delivered
35 When an event occurs, Qt creates an event object to represent it by
36 constructing an instance of the appropriate QEvent subclass, and
37 delivers it to a particular instance of QObject (or one of its
38 subclasses) by calling its \l{QObject::}{event()} function.
40 This function does not handle the event itself; based on the type
41 of event delivered, it calls an event handler for that specific
42 type of event, and sends a response based on whether the event
43 was accepted or ignored.
46 Event delivery means that an
47 event has occurred, the QEvent indicates precisely what, and the
48 QObject needs to respond. Most events are specific to QWidget and its
49 subclasses, but there are important events that aren't related to
50 graphics (e.g., \l{QTimer}{timer events}).
53 Some events, such as QMouseEvent and QKeyEvent, come from the
54 window system; some, such as QTimerEvent, come from other sources;
55 some come from the application itself.
59 Most event types have special classes, notably QResizeEvent,
60 QPaintEvent, QMouseEvent, QKeyEvent, and QCloseEvent. Each class
61 subclasses QEvent and adds event-specific functions. For example,
62 QResizeEvent adds \l{QResizeEvent::}{size()} and
63 \l{QResizeEvent::}{oldSize()} to enable widgets to discover how
64 their dimensions have been changed.
66 Some classes support more than one actual event type. QMouseEvent
67 supports mouse button presses, double-clicks, moves, and other
70 Each event has an associated type, defined in QEvent::Type, and this
71 can be used as a convenient source of run-time type information to
72 quickly determine which subclass a given event object was constructed
75 Since programs need to react in varied and complex ways, Qt's
76 event delivery mechanisms are flexible. The documentation for
77 QCoreApplication::notify() concisely tells the whole story; the
78 \e{Qt Quarterly} article
79 \l{http://doc.qt.io/archives/qq/qq11-events.html}{Another Look at Events}
80 rehashes it less concisely. Here we will explain enough for 95%
83 \section1 Event Handlers
85 The normal way for an event to be delivered is by calling a virtual
86 function. For example, QPaintEvent is delivered by calling
87 QWidget::paintEvent(). This virtual function is responsible for
88 reacting appropriately, normally by repainting the widget. If you
89 do not perform all the necessary work in your implementation of the
90 virtual function, you may need to call the base class's implementation.
92 For example, the following code handles left mouse button clicks on
93 a custom checkbox widget while passing all other button clicks to the
96 \snippet events/events.cpp 0
98 If you want to replace the base class's function, you must
99 implement everything yourself. However, if you only want to extend
100 the base class's functionality, then you implement what you want and
101 call the base class to obtain the default behavior for any cases you
102 do not want to handle.
104 Occasionally, there isn't such an event-specific function, or the
105 event-specific function isn't sufficient. The most common example
106 involves Tab key presses. Normally, QWidget intercepts these to
107 move the keyboard focus, but a few widgets need the Tab key for
110 These objects can reimplement QObject::event(), the general event
111 handler, and either do their event handling before or after the usual
112 handling, or they can replace the function completely. A very unusual
113 widget that both interprets Tab and has an application-specific
114 custom event might contain the following \l{QObject::event()}{event()}
117 \snippet events/events.cpp 1
119 Note that QWidget::event() is still called for all of the cases not
120 handled, and that the return value indicates whether an event was
121 dealt with; a \c true value prevents the event from being sent on
124 \section1 Event Filters
126 Sometimes an object needs to look at, and possibly intercept, the
127 events that are delivered to another object. For example, dialogs
128 commonly want to filter key presses for some widgets; for example,
129 to modify Return-key handling.
131 The QObject::installEventFilter() function enables this by setting
132 up an \e{event filter}, causing a nominated filter object to receive
133 the events for a target object in its QObject::eventFilter()
134 function. An event filter gets to process events before the target
135 object does, allowing it to inspect and discard the events as
136 required. An existing event filter can be removed using the
137 QObject::removeEventFilter() function.
139 When the filter object's \l{QObject::}{eventFilter()} implementation
140 is called, it can accept or reject the event, and allow or deny
141 further processing of the event. If all the event filters allow
142 further processing of an event (by each returning \c false), the event
143 is sent to the target object itself. If one of them stops processing
144 (by returning \c true), the target and any later event filters do not
145 get to see the event at all.
147 \snippet eventfilters/filterobject.cpp 0
149 The above code shows another way to intercept Tab key press
150 events sent to a particular target widget. In this case, the filter
151 handles the relevant events and returns \c true to stop them from
152 being processed any further. All other events are ignored, and the
153 filter returns \c false to allow them to be sent on to the target
154 widget, via any other event filters that are installed on it.
156 It is also possible to filter \e all events for the entire application,
157 by installing an event filter on the QApplication or QCoreApplication
158 object. Such global event filters are called before the object-specific
159 filters. This is very powerful, but it also slows down event delivery
160 of every single event in the entire application; the other techniques
161 discussed should generally be used instead.
163 \section1 Sending Events
165 Many applications want to create and send their own events. You can
166 send events in exactly the same ways as Qt's own event loop by
167 constructing suitable event objects and sending them with
168 QCoreApplication::sendEvent() and QCoreApplication::postEvent().
170 \l{QCoreApplication::}{sendEvent()} processes the event immediately.
171 When it returns, the event filters and/or the object itself have
172 already processed the event. For many event classes there is a function
173 called \l{QEvent::}{isAccepted()} that tells you whether the event was accepted
174 or rejected by the last handler that was called.
176 \l{QCoreApplication::}{postEvent()} posts the event on a queue for
177 later dispatch. The next time Qt's main event loop runs, it dispatches
178 all posted events, with some optimization. For example, if there are
179 several resize events, they are compressed into one. The same
180 applies to paint events: QWidget::update() calls
181 \l{QCoreApplication::}{postEvent()}, which eliminates flickering and
182 increases speed by avoiding multiple repaints.
184 \l{QCoreApplication::}{postEvent()} is also used during object
185 initialization, since the posted event will typically be dispatched
186 very soon after the initialization of the object is complete.
187 When implementing a widget, it is important to realize that events
188 can be delivered very early in its lifetime so, in its constructor,
189 be sure to initialize member variables early on, before there's any
190 chance that it might receive an event.
192 To create events of a custom type, you need to define an event
193 number, which must be greater than QEvent::User, and you may need to
194 subclass QEvent in order to pass specific information about your
195 custom event. See the QEvent documentation for further details.
1.10.0