/usr/share/doc/python-gtk2-tutorial/html/sec-EventHandling.html is in python-gtk2-tutorial 2.4-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>24.2. Event Handling</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="PyGTK 2.0 Tutorial"><link rel="up" href="ch-Scribble.html" title="Chapter 24. Scribble, A Simple Example Drawing Program"><link rel="previous" href="ch-Scribble.html" title="Chapter 24. Scribble, A Simple Example Drawing Program"><link rel="next" href="sec-DrawingAreaWidgetAndDrawing.html" title="24.3. The DrawingArea Widget, And Drawing"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">24.2. Event Handling</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch-Scribble.html">Prev</a> </td><th width="60%" align="center">Chapter 24. Scribble, A Simple Example Drawing Program</th><td width="20%" align="right"> <a accesskey="n" href="sec-DrawingAreaWidgetAndDrawing.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sec-EventHandling"></a>24.2. Event Handling</h2></div></div><div></div></div><p>The GTK+ signals we have already discussed are for high-level
actions, such as a menu item being selected. However, sometimes it is useful
to learn about lower-level occurrences, such as the mouse being moved, or a
key being pressed. There are also GTK+ signals corresponding to these
low-level events. The handlers for these signals have an extra parameter
which is a <tt class="classname">gtk.gdk.Event</tt> object containing
information about the event. For instance, motion event handlers are passed
a <tt class="classname">gtk.gdk.Event</tt> object containing EventMotion
information which has (in part) attributes like:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
type
window
time
x
y
...
state
...
</pre></td></tr></table><p><i class="parameter"><tt>window</tt></i> is the window in which the event
occurred.</p><p><i class="parameter"><tt>x</tt></i> and <i class="parameter"><tt>y</tt></i> give the
coordinates of the event.</p><p><i class="parameter"><tt>type</tt></i> will be set to the event type, in
this case <tt class="literal">MOTION_NOTIFY</tt>. The types (in module gtk.gdk)
are:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
NOTHING a special code to indicate a null event.
DELETE the window manager has requested that the toplevel window be
hidden or destroyed, usually when the user clicks on a special
icon in the title bar.
DESTROY the window has been destroyed.
EXPOSE all or part of the window has become visible and needs to be
redrawn.
MOTION_NOTIFY the pointer (usually a mouse) has moved.
BUTTON_PRESS a mouse button has been pressed.
_2BUTTON_PRESS a mouse button has been double-clicked (clicked twice within
a short period of time). Note that each click also generates a
BUTTON_PRESS event.
_3BUTTON_PRESS a mouse button has been clicked 3 times in a short period of
time. Note that each click also generates a BUTTON_PRESS event.
BUTTON_RELEASE a mouse button has been released.
KEY_PRESS a key has been pressed.
KEY_RELEASE a key has been released.
ENTER_NOTIFY the pointer has entered the window.
LEAVE_NOTIFY the pointer has left the window.
FOCUS_CHANGE the keyboard focus has entered or left the window.
CONFIGURE the size, position or stacking order of the window has changed.
Note that GTK+ discards these events for GDK_WINDOW_CHILD windows.
MAP the window has been mapped.
UNMAP the window has been unmapped.
PROPERTY_NOTIFY a property on the window has been changed or deleted.
SELECTION_CLEAR the application has lost ownership of a selection.
SELECTION_REQUEST another application has requested a selection.
SELECTION_NOTIFY a selection has been received.
PROXIMITY_IN an input device has moved into contact with a sensing surface
(e.g. a touchscreen or graphics tablet).
PROXIMITY_OUT an input device has moved out of contact with a sensing surface.
DRAG_ENTER the mouse has entered the window while a drag is in progress.
DRAG_LEAVE the mouse has left the window while a drag is in progress.
DRAG_MOTION the mouse has moved in the window while a drag is in progress.
DRAG_STATUS the status of the drag operation initiated by the window has changed.
DROP_START a drop operation onto the window has started.
DROP_FINISHED the drop operation initiated by the window has completed.
CLIENT_EVENT a message has been received from another application.
VISIBILITY_NOTIFY the window visibility status has changed.
NO_EXPOSE indicates that the source region was completely available when parts
of a drawable were copied. This is not very useful.
SCROLL ?
WINDOW_STATE ?
SETTING ?
</pre></td></tr></table><p><i class="parameter"><tt>state</tt></i> specifies the modifier state when
the <i class="parameter"><tt>event</tt></i> occurred (that is, it specifies which
modifier keys and mouse buttons were pressed). It is the bitwise
<tt class="literal">OR</tt> of some of the following (in module gtk.gdk):</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
SHIFT_MASK
LOCK_MASK
CONTROL_MASK
MOD1_MASK
MOD2_MASK
MOD3_MASK
MOD4_MASK
MOD5_MASK
BUTTON1_MASK
BUTTON2_MASK
BUTTON3_MASK
BUTTON4_MASK
BUTTON5_MASK
</pre></td></tr></table><p>As for other signals, to determine what happens when an event
occurs we call the <tt class="methodname">connect</tt>() method. But we also
need to let GTK+ know which events we want to be notified about. To do this,
we call the method:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
widget.set_events(<i class="parameter"><tt>events</tt></i>)
</pre></td></tr></table><p>The <i class="parameter"><tt>events</tt></i> argument specifies the events
we are interested in. It is the bitwise <tt class="literal">OR</tt> of constants
that specify different types of events. For future reference, the event
types (in module gtk.gdk) are:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
EXPOSURE_MASK
POINTER_MOTION_MASK
POINTER_MOTION_HINT_MASK
BUTTON_MOTION_MASK
BUTTON1_MOTION_MASK
BUTTON2_MOTION_MASK
BUTTON3_MOTION_MASK
BUTTON_PRESS_MASK
BUTTON_RELEASE_MASK
KEY_PRESS_MASK
KEY_RELEASE_MASK
ENTER_NOTIFY_MASK
LEAVE_NOTIFY_MASK
FOCUS_CHANGE_MASK
STRUCTURE_MASK
PROPERTY_CHANGE_MASK
VISIBILITY_NOTIFY_MASK
PROXIMITY_IN_MASK
PROXIMITY_OUT_MASK
SUBSTRUCTURE_MASK
</pre></td></tr></table><p>There are a few subtle points that have to be observed when
calling the <tt class="methodname">set_events</tt>() method. First, it must be
called before the X window for a PyGTK widget is created. In practical
terms, this means you should call it immediately after creating the widget.
Second, the widget must be one which will be realized with an associated X
window. For efficiency, many widget types do not have their own window, but
draw in their parent's window. These widgets include:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
gtk.Alignment
gtk.Arrow
gtk.Bin
gtk.Box
gtk.Image
gtk.Item
gtk.Label
gtk.Layout
gtk.Pixmap
gtk.ScrolledWindow
gtk.Separator
gtk.Table
gtk.AspectFrame
gtk.Frame
gtk.VBox
gtk.HBox
gtk.VSeparator
gtk.HSeparator
</pre></td></tr></table><p>To capture events for these widgets, you need to use an
<tt class="classname">EventBox</tt> widget. See <a href="ch-ContainerWidgets.html#sec-EventBox" title="10.1. The EventBox">Section 10.1, “The EventBox”</a> widget for details.</p><p>The event attributes that are set by PyGTK for each type of
event are:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
every event type
window
send_event
NOTHING
DELETE
DESTROY # no additional attributes
EXPOSE area
count
MOTION_NOTIFY time
x
y
pressure
xtilt
ytilt
state
is_hint
source
deviceid
x_root
y_root
BUTTON_PRESS
_2BUTTON_PRESS
_3BUTTON_PRESS
BUTTON_RELEASE time
x
y
pressure
xtilt
ytilt
state
button
source
deviceid
x_root
y_root
KEY_PRESS
KEY_RELEASE time
state
keyval
string
ENTER_NOTIFY
LEAVE_NOTIFY subwindow
time
x
y
x_root
y_root
mode
detail
focus
state
FOCUS_CHANGE _in
CONFIGURE x
y
width
height
MAP
UNMAP # no additional attributes
PROPERTY_NOTIFY atom
time
state
SELECTION_CLEAR
SELECTION_REQUEST
SELECTION_NOTIFY selection
target
property
requestor
time
PROXIMITY_IN
PROXIMITY_OUT time
source
deviceid
DRAG_ENTER
DRAG_LEAVE
DRAG_MOTION
DRAG_STATUS
DROP_START
DROP_FINISHED context
time
x_root
y_root
CLIENT_EVENT message_type
data_format
data
VISIBILTY_NOTIFY state
NO_EXPOSE # no additional attributes
</pre></td></tr></table><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id3096656"></a>24.2.1. Scribble - Event Handling</h3></div></div><div></div></div><p>For our drawing program, we want to know when the mouse button
is pressed and when the mouse is moved, so we specify
<tt class="literal">POINTER_MOTION_MASK</tt> and
<tt class="literal">BUTTON_PRESS_MASK</tt>. We also want to know when we need to
redraw our window, so we specify <tt class="literal">EXPOSURE_MASK</tt>. Although
we want to be notified via a Configure event when our window size changes,
we don't have to specify the corresponding <tt class="literal">STRUCTURE_MASK</tt>
flag, because it is automatically specified for all windows.</p><p>It turns out, however, that there is a problem with just
specifying <tt class="literal">POINTER_MOTION_MASK</tt>. This will cause the
server to add a new motion event to the event queue every time the user
moves the mouse. Imagine that it takes us 0.1 seconds to handle a motion
event, but the X server queues a new motion event every 0.05 seconds. We
will soon get way behind the users drawing. If the user draws for 5 seconds,
it will take us another 5 seconds to catch up after they release the mouse
button! What we would like is to only get one motion event for each event we
process. The way to do this is to specify
<tt class="literal">POINTER_MOTION_HINT_MASK</tt>.</p><p>When we specify <tt class="literal">POINTER_MOTION_HINT_MASK</tt>, the
server sends us a motion event the first time the pointer moves after
entering our window, or after a button press or release event. Subsequent
motion events will be suppressed until we explicitly ask for the position of
the pointer using the <tt class="classname">gtk.gdk.Window</tt> method:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
x, y, mask = window.get_pointer()
</pre></td></tr></table><p><i class="parameter"><tt>window</tt></i> is a
<tt class="classname">gtk.gdk.Window</tt> object. <i class="parameter"><tt>x</tt></i> and
<i class="parameter"><tt>y</tt></i> are the coordinates of the pointer and
<i class="parameter"><tt>mask</tt></i> is the modifier mask to detect which keys are
pressed. (There is a <tt class="classname">gtk.Widget</tt> method,
<tt class="methodname">get_pointer</tt>() which provides the same information
as the <tt class="methodname">gtk.gdk.Window get_pointer</tt>() method but it
does not return the mask information)</p><p>The <a href="examples/scribblesimple.py" target="_top"><span><b class="command">scribblesimple.py</b></span></a>
example program demonstrates the basic use of events and event handlers.
<a href="sec-EventHandling.html#simplescribblefig" title="Figure 24.2. Simple Scribble Example">Figure 24.2, “Simple Scribble Example”</a> illustrates the program in action:</p><div class="figure"><a name="simplescribblefig"></a><p class="title"><b>Figure 24.2. Simple Scribble Example</b></p><div class="mediaobject" align="center"><img src="figures/scribblesimple.png" align="middle" alt="Simple Scribble Example"></div></div><p>The event handlers are connected to the drawing_area by the
following lines:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
92 # Signals used to handle backing pixmap
93 drawing_area.connect("expose_event", expose_event)
94 drawing_area.connect("configure_event", configure_event)
95
96 # Event signals
97 drawing_area.connect("motion_notify_event", motion_notify_event)
98 drawing_area.connect("button_press_event", button_press_event)
99
100 drawing_area.set_events(gtk.gdk.EXPOSURE_MASK
101 | gtk.gdk.LEAVE_NOTIFY_MASK
102 | gtk.gdk.BUTTON_PRESS_MASK
103 | gtk.gdk.POINTER_MOTION_MASK
104 | gtk.gdk.POINTER_MOTION_HINT_MASK)
</pre></td></tr></table><p>The <tt class="function">button_press_event</tt>() and<tt class="function">
motion_notify_event</tt>() event handlers in <a href="examples/scribblesimple.py" target="_top"><span><b class="command">scribblesimple.py</b></span></a>
are:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
57 def button_press_event(widget, event):
58 if event.button == 1 and pixmap != None:
59 draw_brush(widget, event.x, event.y)
60 return True
61
62 def motion_notify_event(widget, event):
63 if event.is_hint:
64 x, y, state = event.window.get_pointer()
65 else:
66 x = event.x
67 y = event.y
68 state = event.state
69
70 if state & gtk.gdk.BUTTON1_MASK and pixmap != None:
71 draw_brush(widget, x, y)
72
73 return True
</pre></td></tr></table><p>The <tt class="function">expose_event</tt>() and
<tt class="function">configure_event</tt>() handlers will be described
later.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch-Scribble.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch-Scribble.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sec-DrawingAreaWidgetAndDrawing.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 24. Scribble, A Simple Example Drawing Program </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 24.3. The DrawingArea Widget, And Drawing</td></tr></table></div></body></html>
|