GNOME.org
 

[gnome-devel-docs] tutorials python: data entry widgets with new pages and commented samples

commit 7115a73c0c14a17deb36c2c7c0df59092217d935
Author: Marta Maria Casetti <mmcasetti gmail com>
Date:   Sat Jun 23 21:10:05 2012 +0100

    tutorials python: data entry widgets with new pages and commented samples

 platform-demos/C/entry.py.page         |   53 ++++++++++++++++++++++++++------
 platform-demos/C/samples/entry.py      |   11 ++++--
 platform-demos/C/samples/scale.py      |   42 ++++++++++++------------
 platform-demos/C/samples/spinbutton.py |   26 +++++++--------
 platform-demos/C/scale.py.page         |   46 +++++++++++++++++++++------
 platform-demos/C/spinbutton.py.page    |   36 ++++++++++++++++-----
 6 files changed, 146 insertions(+), 68 deletions(-)
---
diff --git a/platform-demos/C/entry.py.page b/platform-demos/C/entry.py.page
index 8330f6b..f02fb0b 100644
--- a/platform-demos/C/entry.py.page
+++ b/platform-demos/C/entry.py.page
@@ -5,14 +5,19 @@
       id="entry.py">
   <info>
     <link type="guide" xref="beginner.py#entry"/>
-    <revision version="0.1" date="2012-05-24" status="draft"/>
+    <revision version="0.2" date="2012-06-23" status="draft"/>
 
-    <credit type="author copyright">
+    <credit type="author copyright editor">
       <name>Marta Maria Casetti</name>
-      <email>mmcasetti gmail com</email>
+      <email></email>
       <years>2012</years>
     </credit>
 
+    <credit type="author copyright">
+      <name>Sebastian P&#246;lsterl</name>
+      <email>sebp k-d-w org</email>
+      <years>2011</years>
+    </credit>
     <desc>A single line text entry field</desc>
   </info>
 
@@ -20,11 +25,39 @@
   <media type="image" mime="image/png" src="media/entry.png"/>
   <p>This application greets you in the terminal with the name you provide.</p>
 
-<code mime="text/x-python" style="numbered"><xi:include href="samples/entry.py" parse="text"><xi:fallback/></xi:include></code>
-<p>
-  In this sample we used the following:
-</p>
-<list>
-  <item><p><link href="http://developer.gnome.org/gtk3/3.4/GtkEntry.html";>GtkEntry</link></p></item>
-</list>
+  <links type="section" />
+
+  <section id="code">
+  <title>Code used to generate this example</title>
+    <code mime="text/x-python" style="numbered"><xi:include href="samples/entry.py" parse="text"><xi:fallback/></xi:include></code>
+  </section>
+
+  <section id="methods">
+    <title>Useful methods for an Entry widget</title>
+    <p>For an explanation of signals and callback functions, see <link xref="signals-callbacks.py">this page</link>. Some of the signals that a Gtk.Entry widget can emit are: <code>"activate"</code> (emitted when the user activates the Entry key); <code>"backspace"</code> (emitted when the user activates the Backspace or Shift-Backspace keys); <code>"copy-clipboard"</code> (Ctrl-c and Ctrl-Insert); <code>"paste-clipboard"</code> (Ctrl-v and Shift-Insert); <code>"delete-from-cursor"</code> (Delete, for deleting a character; Ctrl-Delete, for deleting a word); <code>"icon-press"</code> (emitted when the user clicks an activable icon); <code>"icon-release"</code> (emitted on the button release from a mouse click over an activable icon);  <code>"insert-at-cursor"</code> (emitted when the user initiates the insertion of a fixed string at the cursor); <code>"move-cursor"</code> (emitted when the user initiates a cursor movement); <code>"populate-popup"</code> (emitted before showin
 g the context menu of the entry; it can be used to add items to it).</p>
+    <list>
+      <item><p><code>get_buffer()</code> and <code>set_buffer(buffer)</code>, where <code>buffer</code> is a Gtk.EntryBuffer object, can be used to get and set the buffer for the entry.</p></item>
+      <item><p><code>get_text()</code> and <code>set_text("some text")</code> can be used to get and set the content for the entry.</p></item>
+      <item><p><code>get_text_length()</code> is self-explanatory.</p></item>
+      <item><p><code>get_text_area()</code> gets the area where the entry's text is drawn.</p></item>
+      <item><p>If we set <code>set_visibility(False)</code> the characters in the entry are displayed as the invisible char. This is the best available in the current font, but it can be changed with <code>set_invisible_char(ch)</code>, where <code>ch</code> is a Unicode charcater. The latter method is reversed by <code>unset_invisbile_char()</code>.</p></item>
+      <item><p><code>set_max_length(int)</code>, where <code>int</code> is an integer, truncates every entry longer than <code>int</code> to have the desired maximum length.</p></item>
+      <item><p>By default, if you press the Entry key the Gtk.Entry emits the signal <code>"activate"</code>. If you would like to activate the default widget for the window (set using <code>set_default(widget)</code> on the window), then use <code>set_activates_default(True)</code>.</p></item>
+      <item><p>To set a frame around the entry: <code>set_has_frame(True)</code>.</p></item>
+      <item><p><code>set_placeholder_text("some text")</code> sets the text to be displayed in the entry when it is empty and unfocused.</p></item>
+      <item><p><code>set_overwrite_mode(True)</code> and <code>set_overwrite_mode(False)</code> are self-explanatory.</p></item>
+      <item><p>If we have <code>set_editable(False)</code> the user cannot edit the text in the widget.</p></item>
+      <item><p><code>set_completion(completion)</code>, where <code>completion</code> is a <link href="http://developer.gnome.org/gtk3/3.4/GtkEntryCompletion.html";><code>Gtk.EntryCompletion</code></link>, sets completion - or disables it if <code>completion</code> is <code>None</code>.</p></item>
+      <item><p>An Entry widget can display progress or activity information behind the text. We use <code>set_progress_fraction(fraction)</code>, where <code>fraction</code> is a <code>float</code> between <code>0.0</code> and <code>1.0</code> inclusive, to fill in the given fraction of the bar. We use <code>set_progress_pulse_step()</code> to set the fraction of total entry width to move the progress bouncing block for each call to <code>progress_pulse()</code>. The latter method indicates that some progress is made, and causes the progress indicator of the entry to enter "activity mode", where a block bounces back and forth. Each call to <code>progress_pulse()</code> causes the block to move by a little bit (the amount of movement per pulse is determined, as said before, by <code>set_progress_pulse_step()</code>).</p></item>
+      <item><p>An Entry widget can also show icons. These icons can be activatable by clicking, can be set up as drag source and can have tooltips. To add an icon, use <code>set_icon_from_stock(icon_position, stock_id)</code>, or one of <code>set_icon_from_pixbuf(icon_position, pixbuf)</code>, <code>set_icon_from_icon_name(icon_position, icon_name)</code>, where <code>icon_position</code> is one of <code>Gtk.EntryIconPosition.PRIMARY</code> (to set the icon at the beginning of the entry) <code>Gtk.EntryIconPosition.SECONDARY</code> (to set the icon at the end of the entry). To set a tooltip on an icon, use <code>set_icon_tooltip_text("tooltip text")</code> or <code>set_icon_tooltip_markup("tooltip text in Pango markup language")</code>.</p></item>
+    </list>
+  </section>
+
+  <section id="references">
+    <title>API References</title>
+    <p>In this sample we used the following:</p>
+    <list>
+      <item><p><link href="http://developer.gnome.org/gtk3/3.4/GtkEntry.html";>GtkEntry</link></p></item>
+    </list>
+  </section>
 </page>
diff --git a/platform-demos/C/samples/entry.py b/platform-demos/C/samples/entry.py
index 351719f..75eb7c2 100644
--- a/platform-demos/C/samples/entry.py
+++ b/platform-demos/C/samples/entry.py
@@ -1,4 +1,3 @@
-from gi.repository import GLib
 from gi.repository import Gtk
 import sys
 
@@ -10,19 +9,23 @@ class MyWindow(Gtk.ApplicationWindow):
 
         # a single line entry
         name_box = Gtk.Entry()
-        # sends a signal when the Enter key is pressed
+        # emits a signal when the Enter key is pressed, connected to the
+        # callback function cb_activate
         name_box.connect("activate", self.cb_activate)
 
+        # add the Gtk.Entry to the window
         self.add(name_box)
 
     # the content of the entry is used to write in the terminal
     def cb_activate(self, entry):
+        # retrieve the content of the widget
 		name = entry.get_text()
-		print "\nHello " + name + "!\n"
+		# print it in a nice form in the terminal
+		print "Hello " + name + "!"
 
 class MyApplication(Gtk.Application):
     def __init__(self):
-        Gtk.Application.__init__(self, application_id="org.example.MyApplication")
+        Gtk.Application.__init__(self)
 
     def do_activate(self):
         win = MyWindow(self)
diff --git a/platform-demos/C/samples/scale.py b/platform-demos/C/samples/scale.py
index 040dfc3..dd4a2ea 100644
--- a/platform-demos/C/samples/scale.py
+++ b/platform-demos/C/samples/scale.py
@@ -15,49 +15,49 @@ class MyWindow(Gtk.ApplicationWindow):
         ad2 = Gtk.Adjustment(50, 0, 100, 5, 10, 0)
 
         # an horizontal scale
-        h_scale = Gtk.Scale(orientation=Gtk.Orientation.HORIZONTAL, adjustment=ad1)
-        h_scale.set_digits(0)
+        self.h_scale = Gtk.Scale(orientation=Gtk.Orientation.HORIZONTAL, adjustment=ad1)
+        # of integers (no digits)
+        self.h_scale.set_digits(0)
         # that can expand horizontally if there is space in the grid (see below)
-        h_scale.set_hexpand(True)
+        self.h_scale.set_hexpand(True)
         # that is aligned at the top of the space allowed in the grid (see below)
-        h_scale.set_valign(Gtk.Align.START)
+        self.h_scale.set_valign(Gtk.Align.START)
 
-        h_scale.connect("value-changed", self.scale_moved)
+        # we connect the signal "value-changed" emitted by the scale with the callback
+        # function scale_moved
+        self.h_scale.connect("value-changed", self.scale_moved)
 
         # a vertical scale
-        v_scale = Gtk.Scale(orientation=Gtk.Orientation.VERTICAL, adjustment=ad2)
+        self.v_scale = Gtk.Scale(orientation=Gtk.Orientation.VERTICAL, adjustment=ad2)
         # that can expand vertically if there is space in the grid (see below)
-        v_scale.set_vexpand(True)
+        self.v_scale.set_vexpand(True)
 
-        v_scale.connect("value-changed", self.scale_moved)
+        # we connect the signal "value-changed" emitted by the scale with the callback
+        # function scale_moved
+        self.v_scale.connect("value-changed", self.scale_moved)
 
         # a label
-        label = Gtk.Label()
-        label.set_text("Move the scale handles...")
+        self.label = Gtk.Label()
+        self.label.set_text("Move the scale handles...")
 
         # a grid to attach the widgets
         grid = Gtk.Grid()
         grid.set_column_spacing(10)
         grid.set_column_homogeneous(True)
-        grid.attach(h_scale, 1, 1, 1, 1)
-        grid.attach_next_to(v_scale, h_scale, Gtk.PositionType.RIGHT, 1, 1)
-        grid.attach(label, 1, 2, 2, 1)
+        grid.attach(self.h_scale, 0, 0, 1, 1)
+        grid.attach_next_to(self.v_scale, self.h_scale, Gtk.PositionType.RIGHT, 1, 1)
+        grid.attach(self.label, 0, 1, 2, 1)
 
         self.add(grid)
 
-        self.label = label
-        self.scale1 = h_scale
-        self.scale2 = v_scale
-
     # any signal from the scales is signaled to the label the text of which is changed
     def scale_moved(self, event):
-        self.label.set_text("Horizontal scale is " + str(int(self.scale1.get_value())) +
-                            "; vertical scale is " + str(self.scale2.get_value()) + ".")
-        return True
+        self.label.set_text("Horizontal scale is " + str(int(self.h_scale.get_value())) +
+                            "; vertical scale is " + str(self.v_scale.get_value()) + ".")
 
 class MyApplication(Gtk.Application):
     def __init__(self):
-        Gtk.Application.__init__(self, application_id="org.example.spinner")
+        Gtk.Application.__init__(self)
 
     def do_activate(self):
         win = MyWindow(self)
diff --git a/platform-demos/C/samples/spinbutton.py b/platform-demos/C/samples/spinbutton.py
index f4d59d3..1aa77a1 100644
--- a/platform-demos/C/samples/spinbutton.py
+++ b/platform-demos/C/samples/spinbutton.py
@@ -11,37 +11,35 @@ class MyWindow(Gtk.ApplicationWindow):
         # step increment - press cursor keys or +/- buttons to see!,
         # page increment - not used here,
         # page size - not used here)
-        ad = Gtk.Adjustment(0, 0, 100, 1, 10, 0)
+        ad = Gtk.Adjustment(0, 0, 100, 1, 0, 0)
 
         # a spin button for integers (digits=0)
-        spin = Gtk.SpinButton(adjustment=ad, climb_rate=1, digits=0)
+        self.spin = Gtk.SpinButton(adjustment=ad, climb_rate=1, digits=0)
         # as wide as possible
-        spin.set_hexpand(True)
+        self.spin.set_hexpand(True)
 
-        spin.connect("value-changed", self.spin_selected)
+        # we connect the signal "value-changed" emitted by the spinbutton with the callback
+        # function spin_selected
+        self.spin.connect("value-changed", self.spin_selected)
 
         # a label
-        label = Gtk.Label()
-        label.set_text("Choose a number")
+        self.label = Gtk.Label()
+        self.label.set_text("Choose a number")
 
         # a grid to attach the widgets
         grid = Gtk.Grid()
-        grid.attach(spin, 1, 1, 1, 1)
-        grid.attach(label, 1, 2, 2, 1)
+        grid.attach(self.spin, 0, 0, 1, 1)
+        grid.attach(self.label, 0, 1, 2, 1)
 
         self.add(grid)
 
-        self.label = label
-        self.spin = spin
-
-    # the signal of the spinbutton is signaled to the label the text of which is changed
+    # callback function: the signal of the spinbutton is used to change the text of the label
     def spin_selected(self, event):
         self.label.set_text("The number you selected is " + str(self.spin.get_value_as_int()) + ".")
-        return True
 
 class MyApplication(Gtk.Application):
     def __init__(self):
-        Gtk.Application.__init__(self, application_id="org.example.spinner")
+        Gtk.Application.__init__(self)
 
     def do_activate(self):
         win = MyWindow(self)
diff --git a/platform-demos/C/scale.py.page b/platform-demos/C/scale.py.page
index c26dacc..eff56e4 100644
--- a/platform-demos/C/scale.py.page
+++ b/platform-demos/C/scale.py.page
@@ -6,7 +6,7 @@
   <info>
     <link type="guide" xref="beginner.py#entry"/>
     <link type="seealso" xref="grid.py"/>
-    <revision version="0.1" date="2012-05-25" status="draft"/>
+    <revision version="0.2" date="2012-06-23" status="draft"/>
 
     <credit type="author copyright">
       <name>Marta Maria Casetti</name>
@@ -21,13 +21,39 @@
   <media type="image" mime="image/png" src="media/scale.png"/>
   <p>Slide the scales!</p>
 
-<code mime="text/x-python" style="numbered"><xi:include href="samples/scale.py" parse="text"><xi:fallback/></xi:include></code>
-<p>
-  In this sample we used the following:
-</p>
-<list>
-  <item><p><link href="http://developer.gnome.org/gtk3/3.4/GtkScale.html";>GtkScale</link></p></item>
-  <item><p><link href="http://developer.gnome.org/gtk3/3.4/GtkAdjustment.html";>GtkAdjustment</link></p></item>
-  <item><p><link href="http://developer.gnome.org/gtk3/3.4/gtk3-Standard-Enumerations.html";>Standard Enumerations</link></p></item>
-</list>
+  <links type="section" />
+
+  <section id="code">
+    <title>Code used to generate this example</title>
+    <code mime="text/x-python" style="numbered"><xi:include href="samples/scale.py" parse="text"><xi:fallback/></xi:include></code>
+  </section>
+
+  <section id="methods">
+    <title>Useful methods for a Scale widget</title>
+    <p>For an explanation of signals and callback functions, see <link xref="signals-callbacks.py">this page</link>. An example is the <code>"value-changed"</code> signal, emitted when the value of the scale changes.</p>
+    <p>A Gtk.Adjustment is needed to construct the Gtk.Scale. This is the representation of a value with a lower and upper bound, together with step and page increments, and a page size, and it is constructed as <code>Gtk.Adjustment(value, lower, upper, step_increment, page_increment, page_size)</code> where the fields are of type <code>float</code>; <code>step_increment</code> is the increment/decrement that is obtained by using the cursor keys, <code>page_increment</code> the one that is obtained clicking on the scale itself. Note that <code>page_size</code> is not used in this case, it should be set to <code>0</code>.</p>
+    <list>
+      <item><p><code>get_value()</code> retrieves the current value of the scale; <code>set_value(value)</code> sets it (if the <code>value</code>, of type <code>float</code>, is outside the minimum or maximum range, it will be clamped to fit inside them). These are methods of the class Gtk.Range.</p></item>
+      <item><p>Use <code>set_draw_value(False)</code> to avoid displaying the current value as a string next to the slider.</p></item>
+      <item><p>To highlight the part of the scale between the origin and the current value:</p>
+        <code mime="text/x-python">
+self.h_scale.set_restrict_to_fill_level(False)
+self.h_scale.set_fill_level(self.h_scale.get_value())
+self.h_scale.set_show_fill_level(True)</code>
+        <p>in the callback function of the "value-changed" signal, so to have the new filling every time the value is changed. These are methods of the class Gtk.Range.</p>
+      </item>
+      <item><p><code>add_mark(value, position, markup)</code> adds a mark at the <code>value</code> (<code>float</code> or <code>int</code> if that is the precision of the scale), in <code>position</code> (<code>Gtk.PositionType.LEFT, Gtk.PositionType.RIGHT, Gtk.PositionType.TOP, Gtk.PositionType.BOTTOM</code>) with text <code>Null</code> or <code>markup</code> in the Pango Markup Language. To clear marks, <code>clear_marks()</code>.</p></item>
+      <item><p><code>set_digits(digits)</code> sets the precision of the scale at <code>digits</code> digits.</p></item>
+    </list>
+  </section>
+
+  <section id="references">
+    <title>API References</title>
+    <p>In this sample we used the following:</p>
+    <list>
+      <item><p><link href="http://developer.gnome.org/gtk3/3.4/GtkScale.html";>GtkScale</link></p></item>
+      <item><p><link href="http://developer.gnome.org/gtk3/3.4/GtkAdjustment.html";>GtkAdjustment</link></p></item>
+      <item><p><link href="http://developer.gnome.org/gtk3/3.4/gtk3-Standard-Enumerations.html";>Standard Enumerations</link></p></item>
+    </list>
+  </section>
 </page>
diff --git a/platform-demos/C/spinbutton.py.page b/platform-demos/C/spinbutton.py.page
index 985ad20..e49ff68 100644
--- a/platform-demos/C/spinbutton.py.page
+++ b/platform-demos/C/spinbutton.py.page
@@ -6,7 +6,7 @@
   <info>
     <link type="guide" xref="beginner.py#entry"/>
     <link type="seealso" xref="grid.py"/>
-    <revision version="0.1" date="2012-05-28" status="draft"/>
+    <revision version="0.2" date="2012-06-23" status="draft"/>
 
     <credit type="author copyright">
       <name>Marta Maria Casetti</name>
@@ -21,12 +21,30 @@
   <media type="image" mime="image/png" src="media/spinbutton.png"/>
   <p>Choose a number, by entering it or by clicking on the -/+ buttons!</p>
 
-<code mime="text/x-python" style="numbered"><xi:include href="samples/spinbutton.py" parse="text"><xi:fallback/></xi:include></code>
-<p>
-  In this sample we used the following:
-</p>
-<list>
-  <item><p><link href="http://developer.gnome.org/gtk3/3.4/GtkSpinButton.html";>GtkSpinButton</link></p></item>
-  <item><p><link href="http://developer.gnome.org/gtk3/3.4/GtkAdjustment.html";>GtkAdjustment</link></p></item>
-</list>
+  <links type="section" />
+
+  <section id="code">
+    <title>Code used to generate this example</title>
+    <code mime="text/x-python" style="numbered"><xi:include href="samples/spinbutton.py" parse="text"><xi:fallback/></xi:include></code>
+  </section>
+
+  <section id="methods">
+    <title>Useful methods for a SpinButton widget</title>
+    <p>For an explanation of signals and callback functions, see <link xref="signals-callbacks.py">this page</link>. An example is the <code>"value-changed"</code> signal, emitted when the value of the spinbutton changes.</p>
+    <p>A Gtk.Adjustment is needed to construct the Gtk.SpinButton. This is the representation of a value with a lower and upper bound, together with step and page increments, and a page size, and it is constructed as <code>Gtk.Adjustment(value, lower, upper, step_increment, page_increment, page_size)</code> where the fields are of type <code>float</code>; <code>step_increment</code> is the increment/decrement that is obtained by using the cursor keys or the buttons of the spinbutton. Note that <code>page_increment</code> and <code>page_size</code> are not used in this case, and they should be set to <code>0</code>.</p>
+    <list>
+      <item><p>If you want the value of the spinbutton to wrap around when they exceed the maximum or the minimum, set <code>set_wrap(True)</code>. The <code>"wrapped"</code> signal is emitted when this happens.</p></item>
+      <item><p><code>set_digits(digits)</code> sets the precision to be displayed by the spinbutton, up to 20 digits.</p></item>
+      <item><p>To get the value of the spinbutton as an integer, use <code>get_value_as_int()</code>.</p></item>
+    </list>
+  </section>
+
+  <section id="references">
+    <title>API References</title>
+    <p>In this sample we used the following:</p>
+    <list>
+      <item><p><link href="http://developer.gnome.org/gtk3/3.4/GtkSpinButton.html";>GtkSpinButton</link></p></item>
+      <item><p><link href="http://developer.gnome.org/gtk3/3.4/GtkAdjustment.html";>GtkAdjustment</link></p></item>
+    </list>
+  </section>
 </page>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]