Skip to content

Commit

Permalink
Updated readme to reflect Gtk3 instructions.
Browse files Browse the repository at this point in the history 
Updated the html readme that accompanies the markdown.
  • Loading branch information
@cdelorme
cdelorme committed Aug 14, 2013
1 parent c6da0b0 commit da7656a
Show file tree
Hide file tree
Showing 2 changed files with 76 additions and 9 deletions.
39 changes: 33 additions & 6 deletions README.html
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@

<html><meta charset="UTF-8"><style>html {
font-size: 100%;
overflow-y: scroll;
Expand Down Expand Up @@ -98,13 +97,13 @@ <h2>File Hierarchy</h2>
<ul>
<li>activity/<ul>
<li>activity.info</li>
<li>activity-icon.svg</li>
<li>icon.svg</li>
</ul>
</li>
<li>activity.py</li>
<li>setup.py</li>
</ul>
<p><em>This activity does not include an <code>activity-icon.svg</code>. You must build (or extend) the <code>activity.py</code> file. Changes to the <code>activity.py</code> file must be accomodated by changes to the <code>activity.info</code>. You will use the <code>setup.py</code> file to create a <code>.xo</code> file later.</em></p>
<p><em>This activity includes an empty icon named <code>exampleicon.svg</code>. It is advised that you create your own icon. You must build (or extend) the <code>activity.py</code> file. Changes to the <code>activity.py</code> file must be accomodated by changes to the <code>activity.info</code>. You will use the <code>setup.py</code> file to create a <code>.xo</code> file later.</em></p>
<h3>Included in This QuickStart</h3>
<ul>
<li>/activity<ul>
Expand Down Expand Up @@ -258,11 +257,39 @@ <h2>Building &amp; Distributing</h2>
<p><strong>If your activity does not appear on the desktop after you have installed it, check the activity list, and check your <code>activity.info</code> file for invalid values.</strong></p>
<h2>GTK and Interfaces</h2>
<p>Sugar has migrated to Gtk3, which uses GObject Introspection.</p>
<p>While this sounds complex, what it means is that the new library of code describes itself, and is used to automatically generate 100% accurate documentation. Unfortunately, this documentation is currently only written in C, so you may have to read C documentation to build with python Gtk3.</p>
<p>This can be a bit tricky, but hopefully the tips here will help new developers going forward.</p>
<p>First, sugar has changed the Gtk3 compatible import to sugar3, which means imports from the sugar libraries should have the sugar3 prefix.</p>
<p>Introspection gives objects the ability to describe themselves, and this means new code can automatically generate accurate documentation at build time. This means no manual documentation is needed, and no human errors exist in documentation that do not exist in the code.</p>
<p>Unfortunately since the source is written in C, the documentation is also for the C libraries. Translating from C to the python API is a bit of a chore, so this section is here to help.</p>
<p>Let's start with some helpful reference sites:</p>
<ul>
<li><a href="http://python-gtk-3-tutorial.readthedocs.org/en/latest/">Python Gtk3 Examples</a></li>
<li><a href="https://developer.gnome.org/gtk3/3.0/">Gtk3 Documentation</a></li>
</ul>
<p>The examples are not complete or comprehensive, but they explain a large portion of commonly used elements and are a good place to start if you are beginning. The documentation is in C, but translating from the C documentation to python is very strait forward, as it has its own rules.</p>
<p>You can also make life easier using a python interpreter such as <a href="http://bpython-interpreter.org/">bpython</a> which uses the introspection to provide auto-complete options. This can be of great help when you are unsure as to a method name, since you can get a list of names automatically. You can install bpython from yum (or aptitude).</p>
<p>The first major change, any time you see a sugar import it should be <code>sugar3</code>, as this is the new library that uses Gtk3 elements.</p>
<p>Second, all of the GObject libraries are imported through the <code>gi.repository</code> library.</p>
<p><em>Note: The sugar3.activity.Activity extends Gtk.Window, which means if you want to test a software outside sugar you can (mostly) swap in Gtk.Window where the class extends sugar3.activity.Activity.</em></p>
<p>Now to guide you through reading Gtk3 documentation, remembering that our goal is to translate from C to Python.</p>
<p>The documentation prefixes all elements with Gtk, for example GtkWindow in the documentation. This is a <code>Gtk.Window()</code> object in python.</p>
<p>If you go to the <a href="https://developer.gnome.org/gtk3/3.0/GtkWindow.html">GtkWindow</a> documentation, you will see a menu at the top of the page. Important sections include:</p>
<ul>
<li>Object Hierarchy</li>
<li>Properties</li>
<li>Signals</li>
</ul>
<p>The others are still valuable, and it starts by providing the list of methods available, but these three are the ones we really want to pay attention to.</p>
<p>Gtk elements extend from GObject, and each layer inherits the parents properties chained upstream. This means GtkWindow also has all of the properties, methods, and signals that belong to GtkBin, which means it also gets the same from GtkContainer, up to GtkWidget, and so on.</p>
<p>This is important, because you will often be searching for a signal or property that may not exist on the child, but belongs to the parent. So your first lookout: <strong>If you cannot find a property, method, or signal on the element, check its parent elements</strong>.</p>
<p>As for the methods, the C naming style accepts the element as the first argument, they do not chain off the element as seen in other languages. So when you see a method such as <code>gtk_window_set_title</code> what that becomes in python is <code>set_title</code>, and you would use it as follows:</p>
<pre><code>window = Gtk.Window()
window.set_title("A Title")
</code></pre>
<p>Alternatively, if you check the properties you will see <code>title</code> is a property, and you can set them on initialization like this instead:</p>
<pre><code>window = Gtk.Window(title="A Title")
</code></pre>
<p>Which will produce the same window as in the first example. Now for your second lookout: <strong>Properties with a hyphen (-) become an underscore.</strong> If you convert hyphens to underscores you can set the properties in the constructor in python.</p>
<p>The final stage is the signals. Signals are fired and can be connected to methods, this is the event handling of C and Python. For example, you can have a method run to scale fonts in the GtkWindow using the <code>check-resize</code> signal, which actually belongs to <a href="https://developer.gnome.org/gtk3/3.0/GtkContainer.html#GtkContainer.signals">GtkContainer</a>, a parent property (<em>First Lookout</em>).</p>
<p>This is about all the major bumps in the road you can expect to run into, just remember to watch out for parent elements, and conversion rules for properties and methods and you should have an easy time of developing in Gtk3 for Python.</p>
<h2>Multi-Lingual Development</h2>
<p>When you run <code>./setup.py genpot</code> this parses your software for any strings wrapped with gettext, and generates a <code>.po</code> file. This <code>.po</code> file can then be sent out for translation.</p>
<pre><code>PENDING FURTHER INSTRUCTIONS
Expand Down
46 changes: 43 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -207,16 +207,56 @@ A symlink only has to be created once, but you should run these two commands fir

Sugar has migrated to Gtk3, which uses GObject Introspection.

While this sounds complex, what it means is that the new library of code describes itself, and is used to automatically generate 100% accurate documentation. Unfortunately, this documentation is currently only written in C, so you may have to read C documentation to build with python Gtk3.
Introspection gives objects the ability to describe themselves, and this means new code can automatically generate accurate documentation at build time. This means no manual documentation is needed, and no human errors exist in documentation that do not exist in the code.

This can be a bit tricky, but hopefully the tips here will help new developers going forward.
Unfortunately since the source is written in C, the documentation is also for the C libraries. Translating from C to the python API is a bit of a chore, so this section is here to help.

First, sugar has changed the Gtk3 compatible import to sugar3, which means imports from the sugar libraries should have the sugar3 prefix.
Let's start with some helpful reference sites:

- [Python Gtk3 Examples](http://python-gtk-3-tutorial.readthedocs.org/en/latest/)
- [Gtk3 Documentation](https://developer.gnome.org/gtk3/3.0/)

The examples are not complete or comprehensive, but they explain a large portion of commonly used elements and are a good place to start if you are beginning. The documentation is in C, but translating from the C documentation to python is very strait forward, as it has its own rules.

You can also make life easier using a python interpreter such as [bpython](http://bpython-interpreter.org/) which uses the introspection to provide auto-complete options. This can be of great help when you are unsure as to a method name, since you can get a list of names automatically. You can install bpython from yum (or aptitude).

The first major change, any time you see a sugar import it should be `sugar3`, as this is the new library that uses Gtk3 elements.

Second, all of the GObject libraries are imported through the `gi.repository` library.

_Note: The sugar3.activity.Activity extends Gtk.Window, which means if you want to test a software outside sugar you can (mostly) swap in Gtk.Window where the class extends sugar3.activity.Activity._

Now to guide you through reading Gtk3 documentation, remembering that our goal is to translate from C to Python.

The documentation prefixes all elements with Gtk, for example GtkWindow in the documentation. This is a `Gtk.Window()` object in python.

If you go to the [GtkWindow](https://developer.gnome.org/gtk3/3.0/GtkWindow.html) documentation, you will see a menu at the top of the page. Important sections include:

- Object Hierarchy
- Properties
- Signals

The others are still valuable, and it starts by providing the list of methods available, but these three are the ones we really want to pay attention to.

Gtk elements extend from GObject, and each layer inherits the parents properties chained upstream. This means GtkWindow also has all of the properties, methods, and signals that belong to GtkBin, which means it also gets the same from GtkContainer, up to GtkWidget, and so on.

This is important, because you will often be searching for a signal or property that may not exist on the child, but belongs to the parent. So your first lookout: **If you cannot find a property, method, or signal on the element, check its parent elements**.

As for the methods, the C naming style accepts the element as the first argument, they do not chain off the element as seen in other languages. So when you see a method such as `gtk_window_set_title` what that becomes in python is `set_title`, and you would use it as follows:

window = Gtk.Window()
window.set_title("A Title")

Alternatively, if you check the properties you will see `title` is a property, and you can set them on initialization like this instead:

window = Gtk.Window(title="A Title")

Which will produce the same window as in the first example. Now for your second lookout: **Properties with a hyphen (-) become an underscore.** If you convert hyphens to underscores you can set the properties in the constructor in python.

The final stage is the signals. Signals are fired and can be connected to methods, this is the event handling of C and Python. For example, you can have a method run to scale fonts in the GtkWindow using the `check-resize` signal, which actually belongs to [GtkContainer](https://developer.gnome.org/gtk3/3.0/GtkContainer.html#GtkContainer.signals), a parent property (_First Lookout_).

This is about all the major bumps in the road you can expect to run into, just remember to watch out for parent elements, and conversion rules for properties and methods and you should have an easy time of developing in Gtk3 for Python.


## Multi-Lingual Development

Expand Down

0 comments on commit da7656a

Please sign in to comment.