diff options
Diffstat (limited to 'doc/html/eventsandfilters.html')
| -rw-r--r-- | doc/html/eventsandfilters.html | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/doc/html/eventsandfilters.html b/doc/html/eventsandfilters.html new file mode 100644 index 0000000..74b4d09 --- /dev/null +++ b/doc/html/eventsandfilters.html @@ -0,0 +1,151 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/object.doc:433 --> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Events and Event Filters</title> +<style type="text/css"><!-- +fn { margin-left: 1cm; text-indent: -1cm; } +a:link { color: #004faf; text-decoration: none } +a:visited { color: #672967; text-decoration: none } +body { background: #ffffff; color: black; } +--></style> +</head> +<body> + +<table border="0" cellpadding="0" cellspacing="0" width="100%"> +<tr bgcolor="#E5E5E5"> +<td valign=center> + <a href="index.html"> +<font color="#004faf">Home</font></a> + | <a href="classes.html"> +<font color="#004faf">All Classes</font></a> + | <a href="mainclasses.html"> +<font color="#004faf">Main Classes</font></a> + | <a href="annotated.html"> +<font color="#004faf">Annotated</font></a> + | <a href="groups.html"> +<font color="#004faf">Grouped Classes</font></a> + | <a href="functions.html"> +<font color="#004faf">Functions</font></a> +</td> +<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>Events and Event Filters</h1> + + + +<p> In Qt, an event is an object that inherits <a href="qevent.html">QEvent</a>. Events are +delivered to objects that inherit <a href="qobject.html">QObject</a> through calling <a href="qobject.html#event">QObject::event</a>(). Event delivery means that an event has occurred, the +<a href="qevent.html">QEvent</a> indicates precisely what, and the <a href="qobject.html">QObject</a> needs to respond. Most +events are specific to <a href="qwidget.html">QWidget</a> and its subclasses, but there are +important events that aren't related to graphics, for example, socket +activation, which is the event used by <a href="qsocketnotifier.html">QSocketNotifier</a> for its +work. +<p> Some events come from the window system, e.g. <a href="qmouseevent.html">QMouseEvent</a>, some +from other sources, e.g. <a href="qtimerevent.html">QTimerEvent</a>, and some come from the +application program. Qt is symmetric, as usual, so you can send +events in exactly the same ways as Qt's own event loop does. +<p> Most events types have special classes, most commonly <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>. +There are many others, perhaps forty or so, but most are rather odd. +<p> Each class subclasses <a href="qevent.html">QEvent</a> and adds event-specific functions; see, +for example, <a href="qresizeevent.html">QResizeEvent</a>. In the case of <a href="qresizeevent.html">QResizeEvent</a>, <a href="qresizeevent.html#size">QResizeEvent::size</a>() and <a href="qresizeevent.html#oldSize">QResizeEvent::oldSize</a>() are added. +<p> Some classes support more than one event type. <a href="qmouseevent.html">QMouseEvent</a> +supports mouse moves, presses, shift-presses, drags, clicks, +right-presses, etc. +<p> Since programs need to react in varied and complex ways, Qt's +event delivery mechanisms are flexible. The documentation for +<a href="qapplication.html#notify">QApplication::notify</a>() concisely tells the whole story, here we +will explain enough for 99% of applications. +<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; for example: +<pre> + MyTable::contentsMouseMoveEvent( <a href="qmouseevent.html">QMouseEvent</a> *me ) + { + // my implementation + + QTable::<a href="qscrollview.html#contentsMouseMoveEvent">contentsMouseMoveEvent</a>( me ); // hand it on + } +</pre> + +If you want to replace the base class's function then you must +implement everything yourself; but if you only want to extend the base +class's functionality, then you implement what you want and then call +the base class. +<p> Occasionally there isn't such an event-specific function, or the +event-specific function isn't sufficient. The most common example is +tab key presses. Normally, those are interpreted by <a href="qwidget.html">QWidget</a> to move +the <a href="focus.html#keyboard-focus">keyboard focus</a>, but a few widgets need the tab key for themselves. +<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 replace it completely. A very unusual widget that both +interprets tab and has an application-specific custom event might +contain: +<p> <pre> + bool MyClass:event( <a href="qevent.html">QEvent</a> *evt ) { + if ( evt-><a href="qevent.html#type">type</a>() == QEvent::KeyPress ) { + <a href="qkeyevent.html">QKeyEvent</a> *ke = (QKeyEvent *)evt; + if ( ke-><a href="qkeyevent.html#key">key</a>() == Key_Tab ) { + // special tab handling here + ke-><a href="qkeyevent.html#accept">accept</a>(); + return TRUE; + } + } else if ( evt-><a href="qevent.html#type">type</a>() >= QEvent::User ) { + <a href="qcustomevent.html">QCustomEvent</a> *ce = (QCustomEvent*) evt; + // custom event handling here + return TRUE; + } + return QWidget::event( evt ); + } +</pre> + +<p> More commonly, an object needs to look at another's events. Qt +supports this using <a href="qobject.html#installEventFilter">QObject::installEventFilter</a>() (and the +corresponding remove). For example, dialogs commonly want to filter +key presses for some widgets, e.g. to modify Return-key handling. +<p> An event filter gets to process events before the target object does. +The filter's <a href="qobject.html#eventFilter">QObject::eventFilter</a>() implementation is called, and +can accept or reject the filter, and allow or deny further processing +of the event. If all the event filters allow further processing of an +event, the event is sent to the target object itself. If one of them +stops processing, the target and any later event filters don't get to +see the event at all. +<p> It's also possible to filter <em>all</em> events for the entire application, +by installing an event filter on <a href="qapplication.html">QApplication</a>. This is what <a href="qtooltip.html">QToolTip</a> does in order to see <em>all</em> the mouse and keyboard activity. +This is very powerful, but it also slows down event delivery of every +single event in the entire application, so it's best avoided. +<p> The global event filters are called before the object-specific +filters. +<p> Finally, many applications want to create and send their own events. +<p> Creating an event of a built-in type is very simple: create an object +of the relevant type, and then call <a href="qapplication.html#sendEvent">QApplication::sendEvent</a>() or <a href="qapplication.html#postEvent">QApplication::postEvent</a>(). +<p> sendEvent() processes the event immediately - when sendEvent() +returns, (the event filters and) the object 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> postEvent() 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 are compacted into one. The same applies to paint events: <a href="qwidget.html#update">QWidget::update</a>() calls postEvent(), which minimizes flickering and +increases speed by avoiding multiple repaints. +<p> postEvent() is also often used during object initialization, since the +posted event will typically be dispatched very soon after the +initialization of the object is complete. +<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 probably you also need +to subclass <a href="qcustomevent.html">QCustomEvent</a> in order to pass characteristics about +your custom event. See the documentation to <a href="qcustomevent.html">QCustomEvent</a> for +details. +<p> +<!-- eof --> +<p><address><hr><div align=center> +<table width=100% cellspacing=0 border=0><tr> +<td>Copyright © 2007 +<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a> +<td align=right><div align=right>Qt 3.3.8</div> +</table></div></address></body> +</html> |