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 classes are used to create and handle events.
  36
  37     For more information see the \link object.html Object model\endlink
  38     and \link signalsandslots.html Signals and Slots\endlink.
  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.nokia.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 */