diff options
Diffstat (limited to 'studio/static/doc/myosa/ch010_package-the-activity.xhtml')
| -rw-r--r-- | studio/static/doc/myosa/ch010_package-the-activity.xhtml | 208 |
1 files changed, 208 insertions, 0 deletions
diff --git a/studio/static/doc/myosa/ch010_package-the-activity.xhtml b/studio/static/doc/myosa/ch010_package-the-activity.xhtml new file mode 100644 index 0000000..527b06b --- /dev/null +++ b/studio/static/doc/myosa/ch010_package-the-activity.xhtml @@ -0,0 +1,208 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" + "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><body><h1>Package The Activity +</h1> +<h2>Add setup.py +</h2> +<p> You'll need to add a Python program called <strong>setup.py</strong> to the same directory that you Activity program is in.  Every setup.py is exactly the same as every other setup.py.  The copies in our Git repository look like this: + <br/></p> +<pre>#!/usr/bin/env python + +# Copyright (C) 2006, Red Hat, Inc. +# +# This program is free software; you can redistribute it +# and/or modify it under the terms of the GNU General +# Public License as published by the Free Software +# Foundation; either version 2 of the License, or (at +# your option) any later version. +# +# This program is distributed in the hope that it will +# be useful, but WITHOUT ANY WARRANTY; without even +# the implied warranty of MERCHANTABILITY or FITNESS +# FOR A PARTICULAR PURPOSE. See the GNU General +# Public License for more details. +# +# You should have received a copy of the GNU General +# Public License along with this program; if not, +# write to the Free Software Foundation, Inc., +# 51 Franklin St, Fifth Floor, Boston, MA +# 02110-1301 USA + +from sugar.activity import bundlebuilder + +bundlebuilder.start()</pre> +<p>Be sure and copy the entire text above, including the comments. + <br/></p> +<p>The setup.py program is used by sugar for a number of purposes.  If you run setup.py from the command line you'll see the options that are used with it and what they do. +</p> +<pre>[jim@simmons bookexamples]$ ./setup.py +/usr/lib/python2.6/site-packages/sugar/util.py:25: +DeprecationWarning: the sha module is deprecated; +use the hashlib module instead + import sha +Available commands: + +build Build generated files +dev Setup for development +dist_xo Create a xo bundle package +dist_source Create a tar source package +fix_manifest Add missing files to the manifest +genpot Generate the gettext pot file +install Install the activity in the system + +(Type "./setup.py <command> --help" for help about a +particular command's options.</pre> +<p>We'll be running some of these commands later on.  Don't be concerned about the <strong>DeprecationWarning</strong> message.  That is just Python's way of telling us that it has a new way of doing something that is better but the old way we are using still works.  The error is coming from code in Sugar itself and should be fixed in some future Sugar release. + <br/></p> +<h2>Create activity.info +</h2> +<p> Next create a directory within the one your progam is in and name it <strong>activity</strong>.  Create a file named <strong>activity.info</strong> within that directory and enter the lines below into it.  Here is the one for our first Activity: + <br/></p> +<pre>[Activity] +name = Read ETexts II +service_name = net.flossmanuals.ReadEtextsActivity +icon = read-etexts +exec = sugar-activity ReadEtextsActivity.ReadEtextsActivity +show_launcher = no +activity_version = 1 +mime_types = text/plain;application/zip +license = GPLv2+</pre> +<p>This file tells Sugar how to run your Activity.  The properties needed in this file are: +</p> +<p> + </p><table border="0" cellpadding="4" cellspacing="0"><tbody><tr><td> <strong>name</strong></td> + <td>The name of your Activity as it will appear to the user. + <br/></td> + </tr><tr><td> <strong>service_name</strong></td> + <td>A unique name that Sugar will use to refer to your Activity.  Any Journal entry created by your Activity will have this name stored in its metadata, so that when someone resumes the Journal entry Sugar knows to use the program that created it to read it. + <br/></td> + </tr><tr><td valign="top"><strong>icon </strong> + <br/></td> + <td>The name of the icon file you have created for the Activity.  Since icons are always .svg files the icon file in the example is named read-etexts.svg. + <br/></td> + </tr><tr><td valign="top"><strong>exec</strong></td> + <td>This tells Sugar how to launch your Activity.  What it says is to create an instance of the class <strong>ReadEtextsActivity </strong>which it will find in file <strong>ReadEtextsActivity.py</strong>. + <br/></td> + </tr><tr><td valign="top"><strong>show_launcher</strong></td> + <td>There are two ways to launch an Activity.  The first is to click on the icon in the Activity view.  The second is to resume an entry in the Journal. Activities that don't create Journal entries can only be resumed from the Journal, so there is no point in putting an icon in the Activity ring for them.  Read Etexts is an Activity like that. + <br/></td> + </tr><tr><td valign="top"><strong>activity_version</strong></td> + <td>An integer that represents the version number of your program.  The first version is 1, the next is 2, and so on. + <br/></td> + </tr><tr><td valign="top"><strong>mime_types</strong></td> + <td>Generally when you resume a Journal entry it launches the Activity that created it.  In the case of an e-book it wasn't created by any Activity, so we need another way to tell the Journal which Activity it can use.  A MIME type is the name of a common file format.  Some examples are text/plain, text/html, application/zip and application/pdf.  In this entry we're telling the Journal that our program can handle either plain text files or Zip archive files. + <br/></td> + </tr><tr><td valign="top"><strong>license</strong></td> + <td>Owning a computer program is not like buying a car.  With a car, you're the owner and you can do what you like with it.  You can sell it, rent it out, make it into a hot rod, whatever.  With a computer program there is always a license that tells the person receiving the program what he is allowed to do with it.  GPLv2+ is a popular standard license that can be used for Activities, and since this is <em>my</em> program that is what goes here.  When you're ready to distribute one of <em>your</em> Activities I'll have more to say about licenses. + <br/></td> + </tr></tbody></table><h2>Create An Icon +</h2> +<p> Next we need to create an icon named <strong>read-etexts.svg</strong> and put it in the <strong>activity</strong> subdirectory. ⁞ We're going to use Inkscape to create the icon.  From the <strong>New</strong> menu in Inkscape select <strong>icon_48x48</strong>.  This will create a drawing area that is a good size. +</p> +<p>You don't need to be an expert in Inkscape to create an icon.  In fact the less fancy your icon is the better.  When drawing your icon remember the following points: +</p> +<ul><li>Your icon needs to look good in sizes ranging from really, really small to large.</li> + <li>It needs to be recognizeable when its really, really small.</li> + <li>You only get to use two colors: a stroke color and a fill color.  It doesn't matter which ones you choose because Sugar will need to override your choices anyway, so just use black strokes on a white background.</li> + <li>A fill color is only applied to an area that is contained within an unbroken stroke.  If you draw a box and one of the corners doesn't quite connect the area inside that box will not be filled.  Free hand drawing is only for the talented.  Circles, boxes, and arcs are easy to draw with Inkscape so use them when you can.</li> + <li>Inkscape will also draw 3D boxes using two point perspective.  Don't use them.  Icons should be flat images.  3D just doesn't look good in an icon.</li> + <li>Coming up with good ideas for icons is tough.  I once came up with a rather nice picture of a library card catalog drawer for <strong>Get Internet Archive Books</strong>.  The problem is, no child under the age of forty has ever seen a card catalog and fewer still understand its purpose.</li> +</ul><p>When you're done making your icon you need to modify it so it can work with Sugar.  Specifically, you need to make it show Sugar can use its own choice of stroke color and fill color.  The SVG file format is based on XML, which means it is a text file with some special tags in it.  This means that once we have finished editing it in Inkscape we can load the file into Eric and edit it as a text file. +</p> +<p>I'm not going to put the entire file in this chapter because most of it you'll just leave alone.  The first part you need to modify is at the very beginning. +</p> +<p>Before: +</p> +<pre><?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg +</pre> +<p> After: +</p> +<pre><?xml version="1.0" ?> +<!DOCTYPE svg PUBLIC '-//W3C//DTD SVG 1.1//EN' + 'http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd' [ + <!ENTITY stroke_color "#000000"> + <!ENTITY fill_color "#FFFFFF"> +]><svg +</pre> +<p>Now in the body of the document you'll find references to <em>fill</em> and <em>stroke</em> as part of an attribute called <em>style</em>.  Every line or shape you draw will have these, like this: +</p> +<pre><rect + style="fill:#ffffff;stroke:#000000;stroke-opacity:1" + id="rect904" + width="36.142857" + height="32.142857" + x="4.1428571" + y="7.1428571" /></pre> +<p>You need to change each one to look like this: +</p> +<pre><rect + style="fill:&fill_color;;stroke:&stroke_color; +;stroke-opacity:1" + id="rect904" + width="36.142857" + height="32.142857" + x="4.1428571" + y="7.1428571" /></pre> +<p>Note that <em>&stroke_color;</em> and <em>&fill_color;</em> both end with semicolons (;), and semicolons are also used to separate the properties for style.  Because of this it is an extremely common beginner's mistake to leave off the trailing semicolon because two semicolons in a row don't look right.  Be assured that the two semicolons in a row are intentional and absolutely necessary!  Second, the value for style should all go <em>on one line</em>.  We split it here to make it fit on the printed page; do not split it in your own icon! + <br/></p> +<h2>Make a MANIFEST File +</h2> +<p> You should remember that setup.py has an option to update a manifest.  Let's try it: +</p> +<pre>./setup.py fix_manifest +/usr/lib/python2.6/site-packages/sugar/util.py:25: +DeprecationWarning: the sha module is deprecated; +use the hashlib module instead + import sha +WARNING:root:Missing po/ dir, cannot build_locale +WARNING:root:Activity directory lacks a MANIFEST file. +</pre> +<p>This actually will build a MANIFEST file containing everything in the directory and its subdirectories.  The /po directory it is complaining about is used to translate Activities into different languages.  We can ignore that for now. +</p> +<p> The MANIFEST file it creates will contain some extra stuff, so we need to get rid of the extra lines using Eric.  The corrected MANIFEST should look like this: +</p> +<pre>setup.py +ReadEtextsActivity.py +activity/read-etexts.svg +activity/activity.info</pre> +<h2>Install The Activity +</h2> +<p> There's just one more thing to do before we can test our Activity under the Sugar emulator.  We need to install it, which in this case means making a symbolic link between the directory we're using for our code in the ~/Activities/ directory.  The symbol ~ refers to the "home" directory of the user we're running Sugar under, and a symbolic link is a way to make a file or directory appear to be located in more than one place without copying it.  We make this symbolic link by running setup.py again: +</p> +<pre>./setup.py dev +</pre> +<h2>Running Our Activity +</h2> +<p>Now at last we can run our Activity under Sugar.  To do that we need to learn how to run <strong>sugar-emulator</strong>. +</p> +<p>Fedora doesn't make a menu option for Sugar Emulator, but it's easy to add one yourself.  The command to run is simply +</p> +<pre>sugar-emulator</pre> +<p>If your screen resolution is smaller than the default size sugar-emulator runs at it will run full screen.  This is not convenient for testing, so you may want to specify your own size: +</p> +<pre>sugar-emulator -i 800x600</pre> +<p>Note that this option only exists in Fedora 11 and later. +</p> +<p>When you run sugar-emulator a window opens up and the Sugar environment starts up and runs inside it.  It looks like this: +</p> +<p><img alt="ReadEtexts_02.jpg" src="static/ActivitiesGuideSugar-ReadEtexts_02-en.jpg" height="480" width="640"/></p> +<p>When running sugar-emulator you may find that some keys don't seem to work in the Sugar environment.  This is caused by bugs in the <strong>Xephyr</strong> software that creates the window that Sugar runs in.  Sometimes it has difficulty identifying your keyboard and as a result some keys get misinterpreted.  On Fedora 11 I noticed that my function keys did not work, and my regular arrow keys didn't work either although my keypad arrow keys did.  I was able to get my function keys working again by putting this line in <em>~/.sugar/debug</em>: +</p> +<pre>run setxkbmap <em><keymap name></em></pre> +<p>This needs more explanation.  First, the symbol "~" refers to your home directory.  Second, any file named starting with a period is considered hidden in Linux, so you'll need to use the option to show hidden files and directories in the GNOME directory browser to navigate to it.  Finally, the keymap name is a two character country code: us for the United States, fr for France, de for Germany, etc. + <br/></p> +<p>To test our Activity we're going to need to have a book in the Journal, so use the <strong>Browse</strong> Activity to visit Project Gutenberg again and download the book of your choice.  This time it's important to download the book in Zip format, because Browse cannot download a plain text file to the Journal.  Instead, it opens the file for viewing as if it was a web page.  If you try the same thing with the Zip file it will create an entry in the Journal. +</p> +<p>We can't just open the file with one click in the Journal because our program did not create the Journal entry and there are several Activities that support the MIME type of the Journal entry.  We need to use the Start With menu option like this: +</p> +<p><img alt="ReadEtexts_03.jpg" src="static/ActivitiesGuideSugar-ReadEtexts_03-en.jpg" height="480" width="640"/></p> +<p>When we do open the Journal entry this is what we see: +</p> +<p><img alt="ReadEtexts_04.jpg" src="static/ActivitiesGuideSugar-ReadEtexts_04-en.jpg" height="480" width="640"/></p> +<p>Technically, this is the first <strong>iteration</strong> of our Activity.  (Iteration is a vastly useful word meaning something you do more than once.  In this book we're building our Activity a bit at a time so I can demonstrate Activity writing principles, but actually building a program in pieces, testing it, getting feedback, and building a bit more can be a highly productive way of creating software.  Using the word <em>iteration</em> to describe each step in the process makes the process sound more formal than it really is). +</p> +<p>While this Activity might be good enough to show your own mother, we really should improve it a bit before we do that.  That part comes next. + <br/></p></body></html>
\ No newline at end of file |