[gnome-devel-docs/beginners: 2/12] GTK+ Python tutorial: widget pages until label
- From: Marta Maria Casetti <mmcasetti src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gnome-devel-docs/beginners: 2/12] GTK+ Python tutorial: widget pages until label
- Date: Sat, 9 Mar 2013 21:46:40 +0000 (UTC)
commit 34c9a9c783ab81a53a140e0da1e060b423b3bcdb
Author: Marta Maria Casetti <mmcasetti gmail com>
Date: Mon Mar 4 11:54:29 2013 +0000
GTK+ Python tutorial: widget pages until label
The pages for Window, GtkApplicationWindow, Image and Label are in a decent
state, with additional samples of code added in the samples directory.
beginners-docs/C/GtkApplicationWindow.py.page | 27 ++++++-
beginners-docs/C/image.py.page | 96 +++++++++-------------
beginners-docs/C/label.py.page | 88 ++++++++++----------
beginners-docs/C/samples/GtkApplicationWindow.py | 14 +---
beginners-docs/C/samples/image.py | 9 +--
beginners-docs/C/samples/image2.py | 28 ++++++
beginners-docs/C/samples/image3.py | 35 ++++++++
beginners-docs/C/samples/label.py | 10 +--
beginners-docs/C/samples/label2.py | 34 ++++++++
beginners-docs/C/samples/window.py | 4 +-
beginners-docs/C/window.py.page | 21 ++++-
11 files changed, 229 insertions(+), 137 deletions(-)
---
diff --git a/beginners-docs/C/GtkApplicationWindow.py.page b/beginners-docs/C/GtkApplicationWindow.py.page
index ad324a0..91accd6 100644
--- a/beginners-docs/C/GtkApplicationWindow.py.page
+++ b/beginners-docs/C/GtkApplicationWindow.py.page
@@ -8,7 +8,7 @@
<title type="text">GtkApplicationWindow (Python)</title>
<link type="seealso" xref="properties.py"/>
<link type="next" xref="image.py"/>
- <revision version="0.3" date="2013-03-03" status="draft"/>
+ <revision version="0.4" date="2013-03-04" status="draft"/>
<credit type="author copyright">
<name>Tiffany Antopolski</name>
@@ -51,13 +51,36 @@
<section id="in-depth">
<title>A more in-depth look</title>
- <p></p>
+ <p>In lines 4–7 we construct a GtkApplicationWindow that belongs to a
+ generic application <code>app</code>.</p>
+
+ <p>In lines 9–11 we construct a GtkApplication, uniquely identified by
+ its <code>application_id</code>. This means that if you start an application
+ with a given <code>application_id</code> more than once, only the first
+ instance (also known as the primary instance) will actually run; every new
+ instance using the same <code>application_id</code> will notify the primary
+ instance and call the <code>do_activate()</code> method on it, and then
+ terminate.</p>
+
+ <p>The default <code>application_id</code> is <code>None</code>; in the next
+ examples we may use this default.</p>
</section>
<section id="exercises">
<title>Exercises</title>
+ <p>Instead of line 15 we could have a similar line somewhere else. Can you
+ guess what and where? [Are you really lost? Look at line 11 in the
+ <link xref="window.py"/> example.]</p>
+
+ <p>Similarly: can you find another way to set the title of the window?</p>
+
+ <p>Modify the code to print to terminal the number of windows created by the
+ application after the <code><var>app</var>.run(sys.argv)</code> method
+ returns. Verify it by opening a number of windows, and checking the result.
+ </p>
+
</section>
<section id="references">
diff --git a/beginners-docs/C/image.py.page b/beginners-docs/C/image.py.page
index 5801caa..784ffe4 100644
--- a/beginners-docs/C/image.py.page
+++ b/beginners-docs/C/image.py.page
@@ -46,68 +46,48 @@
<section id="in-depth">
<title>A more in-depth look</title>
+ <p>We start by creating a window. In line 10 we create an image in the window,
+ then in line 11 we set the image using one in the current folder; finally in
+ line 12 we add the image to the window.</p>
- <p>Another way to obtain what we have in the example is to create the image as an instance of another
class and add it to the instance of <code>MyWindow</code> in the <code>do_activate(self)</code> method:</p>
- <code mime="text/x-python">
-# a class to create a window
-class MyWindow(Gtk.ApplicationWindow):
- def __init__(self, app):
- Gtk.Window.__init__(self, title="Welcome to GNOME", application=app)
- self.set_default_size(300, 300)
-
-# a class to create an image
-class MyImage(Gtk.Image):
- def __init__(self):
- Gtk.Image.__init__(self)
- self.set_from_file("gnome-image.png")
-
-class MyApplication(Gtk.Application):
- def __init__(self):
- Gtk.Application.__init__(self)
-
- def do_activate(self):
- # create an instance of MyWindow
- win = MyWindow(self)
- # create an instance of MyImage and add it to the window
- win.add(MyImage())
- # show the window and everything on it
- win.show_all()</code>
- </section>
+ <p>Another way to obtain what we have in the example is to create the image as
+ an instance of another class and add it to the instance of
+ <code>MyWindow</code> in the <code>do_activate(self)</code> method.</p>
- <section id="methods">
- <title>Useful methods for an Image widget</title>
+ <code mime="text/x-python" style="numbered"><xi:include href="samples/image2.py"
parse="text"><xi:fallback/></xi:include></code>
+
+ <p>GTK+ has a set of stock images that can be set using
+ <code>set_from_stock(<var>stock_id</var>, <var>size</var>)</code>, where
+ <code><var>stock_id</var></code> is a name such as <code>Gtk.STOCK_ABOUT</code>
+ (more can be found at
+ <link href="http://developer.gnome.org/gtk3/unstable/gtk3-Stock-Items";>Stock Items</link>)
+ and <code><var>size</var></code> is a stock icon size to be chosen from
+ <code>Gtk.IconSize.INVALID, Gtk.IconSize.MENU, Gtk.IconSize.SMALL_TOOLBAR, Gtk.IconSize.LARGE_TOOLBAR,
Gtk.IconSize.BUTTON, Gtk.IconSize.DND, Gtk.IconSize.DIALOG</code>.
+ </p>
+
+ <p>There are also stock icons, that can be set with
+ <code>set_from_icon_name(<var>icon_name</var>, <var>size</var>)</code> and can
+ be found at
+ <link href="http://developer.gnome.org/gtk3/unstable/gtk3-Stock-Items";>Stock Items</link>.
+ </p>
+
+ <p>To load an image over a network use <code>set_from_pixbuf(<var>pixbuf</var>)</code>,
+ where <code><var>pixbuf</var></code> is a <link
href="http://developer.gnome.org/gdk-pixbuf/unstable//index.html";>GdkPixbuf</link>.
+ For example, we could have:</p>
+
+ <code mime="text/x-python" style="numbered"><xi:include href="samples/image3.py"
parse="text"><xi:fallback/></xi:include></code>
- <list>
- <item><p>To set a stock icon as image, you can use <code>set_from_stock(stock_id, size)</code> where
<code>stock_id</code> is a stock icon such as <code>Gtk.STOCK_ABOUT</code> (more can be found at <link
href="http://developer.gnome.org/gtk3/unstable/gtk3-Stock-Items";>Stock Items</link>, with the caveat that
they should be modified as above) and <code>size</code> is a stock icon size to be chosen from
<code>Gtk.IconSize.INVALID, Gtk.IconSize.MENU, Gtk.IconSize.SMALL_TOOLBAR, Gtk.IconSize.LARGE_TOOLBAR,
Gtk.IconSize.BUTTON, Gtk.IconSize.DND, Gtk.IconSize.DIALOG</code>.</p></item>
- <item><p>You can also use <code>set_from_icon_name(icon_name, size)</code>, where <code>icon_name</code>
is a stock icon name such as <code>"gtk-about"</code> (more can be found as above) and <code>size</code> is
as above.</p></item>
- <item><p>To load an image over a network use <code>set_from_pixbuf(pixbuf)</code>, where
<code>pixbuf</code> is a <link
href="http://developer.gnome.org/gdk-pixbuf/unstable//index.html";>GdkPixbuf</link>.</p>
- <code mime="text/python">
-from gi.repository import Gtk
-from gi.repository import GdkPixbuf
-import sys
-
-class MyWindow(Gtk.ApplicationWindow):
- # create a window
- def __init__(self, app):
- Gtk.Window.__init__(self, title="Welcome to GNOME", application=app)
- self.set_default_size(300, 300)
-
- # create a pixbuf from file filename="gnome-image.png", with width=32
- # and height=64 amd boolean preserve_aspect_ratio=False.
- pixbuf = GdkPixbuf.Pixbuf.new_from_file_at_scale("gnome-image.png", 64, 128, False)
-
- # create an image
- image = Gtk.Image()
- # set the content of the image as the pixbuf
- image.set_from_pixbuf(pixbuf)
- # add the image to the window
- self.add(image)</code>
- <p>If <code>preserve_aspect_ratio=True</code> we can use <code>new_from_file_at_size(filename, width,
height)</code>. If <code>width</code> or <code>height</code> is <code>-1</code>, it is not constrained.</p>
- <p>For loading from an input stream, see <code>new_from_stream()</code> and
<code>new_from_stream_at_scale()</code> in the documentation</p>
- </item>
- </list>
</section>
-
+
+ <section id="exercises">
+ <title>Exercises</title>
+
+ <p>Comment line-by-line the first two examples.</p>
+
+ <p>Guess and check what the third example returns.</p>
+
+ </section>
+
<section id="references">
<title>API References</title>
<p>In this sample we used the following:</p>
diff --git a/beginners-docs/C/label.py.page b/beginners-docs/C/label.py.page
index 85f0233..0dee278 100644
--- a/beginners-docs/C/label.py.page
+++ b/beginners-docs/C/label.py.page
@@ -3,18 +3,19 @@
xmlns:xi="http://www.w3.org/2001/XInclude";
type="guide" style="task"
id="label.py">
+
<info>
<title type="text">Label (Python)</title>
<link type="guide" xref="beginner.py#display-widgets"/>
<link type="seealso" xref="properties.py" />
<link type="seealso" xref="strings.py" />
<link type="next" xref="properties.py" />
- <revision version="0.2" date="2012-06-18" status="draft"/>
+ <revision version="0.3" date="2013-03-04" status="draft"/>
<credit type="author copyright">
<name>Marta Maria Casetti</name>
<email>mmcasetti gmail com</email>
- <years>2012</years>
+ <years>2012, 2013</years>
</credit>
<credit type="author">
<name>Sebastian Pölsterl</name>
@@ -26,60 +27,63 @@
</info>
<title>Label</title>
- <media type="image" mime="image/png" src="media/label.png"/>
- <p>A simple label</p>
+
+ <synopsis><p>We can write some text inside a label, and add it to a window.
+ </p></synopsis>
<links type="section" />
- <section id="code">
- <title>Code used to generate this example</title>
+ <section id="example">
+ <title>An example</title>
+
+ <p>An example of code for a simple window with a label inside it.</p>
<code mime="text/x-python" style="numbered"><xi:include href="samples/label.py"
parse="text"><xi:fallback/></xi:include></code>
- <p>Another way to obtain what we have in the example is to create the label as an instance of another
class and add it to the instance of <code>MyWindow</code> in the <code>do_activate(self)</code> method:</p>
- <code mime="text/x-python">
-# a class to define a window
-class MyWindow(Gtk.ApplicationWindow):
- def __init__(self, app):
- Gtk.Window.__init__(self, title="Welcome to GNOME", application=app)
- self.set_default_size(200, 100)
-
-# a class to define a label
-class MyLabel(Gtk.Label):
- def __init__(self):
- Gtk.Label.__init__(self)
- self.set_text("Hello GNOME!")
-
-class MyApplication(Gtk.Application):
- def __init__(self):
- Gtk.Application.__init__(self)
-
- def do_activate(self):
- # create an instance of MyWindow
- win = MyWindow(self)
- # create an instance of MyLabel
- label = MyLabel()
- # and add it to the window
- win.add(label)
- # show the window and everything on it
- win.show_all()</code>
+ <p>If you run this code, you should obtain something like the following:</p>
+ <media type="image" mime="image/png" src="media/label.png"/>
+
</section>
+
+ <section id="in-depth">
+ <title>A more in-depth look</title>
+
+ <p>As in the <link xref="image.py"/> example, we create a window and we add
+ something to it - in this case, a label for which in line 11 we set the text.
+ </p>
- <section id="methods">
- <title>Useful methods for a Label widget</title>
- <p>An explanation of how to deal with strings in GTK+ can be found in <link xref="strings.py" />.</p>
- <list>
- <item><p><code>set_line_wrap(True)</code> breaks lines if the text of the label exceeds the size of the
widget.</p></item>
- <item><p><code>set_justify(Gtk.Justification.LEFT)</code> (or <code>Gtk.Justification.RIGHT,
Gtk.Justification.CENTER, Gtk.Justification.FILL</code>) sets the alignment of the lines in the text of the
label relative to each other. The method has no effect on a single-line label.</p></item>
- <item><p>For decorated text we can use <code>set_markup("text")</code>, where <code>"text"</code> is a
text in the <link href="http://developer.gnome.org/pango/stable/PangoMarkupFormat.html";>Pango Markup
Language</link>. An example:</p>
+ <p>Analogously to what we have seen in the <link xref="image.py"/> example,
+ another way to obtain the above is to create the label as an instance of
+ another class and add it to the instance of <code>MyWindow</code> in the
+ <code>do_activate(self)</code> method.</p>
+
+ <code mime="text/x-python" style="numbered"><xi:include href="samples/label2.py"
parse="text"><xi:fallback/></xi:include></code>
+
+ <p>The method <code>set_line_wrap(True)</code> breaks lines if the text of
+ the label exceeds the size of the widget.</p>
+
+ <p>The method <code>set_justify(Gtk.Justification.LEFT)</code>
+ (alternatively: <code>Gtk.Justification.RIGHT, Gtk.Justification.CENTER, Gtk.Justification.FILL</code>)
+ sets the alignment of the lines in the text of the label relative to each
+ other. The method has no effect on a single-line label.</p>
+
+ <p>For decorated text we can use <code>set_markup(<var>"text"</var>)</code>,
+ using the
+ <link href="http://developer.gnome.org/pango/stable/PangoMarkupFormat.html";>Pango
+ Markup Language</link>. An example:</p>
<code mime="text/x-python"><![CDATA[
label.set_markup("Text can be <small>small</small>, <big>big</big>, "
"<b>bold</b>, <i>italic</i> and even point to somewhere "
"in the <a href=\"http://www.gtk.org\"; "
"title=\"Click to find out more\">internets</a>.")]]></code>
- </item>
- </list>
+
+ </section>
+
+ <section id="exercises">
+
+ <p>Try to produce a multiline label, possibly using the Pango Markup Language.</p>
+
</section>
<section id="references">
diff --git a/beginners-docs/C/samples/GtkApplicationWindow.py
b/beginners-docs/C/samples/GtkApplicationWindow.py
index 0611158..de2b443 100644
--- a/beginners-docs/C/samples/GtkApplicationWindow.py
+++ b/beginners-docs/C/samples/GtkApplicationWindow.py
@@ -1,31 +1,19 @@
from gi.repository import Gtk
import sys
-# a Gtk ApplicationWindow
class MyWindow(Gtk.ApplicationWindow):
- # constructor: the window belongs to the application app
def __init__(self, app):
Gtk.Window.__init__(self, application=app)
- # set the title of the window
self.set_title("Welcome to GNOME")
class MyApplication(Gtk.Application):
- # constructor of the Gtk Application
def __init__(self):
- Gtk.Application.__init__(self)
+ Gtk.Application.__init__(self, application_id="org.gnome.ApplicationWindowExample")
- # create and activate a MyWindow, with self (the MyApplication) as
- # application app the window belongs to.
def do_activate(self):
win = MyWindow(self)
- # show the window and all its content
- # note that this line could also go in the constructor of MyWindow
win.show_all()
- # start up the application
- def do_startup(self):
- Gtk.Application.do_startup(self)
-
# create the application
app = MyApplication()
# run the application, which returns the value exit_status
diff --git a/beginners-docs/C/samples/image.py b/beginners-docs/C/samples/image.py
index 640ca75..b3e8a69 100644
--- a/beginners-docs/C/samples/image.py
+++ b/beginners-docs/C/samples/image.py
@@ -2,30 +2,23 @@ from gi.repository import Gtk
import sys
class MyWindow(Gtk.ApplicationWindow):
- # create a window
def __init__(self, app):
Gtk.Window.__init__(self, application=app)
self.set_title("Welcome to GNOME")
self.set_default_size(300, 300)
- # create an image
image = Gtk.Image()
- # set the content of the image as the file filename.png
image.set_from_file("gnome-image.png")
- # add the image to the window
self.add(image)
class MyApplication(Gtk.Application):
def __init__(self):
- Gtk.Application.__init__(self)
+ Gtk.Application.__init__(self, application_id="org.gnome.ImageExample")
def do_activate(self):
win = MyWindow(self)
win.show_all()
- def do_startup(self):
- Gtk.Application.do_startup(self)
-
app = MyApplication()
exit_status = app.run(sys.argv)
sys.exit(exit_status)
diff --git a/beginners-docs/C/samples/image2.py b/beginners-docs/C/samples/image2.py
new file mode 100644
index 0000000..8318811
--- /dev/null
+++ b/beginners-docs/C/samples/image2.py
@@ -0,0 +1,28 @@
+from gi.repository import Gtk
+import sys
+
+# a class to create a window
+class MyWindow(Gtk.ApplicationWindow):
+ def __init__(self, app):
+ Gtk.Window.__init__(self, application=app)
+ self.set_title("Welcome to GNOME")
+ self.set_default_size(300, 300)
+
+# a class to create an image
+class MyImage(Gtk.Image):
+ def __init__(self):
+ Gtk.Image.__init__(self)
+ self.set_from_file("gnome-image.png")
+
+class MyApplication(Gtk.Application):
+ def __init__(self):
+ Gtk.Application.__init__(self, application_id="org.gnome.ImageExample2")
+
+ def do_activate(self):
+ win = MyWindow(self)
+ win.add(MyImage())
+ win.show_all()
+
+app = MyApplication()
+exit_status = app.run(sys.argv)
+sys.exit(exit_status)
diff --git a/beginners-docs/C/samples/image3.py b/beginners-docs/C/samples/image3.py
new file mode 100644
index 0000000..dbc540f
--- /dev/null
+++ b/beginners-docs/C/samples/image3.py
@@ -0,0 +1,35 @@
+from gi.repository import Gtk
+import sys
+
+from gi.repository import Gtk
+from gi.repository import GdkPixbuf
+import sys
+
+class MyWindow(Gtk.ApplicationWindow):
+ def __init__(self, app):
+ Gtk.Window.__init__(self, application=app)
+ self.set_title("Welcome to GNOME")
+ self.set_default_size(300, 300)
+
+ # create a pixbuf from file filename="gnome-image.png", with width=32
+ # and height=64 amd boolean preserve_aspect_ratio=False.
+ pixbuf = GdkPixbuf.Pixbuf.new_from_file_at_scale("gnome-image.png", 64, 128, False)
+
+ # create an image
+ image = Gtk.Image()
+ # set the content of the image as the pixbuf
+ image.set_from_pixbuf(pixbuf)
+ # add the image to the window
+ self.add(image)
+
+class MyApplication(Gtk.Application):
+ def __init__(self):
+ Gtk.Application.__init__(self, application_id="org.gnome.ImageExample")
+
+ def do_activate(self):
+ win = MyWindow(self)
+ win.show_all()
+
+app = MyApplication()
+exit_status = app.run(sys.argv)
+sys.exit(exit_status)
diff --git a/beginners-docs/C/samples/label.py b/beginners-docs/C/samples/label.py
index ebca626..5e2cf70 100644
--- a/beginners-docs/C/samples/label.py
+++ b/beginners-docs/C/samples/label.py
@@ -2,16 +2,13 @@ from gi.repository import Gtk
import sys
class MyWindow(Gtk.ApplicationWindow):
- # constructor for a Gtk.ApplicationWindow
def __init__(self, app):
- Gtk.Window.__init__(self, title="Welcome to GNOME", application=app)
+ Gtk.Window.__init__(self, application=app)
+ self.set_title("Welcome to GNOME")
self.set_default_size(200, 100)
- # create a label
label = Gtk.Label()
- # set the text of the label
label.set_text("Hello GNOME!")
- # add the label to the window
self.add(label)
class MyApplication(Gtk.Application):
@@ -22,9 +19,6 @@ class MyApplication(Gtk.Application):
win = MyWindow(self)
win.show_all()
- def do_startup(self):
- Gtk.Application.do_startup(self)
-
app = MyApplication()
exit_status = app.run(sys.argv)
sys.exit(exit_status)
diff --git a/beginners-docs/C/samples/label2.py b/beginners-docs/C/samples/label2.py
new file mode 100644
index 0000000..920ae11
--- /dev/null
+++ b/beginners-docs/C/samples/label2.py
@@ -0,0 +1,34 @@
+from gi.repository import Gtk
+import sys
+
+# a class for the window
+class MyWindow(Gtk.ApplicationWindow):
+ def __init__(self, app):
+ Gtk.Window.__init__(self, application=app)
+ self.set_title("Welcome to GNOME")
+ self.set_default_size(200, 100)
+
+# a class for the label
+class MyLabel(Gtk.Label):
+ def __init__(self):
+ Gtk.Label.__init__(self)
+ self.set_text("Hello GNOME!")
+
+# the application
+class MyApplication(Gtk.Application):
+ def __init__(self):
+ Gtk.Application.__init__(self)
+
+ def do_activate(self):
+ # create an instance of MyWindow
+ win = MyWindow(self)
+ # create an instance of MyLabel
+ label = MyLabel()
+ # and add the label to the window
+ win.add(label)
+ # show the window and everything on it
+ win.show_all()
+
+app = MyApplication()
+exit_status = app.run(sys.argv)
+sys.exit(exit_status)
diff --git a/beginners-docs/C/samples/window.py b/beginners-docs/C/samples/window.py
index 9b2491e..788e925 100644
--- a/beginners-docs/C/samples/window.py
+++ b/beginners-docs/C/samples/window.py
@@ -3,11 +3,9 @@ from gi.repository import Gtk
class MyWindow(Gtk.Window):
def __init__(self):
Gtk.Window.__init__(self)
- # set the title
self.set_title("Welcome to GNOME")
- # set a default size: width of 200 and default height
+ # set the default size: width of 200 and the content's natural height
self.set_default_size(200, -1)
- # set a default position: center of the screen
self.set_position(Gtk.WindowPosition.CENTER)
# show the window
self.show_all()
diff --git a/beginners-docs/C/window.py.page b/beginners-docs/C/window.py.page
index 6448dc8..ff3d45c 100644
--- a/beginners-docs/C/window.py.page
+++ b/beginners-docs/C/window.py.page
@@ -8,7 +8,7 @@
<title type="text">Window (Python)</title>
<link type="next" xref="GtkApplicationWindow.py"/>
<link type="seealso" xref="properties.py"/>
- <revision version="0.3" date="2013-03-03" status="draft"/>
+ <revision version="0.4" date="2013-03-04" status="draft"/>
<credit type="author copyright">
<name>Tiffany Antopolski</name>
@@ -50,9 +50,24 @@
<p>In this first example, we create a window with a title and a size, in a
given position. The creation is given by the constructor
<code>__init__(self)</code>; the properties such as title, size and position
- are given by the methods in lines 6–13.</p>
+ are given by the methods in lines 6–9.</p>
+
+ <p>In GTK+3, the widgets have a natural and a minimum size. For a window,
+ there is also a default size, that is an initial size, set with
+ <code>set_default_size(<var>width</var>, <var>height</var>)</code>.
+ The default size cannot be smaller than the minimum size of
+ the widgets inside the window (known as "children widgets").</p>
+
+ <p>The minimum size for a widget (including the window) can be set with
+ <code>set_size_request(<var>width</var>, <var>height</var>)</code>.</p>
+
+ <p>In both methods, the variables <var>width</var> and <var>height</var> can
+ take the value of <code>-1</code>: in this case, they will take the natural
+ size of the children widgets.</p>
+
+ <p>Line 11 makes the window visible.</p>
- <p>Do not worry too much of what happens in lines 15–20: we will see it
+ <p>Do not worry too much of what happens in lines 13–18: we will see it
in <link xref="signals-callbacks.py"/>.</p>
</section>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
