README.html

<html><meta charset="UTF-8"><style>html {
    font-size: 100%;
    overflow-y: scroll;
    -webkit-text-size-adjust: 100%;
    -ms-text-size-adjust: 100%;
}

body{
    font-family: helvetica, arial, freesans, clean, sans-serif;
    color: #333;
    background-color: #fff;
    border-color: #999999;
    border-width: 2px;
    line-height: 1.5;
    margin: 2em 3em;
    text-align:left;
    padding: 0 100px 0 100px;
}

pre{
    background-color: #eee;
    padding: 10px;
    -webkit-border-radius: 5px;
    -moz-border-radius: 5px;
    border-radius: 5px;
    overflow: auto;
}
code{
    background-color: #eee;
    padding: 1px 3px;
    -webkit-border-radius: 2px;
    -moz-border-radius: 2px;
    border-radius: 2px;
}
pre code {
    padding-left: 0px;
    padding-right: 0px;
}
li p{
    margin: 0.3em;
}
ul > li{
    list-style-type: disc;
}
a:link, a:visited{
    color: #33e;
    text-decoration: none;
}
a:hover{
    color: #00f;
    text-shadow:1px 1px 2px #ccf;
    text-decoration:underline;
}
h1{
    color: #999;
    font-weight: 400;
    font-size: 36px;
}
h2{
    border-bottom: 1px dotted #aaa;
    margin-bottom: 1em;
    color: #333;
    font-size: 30px;
}
h3{
    color: #666;
    font-size: 24px;
}
h4 {
    font-size: 21px;
}
h5 {
    font-size: 18px;
}
.shadow{
    -webkit-box-shadow:0 5px 15px #000;
    -moz-box-shadow:0 5px 15px #000;
    box-shadow:0 5px 15px #000;
}
</style><body><h1>Sugar_Activity_Quickstart</h1>
<p>This is the framework for a Sugar Activity. Everything needed to quickly start an activity for the Sugar OLPC XO. Credit for this repo is given to Robin Brooke, whose blog can be found <a href="http://rbrooke.blogspot.com/2010/01/creating-xo-file.html">here: http://rbrooke.blogspot.com/2010/01/creating-xo-file.html</a></p>
<p><strong>NOTE: The latest Sugar (since the Gtk3 migration) now ignores MANIFEST files, don't create one.</strong></p>
<h2>Table of Contents</h2>
<ul>
<li>File Hierarchy<ul>
<li>What is included</li>
<li>Description of Project Files</li>
</ul>
</li>
<li>Building &amp; Distributing</li>
<li>GTK and Interfaces</li>
<li>Multi-Lingual Development</li>
<li>Example Activity</li>
</ul>
<h2>File Hierarchy</h2>
<p>A basic bare-minimum Sugar Activity will consist of these files:</p>
<ul>
<li>activity/<ul>
<li>activity.info</li>
<li>icon.svg</li>
</ul>
</li>
<li>activity.py</li>
<li>setup.py</li>
</ul>
<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>
<li>activity.info</li>
</ul>
</li>
<li>activity.py</li>
<li>setup.py</li>
<li>README.md (this file)</li>
<li>README.html</li>
</ul>
<h3>Description of Project Files</h3>
<p>As you would expect, each file serves a specific purpose.</p>
<p>The <code>activity</code> folder stores meta-data about the activity.  This includes an <code>activity.info</code> file which describes the activity and how to execute it from the sugar desktop.  It also stores the activity display icon in SVG (XML Standard Vector Graphics) format.</p>
<p>The <code>setup.py</code> file aids with testing, building, and installing activities.  It does not change between activities.  It will help generate language files, symlink to your sugar activities for development.  It also packages the software into a compressed <code>.xo</code> file for distribution to other XO laptops.</p>
<p>A commonly used name is <code>activity.py</code>, but you can technically call it whatever you like.  This is the name used most commonly by sugar activities.</p>
<hr />
<h4>setup.py</h4>
<p>This file is used to generate your po translation files, build/test your code, symlink it for development, and creating a compressed .xo package file.</p>
<p>If you run it with no commands it will give you all available commands and a short description.</p>
<p><em>It must be executable to be run.</em></p>
<p>It is two lines long:</p>
<pre><code>from sugar3.activity import bundlebuilder
bundlebuilder.start()
</code></pre>
<p>Example Commands:</p>
<pre><code>./setup.py genpot
./setup.py build
./setup.py dev
./setup.py dist_xo
</code></pre>
<h4>activity/</h4>
<p>This folder contains your <code>activity.info</code> file used to launch your activity, as well as your SVG icon.</p>
<h4>activity/activity.info</h4>
<p>This file is used to define the icon used on the sugar desktop, and is responsible for executing the program when that icon is selected.</p>
<p>Here is an example (included in the default files):</p>
<pre><code>[Activity]
name = example
bundle_id = example.laptop.org
icon = exampleicon
exec = sugar-activity activity.Example
show_launcher = yes
activity_version = 1
license = GPLv2+
</code></pre>
<p>Now to explain what each of these do:</p>
<ul>
<li>name<ul>
<li>The name of the activity as seen by the user.</li>
</ul>
</li>
<li>bundle_id<ul>
<li>Unique name used by sugar to refer to your activity, which may also be used in your code (such as accessing the journal).</li>
</ul>
</li>
<li>icon<ul>
<li>The name of your SVG icon (automatically infers a <code>.svg</code> suffix, <strong>do not include .svg</strong>)</li>
</ul>
</li>
<li>exec<ul>
<li>Used to launch your activity, specifying the type (<code>sugar-activity</code>), the file name, and the method to use to launch your program.</li>
</ul>
</li>
<li>show_launcher<ul>
<li>Display the activity in the sugar activity panel</li>
</ul>
</li>
<li>activity_version<ul>
<li>An integer representing the iteration of your activity (<em>cannot have decimals</em>)</li>
</ul>
</li>
<li>license<ul>
<li>The license your software is under, explains to users their rights with regard to your software.</li>
<li>GPL is a popular license, both 2 and 3 are commonly used.<ul>
<li>GPLv2+ means version 2 and newer applies.</li>
</ul>
</li>
</ul>
</li>
</ul>
<p>Troubleshooting:</p>
<ul>
<li>If the icon fails to display, it is likely that the icon name in <code>activity.info</code> is invalid.<ul>
<li>Remember not to include the <code>.svg</code> suffix for the file.</li>
</ul>
</li>
<li>If you are working on an older version of an activity, make sure the correct file and class names are used by <code>exec</code>.</li>
</ul>
<h4>activity/activity.svg</h4>
<p>The icons are in SVG format (XML Standard Vector Graphics).  It is suggested that users create icons using <a href="http://inkscape.org/">Inkscape</a>, a wonderful free and open source vector graphics software.</p>
<p><strong>Sugar recommends a 48x48 pixel size for its icons.</strong></p>
<p>After creating an icon in Inkscape, some fine-tuning is advised:</p>
<p><strong>Part One:</strong></p>
<pre><code>Before:--------------------------------
&lt;?xml version="1.0" encoding="UTF-8" standalone="no"?&gt;
&lt;!-- Created with Inkscape (http://www.inkscape.org/) --&gt;

After:---------------------------------
&lt;?xml version="1.0" ?&gt;&lt;!DOCTYPE svg PUBLIC '-//W3C//DTD SVG 1.1//EN' 'http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd'
[&lt;!ENTITY stroke_color "#000000"&gt;
&lt;!ENTITY fill_color "#FFFFFF"&gt;]&gt;&lt;svg
</code></pre>
<p><strong>Part TWO:</strong></p>
<pre><code>Before:--------------------------------
&lt;rect
style="fill:#ffffff;stroke:#000000;stroke-opacity:1"
id="rect904"
width="36.142857"
height="32.142857"
x="4.1428571"
y="7.1428571" /&gt;

After:---------------------------------
&lt;rect
style="fill:&amp;fill_color;;stroke:&amp;stroke_color;;stroke-opacity:1"
id="rect904"
width="36.142857"
height="32.142857"
x="4.1428571"
y="7.1428571" /&gt;
</code></pre>
<p>Saving these changes will set sugar colors for FILL and STROKE within the STYLE attribute.</p>
<h4>activity.py</h4>
<p>Activities are programmed in the <a href="http://www.python.org/">python programming language</a>.</p>
<p>Activities extend the sugar library, which are classes, and therefore need to be designed around class structures.  Without extending the sugar components they will not be executed properly under the sugar environment.</p>
<p><em>Larger programs can be separated into multiple files and included as components.</em></p>
<p><strong>Known Bug: Classes extending sugar components will not work outside the sugar desktop environment.</strong></p>
<p>There are a few options for developing for, or testing outside the sugar desktop environment:</p>
<ol>
<li>Create a separate version of the software that does not extend sugar library, and merging changes to the sugar version once tests are successful.</li>
<li>Create two versions of the top-level class and shared classes in separate files, executing one in sugar and the other for testing.</li>
</ol>
<h2>Building &amp; Distributing</h2>
<p>There are two ways to install and test your software.  Both assume that an XO laptop or Sugar Desktop Environment (or Development Environment) are being used.</p>
<ol>
<li>Create a <code>.xo</code> file and distribute it to the XO laptop(s)</li>
</ol>
<p>To create a package run:</p>
<pre><code>./setup genpot
./setup build
./setup dist_xo
</code></pre>
<p>The last command will generate a <code>dist/</code> folder with a <code>.xo</code> file inside it named after your activity.  This file is a compressed Sugar Package file which can be installed off a USB drive to other XO laptops.</p>
<ol>
<li>Create a symlink to the development activity using <code>./setup.py dev</code></li>
</ol>
<p>A symlink only has to be created once, but you should run these two commands first (and preferably before each test run):</p>
<pre><code>./setup genpot
./setup build
</code></pre>
<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>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
</code></pre>
<h2>Example Activity</h2>
<p>The <code>activity.py</code> has been populated with some basic content as a demonstration.</p>
<p>Move these files to a Sugar Desktop Environment, and run these commands:</p>
<pre><code>./setup.py genpot
./setup.py build
./setup.py dev
</code></pre>
<p>The icon should appear on the sugar desktop, or in the activities list, and be available for testing.</p></body></html>