Sugar

Modifying Sugar

Sugar is meant to be changed by you. Sugar is written in Python, an interpreted programming language, so that you can access the underlying code to see how things work. You can customize the Sugar platform however you like. In the spirit of free and open-source software, we hope that you share your improvements with the Sugar community.

In this chapter, we walk you through an example of changing Sugar:

  • changing the Home View from a circle to a spiral
  • changing your XO icon
Our hope is that you go beyond this example; learning something in the process.

Other things you might want to try include:

  • changing the home page of the Browse Activity
  • changing the start-up animation
  • "reskinning" Sugar

Changing the Home View

Revealing hidden views

The Home View defaults to a circular ring of Activity icons, but other patterns are available. There are preprogrammed patterns in Sugar and you can create your own.

1. You need to familiarize yourself with the Terminal Activity before you begin. Please refer to the chapter on the Terminal Activity for details on the GNU/Linux shell.

2. Open the Terminal Activity.

3. Since the Sugar source code is in a protected part of the system, you'll need to get a "root shell" in order to make changes. Type this command and press enter:

su -l

Note: This is a lower case L (an l), not a one (1).

4. The Home View code is in /usr/share/sugar/shell/view/Home. Type this command and press enter:

cd /usr/share/sugar/shell/view/home

5. It is always a good idea to make a backup copy of your code before making changes. Type this command and press enter:

cp favoritesview.py favoritesview.py.bak

6. Use vi (or your favorite text editor) to open favoritesview.py. Type this command and press enter:

vi favoritesview.py

Tip: Some basic commands for using the vi editor:

i (enter insert mode)

esc (exit insert mode)

:w (write/save your changes)

:q (quit vi)

7. You want to uncomment the code that unlocks the preprogrammed patterns by removing the # symbol (lines beginning with # are comments in Python).

Before:

_LAYOUT_MAP = {RING_LAYOUT: favoriteslayout.RingLayout,
               #BOX_LAYOUT: favoriteslayout.BoxLayout,
               #TRIANGLE_LAYOUT: favoriteslayout.TriangleLayout,
               #SUNFLOWER_LAYOUT: favoriteslayout.SunflowerLayout,
               RANDOM_LAYOUT: favoriteslayout.RandomLayout}

After:

_LAYOUT_MAP = {RING_LAYOUT: favoriteslayout.RingLayout,
               BOX_LAYOUT: favoriteslayout.BoxLayout,
               TRIANGLE_LAYOUT: favoriteslayout.TriangleLayout,
               SUNFLOWER_LAYOUT: favoriteslayout.SunflowerLayout,
               RANDOM_LAYOUT: favoriteslayout.RandomLayout}

8. Restart Sugar (by pressing ctrl + alt + erase). You can enjoy three new layouts for your Sugar Activity icons. (Tip of the hat to C. Scott Ananian for programming the "hidden" views.)

homeview_5choices

homeview_square

homeview_square

homeview_square

Creating a new view

You can also create your own view. Circles, squares, and triangles are nice, but a spiral is fun. In this example, we add some new code to two files: favoritesview.py and favoriteslayout.py.

The equation for an Archimedean spiral is

r = a + bθ
where r is the radius or distance from the center; a is the minimum (starting) radius of the spiral; and bθ is the increase of radius based on the increase in the angle of rotation.

1. Open the Terminal Activity. 

2. Again, you'll need to get a "root shell" in order to make changes. Type this command and press enter:

su -l

3. Go to /usr/share/sugar/shell/view/Home. Type this command and press enter:

cd /usr/share/sugar/shell/view/home

4. It is always a good idea to make a backup copy of your code before making changes. Type this command and press enter:

cp favoritesview.py favoritesview.py.bak
cp favoriteslayout.py favoriteslayout.py.bak

5. Use vi (or your favorite text editor) to open favoriteslayout.py. Type this command and press enter:

vi favoriteslayout.py

6. Add a new method at the end of the file:

class MyLayout(RingLayout):
    """Spiral layout based on Archimedean spiral: r = a + b*theta."""

    __gtype_name__ = 'MyLayout'

    icon_name = 'view-mylayout'
    """Name of icon used in home view dropdown palette."""

    profile_key = 'my-layout'
    """String used in profile to represent this view."""

    def __init__(self):
        RingLayout.__init__(self)

    def _calculate_radius_and_icon_size(self, children_count):
        """Stub out this method; not used in `My Layout`."""
        return None, style.STANDARD_ICON_SIZE

    def _calculate_position(self, radius, icon_size, index, children_count):
        """ Increment the radius as you go; decrease the angle of rotation
        as the radius increases to keep the distance between icons constant."""
        width, height = self.box.get_allocation()
        # angle decreases as the radius increases
        angle = index * (2 * math.pi / (12.0 + index / 6.0)) - math.pi / 2
        # radius is proportional to index/children_count
        myminimum = _MINIMUM_RADIUS * .67
        newradius = ((_MAXIMUM_RADIUS - myminimum) * (index * 1.1) / children_count) + myminimum
        x = newradius * math.cos(angle) + (width - icon_size) / 2
        y = newradius * math.sin(angle) + (height - icon_size - style.GRID_CELL_SIZE) / 2
        return x, y

7. Use vi (or your favorite text editor) to open favoritesview.py. Type this command and press enter:

vi favoritesview.py

8. Add your new layout by modifying these two lines:

RING_LAYOUT, BOX_LAYOUT, TRIANGLE_LAYOUT, SUNFLOWER_LAYOUT, MY_LAYOUT, RANDOM_LAYOUT = \
             xrange(6)

_LAYOUT_MAP = {RING_LAYOUT: favoriteslayout.RingLayout,
               BOX_LAYOUT: favoriteslayout.BoxLayout,
               TRIANGLE_LAYOUT: favoriteslayout.TriangleLayout,
               SUNFLOWER_LAYOUT: favoriteslayout.SunflowerLayout,
               MY_LAYOUT: favoriteslayout.MyLayout,
               RANDOM_LAYOUT: favoriteslayout.RandomLayout}

9. You will need an icon for your new layout. You can copy an existing icon:

cd /usr/share/icons/sugar/scalable/action
cp view-radial.svg view-mylayout.svg

Or you can modify the icon by following the discussion of Sugar icons in the section below.

10. Restart Sugar (by pressing ctrl + alt + erase).

Tip: If something goes wrong, which invariably it will, you can switch to one of the other Home Views, go back into the Terminal Activity and debug your code. If for some reason you even cannot launch the Terminal Activity, open the console by typing ctrl + alt + f1. From the console, you can restore your backup files (created in Step 4 above).

cd /usr/share/sugar/shell/view/home
cp favoritesview.py.bak favoritesview.py
cp favoriteslayout.py.bak favoriteslayout.py

Here's an example of the new spiral layout for your Home View.

homeview_6choices 

newspiral_1

The modified files are found here:

sugarlabs.org/go/User:Walter/favoriteslayout.py

sugarlabs.org/go/User:Walter/favoritesview.py

The icon used in the above example is found here:

sugarlabs.org/go/User:Walter/View-mylayout.svg

Changing your XO icon

Your XO icon is stored as a scalable vector graphics (SVG) file. By modifying this file, you can change the appearance of your XO icon.

About SVG

SVG is a language for describing two-dimensional graphics and graphical applications in XML. The SVG format allows Sugar to dynamically scale and color icons without any degradation in quality. The World-wide Web consortium (W3C) has an over of SVG at www.w3.org/Graphics/SVG/About.

There is a tutorial on preparing SVG files for Sugar at wiki.laptop.org/go/Making_SVG_Icons_for_Sugar.

You can edit SVG files using a variety of available tools, including www.inkscape.org/. (See The Inkscape Manual for details on how to use Inkscape).

Creating a simple icon by hand

Sugar defines the standard width and height of an icon canvas to be 55 pixels. The recommended width and height of the graphics is 45 pixels.

<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
 <svg xmlns="http://www.w3.org/2000/svg" width="55" height="55">
     <rect x="5" y="5" width="45" height="45" stroke="#666666" fill="#FFFFFF" stroke-width="3.5"/>
 </svg>

generic_icon
The icon defined above is a simple square.

Defining entities

Sugar uses "entities" in order to dynamically change icon colors.

  • add the entity declaration block inside the DOCTYPE.
  • replace all occurrences of colors within the body of the SVG.
Entity references begin with an ampersand (&) and end with a semi-colon (;), the entity name is in the middle (e.g., "&stroke_color;"). 
<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
     "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd" [
     <!ENTITY stroke_color "#666666">
     <!ENTITY fill_color "#FFFFFF">
 ]>
 <svg xmlns="http://www.w3.org/2000/svg" width="55" height="55">
     <rect x="5" y="5" width="45" height="45" stroke="&stroke_color;"
         fill="&fill_color;" stroke-width="3.5"/>
 </svg>

Your SVG icon is now Sugar-enabled.

Replacing the XO icon in the Home View

Follow these steps to replace the XO icon on your Home View with your own creation:

  1. Make a Sugar-enabled icon as per the instructions above.
  2. Name your file "my-xo.svg" and copy it onto a USB storage device.
  3. Start the Terminal Activity and enter these commands: 
    su -l

cp /media/*/my-xo.svg /usr/share/icons/sugar/scalable/device/
  4. Use vi (or your favorite text editor) to open /usr/share/sugar/shell/view/home/MyIcon.py. 
    vi /usr/share/sugar/shell/view/home/MyIcon.py
  5. Change the icon_name to "my-xo". 
    class MyIcon(CanvasIcon):
    def __init__(self, size):
        CanvasIcon.__init__(self, size=size,
                            icon_name='my-xo',
                            xo_color=profile.get_color())
  6. Restart Sugar (by pressing ctrl + alt + erase).

Your icon appears in the center of the Home View instead of the standard XO icon.

neko

Replacing the XO icon everywhere

In the previous section, we replaced the XO icon on the Home View. If you would like to replace it everywhere, you need to make one additional change.

Sugar looks for the XO icon in the file stored here:

/usr/share/icons/sugar/scalable/device/computer-xo.svg

Follow these steps to replace the XO icon with your own creation:

  1. Make a Sugar-enabled icon as per the instructions above.
  2. Name your file "computer-xo.svg" and copy it onto a USB storage device.
  3. Start the Terminal Activity and enter these commands: 
    su -l

cp /usr/share/icons/sugar/scalable/device/computer-xo.svg
/usr/share/icons/sugar/scalable/device/computer-xo.svg.bak

cp /media/*/computer-xo.svg
/usr/share/icons/sugar/scalable/device/computer-xo.svg
  4. Restart Sugar by pressing ctrl + alt + erase.

Note to parents and teachers

Sugar is designed to be modified by the user. Rather than build a "hardened" but brittle and opaque platform, Sugar is easy to change—but also easy to recover in case you make a mistake. Sugar takes computing "beyond black boxes". Look inside, make changes, and learn through debugging. You may find it frustrating at first, but you will be amply rewarded for your efforts as you learn to master the machine, rather than have it master you. Try it, you'll like it.