/usr/share/doc/python-gtk2-tutorial/html/sec-TheoryOfSignalsAndCallbacks.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 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>2.2. Theory of Signals and Callbacks</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-GettingStarted.html" title="Chapter 2. Getting Started"><link rel="previous" href="ch-GettingStarted.html" title="Chapter 2. Getting Started"><link rel="next" href="sec-Events.html" title="2.3. Events"></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">2.2. Theory of Signals and Callbacks</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch-GettingStarted.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Getting Started</th><td width="20%" align="right"> <a accesskey="n" href="sec-Events.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-TheoryOfSignalsAndCallbacks"></a>2.2. Theory of Signals and Callbacks</h2></div></div><div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>In GTK+ version 2.0, the signal system has been moved from GTK
to GLib. We won't go into details about the extensions which the GLib 2.0
signal system has relative to the GTK+ 1.2 signal system. The differences
should not be apparent to PyGTK users.</p></div><p> Before we look in detail at <a href="examples/helloworld.py" target="_top"><span><b class="command">helloworld.py</b></span></a>, we'll
discuss signals and callbacks. GTK+ is an event driven toolkit, which means
it will sleep in <tt class="function">gtk.main</tt>() until an event occurs and
control is passed to the appropriate function.</p><p>This passing of control is done using the idea of "signals".
(Note that these signals are not the same as the Unix system signals, and
are not implemented using them, although the terminology is almost
identical.) When an event occurs, such as the press of a mouse button, the
appropriate signal will be "emitted" by the widget that was pressed. This is
how GTK+ does most of its useful work. There are signals that all widgets
inherit, such as "destroy", and there are signals that are widget specific,
such as "toggled" on a toggle button.</p><p>To make a button perform an action, we set up a signal handler
to catch these signals and call the appropriate function. This is done by
using a <tt class="classname">GtkWidget</tt> (from the
<tt class="classname">GObject</tt> class) method such as:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
handler_id = object.connect(name, func, func_data)
</pre></td></tr></table><p>where object is the <tt class="classname">GtkWidget</tt> instance
which will be emitting the signal, and the first argument
<i class="parameter"><tt>name</tt></i> is a string containing the name of the signal you
wish to catch. The second argument, <i class="parameter"><tt>func</tt></i>, is the
function you wish to be called when it is caught, and the third,
<i class="parameter"><tt>func_data</tt></i>, the data you wish to pass to this function.
The method returns a <span class="returnvalue">handler_id</span> that can be used
to disconnect or block the handler.</p><p>The function specified in the second argument is called a
"callback function", and should generally be of the form:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
def callback_func(widget, callback_data):
</pre></td></tr></table><p>where the first argument will be a pointer to the
<i class="parameter"><tt>widget</tt></i> that emitted the signal, and the second
(<i class="parameter"><tt>callback_data</tt></i>) a pointer to the data given as the last
argument to the <tt class="methodname">connect</tt>() method as shown above.</p><p>If the callback function is an object method then it will have
the general form:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
def callback_meth(self, widget, callback_data):
</pre></td></tr></table><p>where <i class="parameter"><tt>self</tt></i> is the object instance
invoking the method. This is the form used in the <a href="examples/helloworld.py" target="_top"><span><b class="command">helloworld.py</b></span></a>
example program.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The above form for a signal callback function declaration
is only a general guide, as some widget specific signals generate different
calling parameters.</p></div><p>Another call used in the <a href="examples/helloworld.py" target="_top"><span><b class="command">helloworld.py</b></span></a>
example is:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
handler_id = object.connect_object(name, func, slot_object)
</pre></td></tr></table><p><tt class="methodname">connect_object</tt>() is the same as
<tt class="methodname">connect</tt>() except a callback function only uses one
argument and a callback method, two arguments:</p><table border="0" bgcolor="#E0E0E0" width="100%"><tr><td><pre class="programlisting">
def callback_func(object)
def callback_meth(self, object)
</pre></td></tr></table><p>where <i class="parameter"><tt>object</tt></i> is usually a widget.
<tt class="methodname">connect_object</tt>() allows the PyGTK widget methods
that only take a single argument (<i class="parameter"><tt>self</tt></i>) to be used as
signal handlers.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch-GettingStarted.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch-GettingStarted.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sec-Events.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 2. Getting Started </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 2.3. Events</td></tr></table></div></body></html>
|