<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- eventsandfilters.qdoc -->
<title>Qt 4.8: The Event System</title>
<link rel="stylesheet" type="text/css" href="style/style.css" />
<script src="scripts/jquery.js" type="text/javascript"></script>
<script src="scripts/functions.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="style/superfish.css" />
<link rel="stylesheet" type="text/css" href="style/narrow.css" />
<!--[if IE]>
<meta name="MSSmartTagsPreventParsing" content="true">
<meta http-equiv="imagetoolbar" content="no">
<![endif]-->
<!--[if lt IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie6.css">
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie7.css">
<![endif]-->
<!--[if IE 8]>
<link rel="stylesheet" type="text/css" href="style/style_ie8.css">
<![endif]-->
<script src="scripts/superfish.js" type="text/javascript"></script>
<script src="scripts/narrow.js" type="text/javascript"></script>
</head>
<body class="" onload="CheckEmptyAndLoadList();">
<div class="header" id="qtdocheader">
<div class="content">
<div id="nav-logo">
<a href="index.html">Home</a></div>
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
<div id="narrowsearch"></div>
<div id="nav-topright">
<ul>
<li class="nav-topright-home"><a href="http://qt.digia.com/">Qt HOME</a></li>
<li class="nav-topright-dev"><a href="http://qt-project.org/">DEV</a></li>
<li class="nav-topright-doc nav-topright-doc-active"><a href="http://qt-project.org/doc/">
DOC</a></li>
<li class="nav-topright-blog"><a href="http://blog.qt.digia.com/">BLOG</a></li>
</ul>
</div>
<div id="shortCut">
<ul>
<li class="shortCut-topleft-inactive"><span><a href="index.html">Qt 4.8</a></span></li>
<li class="shortCut-topleft-active"><a href="http://qt-project.org/doc/">ALL VERSIONS </a></li>
</ul>
</div>
<ul class="sf-menu" id="narrowmenu">
<li><a href="#">API Lookup</a>
<ul>
<li><a href="classes.html">Class index</a></li>
<li><a href="functions.html">Function index</a></li>
<li><a href="modules.html">Modules</a></li>
<li><a href="namespaces.html">Namespaces</a></li>
<li><a href="qtglobal.html">Global Declarations</a></li>
<li><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</li>
<li><a href="#">Qt Topics</a>
<ul>
<li><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li><a href="supported-platforms.html">Supported Platforms</a></li>
<li><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</li>
<li><a href="#">Examples</a>
<ul>
<li><a href="all-examples.html">Examples</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="demos.html">Demos</a></li>
<li><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="wrapper">
<div class="hd">
<span></span>
</div>
<div class="bd group">
<div class="sidebar">
<div class="searchlabel">
Search index:</div>
<div class="search" id="sidebarsearch">
<form id="qtdocsearch" action="" onsubmit="return false;">
<fieldset>
<input type="text" name="searchstring" id="pageType" value="" />
<div id="resultdialog">
<a href="#" id="resultclose">Close</a>
<p id="resultlinks" class="all"><a href="#" id="showallresults">All</a> | <a href="#" id="showapiresults">API</a> | <a href="#" id="showarticleresults">Articles</a> | <a href="#" id="showexampleresults">Examples</a></p>
<p id="searchcount" class="all"><span id="resultcount"></span><span id="apicount"></span><span id="articlecount"></span><span id="examplecount"></span> results:</p>
<ul id="resultlist" class="all">
</ul>
</div>
</fieldset>
</form>
</div>
<div class="box first bottombar" id="lookup">
<h2 title="API Lookup"><span></span>
API Lookup</h2>
<div id="list001" class="list">
<ul id="ul001" >
<li class="defaultLink"><a href="classes.html">Class index</a></li>
<li class="defaultLink"><a href="functions.html">Function index</a></li>
<li class="defaultLink"><a href="modules.html">Modules</a></li>
<li class="defaultLink"><a href="namespaces.html">Namespaces</a></li>
<li class="defaultLink"><a href="qtglobal.html">Global Declarations</a></li>
<li class="defaultLink"><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</div>
</div>
<div class="box bottombar" id="topics">
<h2 title="Qt Topics"><span></span>
Qt Topics</h2>
<div id="list002" class="list">
<ul id="ul002" >
<li class="defaultLink"><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li class="defaultLink"><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li class="defaultLink"><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li class="defaultLink"><a href="supported-platforms.html">Supported Platforms</a></li>
<li class="defaultLink"><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li class="defaultLink"><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</div>
</div>
<div class="box" id="examples">
<h2 title="Examples"><span></span>
Examples</h2>
<div id="list003" class="list">
<ul id="ul003">
<li class="defaultLink"><a href="all-examples.html">Examples</a></li>
<li class="defaultLink"><a href="tutorials.html">Tutorials</a></li>
<li class="defaultLink"><a href="demos.html">Demos</a></li>
<li class="defaultLink"><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</div>
</div>
</div>
<div class="wrap">
<div class="toolbar">
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li>The Event System</li>
</ul>
</div>
<div class="toolbuttons toolblock">
<ul>
<li id="smallA" class="t_button">A</li>
<li id="medA" class="t_button active">A</li>
<li id="bigA" class="t_button">A</li>
<li id="print" class="t_button"><a href="javascript:this.print();">
<span>Print</span></a></li>
</ul>
</div>
</div>
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#how-events-are-delivered">How Events are Delivered</a></li>
<li class="level1"><a href="#event-types">Event Types</a></li>
<li class="level1"><a href="#event-handlers">Event Handlers</a></li>
<li class="level1"><a href="#event-filters">Event Filters</a></li>
<li class="level1"><a href="#sending-events">Sending Events</a></li>
</ul>
</div>
<h1 class="title">The Event System</h1>
<span class="subtitle"></span>
<!-- $$$eventsandfilters.html-description -->
<div class="descr"> <a name="details"></a>
<p>In Qt, events are objects, derived from the abstract <a href="qevent.html">QEvent</a> class, that represent things that have happened either within an application or as a result of outside activity that the application needs to know about. Events can be received and handled by any instance of a <a href="qobject.html">QObject</a> subclass, but they are especially relevant to widgets. This document describes how events are delivered and handled in a typical application.</p>
<a name="how-events-are-delivered"></a>
<h2>How Events are Delivered</h2>
<p>When an event occurs, Qt creates an event object to represent it by constructing an instance of the appropriate <a href="qevent.html">QEvent</a> subclass, and delivers it to a particular instance of <a href="qobject.html">QObject</a> (or one of its subclasses) by calling its <a href="qobject.html#event">event()</a> function.</p>
<p>This function does not handle the event itself; based on the type of event delivered, it calls an event handler for that specific type of event, and sends a response based on whether the event was accepted or ignored.</p>
<p>Some events, such as <a href="qmouseevent.html">QMouseEvent</a> and <a href="qkeyevent.html">QKeyEvent</a>, come from the window system; some, such as <a href="qtimerevent.html">QTimerEvent</a>, come from other sources; some come from the application itself.</p>
<a name="event-types"></a>
<h2>Event Types</h2>
<p>Most events types have special classes, notably <a href="qresizeevent.html">QResizeEvent</a>, <a href="qpaintevent.html">QPaintEvent</a>, <a href="qmouseevent.html">QMouseEvent</a>, <a href="qkeyevent.html">QKeyEvent</a>, and <a href="qcloseevent.html">QCloseEvent</a>. Each class subclasses <a href="qevent.html">QEvent</a> and adds event-specific functions. For example, <a href="qresizeevent.html">QResizeEvent</a> adds <a href="qresizeevent.html#size">size()</a> and <a href="qresizeevent.html#oldSize">oldSize()</a> to enable widgets to discover how their dimensions have been changed.</p>
<p>Some classes support more than one actual event type. <a href="qmouseevent.html">QMouseEvent</a> supports mouse button presses, double-clicks, moves, and other related operations.</p>
<p>Each event has an associated type, defined in <a href="qevent.html#Type-enum">QEvent::Type</a>, and this can be used as a convenient source of run-time type information to quickly determine which subclass a given event object was constructed from.</p>
<p>Since programs need to react in varied and complex ways, Qt's event delivery mechanisms are flexible. The documentation for <a href="qcoreapplication.html#notify">QCoreApplication::notify</a>() concisely tells the whole story; the <i>Qt Quarterly</i> article <a href="http://doc.qt.digia.com/qq/qq11-events.html">Another Look at Events</a> rehashes it less concisely. Here we will explain enough for 95% of applications.</p>
<a name="event-handlers"></a>
<h2>Event Handlers</h2>
<p>The normal way for an event to be delivered is by calling a virtual function. For example, <a href="qpaintevent.html">QPaintEvent</a> is delivered by calling <a href="qwidget.html#paintEvent">QWidget::paintEvent</a>(). This virtual function is responsible for reacting appropriately, normally by repainting the widget. If you do not perform all the necessary work in your implementation of the virtual function, you may need to call the base class's implementation.</p>
<p>For example, the following code handles left mouse button clicks on a custom checkbox widget while passing all other button clicks to the base <a href="qcheckbox.html">QCheckBox</a> class:</p>
<pre class="cpp"> <span class="type">void</span> MyCheckBox<span class="operator">::</span>mousePressEvent(<span class="type"><a href="qmouseevent.html">QMouseEvent</a></span> <span class="operator">*</span>event)
{
<span class="keyword">if</span> (event<span class="operator">-</span><span class="operator">></span>button() <span class="operator">=</span><span class="operator">=</span> <span class="type"><a href="qt.html">Qt</a></span><span class="operator">::</span>LeftButton) {
<span class="comment">// handle left mouse button here</span>
} <span class="keyword">else</span> {
<span class="comment">// pass on other buttons to base class</span>
<span class="type"><a href="qcheckbox.html">QCheckBox</a></span><span class="operator">::</span>mousePressEvent(event);
}
}</pre>
<p>If you want to replace the base class's function, you must implement everything yourself. However, if you only want to extend the base class's functionality, then you implement what you want and call the base class to obtain the default behavior for any cases you do not want to handle.</p>
<p>Occasionally, there isn't such an event-specific function, or the event-specific function isn't sufficient. The most common example involves <b>Tab</b> key presses. Normally, <a href="qwidget.html">QWidget</a> intercepts these to move the keyboard focus, but a few widgets need the <b>Tab</b> key for themselves.</p>
<p>These objects can reimplement <a href="qobject.html#event">QObject::event</a>(), the general event handler, and either do their event handling before or after the usual handling, or they can replace the function completely. A very unusual widget that both interprets <b>Tab</b> and has an application-specific custom event might contain the following <a href="qobject.html#event">event()</a> function:</p>
<pre class="cpp"> <span class="type">bool</span> MyWidget<span class="operator">::</span>event(<span class="type"><a href="qevent.html">QEvent</a></span> <span class="operator">*</span>event)
{
<span class="keyword">if</span> (event<span class="operator">-</span><span class="operator">></span>type() <span class="operator">=</span><span class="operator">=</span> <span class="type"><a href="qevent.html">QEvent</a></span><span class="operator">::</span>KeyPress) {
<span class="type"><a href="qkeyevent.html">QKeyEvent</a></span> <span class="operator">*</span>ke <span class="operator">=</span> <span class="keyword">static_cast</span><span class="operator"><</span><span class="type"><a href="qkeyevent.html">QKeyEvent</a></span> <span class="operator">*</span><span class="operator">></span>(event);
<span class="keyword">if</span> (ke<span class="operator">-</span><span class="operator">></span>key() <span class="operator">=</span><span class="operator">=</span> <span class="type"><a href="qt.html">Qt</a></span><span class="operator">::</span>Key_Tab) {
<span class="comment">// special tab handling here</span>
<span class="keyword">return</span> <span class="keyword">true</span>;
}
} <span class="keyword">else</span> <span class="keyword">if</span> (event<span class="operator">-</span><span class="operator">></span>type() <span class="operator">=</span><span class="operator">=</span> MyCustomEventType) {
MyCustomEvent <span class="operator">*</span>myEvent <span class="operator">=</span> <span class="keyword">static_cast</span><span class="operator"><</span>MyCustomEvent <span class="operator">*</span><span class="operator">></span>(event);
<span class="comment">// custom event handling here</span>
<span class="keyword">return</span> <span class="keyword">true</span>;
}
<span class="keyword">return</span> <span class="type"><a href="qwidget.html">QWidget</a></span><span class="operator">::</span>event(event);
}</pre>
<p>Note that <a href="qwidget.html#event">QWidget::event</a>() is still called for all of the cases not handled, and that the return value indicates whether an event was dealt with; a <tt>true</tt> value prevents the event from being sent on to other objects.</p>
<a name="event-filters"></a>
<h2>Event Filters</h2>
<p>Sometimes an object needs to look at, and possibly intercept, the events that are delivered to another object. For example, dialogs commonly want to filter key presses for some widgets; for example, to modify <b>Return</b>-key handling.</p>
<p>The <a href="qobject.html#installEventFilter">QObject::installEventFilter</a>() function enables this by setting up an <i>event filter</i>, causing a nominated filter object to receive the events for a target object in its <a href="qobject.html#eventFilter">QObject::eventFilter</a>() function. An event filter gets to process events before the target object does, allowing it to inspect and discard the events as required. An existing event filter can be removed using the <a href="qobject.html#removeEventFilter">QObject::removeEventFilter</a>() function.</p>
<p>When the filter object's <a href="qobject.html#eventFilter">eventFilter()</a> implementation is called, it can accept or reject the event, and allow or deny further processing of the event. If all the event filters allow further processing of an event (by each returning <tt>false</tt>), the event is sent to the target object itself. If one of them stops processing (by returning <tt>true</tt>), the target and any later event filters do not get to see the event at all.</p>
<pre class="cpp"> <span class="type">bool</span> FilterObject<span class="operator">::</span>eventFilter(<span class="type"><a href="qobject.html">QObject</a></span> <span class="operator">*</span>object<span class="operator">,</span> <span class="type"><a href="qevent.html">QEvent</a></span> <span class="operator">*</span>event)
{
<span class="keyword">if</span> (object <span class="operator">=</span><span class="operator">=</span> target <span class="operator">&</span><span class="operator">&</span> event<span class="operator">-</span><span class="operator">></span>type() <span class="operator">=</span><span class="operator">=</span> <span class="type"><a href="qevent.html">QEvent</a></span><span class="operator">::</span>KeyPress) {
<span class="type"><a href="qkeyevent.html">QKeyEvent</a></span> <span class="operator">*</span>keyEvent <span class="operator">=</span> <span class="keyword">static_cast</span><span class="operator"><</span><span class="type"><a href="qkeyevent.html">QKeyEvent</a></span> <span class="operator">*</span><span class="operator">></span>(event);
<span class="keyword">if</span> (keyEvent<span class="operator">-</span><span class="operator">></span>key() <span class="operator">=</span><span class="operator">=</span> <span class="type"><a href="qt.html">Qt</a></span><span class="operator">::</span>Key_Tab) {
<span class="comment">// Special tab handling</span>
<span class="keyword">return</span> <span class="keyword">true</span>;
} <span class="keyword">else</span>
<span class="keyword">return</span> <span class="keyword">false</span>;
}
<span class="keyword">return</span> <span class="keyword">false</span>;
}</pre>
<p>The above code shows another way to intercept <b>Tab</b> key press events sent to a particular target widget. In this case, the filter handles the relevant events and returns <tt>true</tt> to stop them from being processed any further. All other events are ignored, and the filter returns <tt>false</tt> to allow them to be sent on to the target widget, via any other event filters that are installed on it.</p>
<p>It is also possible to filter <i>all</i> events for the entire application, by installing an event filter on the <a href="qapplication.html">QApplication</a> or <a href="qcoreapplication.html">QCoreApplication</a> object. Such global event filters are called before the object-specific filters. This is very powerful, but it also slows down event delivery of every single event in the entire application; the other techniques discussed should generally be used instead.</p>
<a name="sending-events"></a>
<h2>Sending Events</h2>
<p>Many applications want to create and send their own events. You can send events in exactly the same ways as Qt's own event loop by constructing suitable event objects and sending them with <a href="qcoreapplication.html#sendEvent">QCoreApplication::sendEvent</a>() and <a href="qcoreapplication.html#postEvent">QCoreApplication::postEvent</a>().</p>
<p><a href="qcoreapplication.html#sendEvent">sendEvent()</a> processes the event immediately. When it returns, the event filters and/or the object itself have already processed the event. For many event classes there is a function called isAccepted() that tells you whether the event was accepted or rejected by the last handler that was called.</p>
<p><a href="qcoreapplication.html#postEvent">postEvent()</a> posts the event on a queue for later dispatch. The next time Qt's main event loop runs, it dispatches all posted events, with some optimization. For example, if there are several resize events, they are compressed into one. The same applies to paint events: <a href="qwidget.html#update">QWidget::update</a>() calls <a href="qcoreapplication.html#postEvent">postEvent()</a>, which eliminates flickering and increases speed by avoiding multiple repaints.</p>
<p><a href="qcoreapplication.html#postEvent">postEvent()</a> is also used during object initialization, since the posted event will typically be dispatched very soon after the initialization of the object is complete. When implementing a widget, it is important to realise that events can be delivered very early in its lifetime so, in its constructor, be sure to initialize member variables early on, before there's any chance that it might receive an event.</p>
<p>To create events of a custom type, you need to define an event number, which must be greater than <a href="qevent.html#Type-enum">QEvent::User</a>, and you may need to subclass <a href="qevent.html">QEvent</a> in order to pass specific information about your custom event. See the <a href="qevent.html">QEvent</a> documentation for further details.</p>
</div>
<!-- @@@eventsandfilters.html -->
</div>
</div>
</div>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2015 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Qt and respective logos are trademarks of The Qt Company Ltd
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
<script src="scripts/functions.js" type="text/javascript"></script>
</body>
</html>
