[gnome-devel-docs] tutorials python: signals and callbacks page

[Tiffany Antopolski <antopolski src gnome org>]

commit 50b70085064f3ef9071d07564a3295a90e0fc8bd
Author: Marta Maria Casetti <mmcasetti gmail com>
Date:   Sat Jun 16 18:29:59 2012 +0100

    tutorials python: signals and callbacks page

 platform-demos/C/button.py.page            |    2 +-
 platform-demos/C/checkbutton.py.page       |    2 +-
 platform-demos/C/linkbutton.py.page        |    2 +-
 platform-demos/C/radiobutton.py.page       |    2 +-
 platform-demos/C/signals-callbacks.py.page |   15 ++++++++++++---
 platform-demos/C/switch.py.page            |    2 +-
 platform-demos/C/togglebutton.py.page      |    2 +-
 7 files changed, 18 insertions(+), 9 deletions(-)
---
diff --git a/platform-demos/C/button.py.page b/platform-demos/C/button.py.page
index f3d39ce..d4065d4 100644
--- a/platform-demos/C/button.py.page
+++ b/platform-demos/C/button.py.page
@@ -27,7 +27,7 @@
   </section>
   <section id="methods">
     <title>Useful methods for a Button widget</title>
-    <p>For an explanation of signals and callback functions, see <link href="signals-callbacks.py.page">this page</link>.</p>
+    <p>For an explanation of signals and callback functions, see <link type="seealso" xref="signals-callbacks.py.page">this page</link>.</p>
     <list>
       <item><p><code>set_relief(Gtk.ReliefStyle.NONE)</code> sets to none the relief style of the edges of the Gtk.Button - as opposed to <code>Gtk.ReliefStyle.NORMAL</code>.</p></item>
       <item><p>If the label of the button is a <link href="http://developer.gnome.org/gtk3/3.4/gtk3-Stock-Items.html";>stock icon</link>, <code>set_use_stock(True)</code> sets the label as the name of the corresponding stock icon.</p></item>
diff --git a/platform-demos/C/checkbutton.py.page b/platform-demos/C/checkbutton.py.page
index f5d4aeb..aa3a7b8 100644
--- a/platform-demos/C/checkbutton.py.page
+++ b/platform-demos/C/checkbutton.py.page
@@ -31,7 +31,7 @@
 
   <section id="methods">
     <title>Useful methods for a CheckButton widget</title>
-    <p>For a discussion on signals and callback functions, see <link href="signals-callbacks.py.page">this page</link>.</p>
+    <p>For a discussion on signals and callback functions, see <link type="seealso" xref="signals-callbacks.py">this page</link>.</p>
 
   </section>
 
diff --git a/platform-demos/C/linkbutton.py.page b/platform-demos/C/linkbutton.py.page
index b264661..bd99969 100644
--- a/platform-demos/C/linkbutton.py.page
+++ b/platform-demos/C/linkbutton.py.page
@@ -32,7 +32,7 @@
     <list>
       <item><p><code>get_visited()</code> returns the 'visited' state (<code>True</code> or <code>False</code>) of the URI where the LinkButton points. The button becomes visited when it is clicked.</p></item>
       <item><p><code>set_visited(True)</code> sets the 'visited' state of the URI where the LinkButton points as <code>True</code> (analogously for <code>False</code>).</p></item>
-      <item><p>Each time the button is clicked, the signal <code>"activate-link"</code> is emitted. For an explanation of signals and callback functions, see <link href="signals-callbacks.py.page">this page</link>.</p></item>
+      <item><p>Each time the button is clicked, the signal <code>"activate-link"</code> is emitted. For an explanation of signals and callback functions, see <link type="seealso" xref="signals-callbacks.py.page">this page</link>.</p></item>
     </list>
   </section>
   <section id="references">
diff --git a/platform-demos/C/radiobutton.py.page b/platform-demos/C/radiobutton.py.page
index 895565c..b97abd8 100644
--- a/platform-demos/C/radiobutton.py.page
+++ b/platform-demos/C/radiobutton.py.page
@@ -30,7 +30,7 @@
 
   <section id="methods">
     <title>Useful methods for a RadioButton widget</title>
-    <p>For an explanation of signals and callback functions, see <link href="signals-callbacks.py.page">this page</link>.</p>
+    <p>For an explanation of signals and callback functions, see <link type="seealso" xref="signals-callbacks.py.page">this page</link>.</p>
 
     <p>Instead of <code>button1 = Gtk.RadioButton(label="Button 1")</code> we could create the button and label it with</p>
     <code>
diff --git a/platform-demos/C/signals-callbacks.py.page b/platform-demos/C/signals-callbacks.py.page
index f29e424..cd94dc8 100644
--- a/platform-demos/C/signals-callbacks.py.page
+++ b/platform-demos/C/signals-callbacks.py.page
@@ -2,13 +2,13 @@
 <page xmlns="http://projectmallard.org/1.0/";
       xmlns:e="http://projectmallard.org/experimental/";
       type="guide" style="task"
-      id="beginner.py">
+      id="signals-callbacks.py">
 
 <info>
   <link type="guide" xref="py"/>
-  <revision version="0.1" date="2012-06-16" status="stub"/>
+  <revision version="0.1" date="2012-06-16" status="draft"/>
 
-  <desc></desc>
+  <desc>An explanation of signals and callbacks in GTK+.</desc>
   <credit type="author copyright">
     <name>Sebastian P&#246;lsterl</name>
     <email>sebp k-d-w org</email>
@@ -23,5 +23,14 @@
 
 <title>Signals and callbacks</title>
 
+<p>Like most GUI toolkits, GTK+ uses an event-driven programming model. When the user is doing nothing, GTK+ sits in the main loop and waits for input. If the user performs some action - say, a mouse click - then the main loop &#34;wakes up&#34; and delivers an event to GTK+.</p>
+
+<p>When widgets receive an event, they frequently emit one or more signals. Signals notify your program that &#34;something interesting happened&#34; by invoking functions you have connected to the signal. Such functions are commonly known as callbacks. When your callbacks are invoked, you would typically take some action. After a callback finishes, GTK+ will return to the main loop and await more user input.</p>
+
+<p>A generic example is: <code>handler_id = widget.connect("event", callback, data)</code>.</p>
+
+<p>Firstly, <code>widget</code> is an instance of a widget we created earlier. Next, the event we are interested in. Each widget has its own particular events which can occur. For instance, if you have a Gtk.Button you usually want to connect to the &#34;clicked&#34; event. This means that when the button is clicked, the signal is issued. Thirdly, the callback argument is the name of the callback function. It contains the code which runs when signals of the specified type are issued. Finally, the data argument includes any data which should be passed when the signal is issued. However, this argument is completely optional and can be left out if not required.</p>
+
+<p>The function returns a number (the <code>handler_id</code>) that identifies this particular signal-callback pair. This number is required to disconnect from a signal such that the callback function will not be called during any future or currently ongoing emissions of the signal it has been connected to, as in <code>widget.disconnect(handler_id)</code>.</p>
 
 </page>
diff --git a/platform-demos/C/switch.py.page b/platform-demos/C/switch.py.page
index 35bca5d..c24d26e 100644
--- a/platform-demos/C/switch.py.page
+++ b/platform-demos/C/switch.py.page
@@ -34,7 +34,7 @@
   </section>
   <section id="methods">
     <title>Useful methods for a Switch widget</title>
-    <p>For a discussion on signals and callback functions, see <link href="signals-callbacks.py.page">this page</link>.</p>
+    <p>For a discussion on signals and callback functions, see <link type="seealso" xref="signals-callbacks.py.page">this page</link>.</p>
 
   </section>
   <section id="references">
diff --git a/platform-demos/C/togglebutton.py.page b/platform-demos/C/togglebutton.py.page
index 149c7ef..2a7a0c0 100644
--- a/platform-demos/C/togglebutton.py.page
+++ b/platform-demos/C/togglebutton.py.page
@@ -31,7 +31,7 @@
 
   <section id="methods">
     <title>Useful methods for a ToggleButton widget</title>
-    <p>For an explanation of signals and callback functions, see <link href="signals-callbacks.py.page">this page</link>.</p>
+    <p>For an explanation of signals and callback functions, see <link type="seealso" xref="signals-callbacks.py.page">this page</link>.</p>
   </section>
 
   <section id="references">