Sugar Labs - User contributions [en]

Activities/Implode

2009-05-25T18:47:11Z

Leejc: New page: = Implode = Image:Activity-implode.svg == Overview == Implode is a logic game based on the "falling block" model of Tetris. The game starts with a grid partially filled with blocks....

= Implode =

[[Image:Activity-implode.svg]]

== Overview ==
Implode is a logic game based on the "falling block" model of Tetris. The game starts with a grid partially filled with blocks. The player makes a move by removing adjacent blocks of the same color in groups of three or more. When blocks are removed, higher blocks fall to fill their space, and when a column is cleared, the blocks on either side close to fill the gap. The object of the game is to remove all the blocks. Since the patterns of blocks above changes when lower blocks are removed, the player must carefully decide what order in which to remove the blocks so that there are no isolated blocks left at the end of the game. (The levels are generated in such a way that there is always a sequence of removals that clears the board.)

== Screenshot ==
[[Image:Implode.png | 320px]]

== How to play ==

* The game starts up with a field of blocks.
* Using the mouse pointer, click on a block that is in a group of three or more of the same color (clickable groups highlight as you pass the mouse cursor over them). Clicking on a group removes it and compacts the playing field.
* Continue clicking groups of blocks until the board is cleared.
* If you get stuck with leftover blocks, you can:
** Click the Undo icon in the toolbar to undo some moves so that you can try again.
** Click the Restart icon in the toolbar to try the puzzle again from the beginning.
** Click the New icon in the tool bar to try a different puzzle.

The game can also be played via the game keys and directional pad:
* Use the directional pad to move the selection cursor.
* Use the checkmark game key to remove a selected group of blocks.
* Use the circle game key to undo a move.
* Use the X game key to redo a move.
* Use the square game key to start a new game (only active when the level is cleared).

== To do ==

* More localization.
* Rectangle invalidation could be improved.
* A tutorial mode or sequence of introductory games might help.
* The code documentation and organization needs to be improved. Some calculations are repeated.
* Audio cues might be nice.
* Tracking win/loss statistics might be nice.
* The game could detect a loss and display a "Try again" graphic.

== Resources ==

* [http://activities.sugarlabs.org/en-US/sugar/addon/4086 Activity download page]
* [http://git.sugarlabs.org/projects/implode Source]

[[Category:Activities]]

File:Activity-implode.svg

2009-05-25T18:46:38Z

Leejc: Icon of implode activity

Icon of implode activity

File:Implode.png

2009-05-25T18:40:35Z

Leejc: Screenshot of the Implode activity

Screenshot of the Implode activity

Development Team/Almanac/Code Snippets

2008-03-16T20:47:45Z

Leejc: /* Files */ added get_activity_root snippet

{{OLPC}}
{{Translations}}

== Smooth animation ==

[[PyGTK/Smooth_Animation_with_PyGTK]]

== WebView ==
Use the WebView in a widget.
import os
import hulahop
from sugar import env
hulahop.startup(os.path.join(env.get_profile_path(), 'gecko'))

from hulahop.webview import WebView

import gtk

win = gtk.Window(gtk.WINDOW_TOPLEVEL)
win.set_size_request(800,600)
win.connect('destroy', gtk.main_quit)
wv = WebView()
wv.load_uri('http://wiki.laptop.org/go/Guido_van_Robot')
wv.show()

win.add(wv)

win.show()
gtk.main()

=== Notes ===
* I'm not sure what the purpose is of the call to hulahop.startup as the documentation is rather sparse. I only knows it's needed to get it to work [[User:Stas_z|Stas Zytkiewicz]] 2 Dec 2007

== Toolbar ==

=== Toolbar icons ===

Setting a standard Sugar toolbar.
from sugar.activity import activity
...
class MyActivity(activity.Activity):
...
toolbox = activity.ActivityToolbox(self)
self.set_toolbox(toolbox)
toolbox.show()

Adding a custom toolbar and icons.
from sugar.graphics.toolbutton import ToolButton
from sugar.activity import activity
...
class MyActivity(activity.Activity):
...
mytoolbox = gtk.Toolbar()
helpbut = ToolButton('help') #Stock help icon
helpbut.set_tooltip(_("Get help"))
helpbut.connect('clicked', self.help_button_pressed)
mytoolbox.insert(helpbut, -1)
helpbut.show()
mytoolbox.show()

toolbox = activity.ActivityToolbox(self)
toolbox.add_toolbar("mytoolbar",mytoolbox)
self.set_toolbox(toolbox)
toolbox.show()

In addition to the standard icons in /usr/share/icons/sugar/scalable/ (eg, "go-next"), you can create additional icons by putting an svg in your activity's icons/ directory. E.g.,
icons/my-icon.svg
And then use it.
mybut = ToolButton('my-icon')# without extension

== Files ==

This snippet shows how to get a [http://mailman.laptop.org/pipermail/sugar/2007-February/001459.html path to files in the running Activity]:

from sugar.activity import activity
bundle_path = activity.get_bundle_path()

This snippet shows how to get [http://lists.laptop.org/pipermail/devel/2008-March/011799.html a path to an activity's writable directories] (i.e. the SUGAR_ACTIVITY_ROOT environment variable; see also [[Activity_DBus_API#Security | the activity DBus API]]):

class WebActivity(activity.Activity):
def __init__(self, handle):
activity.Activity.__init__(self, handle)
temp_path = os.path.join(self.get_activity_root(), 'instance')

== Images ==

* [http://mailman.laptop.org/pipermail/sugar/2007-February/001528.html Loading an SVG file onto a surface with a transparent background]:

target = ctx.get_target()
buf = target.create_similar(cairo.CONTENT_COLOR_ALPHA, w, h)
ctx.set_source_surface(buf, x, y)
ctx.paint()

* [http://mailman.laptop.org/pipermail/sugar/2007-February/001547.html Measuring an SVG file's original dimensions]

width, height = handle.get_dimension_data()

* Loading a JPEG file onto a surface:

pixbuf = gtk.gdk.pixbuf_new_from_file("foo.jpg")
ctx = # a cairo context
ctx.set_source_pixbuf(pixbuf, 0, 0)
ctx.paint()

libjpeg is said to be an alternative to using pixbuf. Which is better? Perhaps Sugar/[[HippoCanvas]] provides an easier way to do this?

[[Cairo]] image expansion is good quality, but expensive. Shrinking is fine and notably faster. So for images rendered large (ie, screen-size), you might want to start with a big image, rather than expanding a small one. A speed/space tradeoff. And use SVG instead if appropriate, of course. [[User:MitchellNCharity|MitchellNCharity]] 10:37, 10 May 2007 (EDT)

== Audio ==

* [http://lists.laptop.org/pipermail/sugar/2007-October/003480.html Playing a sound via csound]:

import sys
sys.path.append('/usr/share/activities/Pippy.activity/sound')
from sound import *
playWave(sound='triangle')
audioOut()

== Processes ==

* [http://lists.laptop.org/pipermail/sugar/2007-October/003596.html Starting an external process]

: Use Python's [http://docs.python.org/lib/module-subprocess.html subprocess module].

* [http://lists.laptop.org/pipermail/sugar/2007-October/003597.html Starting a binary activity instead of a Python activity]

: Set the "exec" property of the <tt>activity.info</tt> file to your binary.

== Not yet sorted ==

* [http://mailman.laptop.org/pipermail/sugar/2007-March/002028.html Getting a unique ID for the XO user]:

from sugar import profile

key = profile.get_pubkey()

# If you want a shorter key, you can hash that like:

from sugar import util

key_hash = util._sha_data(key)
hashed_key = util.printable_hash(key_hash)

* Avoid memory exhaustion from large dead pygtk objects by using

import gc

gc.collect()

Not all trash pygtk objects are garbage collected promptly. If you are throwing away large pixmaps, for instance, this can be deadly. gc.collect() forces a garbage collection pass.

== Performance Tips ==
''This section belongs on a different, as yet non-existent page. But a good organization for software development tips is currently unclear to me, so I'll stash this here for now.'' [[User:MitchellNCharity|MitchellNCharity]] 14:05, 10 May 2007 (EDT)

* ctx.stroke() several lines at once. stroke() currently has significant overhead. So it is faster to stroke several, than to stroke them individually. They need not be contiguous. [[User:MitchellNCharity|MitchellNCharity]] 14:05, 10 May 2007 (EDT)

== Old snippets which need to be overhauled ==
=== Toolbar ===

This snippet shows how an activity would have a toolbar with a button and a gtk.TextView widget embedded in a hippo Canvas:

import logging
import hippo
import gtk

from gettext import gettext as _

from sugar.activity import activity
from sugar.graphics.toolbar import Toolbar
from sugar.graphics.iconbutton import IconButton
from sugar.graphics.entry import Entry
from sugar.graphics.optionmenu import OptionMenu
from sugar.graphics.menu import MenuItem

class FooActivity(activity.Activity):

_ACTION_ANYTHING = 1
_ACTION_APPLES = 2
_ACTION_ORANGES = 3

def __init__(self, handle):
activity.Activity.__init__(self, handle)

vbox = hippo.CanvasBox()
self.set_root(vbox)

toolbar = Toolbar()
vbox.append(toolbar)

button = IconButton(icon_name='theme:stock-close')
button.connect("activated", self._button_activated_cb)
toolbar.append(button)

entry = Entry()
button.connect("activated", self._entry_activated_cb)
toolbar.append(entry)

option_menu = OptionMenu()
option_menu.add_item(MenuItem(self._ACTION_ANYTHING, _('Anything')))
option_menu.add_item(MenuItem(self._ACTION_APPLES, _('Apples'),
'theme:stock-close'))
option_menu.add_item(MenuItem(self._ACTION_ORANGES, _('Oranges')))
option_menu.add_separator()
toolbar.append(option_menu)

text_view_widget = hippo.CanvasWidget()
vbox.append(text_view_widget, hippo.PACK_EXPAND)

text_view = gtk.TextView()
text_view.get_buffer().set_text('Write here!', -1)
text_view_widget.props.widget = text_view

def _button_activated_cb(self, button):
logging.debug('FooActivity._button_activated_cb')

def _entry_activated_cb(self, entry):
logging.debug('FooActivity._entry_activated_cb')

:In build 443 (June '07), <tt>from sugar.graphics.entry import Entry</tt> yields ''ImportError: No module named entry''. [[User:MitchellNCharity|MitchellNCharity]] 19:52, 15 June 2007 (EDT)
:And obsolete, now deleted code like sugar.graphics.toolbar is being used. Snippet needs to be overhauled. [[User:MitchellNCharity|MitchellNCharity]] 18:04, 21 June 2007 (EDT)

[[Category:HowTo]]
[[Category:Sugar]]

Development Team/Manual/translations

2008-03-02T16:52:48Z

Leejc: Reverted edits by 61.133.87.226 (Talk); changed back to last version by RafaelOrtiz

Development Team/Manual/translations

2008-02-27T00:03:00Z

Leejc: Reverted edits by 65.47.164.46 (Talk); changed back to last version by Mcfletch

Development Team/Manual/translations

2008-02-23T00:32:30Z

Leejc: Reverted edits by 200.31.110.176 (Talk); changed back to last version by RafaelOrtiz

Development Team/Manual/translations

2008-02-12T00:29:10Z

Leejc: Reverted edits by 200.29.96.75 (Talk); changed back to last version by RafaelOrtiz

Development Team/Manual/translations

2008-02-08T00:55:40Z

Leejc: Reverted edits by 217.116.232.113 (Talk); changed back to last version by Chihyu

Development Team/Manual/translations

2008-02-01T17:52:49Z

Leejc: Reverted edits by 69.217.73.52 (Talk); changed back to last version by LeeSI

Human Interface Guidelines/Activities/Activity Bundles/lang-es

2008-02-01T17:52:41Z

Leejc: Reverted edits by 69.217.73.52 (Talk); changed back to last version by Walter

<noinclude>
{{OLPC}}
{{Translation | lang = es | source = OLPC Human Interface Guidelines/Activities/Activity Bundles | version = 47787 | source_display = OLPC-HIG-Activity Bundles}}
</noinclude>
<div style="background-color: #FFF; margin-left:auto; margin-right: auto; width: 95%;">
{{hig-subnav-inter-lang | lang=es
| p_link=Activities/Activity Basics
| c_section=Activities | c_page=Activity Bundles
| n_link=Security}}

{{anchor|The Activity Bundle}}

==={{:OLPC Human Interface Guidelines/Activities/Activity Bundles/lang-es/title}}===

{|border=1 cellpadding=1 cellspacing=0 style="float: right; width: 175px; border: 1px #666666 solid; border-collapse: collapse; background: #f9f9f9;"
!style="background:#D6784C"|Referencia API
|-
|[[Activity Bundles|Especificacion técnica de un Activity Bundle (en inglés)]]
|}
<font size="1">
{|border=1 cellpadding=1 cellspacing=0 style="float: right; width: 175px; border: 1px #666666 solid; border-collapse: collapse; background: #f9f9f9;"
!style="background:#D6784C"|API Reference
|-
|[[Activity Bundles|Activity Bundle technical specifications]]
|}
</font>
Las actividades existirán en forma de paquetes (''bundles''). Estos paquetes se manifestarán como un grupo de archivos relacionados—código fuente, imágenes, documentación, etc.—que conforman una dada actividad. Como módulos auto-contenidos, la distribución e instalación de una actividad se reduce a una simple transferencia del paquete de una actividad a una laptop. Las propiedades guardadas dentro de un paquete proveen información sobre su versión y creador(es).
{{ Translated text |
Activities will exist in the form of bundles. These bundles will manifest as groups of related files—source code, images, documentation, etc—that compose a given activity. As self-contained modules, the distribution and installation of an activity distills to a simple transfer of the activity bundle to a laptop. Properties stored within a bundle provide information about its version and its creator(s).
| display = block }}

{{anchor|Bundle Types}}
====Tipos de Paquetes====

La OLPC soportará un tipo de paquete "oficial" firmado. Paquetes firmados han sido probados y verificados por una autoridad tal como laptop.org o cualquier otra organización a través de la cual los chicos obtengan paquetes de forma oficial, tal como los repositorios oficiales de un país. Este sistema puede soportar una metáfora de goteo-hacia-arriba (''trickle-up'') por medio de la cual los paquetes firmados localmente se propagan hacia arriba hacia autoridades superiores, permitiendo una mayor distribución de actividades y contenidos recientemente creados hacia otras regiones y países.
{{ Translated text |
OLPC will support a signed "official" bundle type. Signed bundles have been tested and verified by an authority such as laptop.org or any other organization through which children obtain bundles in some official capacity, such as a country's official repository. This system may support a trickle-up metaphor through which locally signed bundles propagate upward to higher authorities, allowing wider distribution of newly created activities and content to other regions and countries.
| display = block }}

Paquetes personales, por otro lado, han sido creados o modificados por un individuo dentro de la comunidad de laptops. Un paquete personal no está firmado o verificado por una fuente oficial; en cambio, está firmado o 'marcado al agua' (''watermarked'') con la identidad del individuo que lo modificó. Esta 'marca al agua' (''watermark'') permanece junto al paquete a lo largo de su vida. Como otros pueden a su vez modificarlo o cambiarlo, sus propias marcas al agua serán agregadas al paquete. Esto le brinda al paquete personal cierto sentido de origen y los medios por los cuales es posible dar crédito y responsabilidad.
{{ Translated text |
Personal bundles, on the other hand, have been created or modified by an individual among the laptop community. A personal bundle isn't signed or verified by an official source; instead, it is signed or watermarked with the identity of the individual who modified it. This watermark remains attached to the bundle throughout its lifetime. As others modify or change it, their own watermark should be appended to the bundle. This gives a personal bundle some sense of origin and a means through which it is possible to give credit or responsibility.
| display = block }}

{{anchor|Bundle Versions}}
====Versiones de Paquetes====

Los paquetes se actualizarán de forma automática a la versión oficialmente firmada más reciente presente en la red. Si el amigo de un chico tiene una versión firmada más reciente, Sugar la descargará y actualizará la laptop automáticamente. Esto requiere que los paquetes comuniquen un identificador único de paquete y versión, así como su firma si la tienen.
{{ Translated text |
Bundles always automatically update to the latest officially signed version present within the laptop's network. If a child's friend has a more recent version of a signed bundle, Sugar will download that newer version and update the laptop automatically. This requires bundles to communicate a unique bundle identifier and version, as well as their signature if they have one.
| display = block }}

{{anchor|Naming Activities}}
====Nombrando Actividades====

La OLPC apunta a proveer una plataforma que incentive la expresión por medio de la creación. Soportando esta idea, las actividades—no aplicaciones—proveen la herramienta principal por la cual se crean objetos. Dentro de lo posible, las actividades deben ser nombradas con verbos descriptivos, o pseudo-verbos, con la finalidad de reforzar su función como ''cosas que uno hace''.
{{ Translated text |
OLPC aims to provide a platform which encourages expression through creation. In support of this idea, activities — not applications — provide the main tools through which objects are created. Whenever possible, activities should be named with descriptive verbs, or suitable pseudo-verbs, in order to emphasize their function as ''things you do.''
| display = block }}

{{anchor|Activities as Verbs}}
=====Actividades como Verbos=====

Las actividades ''son'' verbos. Como la frase "<actividad> con mis amigos" debería tener sentido. Por ejemplo, "pinto con mis amigos", "navego con mis amigos", "hablo con mis amigos" y "edito texto con mis amigos" tienen mucho mas sentido que "editor de texto con mis amigos." De igual modo, "Tam-tam con mis amigos" se lee como una acción, aun cuando uno nunca haya escuchado a "tam-tam" antes. Utilizar una actividad como una acción (verbo) y no como una cosa (sustantivo) mantiene al modelo interactivo que la laptop trata de corporizar.
{{ Translated text |
Activities ''are'' verbs. As such, the phrase "<activity> with my friends" should make sense. For instance "draw with my friends," "browse with my friends", "chat with my friends" and "edit text with my friends" all make much more sense than "text editor with my friends." Similarly, "Tam-tam with my friends" reads as an action, even though you may have never heard "tam-tam" before. Treating the activity as an action (verb) and not as a thing (noun) maintains the interaction model that the laptop tries to embody.
| display = block }}

{{anchor|Meaningful Naming}}
=====Nombres con Sentido=====

Por supuesto, no es nuestra intención imponer límites arbitrarios a los tipos y cantidades de actividades que la plataforma pueda soportar. Simplemente porque ya exista una actividad "Draw" ("Dibujo") no quiere decir que uno deba encontrar un sinónimo o hacer otra actividad. (Sin embargo, cabe destacar que la primera opción puede ser muy razonable ya que un sinónimo puede de hecho tener sutiles diferencias en su connotación que se adhieren mejor al concepto de la actividad. Por ejemplo, dibujar y pintar típicamente implican dos tipos diferentes de materiales, seco y mojado respectivamente. Se gana mucho cuando estos tipos de diferencias son reflejados en la naturaleza de la actividad, en vez de simplemente arbitrariedades.) <u>'''<font color=red>NB: lo que sigue es literal, no semántico</font>''' En algunos idiomas, la «verbalización» (''[http://en.wikipedia.org/wiki/Verbing verbification]'') es una práctica oral usual. Muchas palabras funcionan tanto como sujetos y verbos, indicando una acción de creación y el producto resultante de dicha acción; además, muchos sujetos también pueden funcionar como verbos. Por ejemplo, si habla inglés, es probable que Ud. haya «Googleado» (''Googled'') algo hace poco. Muchos sujetos, pueden ser utilizados de forma similar.</u>
{{ Translated text |
Of course, we don't mean to impose arbitrary limits on the types and number of activities that the platform has the potential to support. Just because there is a "Draw" activity doesn't mean that one must either find a synonym or come up with a different activity. (However, note that the former can be a very reasonable approach, as a synonym might actually have subtly different connotations which better support the concept of the activity. For instance, drawing and painting typically imply two very different types of media, dry and wet respectively. Much is gained when these types of differences are reflected in the nature of the activity, and are not simply arbitrary.) In some languages, [http://en.wikipedia.org/wiki/Verbing verbification] has become common practice in speech. Many words function as both nouns and as verbs, indicating the action of creation and the resulting product of that action; additionally, many nouns can also function as verbs. For instance, if you speak English, you've probably "Googled" something in the past few days. Many nouns, not just proper ones, can be used in a similar manner.
| display = block }}

<font size="5" color="red">What follows is too english-centric... and not common in spanish without mangling the language... either that or I'm out of ideas... :(</font>
{{Pending|out of ideas...}}

{{ Translated text |
Additionally, while straightforward names can simplify the interface and provide a means of understanding an activity before entering it, compound names may also be used. Providing a modifier, such as an adjective, can personalize the activity and provide that extra bit of information which differentiates it from similar ones. For instance: "Finger Paint." However, please refrain from resorting to simple [http://en.wikipedia.org/wiki/One-upmanship one-upmanship] in the form of "Super Sketch" or "Ultra Paint," especially if another activity already uses the modified base. Such names only serve to indicate superiority, and don't provide any useful feedback about the particular activity which makes it unique or useful. Providing a meaningful name goes a long way to making the activity intuitive and enticing to the children using it.
| display = block }}

{{anchor|Credit}}
=====Crédito=====

Finalmente, por favor eviten el incorporar su nombre o el de su compañia al nombre de la actividad. Como iniciativa ''open-source'' creemos firmemente en dar crédito donde corresponda, pero el nombre de su actividad no es el lugar apropiado donde obtenerlo.
{{ Translated text |
Finally, please avoid integrating the name of yourself or of your company into the name of your activity. As an open-source initiative we fully believe in giving due credit, but the name of your activity doesn't provide the appropriate place for accreditation.
| display = block }}

{{anchor|Activity Tags}}
====Etiquetas de la Actividad====

Si bien todavía no está en funcionamiento, el archivo <tt>.info</tt> de una actividad deberá tener una lista de etiquetas asociadas. Estas etiquetas proveen información adicional sobre el contexto de una actividad específica, permitiendo una búsqueda potente en la Malla por medio de generalizaciones o categorías de actividades. Por ejemplo, al buscar por "juego" debería retornar las actividades de "Memoria", "Ajedrez" y "Tres-en-linea". De modo similar, buscar por "dibujar" deberia encontrar cualquier actividad relacionada con dibujar, pintar, garabatear, etc.
{{ Translated text |
Though not yet supported, the .info file for an activity will require a list of associated tags. These tags provide additional information about the context of a specific activity, enabling powerful searching on the Mesh for generalizations or categories of activities. For instance, searching for "game" should return the "Memory," "Chess," and "Tic-Tac-Toe" activities. Likewise, searching for "drawing" should return any activities that relate to drawing, painting, sketching, etc.
| display = block }}

{{anchor|Obtaining Activity Bundles}}
====Obtener Paquetes de Actividad====

Los paquetes de actividad oficialmente firmados deberían propagarse por el Vecindario de la malla; tanto su información como los paquetes mismos deben ser libremente accesibles para cualquiera dentro del rango de comunicación. Su instalación y actualización debería ser implícito.
{{ Translated text |
Officially signed bundles should spread freely across the mesh Neighborhood; their information and the bundles themselves should be readily available to anyone within communication range. Installation and updates should occur implicitly.
| display = block }}

Si bien los paquetes de actividades personales estan más restringidos, por el momento se piensa limitar la distribución de paquetes personales solamente entre los amigos de un chico. Esto debería limitar la capacidad destructiva de un paquete maligno de propagarse por el Vecindario, pero permitiendo que la gente abra el código fuente de su paquete, mejorarlo y compartirlo explicitamente.
{{ Translated text |
While personal bundles are slightly more restricted, current thinking would limit distribution of personal bundles amongst a child's friends only. This should help limit the destructive power of a malicious bundle from spreading across the Neighborhood, yet still allow people to open up their bundle source code, improve it and share it explicitly.
| display = block }}

=====Compartir Paquetes Implícitamente=====
{{anchor|Implicit Bundle Sharing}}

El compartir los paquetes implícitamente permitirá actualizar de modo automático los paquetes firmados en la máquina de un chico siempre que la red lo permita. Si un chico encuentra una actividad de su interés en la malla del Vecindario, la descarga e instalación se hará de forma implícita al momento de unirse a la actividad. Esto permite obtener paquetes completamente nuevos ya que no es necesario disponer la versión anterior del paquete previamente instalado para unirse. Por supuesto, dado que probablemente existirá una demora mientras se descarga la actividad, un indicador visual de su progreso aparecerá mientras se lanza.
{{ Translated text |
Implicit bundle sharing will automatically update signed bundles on a child's machine when the network allows. If a child finds an interesting activity running on the mesh Neighborhood, she will implicitly download and install the activity on her own machine when she joins that activity. Additionally, this provides a means of obtaining completely new bundles, since she doesn't necessarily need to have an older version of the bundle installed prior to joining. Of course, since there will likely be some download time before the activity can begin, a visual indication of the progress will appear during launch.
| display = block }}

En el caso que un chico se una a un grupo corriendo una version anterior de una actividad para la cual dispone de una versión más nueva, ocurrirá lo mismo. Su laptop descargará silenciosamente la versión más vieja de la actividad de modo tal que cuando se una, su actividad sea compatible tanto a nivel de servicios como de comunicaciones. Sin embargo, en dichas circunstancias la vieja versión no sobre-escribirá a la mas reciente, y en su lugar permanacerá como un detalle transparente por razones de compatibilidad. La versión más nueva permanecerá en su máquina para que las actividades futuras que inicie sean con la nueva versión, de modo tal de favorecer la propagación de las versiones más nuevas.
{{ Translated text |
In cases where a child joins a group running an older version of an activity she has a newer version of, the same will happen. Her laptop will silently download the older version of the activity so that when she joins, her active instance is service and communication level compatible. However, in such instances the old version will not overwrite the newer version, and will instead remain a transparent detail for compatibility reasons. The newer will remain present on her machine, so that future activities which she initiates begin with the new version, ultimately encouraging the spread of newer bundles.
| display = block }}

Quizás sea necesario algún tipo de advertencia cuando se está por unir a una actividad en la malla cuyo paquete no este firmado...
{{stub}}
{{ Translated text |
We might need some kind of warning when joining an activity on the mesh whose bundle is not signed...
| display = block }}

=====Compartir Explícitamente los Paquetes=====
{{anchor|Explicit Bundle Sharing}}

En el caso de los paquetes personales, se necesita compartirlos explícitamente. La razón es que muchos chicos pueden en última instancia editar y redistribuir versiones de paquetes nuevos y modificados de múltiples softwares; la distribución automática de tales modificaciones no es ni seguro ni eficiente.
{{ Translated text |
In the case of personal bundles, explicit sharing will be required. This results from the fact that many children may ultimately edit and redistribute new and altered bundle versions of a variety of software; automatic distribution of such modifications is neither secure nor efficient.
| display = block }}

En estos casos, las actividades pueden ser publicadas en Carteleras privadas, o ser distribuidos directamente a los amigos de un chico por medio del uso de metáforas de ''drag-and-drop'' usadas en la interfaz.
{{ Translated text |
In these cases, activities may be posted to private Bulletin Boards, or distributed directly to a child's friends through the drag and drop metaphors used elsewhere in the interface.
| display = block }}

{{anchor|Where Are Bundles Stored?}}
====Donde se Guardan los Paquetes?====

El Diario mantiene un registro de todos lo paquetes en la laptop. La instalación de un paquete crea una entrada que indica de quien se descargó el paquete y su versión. Si la instalación se produjo como la consecuencia de unirse a una actividad, la entrada de la actividad en el Diario tendrá una referencia al paquete recientemente actualizado. Por supuesto, una vez guardado en el Diario, el Paquete estará disponible para su activación en la sección de Acciones del Marco.
{{ Translated text |
The Journal keeps a record of all bundles on the laptop. Installing a bundle creates an entry that indicates who the child downloaded the bundle from and its version. If she installed the bundle through the joining of an activity, the activity entry in the journal will reference the newly updated bundle. Of course, once stored within the journal, the Bundle will be available for activation within the Actions section of the Frame.
| display = block }}

{{anchor|Removing Bundles}}
====Eliminando Paquetes====

El registro en el Diario para un paquete de actividad también permite su eliminación; es borrado en la misma manera que uno podría eliminar cualquier otro ítem del Diario.

{{ Translated text |
The journal entry for an activity bundle also allows for its removal; it is deleted in the same way one would remove any other item from the Journal.
| display = block }}

{{hig-subnav-inter-lang | lang=es
| p_link=Activities/Activity Basics
| c_section=Activities | c_page=Activity Bundles
| n_link=Security}}

Human Interface Guidelines/Activities/Activity Bundles

2008-02-01T17:52:37Z

Leejc: Reverted edits by 69.217.73.52 (Talk); changed back to last version by 74.184.170.64

<div style="background-color: #FFF; margin-left:auto; margin-right: auto; width: 95%;">
<noinclude>{{Translations}}</noinclude>
{{hig-subnav-inter|p_link=Activities/Activity Basics|p_label=Activity Basics|c_section=Activities|c_page=Activity Bundles|n_link=Security|n_label=Security}}

===The Activity Bundle===

{|border=1 cellpadding=1 cellspacing=0 style="float: right; width: 175px; border: 1px #666666 solid; border-collapse: collapse; background: #f9f9f9;"
!style="background:#D6784C"|API Reference
|-
|[[Activity Bundles|Activity Bundle technical specifications]]
|}
Activities will exist in the form of bundles. These bundles will manifest as groups of related files—source code, images, documentation, etc—that compose a given activity. As self-contained modules, the distribution and installation of an activity distills to a simple transfer of the activity bundle to a laptop. Properties stored within a bundle provide information about its version and its creator(s).

====Bundle Types====
OLPC will support a signed "official" bundle type. Signed bundles have been tested and verified by an authority such as laptop.org or any other organization through which children obtain bundles in some official capacity, such as a country's official repository. This system may support a trickle-up metaphor through which locally signed bundles propagate upward to higher authorities, allowing wider distribution of newly created activities and content to other regions and countries.

Personal bundles, on the other hand, have been created or modified by an individual among the laptop community. A personal bundle isn't signed or verified by an official source; instead, it is signed or watermarked with the identity of the individual who modified it. This watermark remains attached to the bundle throughout its lifetime. As others modify or change it, their own watermark should be appended to the bundle. This gives a personal bundle some sense of origin and a means through which it is possible to give credit or responsibility.

====Bundle Versions====
Bundles always automatically update to the latest officially signed version present within the laptop's network. If a child's friend has a more recent version of a signed bundle, Sugar will download that newer version and update the laptop automatically. This requires bundles to communicate a unique bundle identifier and version, as well as their signature if they have one.

====Naming Activities====

OLPC aims to provide a platform which encourages expression through creation. In support of this idea, activities — not applications — provide the main tools through which objects are created. Whenever possible, activities should be named with descriptive verbs, or suitable pseudo-verbs, in order to emphasize their function as ''things you do.''

=====Activities as Verbs=====

Activities ''are'' verbs. As such, the phrase "<activity> with my friends" should make sense. For instance "draw with my friends," "browse with my friends", "chat with my friends" and "edit text with my friends" all make much more sense than "text editor with my friends." Similarly, "Tam-tam with my friends" reads as an action, even though you may have never heard "tam-tam" before. Treating the activity as an action (verb) and not as a thing (noun) maintains the interaction model that the laptop tries to embody.

=====Meaningful Naming=====

Of course, we don't mean to impose arbitrary limits on the types and number of activities that the platform has the potential to support. Just because there is a "Draw" activity doesn't mean that one must either find a synonym or come up with a different activity. (However, note that the former can be a very reasonable approach, as a synonym might actually have subtly different connotations which better support the concept of the activity. For instance, drawing and painting typically imply two very different types of media, dry and wet respectively. Much is gained when these types of differences are reflected in the nature of the activity, and are not simply arbitrary.) In some languages, [http://en.wikipedia.org/wiki/Verbing verbification] has become common practice in speech. Many words function as both nouns and as verbs, indicating the action of creation and the resulting product of that action; additionally, many nouns can also function as verbs. For instance, if you speak English, you've probably "Googled" something in the past few days. Many nouns, not just proper ones, can be used in a similar manner.

Additionally, while straightforward names can simplify the interface and provide a means of understanding an activity before entering it, compound names may also be used. Providing a modifier, such as an adjective, can personalize the activity and provide that extra bit of information which differentiates it from similar ones. For instance: "Finger Paint." However, please refrain from resorting to simple [http://en.wikipedia.org/wiki/One-upmanship one-upmanship] in the form of "Super Sketch" or "Ultra Paint," especially if another activity already uses the modified base. Such names only serve to indicate superiority, and don't provide any useful feedback about the particular activity which makes it unique or useful. Providing a meaningful name goes a long way to making the activity intuitive and enticing to the children using it.

=====Credit=====

Finally, please avoid integrating the name of yourself or of your company into the name of your activity. As an open-source initiative we fully believe in giving due credit, but the name of your activity doesn't provide the appropriate place for accreditation.

====Activity Tags====

Though not yet supported, the .info file for an activity will require a list of associated tags. These tags provide additional information about the context of a specific activity, enabling powerful searching on the Mesh for generalizations or categories of activities. For instance, searching for "game" should return the "Memory," "Chess," and "Tic-Tac-Toe" activities. Likewise, searching for "drawing" should return any activities that relate to drawing, painting, sketching, etc.

====Obtaining Activity Bundles====

Officially signed bundles should spread freely across the mesh Neighborhood; their information and the bundles themselves should be readily available to anyone within communication range. Installation and updates should occur implicitly.

While personal bundles are slightly more restricted, current thinking would limit distribution of personal bundles amongst a child's friends only. This should help limit the destructive power of a malicious bundle from spreading across the Neighborhood, yet still allow people to open up their bundle source code, improve it and share it explicitly.

We may wish to allow distribution to any Group rather than just to Friends,
so that if a child wrote an activity that is useful for her whole class, she
does not have to add everyone to her Friend group, breaking the metaphor.

=====Implicit Bundle Sharing=====
Implicit bundle sharing will automatically update signed bundles on a child's machine when the network allows. If a child finds an interesting activity running on the mesh Neighborhood, she will implicitly download and install the activity on her own machine when she joins that activity. Additionally, this provides a means of obtaining completely new bundles, since she doesn't necessarily need to have an older version of the bundle installed prior to joining. Of course, since there will likely be some download time before the activity can begin, a visual indication of the progress will appear during launch.

In cases where a child joins a group running an older version of an activity she has a newer version of, the same will happen. Her laptop will silently download the older version of the activity so that when she joins, her active instance is service and communication level compatible. However, in such instances the old version will not overwrite the newer version, and will instead remain a transparent detail for compatibility reasons. The newer will remain present on her machine, so that future activities which she initiates begin with the new version, ultimately encouraging the spread of newer bundles.

We might need some kind of warning when joining an activity on the mesh whose bundle is not signed...

=====Explicit Bundle Sharing=====
In the case of personal bundles, explicit sharing will be required. This results from the fact that many children may ultimately edit and redistribute new and altered bundle versions of a variety of software; automatic distribution of such modifications is neither secure nor efficient.

In these cases, activities may be posted to private Bulletin Boards, or distributed directly to a child's friends through the drag and drop metaphors used elsewhere in the interface.

====Where Are Bundles Stored?====
The Journal keeps a record of all bundles on the laptop. Installing a bundle creates an entry that indicates who the child downloaded the bundle from and its version. If she installed the bundle through the joining of an activity, the activity entry in the journal will reference the newly updated bundle. Of course, once stored within the journal, the Bundle will be available for activation within the Actions section of the Frame.

====Removing Bundles====
The journal entry for an activity bundle also allows for its removal; it is deleted in the same way one would remove any other item from the Journal.

{{hig-subnav-inter|p_link=Activities/Activity Basics|p_label=Activity Basics|c_section=Activities|c_page=Activity Bundles|n_link=Security|n_label=Security}}

Human Interface Guidelines/Activities/translations

2008-02-01T17:51:51Z

Leejc: Reverted edits by 65.115.69.130 (Talk); changed back to last version by Walter

Human Interface Guidelines/Activities/Activity Basics

2008-02-01T17:51:10Z

Leejc: Reverted edits by 65.115.69.130 (Talk); changed back to last version by 74.184.170.64

<div style="background-color: #FFF; margin-left:auto; margin-right: auto; width: 95%;">
<noinclude>{{Translations}}</noinclude>
{{hig-subnav-intra|p_page=Introduction|c_section=Activities|c_page=Activity Basics|n_page=Activity Bundles}}

===Starting Activities===
Activities appear in the Actions section of the frame; starting an activity amounts to creating an active instance of it, represented in the activity ring. They can be started with a single click. An activity may also be directly manipulated; dragging an activity into the ring will also create a new active instance of it.

Visual cues differentiate between instances of an activity and the [[OLPC Human Interface Guidelines/The Sugar Interface/Icons#Activity Icons|activity icon]] in the frame. Specifically, any activity installed on the system and appearing in the Actions edge is drawn as a white outline stroke, with no fill. Upon instantiation the icon receives a fill; both [[OLPC Human Interface Guidelines/The Sugar Interface/Icons#Strokes & Fills|stroke and fill colors]] match the XO colors of the child who created it.

====Private Activities====
Newly created activity instances inherit the scope of the view in which they are created. This means that any activity started from the Home view begins as a private one by default. Children may later [[OLPC Human Interface Guidelines/Activities/Activity Basics#Sharing_Activities|share]] private activities, opening them up to friends, classmates, group members, or anyone on the mesh through an [[OLPC Human Interface Guidelines/Activities/Activity Basics#Invitations|explicit invitation]].

====Shared Activities====
Since newly created activities inherit the scope of the view, any activity started directly from the Friends Group view will be open for her friends to participate in. This applies to any group the child belongs to as well. [[OLPC Human Interface Guidelines/Activities/Activity Basics#Implicit_Invitations|Implicit invitations]] are sent to all of the members of the currently selected Group, alerting them of the activity. Likewise, any activity started from the (unfiltered) Mesh view will be open to everyone on the mesh, although invitations are not sent.

The views provide scope for instantiating activities. For finer granularity, the search (located in the Frame) provides an incremental filtering system that enables arbitrary selection of scope. As a query is entered into the search field, the view—Friends or Mesh—dynamically updates to reveal the matching selection. Matches remain in color, while those filtered out appear with a white outline. The filter terms apply parameters such as the names of activities, the types of activities, the names of individuals, and the interests of individuals. For instance, a child could search for anyone who likes games before starting a new game of Memory, or everyone in the same grade in a classroom setting, or a specific group of individuals by name. The results of the query become the scope for any new activity instance, and all XOs within that scope receive implicit invitations when an activity begins. These groupings may be saved as groups for future use.

Once a shared activity begins, the child who initiated the activity is taken into Activity view. Others who received invitations won't join the activity until they accept the invitation; white outline placeholders for their XO icons appear in the People section of the frame to indicate their potential arrival. If they accept an invitation, their XO fills with their colors; if they decline the outline disappears.

===Joining Activities===
Children will often find themselves joining activities already started by others. Activities can be discovered through search; searches may specify an activity name, an activity type, interests of individuals, and names of individuals. For instance, one could search for all activities that relate to music, or all activities that have participants who like camping, or all the active chat activities, or a few specific people by name. Once an appropriate activity is found, a single click on the activity icon will engage it.

===Sharing Activities===

Activities may begin as private, or restricted to a small group of individuals. There may be occasion to open up activities to a broader scope. For instance, a class may break into groups to work on a project within private group activities. At the end of the session, all groups may wish to open up their activities to the rest of the class for discussion and critique. Through selection in the activities contextual rollover, one may set the scope of children who may join an activity to one of Private, Mesh, or any specific Group to which she belongs, including her class, her friends, and potentially others.

A child may lock activities in a similar manner, tightening an activity's scope. Participants must leave on their own volition or at the request of others within the activity before locking it.

===Switching Activities===
The activity ring indicates the activities currently running on the laptop. From the Home view, a single click on any activity in the ring will select it as the active activity, automatically transitioning back to its Activity view. Keyboard shortcuts enable quick transitions among open activities.

===Ending Activities===

Ending an activity happens as easily as starting one. To complete the metaphor, dragging an activity out of the ring will end it. Selecting the End action in the activities contextual rollover will do likewise. Note that ending a shared activity—even one ''you'' started—does not necessarily "close" it. An activity instance remains active on the mesh as long as one or more individuals remain as participants.

===Resuming Activities===

In lieu of an "Open" command, one may simply resume an activity. If a drawing resides in the Journal, then resuming it will automatically restart the Draw activity, allowing modifications to that drawing. Due to the emphasis on collaborative activities, special consideration has to be given when resuming them; An activity fingerprint identifies a particular instance on the mesh. Resuming an activity implicitly invites all others who at one point participated in its creation that also remain within its currently specified scope. Additionally, cases may arise when an activity being resumed is already active on the mesh. In such cases, the child will automatically join the already active instance.

===Activity Robustness===

All activities designed for the laptop should place a strong emphasis on robustness. Two essential robustness considerations are input and network.

===Invitations===

Invitations perform an essential functionality in a computing environment that so strongly emphasizes collaborative learning and creation. For this reason, two forms of invitations are present in the OS: explicit and implicit.

====Explicit Invitations====
Explicit invitations are used to invite specific individuals into already active activities. The ability to send explicit invitations to others serves particular use when in a private activity, be it a private group or a solitary one. In these cases, an explicit invitation can extend the group by including one or more specific individuals, without opening up the activity to a broader scope.

A child may initiate an explicit invitation either from within the activity itself or by identifying an individual or group in either the Groups or Neighborhood views.

====Implicit Invitations====
Implicit invitations do not require specific action on the part of the child. These invitations go to the appropriate individuals whenever actions suggest it, such as when starting an activity from the Groups or Neighborhood views. All individuals within the activity's scope receive implicit invitations to join. When an activity is resumed, those who participated previously receive an invitation.

====Receiving Invitations====
Incoming invitations appear within the [[OLPC Human Interface Guidelines/The Laptop Experience/The Frame#Actions|Actions]] section of the Frame, adjacent to the installed activities; they are rendered in the color of the inviter. Rollover reveals both the name of the inviter as well as the name and type of the activity. On extended rollover, the options to accept and decline appear. There is an optional message back to the inviter upon declining an invitation.

===Notifications===

Notifications behave similarly to Invitations; they also appear in the [[OLPC Human Interface Guidelines/The Laptop Experience/The Frame#Actions|Actions]] edge of the frame. However, unlike invitations, which are sent from people on the mesh, Notifications come from activities or directly from the system. As new notifications come in, they form a queue, with the most recent in the lower left-hand corner for quick access.

====Sticky Notifications====
By default, notifications will remain in the frame until the child acknowledges them.

====Transient Notifications====
Transient notifications alert a child when they arrive, but as they contain information that has a limited lifetime, they expire. Thus Activities may specify timeouts on notifications, after which they will automatically disappear.

{{hig-subnav-intra|p_page=Introduction|c_section=Activities|c_page=Activity Basics|n_page=Activity Bundles}}

Development Team/Manual/translations

2008-01-27T19:32:46Z

Leejc: Reverted edits by 212.142.143.116 (Talk); changed back to last version by RafaelOrtiz

Development Team/Manual/translations

2008-01-24T15:46:32Z

Leejc: Reverted edits by 61.130.11.115 (Talk); changed back to last version by LeeSI

Development Team/Manual/Setup

2008-01-18T15:20:33Z

Leejc: /* A Real OLPC-XO Laptop */ removing affiliate link

{{Developers}}
[[Developers|Previous]] [[Developers/Stack|Next]]

[[Image:Sugar.png|right|thumb|Sugar GUI Shell (Our Goal)]]
The OLPC's software environment is a heavily modified [[Fedora]] 7 Linux system running a custom [[Sugar|GUI shell]] (Sugar). To develop for the platform you will eventually need access to a platform which runs in a manner substantially similar to the OLPC environment. To put it simply, you will likely need to have Sugar running on a computer.

There are two major approaches to running Sugar, running it natively on your machine, and running it in an emulated environment. Which approach you choose will depend on a number of factors, including:

* whether you are just wanting to check the platform out, or are setting up for long-term development work (i.e how much time you want to invest in getting the best possible setup)
* what type of hardware you have available to you
* how comfortable you are with working with traditional Linux tools such as ssh, and vim/nano editors
* what type of development work you are interested in doing

If you can neither run an emulated machine or run Sugar natively, it is still possible that you may be able to develop for the platform by [[#Cross Coding]]. Even if this isn't possible, you could consider working on one of the [[Software components|software components]] we use.

= About Emulation =

There are a number of tools which allow you to run an image of one operating system in a window on another system. If you have the hardware and want to get started as fast as possible, choosing an emulated approach is probably for you.

Emulation is a computationally intensive operation, it requires a powerful (modern) host machine with lots of RAM and lots of storage space. Each official image you wish to use will require about 2GB of disk storage with ancillary files and unpacking requirements.

Emulation is also a 90% thing, that is, it normally gets about 90% of the emulation correct, but things such as peripherals, sound, cameras, keyboards and the like can be "slightly off" in an emulated environment. You should always keep this in mind when working with a emulator.

== Emulation Packages/Products ==

Emulation is a hot topic these days, there are lots of emulation systems available, some no-cost, some Open Source, some commercial. We cannot hope to support all of these systems, so we have focused our efforts on small subset of systems:

* [[Qemu]] (with the KQemu Accelerator)
** Our best-supported emulation system
** With the KQemu package provides reasonably fast emulation
** Open Source and runs well on Linux and Windows machines
** Basic setup is reasonably easy
** Allows for working in "overlays"
** Command-line interface on Windows, Linux and Mac, GUI available for Windows and Mac
** Works directly with offical builds
* [[VMWare]] / [[VirtualBox]]
** Commercial emulation packages with no-cost "players" for images
** Somewhat easier setup than Qemu, particularly for advanced networking on Linux hosts
** Require converted images, which are not always kept up-to-the-minute and do not include experimental/testing builds
** Beta version of VMWare (Fusion) available for Mac OS X
* [[Emulating the XO/Parallels|Parallels Desktop]]
** Commercial emulation package
** Extremely difficult setup
** Mac friendly

Which emulation system you choose is mostly a matter of preference and suitability for your system.

See Also:

* [[Emulating the XO]] -- has a handy chart outlining which system has been reported to work with which type of emulation task

== Emulation for Exploration ==

Want to just see what Sugar is like? Want to play with the activities and kick the tires? Downloading a Qemu or VMWare/VirtualBox image and running it is normally a matter of a half hour or so.

== Emulation for Development ==

It is possible to code software on an OLPC-XO running Sugar. One of our long-term goals is to make this an easy and straightforward process. The "Gear" key on the keyboard of the OLPC-XO will eventually hook up to an [[Develop|IDE]] activity for altering and creating new code. That IDE is not yet finished, however.

''Official Images''

The only "normal" code editing environments present on the OLPC-XO are all command-line environments available through the [[Terminal]] activity. Official Sugar images include both the vim and nano editors, so users who know these editors can use them to write and modify software within the images.

Developers wishing to use the [[Developers/Stack#EToys|EToys]] application stack can create new software from EToys built-in development environment while running on an emulator.

''Developer's Desktops''

If you have a very powerful host machine, it is possible to run an entire "regular" Linux desktop with a sugar-jhbuild or package-based install of Sugar. This will tend to take a lot more memory, processing power and disk space than using an official image (which is, of course, intended to run on a relatively lightweight computer), but it gives you most of the benefits of the native Sugar approach.

See [[#Native Sugar]]

=== Emulation for Compilation/Experiments ===

One very useful feature of emulation systems is their ability to "snapshot" or "overlay" images. This feature allows you to leave a base image untouched while performing some messy or dangerous operation. When you are finished the operation, you can return to the unmodified base image.

For example:

If you want to support a piece of hardware that requires a kernel module, you can mount a Qemu copy-on-write or VMWare snapshot into which you install the whole kernel-compilation toolset (likely getting quite close to filling up the whole storage).

You can then [[Kernel Building|compile the kernel]] and then the missing driver. When you are finished, you copy the driver to the host machine and can install the compiled driver into the base image.

== Emulation for Testing ==

If you are [[#Cross Coding]] or using a [[#Native Sugar]] environment, you will often want to use an emulated official image for testing. This is often far more convenient than loading the image onto a real XO and doesn't require hardware you might not have.

For support operations, it is often handy to be able to load exactly the operating system image that a user is using in order to be able to duplicate a bug. You can use an emulated version of the system instead of a real XO to save "wear and tear" on the XO's flash storage.

Emulation tools often have the ability to share folders with the emulated machines, this lets you work on your host machine, quickly see if the code works on the emulator, and only then package up and test on a real machine (or potentially have someone else test).

It should be noted that emulators often have difficulties with sound support and graphics resolutions. They also can wind up being much faster or slower than the target hardware. See [[Developers/FAQ|the Developer's FAQ]] below for some pointers on how to simulate the special hardware. Testing in emulation is valuable, but ''eventually'' the software needs to be tested on real hardware.

== Getting Started (Emulation) ==

<div style="border: solid black thin">For a detailed exploration of emulation issues with a focus on using the official images, see [[Emulating the XO]], which includes setup and configuration issues, tips and hints, and a grid of known-working approaches to emulating an OLPC-XO laptop.</div>

You will need to install one of the emulation systems and download an image:

* [[Qemu]] + KQemu (recommended where possible)
** [http://xs-dev.laptop.org/~cscott/olpc/streams/ship.2 Ship.2] -- patch releases for Official Releases
** [http://xs-dev.laptop.org/~cscott/olpc/streams/joyride Joyride] -- Bleeding Edge/Development Releases
** [http://pilgrim.laptop.org/~pilgrim/olpc/streams/update.1 Update.1] -- release candidates for the Update.1 refresh
* [[VMWare]], [[VirtualBox]] (good secondary choices, particularly if you already have one installed)
** [http://dev.laptop.org/virtualbox/ All Builds] -- collection of all the pre-converted images (the same images work on either system)

More complete descriptions of the various [[OS images#Build names and branches|Image Types]] are available. Follow the specific instructions on the emulation-system-specific pages linked to above to get started.

See Also:

* [[#Configuration and Usage]] -- instructions on how to setup and use Sugar once you have it installed

= Native Sugar =

If you are running a modern Linux Operating System (whether as your primary OS, as a Live CD, via dual-booting, or potentially even via emulation), it is quite possible that you can run Sugar directly on your Linux machine with its current OS.

Core developers will likely need to set up a sugar-jhbuild environment, sugar-jhbuild uses the bleeding edge version of each component, often checked directly out of the source-code-control for each project. It allows you to work with developers across many different projects, but it tends to be fragile as a result.

Activity developers can get away without a Native Sugar setup, but if you are coding a non-trivial Activity on a "normal" Linux machine, it is probably worth setting up either a sugar-jhbuild or a package-based sugar install to speed up your edit-run cycle.

''Sugar as Your Shell''

Sugar, though a bit exotic seeming compared to most GUI shells, such as KDE or Gnome, is really just a GUI shell. As such, you can run it either as the actual shell for a GUI login session, or in a virtual X session (that is, a window that mimics a whole X session/server).

The official OLPC images, of course, run Sugar as the GUI shell for the primary X server. So if you are running an official image (for example because you are working directly on an OLPC-XO) you will be running Sugar as your GUI shell. Similarly, the [[#Live CD|Live Backup Live CD]], which is based on an official image, boots directly into the Sugar shell. On Fedora 7, you can also (with recent versions of Sugar) choose a Sugar session from your GDM/KDM/XDM-based login manager.

''Virtual X Server''

In most other cases, you want to run Sugar in a virtual X session. This allows you to have multiple Sugar desktops running and visible simultaneously to test networking and the like. The virtual X sessions can be quickly shut down and restarted without needing to log out and back in again. Most core developers are using this type of setup using sugar-jhbuild.

== sugar-jhbuild ==

This is what the core development team uses and is one of the most pleasant ways to work (once set up). Compared with using an Emulated XO, installing sugar takes more time and space to set up, and can be difficult to maintain, but results in a more flexible environment.

The 'native' environment for sugar-jhbuild is [[Sugar_on_Fedora_7|Fedora 7]], and this is by far the best supported development platform for sugar-jhbuild. [[Sugar_on_Ubuntu_Linux|Ubuntu]] (Feisty or Gutsy) and [[Sugar_on_Gentoo_Linux|Gentoo]] can also build the environment.

Currently sugar-jhbuild requires about 2.5 hours to complete building on a modern workstation (AMD4800+).

You can [[Emulated Sugar-jhbuild|run sugar-jhbuild under emulation]]. This has the advantage of working on a wider range of Linux hosts (as well as Windows or Mac OS-X), and does not "pollute" your host machine with Sugar libraries. It requires a lot of disk space and processing power, however.

See [[Sugar with sugar-jhbuild]] to get started.

See Also:

* [[#Configuration and Usage]] -- instructions on how to setup and use Sugar once you have it installed

== Native Sugar Packages on Linux ==

As Sugar stabilizes and is ported to more distributions, it should be possible to use your Linux distribution's package management system to install Sugar. Distributions with ports so far:

* [[Sugar_on_Ubuntu_Linux#Option_3_-_Deb_Packages_for_Gutsy|Ubuntu Gutsy]] -- Note that we need more testing of this package-set, please let us know your experiences
* [[Sugar on Debian]]-- Note that we need more testing of this package-set, please let us know your experiences

If you don't see your distribution here, ask your distribution maintainers, or if you have the skills, create the packages yourself and submit them.

See Also:

* [[#Configuration and Usage]] -- instructions on how to setup and use Sugar once you have it installed

== A Real OLPC-XO Laptop ==

Hardware Developer's Program - while there are only a small number of test units available for free, developers can [[Developers_Program|submit proposals]] to receive one of those units for testing and development.

A large number of units were distributed in the [[XO Giving|Give 1 Get 1 program]] throughout the US or Canada. If you have sufficient funds, you can acquire a production-run machine from a secondary market such as EBay.

If you would like to run a non-official (i.e. experimental, unstable) build on a Mass-Production/G1G1 machine you will need to acquire a [[Activation and Developer Keys|developer key]] to allow your (locked) laptop to load the unsigned image. You probably ''do not'' need to run an experimental image for most activity development purposes.

See Also:

* [[#Emulation for Development]] -- discussions on the current limitations on using the official images as development environments
* [http://laptop.org/start Getting Started] -- guide to using a new OLPC-XO Laptop

=== Almost an OLPC ===

The introduction of the OLPC-XO has ignited the low-cost computer market. There are a large number of low-cost machines with approximately the same performance level as an OLPC-XO. As of right now, we don't have any reason to recommend that you should buy one of these "almost an OLPC" machines, while they may be superficially similar to an XO, they are not likely to be any closer than an emulated XO running an official image.

See: [[Development Systems]]

== Live CDs ==

There are currently a number of projects underway to produce various types of [[LiveCD]]. LiveCDs are not a "normal" part of the development process, normally being used for lightweight deployments, experimentation, testing, and potentially installation onto a dedicated machine to create a workstation.

See [[#Emulation for Development]] for considerations regarding installing LiveCD's based on official images for development.

= Cross Coding =

If you can neither run an emulated machine nor run Sugar natively, it is still possible that you may be able to develop for the platform by developing your code on one machine and then porting it to the platform when you are finished.

Cross coding generally works best when you are working in a relatively constrained and abstracted environment. Of the stacks available on the Sugar platform, the following are well suited to Cross Coding activities:

* [[Developers/Stack#Browser|Browser]] -- Mozilla/Firefox-derived web browser
* [[Developers/Stack#EToys|EToys]] -- Squeak/Smalltalk multimedia environment
* [[Developers/Stack#OLPCGames|Pygame]] -- raster-graphics game development framework
* [[Developers/Stack#Flash|Flash]] -- Gnash or Adobe-Flash engine

You may be able to install just the software involved in that stack in order to test and develop your game. You can then have a development partner do porting and testing to a Sugar environment.

= Configuration and Usage =

Now that you have either a native or emulated Sugar environment, you are likely wondering how to use and configure it for your needs:

* [[Sugar Instructions]] -- how to get around inside Sugar (i.e. how to use it)
* [[Support]] -- how to get help with running Sugar (on an OLPC-XO)

You can install new software in your Sugar environment in a couple of ways.

* [[Activities]] -- can be downloaded using the built-in browser or installed from the command line
* General Linux packages can be downloaded and installed using Yum (note, these changes will be wiped out on the next OS upgrade)

== Jabber Servers ==

By default your image may have been configured to connect to either an inaccessible or a non-existent Jabber server. You can see this by zooming out to the network view (Alt-F1 in an emulator). If there are no other XO icons in the view you are likely not connecting to a server.

At the moment (2007-12-17) we are in the middle of rebuilding the Jabber servers to support the much larger loads seen during deployment. Ask on the #olpc IRC channel which Jabber server you should use, then open a [[Terminal]] activity and use either a command-line editor such as vi or nano to specify the appropriate server:

vi ~/.sugar/default/config

and change the server line to:

server=jabber-server.we.want.to.use

and then restart the X server, either restart the machine or use ctrl-alt-backspace (erase), but do '''not''' do ctrl-alt-backspace on an emulator, or you will kill your entire GUI session!

== SSH Access ==

You will often want to be able to use file-transfer and remote-login operations to access your Sugar environment. We generally recommend using ssh-based access for working with your Sugar environment remotely.

Note: If you are using sugar-jhbuild you likely do '''not''' need to follow these instructions (since you're already using a running Linux desktop that shares its login and file-system with the Sugar instance).

See:

* ??? SSH user's guide
** ??? SFTP user's guide and tools

=== Password Based ===

Password-based SSH authentication is convenient and simple to set up, but it is far easier to crack than key-based access. Consider using key-based authentication unless you are absolutely sure that no-one can reach your Sugar environment from untrusted networks (and maybe even then).

Open a [[Terminal]] activity and run:

passwd

which will prompt you to enter a password (and confirm it).

Note: you can also set a password on the root account by doing:

su root
passwd

in the terminal window. This is strongly recommended if you are going to allow remote access to your machine.

=== SSH Key Based ===

SSH Key based authentication provides strong public-key encrypted access control for your Sugar environment, but takes a bit more work than SSH Password base authentication.

In summary, you create a private key which will be stored on your remote system and encrypted with a strong password. You transfer the public key (think of it as a lock) that corresponds to that key to the Sugar environment and install it as an "authenticated key" which can be used to log into the Sugar environment.

On your remote system, install SSH (Linux and MacOS will already have it installed, on Windows use the PuTTY program) and generate a new ssh key pair (following is for Linux/MacOS, refer to PuTTY's documentation for details on Windows):

ssh-keygen

Usage notes:

* Accept the defaults for key-type and size.
* If ssh-keygen asks if you want to overwrite a key say '''No''', you are about to destroy your current ssh key!
* Use a strong pass-phrase that you can remember easily (the pass phrase will need to be entered frequently unless you make use of an ssh-agent such as offered by PuTTY or Gentoo's keychain)

This will normally create a file in your ~/.ssh/ directory named id_rsa.pub (if you accepted the defaults). You now need to copy this file to your Sugar environment and add it to the contents of your ~/.ssh/authorized_keys file (you may need to create the file).

mkdir ~olpc/.ssh
cat id_rsa.pub >> ~olpc/.ssh/authorized_keys

add your key to your keychain/ssh-agent application and you can now use SSH with just a single sign-on for many concurrent actions.

See: [[Emulating the XO/Help_and_tips#SSH into qemu|SSH Into Qemu]] for Qemu-specific notes regarding port forwarding

= See Also =

* [[Building custom images]] -- how to create entirely custom Sugar OS images using Pilgrim

[[Developers|Previous]] [[Developers/Stack|Next]]

[[Category:Emulation]] [[Category:Developers]]

Development Team/Manual

2008-01-13T21:59:46Z

Leejc: Reverted edits by 212.67.29.0 (Talk); changed back to last version by MitchellNCharity

{{Translations}}
{{Developers}}

<div style="margin: 20; padding-left: 30; padding: 10; border: black thin solid; background-color: #e0ffe0">This is a quick intro to working on activities for the XO, and other code for OLPC. Feel free to add to and update the manual; it is a work in progress.</div>

This manual tries to provide you with the answers you need to get started either by contributing to existing projects or starting your own. Although it focuses on the software development side of the process, we are also very interested in encouraging [[Participate|other contribtions]].

== Overview ==
* [[Developers/Setup]]
** Describes how to set up a [[Sugar]] development environment, with a discussion of which approach is likely to be the most appropriate for you
* [[Developers/Stack]]
** Describes the "operating stack" of the OLPC [[Sugar]] environment, the combination of hardware, operating system, services, libraries and activities that combine to form the environment in which you will be programming
* [[Developers/Issues]]
** Describes the special considerations required for working on the OLPC project, particularly those driven by our target hardware and deployment environments
* [[Developers/Projects]]
** Suggests ways to choose a particular project, whether one that already exists, or one of your own, and how to start working on the project once you have chosen it
* [[Developers/Communication]]
** Describes the various support and communications channels used by the project, including how to get help with problems, and how to set up your own per-project communications channels
* [[Developers/Documentation]]
** Collects pointers to the various sources of documentation available for the project. Helping us better document our code is always a welcome contribution.
* [[Developers/FAQ]]
** Collects and attempts to answer common questions that developers have when working on the Sugar platform

== Release Schedule ==

We expect to be doing updates monthly through the first quarter of 2008. After that, we will likely adopt a three-month update cycle. Eventually we will adopt a six-month update cycle. It should also be noted that we will be—when time permits—moving to a build environment that enables individual activity developers to maintain their own build cycles.

== Related docs and manuals ==
* [[Simplified users guide]]
* [https://www6.software.ibm.com/developerworks/education/l-sugarpy/l-sugarpy-pdf.pdf Application Development for the OLPC Laptop] (Tim Jones of IBM)

[[Category:Developers]]
[[Category:Software development]]

Development Team/Manual/translations

2008-01-13T20:28:29Z

Leejc: Reverted edits by 77.220.179.20 (Talk); changed back to last version by Walter

Development Team/Manual/translations

2008-01-08T15:24:16Z

Leejc: Reverted edits by 80.250.210.12 (Talk); changed back to last version by 202.226.241.235

Development Team/Manual/translations

2008-01-03T23:44:28Z

Leejc: Reverted edits by 200.51.208.38 (Talk); changed back to last version by LeeSI

[[Developers manual|English]] | [[Developers manual/lang-ko|한글]]

Development Team/Almanac/Code Snippets

2008-01-03T16:39:10Z

Leejc: /* Toolbar icons */ typos

{{OLPC}}
{{Translations}}

== WebView ==
Use the WebView in a widget.
import os
import hulahop
from sugar import env
hulahop.startup(os.path.join(env.get_profile_path(), 'gecko'))

from hulahop.webview import WebView

import gtk

win = gtk.Window(gtk.WINDOW_TOPLEVEL)
win.set_size_request(800,600)
win.connect('destroy', gtk.main_quit)
wv = WebView()
wv.load_uri('http://wiki.laptop.org/go/Guido_van_Robot')
wv.show()

win.add(wv)

win.show()
gtk.main()

=== Notes ===
* I'm not sure what the purpose is of the call to hulahop.startup as the documentation is rather sparse. I only knows it's needed to get it to work [[User:Stas_z|Stas Zytkiewicz]] 2 Dec 2007

== Toolbar ==

=== Toolbar icons ===

Setting a standard Sugar toolbar.
from sugar.activity import activity
...
class MyActivity(activity.Activity):
...
toolbox = activity.ActivityToolbox(self)
self.set_toolbox(toolbox)
toolbox.show()

Adding a custom toolbar and icons.
from sugar.graphics.toolbutton import ToolButton
from sugar.activity import activity
...
class MyActivity(activity.Activity):
...
mytoolbox = gtk.Toolbar(self)
helpbut = ToolButton('help')#Stock help icon
helpbut.set_tooltip(_("Get help"))
helpbut.connect('clicked', self.help_button_pressed)
mytoolbox.insert(helpbut, -1)
helpbut.show()
mytoolbox.show()

toolbox = activity.ActivityToolbox(self)
toolbox.add_toolbar("mytoolbar",mytoolbox)
self.set_toolbox(toolbox)
toolbox.show()

In addition to the standard icons in /usr/share/icons/sugar/scalable/ (eg, "go-next"), you can create additional icons by putting an svg in your activity's icons/ directory. E.g.,
icons/my-icon.svg
And then use it.
mybut = ToolButton('my-icon')# without extension

== Files ==

This snippet shows how to get a [http://mailman.laptop.org/pipermail/sugar/2007-February/001459.html path to files in the running Activity]:

from sugar.activity import activity
bundle_path = activity.get_bundle_path()

== Images ==

* [http://mailman.laptop.org/pipermail/sugar/2007-February/001528.html Loading an SVG file onto a surface with a transparent background]:

target = ctx.get_target()
buf = target.create_similar(cairo.CONTENT_COLOR_ALPHA, w, h)
ctx.set_source_surface(buf, x, y)
ctx.paint()

* [http://mailman.laptop.org/pipermail/sugar/2007-February/001547.html Measuring an SVG file's original dimensions]

width, height = handle.get_dimension_data()

* Loading a JPEG file onto a surface:

pixbuf = gtk.gdk.pixbuf_new_from_file("foo.jpg")
ctx = # a cairo context
ctx.set_source_pixbuf(pixbuf, 0, 0)
ctx.paint()

libjpeg is said to be an alternative to using pixbuf. Which is better? Perhaps Sugar/[[HippoCanvas]] provides an easier way to do this?

[[Cairo]] image expansion is good quality, but expensive. Shrinking is fine and notably faster. So for images rendered large (ie, screen-size), you might want to start with a big image, rather than expanding a small one. A speed/space tradeoff. And use SVG instead if appropriate, of course. [[User:MitchellNCharity|MitchellNCharity]] 10:37, 10 May 2007 (EDT)

== Audio ==

* [http://lists.laptop.org/pipermail/sugar/2007-October/003480.html Playing a sound via csound]:

import sys
sys.path.append('/usr/share/activities/Pippy.activity/sound')
from sound import *
playWave(sound='triangle')
audioOut()

== Processes ==

* [http://lists.laptop.org/pipermail/sugar/2007-October/003596.html Starting an external process]

: Use Python's [http://docs.python.org/lib/module-subprocess.html subprocess module].

* [http://lists.laptop.org/pipermail/sugar/2007-October/003597.html Starting a binary activity instead of a Python activity]

: Set the "exec" property of the <tt>activity.info</tt> file to your binary.

== Not yet sorted ==

* [http://mailman.laptop.org/pipermail/sugar/2007-March/002028.html Getting a unique ID for the XO user]:

from sugar import profile

key = profile.get_pubkey()

# If you want a shorter key, you can hash that like:

from sugar import util

key_hash = util._sha_data(key)
hashed_key = util.printable_hash(key_hash)

* Avoid memory exhaustion from large dead pygtk objects by using

import gc

gc.collect()

Not all trash pygtk objects are garbage collected promptly. If you are throwing away large pixmaps, for instance, this can be deadly. gc.collect() forces a garbage collection pass.

== Performance Tips ==
''This section belongs on a different, as yet non-existent page. But a good organization for software development tips is currently unclear to me, so I'll stash this here for now.'' [[User:MitchellNCharity|MitchellNCharity]] 14:05, 10 May 2007 (EDT)

* ctx.stroke() several lines at once. stroke() currently has significant overhead. So it is faster to stroke several, than to stroke them individually. They need not be contiguous. [[User:MitchellNCharity|MitchellNCharity]] 14:05, 10 May 2007 (EDT)

== Old snippets which need to be overhauled ==
=== Toolbar ===

This snippet shows how an activity would have a toolbar with a button and a gtk.TextView widget embedded in a hippo Canvas:

import logging
import hippo
import gtk

from gettext import gettext as _

from sugar.activity import activity
from sugar.graphics.toolbar import Toolbar
from sugar.graphics.iconbutton import IconButton
from sugar.graphics.entry import Entry
from sugar.graphics.optionmenu import OptionMenu
from sugar.graphics.menu import MenuItem

class FooActivity(activity.Activity):

_ACTION_ANYTHING = 1
_ACTION_APPLES = 2
_ACTION_ORANGES = 3

def __init__(self, handle):
activity.Activity.__init__(self, handle)

vbox = hippo.CanvasBox()
self.set_root(vbox)

toolbar = Toolbar()
vbox.append(toolbar)

button = IconButton(icon_name='theme:stock-close')
button.connect("activated", self._button_activated_cb)
toolbar.append(button)

entry = Entry()
button.connect("activated", self._entry_activated_cb)
toolbar.append(entry)

option_menu = OptionMenu()
option_menu.add_item(MenuItem(self._ACTION_ANYTHING, _('Anything')))
option_menu.add_item(MenuItem(self._ACTION_APPLES, _('Apples'),
'theme:stock-close'))
option_menu.add_item(MenuItem(self._ACTION_ORANGES, _('Oranges')))
option_menu.add_separator()
toolbar.append(option_menu)

text_view_widget = hippo.CanvasWidget()
vbox.append(text_view_widget, hippo.PACK_EXPAND)

text_view = gtk.TextView()
text_view.get_buffer().set_text('Write here!', -1)
text_view_widget.props.widget = text_view

def _button_activated_cb(self, button):
logging.debug('FooActivity._button_activated_cb')

def _entry_activated_cb(self, entry):
logging.debug('FooActivity._entry_activated_cb')

:In build 443 (June '07), <tt>from sugar.graphics.entry import Entry</tt> yields ''ImportError: No module named entry''. [[User:MitchellNCharity|MitchellNCharity]] 19:52, 15 June 2007 (EDT)
:And obsolete, now deleted code like sugar.graphics.toolbar is being used. Snippet needs to be overhauled. [[User:MitchellNCharity|MitchellNCharity]] 18:04, 21 June 2007 (EDT)

[[Category:HowTo]]
[[Category:Sugar]]

Human Interface Guidelines/The Sugar Interface/Cursor

2007-12-29T18:19:52Z

Leejc: Reverted edits by 125.33.66.149 (Talk); changed back to last version by XaviBot

<div style="background-color: #FFF; margin-left:auto; margin-right: auto; width: 95%;">
<noinclude>{{Translations}}</noinclude>
{{hig-subnav-intra|p_page=Controls|c_section=The Sugar Interface|c_page=Cursor|n_page=Cursor}}

===Cursor===

Coming soon...
{{stub}}

{{hig-subnav-intra|p_page=Controls|c_section=The Sugar Interface|c_page=Cursor|n_page=Cursor}}

Template:Ongoing Translation

2007-12-29T18:14:51Z

Leejc: Reverted edits by 211.97.70.252 (Talk); changed back to last version by Xavi

:''This is an [[:Category:Ongoing Translation|on-going translation]]''
[[Category:Ongoing Translation]]<noinclude>
Pages tagged with this template will automagically be included in the [[:Category:Ongoing Translation]].
[[Category:Template]]</noinclude>

Human Interface Guidelines/The Laptop Experience/Bulletin Boards

2007-11-29T00:51:40Z

Leejc: Reverted edits by 58.147.0.228 (Talk); changed back to last version by Xavi

<div style="background-color: #FFF; margin-left:auto; margin-right: auto; width: 95%;">
<noinclude>{{Translations}}</noinclude>
{{hig-subnav-intra|p_page=The Frame|c_section=The Laptop Experience|c_page=Bulletin Boards|n_page=View Source}}

===Bulletin Boards===

[[Image:bulletin-board.jpg|left|thumb|240px|Bulletin boards provide a layer for contextual chat and sharing around any view.]]

Since the laptops have implicit connectivity via the mesh network, an additional layer of the UI has been designed to take advantage of it: Bulletin Boards. Taken literally, the Bulletin Boards provide a space for ''posting things.''

Context is key to the usefulness of Bulletin Boards on the laptops. A button in the Places edge of the Frame toggles the Bulletin Board layer on and off, and although only one button exists for this purpose, each view among the various zoom levels has its own Bulletin Board. The scope of individuals who have access to a given Bulletin Board matches the scope of individuals that the view currently represents. For example, any items posted to the Home view Bulletin Board may only be seen by the child that posted them, effectively providing a traditional desktop environment. Likewise, anyone within the child's list of Friends may view things the child has posted to the Friends view Bulletin Board, and all of a child's classmates and her teacher can view her posts to the Class Bulletin Board; the Mesh view Bulletin Board provides an environment for sharing with the entire laptop community. Furthermore, each activity has its own Bulletin Board, providing a space for sharing files and ideas surrounding the activity itself that don't have a place within it.

<br clear="all"/> 

====Spatially Contextual Chatting Interface====

As a transparent layer above any view, the Bulletin Board provides a spatially contextual chatting interface. This means that, unlike traditional forum-style threads that organize temporally, chat bubbles may be freely positioned on screen. Discussions formulate around specific areas of the activity beneath. Annotation-style comments open the door to a wide variety of conversational interactions. In a drawing of the ocean, for instance, one conversation could be happening below the water's surface, while another group of children discuss what kind of birds fly through the sky. In another situation, one child could remotely assist another in learning how to use a new activity, pointing out specific interface elements with detailed descriptions of their functionality. In a literary application, child or teacher could proofread another child's story, correcting spelling mistakes, pointing out grammatical errors, and sharing thoughts about specific sections of the story without directly editing the work on the activity layer beneath.

====An Environment for Sharing====

In addition to contextual chats, Bulletin Boards provide a space for sharing. Any object may be posted to a Bulletin Board for others to look at and enjoy and to pass on to others, promoting viral sharing. The sharing environment is an integral element of all views.

In the Home view, for instance, only the child to whom the laptop belongs has access to the contents of the Bulletin Board. Here, the Bulletin Board provides a convenient area for the temporary storage of objects and activities, as well as those things kept around for quick access: tomorrow's homework assignment, the pictures taken last week, the book the child is reading, a favorite game. In this way, the traditional desktop that the zoom levels replaced finds its way back through the Home view Bulletin Board. The functionality described here mimics the traditional desktop to some extent. Note that the contextual chat bubbles are also available in the Home view, providing a mechanism for writing "notes-to-self". The Bulletin Board metaphor emphasizes a temporary and ever changing space for placing objects, distinctly separate from the space in which they are stored. This may prevent the common overuse of the desktop as the primary place to store ''everything'', which limits its usefulness as a quick way to find the files that matter most at any given point in time.

From the Friends and Mesh view, the Bulletin Board serves as a place to share interesting things a child has found or created with friends, and the entire mesh respectively. The important thing to remember with regard to sharing, of course, is that "Share this JPEG (or GIF or SVG or any other picture format) file with Bob and Sue" translates to "Share this photo (or picture) with Bob and Sue." The sharing metaphor functions much more naturally than the file transfer systems we're used to, since file transfer really just represents a technical implementation of the more abstract idea of sharing in the first place. Of course, children can also view the things that others have posted as well. Moreover, as a community space, group sharing occurs naturally.

Finally, the shared space the Bulletin Boards provide take on a slightly different, yet quite powerful meaning at the Activity level. Again, contextual to the current view, each activity has its own shared Bulletin-board. Posts to this layer provide supporting materials for the underlying activity that other participants in the activity may view (Or, if they'd like, keep for themselves). This actually means a great deal, since any object at all can be shared this way, including many objects that the activity itself may not provide support for. For instance, though one couldn't paste a song inside a drawing (no compound document), a song posted to the Bulletin Board layer could provide inspiration for it. Similarly, it provides a means of collecting materials relevant to the task at hand within the activity. Rather than having 5 individuals each pasting images of a shark directly into the drawing, they could instead post them to the Bulletin Board for others to see and discuss before deciding which to use as a basis for the drawing. Thus, Bulletin Boards provide a space for gathering research and supporting materials, and holding discussions around both them and the activity.

{{hig-subnav-intra|p_page=The Frame|c_section=The Laptop Experience|c_page=Bulletin Boards|n_page=View Source}}

Template:Hig-nav-lang

2007-11-17T20:14:49Z

Leejc: Reverted edits by 59.95.246.6 (Talk); changed back to last version by Xavi

<div style="border-top:1px solid #888888; border-bottom:1px solid #888888; margin:0px;">
{| width="100%" cellpadding="0" cellspacing="0"
|-
|width=25% align=left bgcolor=#C3D9FF|← '''[[OLPC Human Interface Guidelines/{{{prev}}}/lang-{{{lang}}}|{{:OLPC Human Interface Guidelines/{{{prev}}}/lang-{{{lang}}}/title}}]]'''
|width=50% align=center bgcolor=#C3D9FF|'''[[OLPC Human Interface Guidelines/{{{curr}}}/lang-{{{lang}}}|{{:OLPC Human Interface Guidelines/{{{curr}}}/lang-{{{lang}}}/title}}]] [[{{NAMESPACE}} talk:OLPC Human Interface Guidelines/{{{curr}}}/lang-{{{lang}}}|<font color="white"><b>(discussion)</b></font>]]'''
|width=25% align=right bgcolor=#C3D9FF| '''[[OLPC Human Interface Guidelines/{{{next}}}/lang-{{{lang}}}|{{:OLPC Human Interface Guidelines/{{{next}}}/lang-{{{lang}}}/title}}]]''' →
|}
</div><noinclude>[[Category:Template]]
The 'normal' [[Template:hig-nav]] assumes that all chapters are sub-pages of [[OLPC Human Interface Guidelines]].

This modification assumes not only that, but adds two more things:
# Translated chapters are sub-pages of the original chapter, and labeled ''.../lang-xx''
# The title of the chapters are are themselves a sub-page of the translated chapter's sub-page: ''.../lang-xx/title''

The purpose of this is that changing the ''translation'' of a chapter's name as simple as changing the contents of the title page (ie: .../lang-xx/title) and all navigation bars and the table of contents remains consistent.

So a 'typical' structure would be:

* OLPC Human Interface Guidelines
** /aChapterName - ''the original chapter in english''
*** /lang-xx - ''the translation of the chapter into language 'xx'''
**** /title - ''the translated title of the previous chapter into language 'xx'''
** /anotherChapterName - ''another original chapter in english''
*** /lang-xx - ''the translation of another chapter into language 'xx'''
**** /title - ''the translated title of another chapter into language 'xx'''

== Usage ==

Same structure as the [[Template:hig-nav]] with the addition of an extra parameter "<tt>| lang=xx</tt>" where ''xx'' should be replaced by a standard language identificacion (ie: es, fr, etc.)
</noinclude>

Human Interface Guidelines/Activities/Activity Basics

2007-11-14T14:29:27Z

Leejc: Reverted edits by 216.232.246.209 (Talk); changed back to last version by XaviBot

<div style="background-color: #FFF; margin-left:auto; margin-right: auto; width: 95%;">
<noinclude>{{Translations}}</noinclude>
{{hig-subnav-intra|p_page=Introduction|c_section=Activities|c_page=Activity Basics|n_page=Activity Bundles}}

===Starting Activities===
Activities appear in the Actions section of the frame; starting an activity amounts to creating an active instance of it, represented in the activity ring. They can be started with a single click. An activity may also be directly manipulated; dragging an activity into the ring will also create a new active instance of it.

Visual cues differentiate between instances of an activity and the [[OLPC Human Interface Guidelines/The Sugar Interface/Icons#Activity Icons|activity icon]] in the frame. Specifically, any activity installed on the system and appearing in the Actions edge is drawn as a white outline stroke, with no fill. Upon instantiation the icon receives a fill; both [[OLPC Human Interface Guidelines/The Sugar Interface/Icons#Strokes & Fills|stroke and fill colors]] match the XO colors of the child who created it.

====Private Activities====
Newly created activity instances inherit the scope of the view in which they are created. This means that any activity started from the Home view begins as a private one by default. Children may later [[OLPC Human Interface Guidelines/Activities/Activity Basics#Sharing_Activities|share]] private activities, opening them up to friends, classmates, group members, or anyone on the mesh through an [[OLPC Human Interface Guidelines/Activities/Activity Basics#Invitations|explicit invitation]].

====Shared Activities====
Since newly created activities inherit the scope of the view, any activity started directly from the Friends Group view will be open for her friends to participate in. This applies to any group the child belongs to as well. [[OLPC Human Interface Guidelines/Activities/Activity Basics#Implicit_Invitations|Implicit invitations]] are sent to all of the members of currently selected Group, alerting them of the activity. Likewise, any activity started from the (unfiltered) Mesh view will be open to everyone on the mesh, although invitations are not sent.

The views provide scope for instantiating activities. For finer granularity, the search (located in the Frame) provides an incremental filtering system that enables arbitrary selection of scope. As a query is entered into the search field, the view—Friends or Mesh—dynamically updates to reveal the matching selection. Matches remain in color, while those filtered out appear with a white outline. The filter terms apply parameters such as the names of activities, the types of activities, the names of individuals, and the interests of individuals. For instance, a child could search for anyone who likes games before starting a new game of Memory, or everyone in the same grade in a classroom setting, or a specific group of individuals by name. The results of the query become the scope for any new activity instance, and all XOs within that scope receive implicit invitations when an activity begins. These groupings may be saved as groups for future use.

Once a shared activity begins, the child who initiated the activity is taken into Activity view. Others who received invitations won't join the activity until they accept the invitation; white outline placeholders for their XO icons appear in the People section of the frame to indicate their potential arrival. If they accept an invitation, their XO fills with their colors; if they decline the outline disappears.

===Joining Activities===
Children will often find themselves joining activities already started by others. Activities can be discovered through search; searches may specify an activity name, an activity type, interests of individuals, and names of individuals. For instance, one could search for all activities that relate to music, or all activities that have participants who like camping, or all the active chat activities, or a few specific people by name. Once an appropriate activity is found, a single click on the activity icon will engage it.

===Sharing Activities===

Activities may begin as private, or restricted to a small group of individuals. There may be occasion to open up activities to a broader scope. For instance, a class may break into groups to work on a project within private group activities. At the end of the session, all groups may wish to open up their activities to the rest of the class for discussion and critique. Through selection in the activities contextual rollover, one may set the scope of children who may join an activity to one of Private, Mesh, or any specific Group to which she belongs, including her class, her friends, and potentially others.

A child may lock activities in a similar manner, tightening an activity's scope. Participants must leave on their own volition or at the request of others within the activity before locking it.

===Switching Activities===
The activity ring indicates the activities currently running on the laptop. From the Home view, a single click on any activity in the ring will select it as the active activity, automatically transitioning back to its Activity view. Keyboard shortcuts enable quick transitions among open activities.

===Ending Activities===

Ending an activity happens as easily as starting one. To complete the metaphor, dragging an activity out of the ring will end it. Selecting the End action in the activities contextual rollover will do likewise. Note that ending a shared activity—even one ''you'' started—does not necessarily "close" it. An activity instance remains active on the mesh as long as one or more individuals remain as participants.

===Resuming Activities===

In lieu of an "Open" command, one may simply resume an activity. If a drawing resides in the Journal, then resuming it will automatically restart the Draw activity, allowing modifications to that drawing. Due to the emphasis on collaborative activities, special consideration has to be given when resuming them; An activity fingerprint identifies a particular instance on the mesh. Resuming an activity implicitly invites all others who at one point participated in its creation that also remain within its currently specified scope. Additionally, cases may arise when an activity being resumed is already active on the mesh. In such cases, the child will automatically join the already active instance.

===Activity Robustness===

All activities designed for the laptop should place a strong emphasis on robustness. Two essential robustness considerations are input and network.

===Invitations===

Invitations perform an essential functionality in a computing environment that so strongly emphasizes collaborative learning and creation. For this reason, two forms of invitations are present in the OS: explicit and implicit.

====Explicit Invitations====
Explicit invitations are used to invite specific individuals into already active activities. The ability to send explicit invitations to others serves particular use when in a private activity, be it a private group or a solitary one. In these cases, an explicit invitation can extend the group by including one or more specific individuals, without opening up the activity to a broader scope.

A child may initiate an explicit invitation either from within the activity itself or by identifying an individual or group in either the Groups or Neighborhood views.

====Implicit Invitations====
Implicit invitations do not require specific action on the part of the child. These invitations go to the appropriate individuals whenever actions suggest it, such as when starting an activity from the Groups or Neighborhood views. All individuals within the activity's scope receive implicit invitations to join. When an activity is resumed, those who participated previously receive an invitation.

====Receiving Invitations====
Incoming invitations appear within the [[OLPC Human Interface Guidelines/The Laptop Experience/The Frame#Actions|Actions]] section of the Frame, adjacent to the installed activities; they are rendered in the color of the inviter. Rollover reveals both the name of the inviter as well as the name and type of the activity. On extended rollover, the options to accept and decline appear. There is an optional message back to the inviter upon declining and invitation.

===Notifications===

Notifications behave similarly to Invitations; they also appear in the [[OLPC Human Interface Guidelines/The Laptop Experience/The Frame#Actions|Actions]] edge of the frame. However, unlike invitations, which are sent from people on the mesh, Notifications come from activities or directly from the system. As new notifications come in, they form a queue, with the most recent in the lower left-hand corner for quick access.

====Sticky Notifications====
By default, notifications will remain in the frame until the child acknowledges them.

====Transient Notifications====
Transient notifications alert a child when they arrive, but as they contain information that has a limited lifetime, they expire. Thus Activities may specify timeouts on notifications, after which they will automatically disappear.

{{hig-subnav-intra|p_page=Introduction|c_section=Activities|c_page=Activity Basics|n_page=Activity Bundles}}

Human Interface Guidelines/The Sugar Interface/Text and Fonts/lang-es

2007-11-13T18:15:47Z

Leejc: Reverted edits by 87.101.241.39 (Talk); changed back to last version by MitchellNCharity

<noinclude>
{{OLPC}}
{{Translation | lang = es | source = OLPC Human Interface Guidelines/The Sugar Interface/Text and Fonts | version = 38148 | source_display = OLPC-HIG-Text and Fonts}}
</noinclude>
<div style="background-color: #FFF; margin-left:auto; margin-right: auto; width: 95%;">
{{hig-subnav-intra-lang | lang=es
| p_page=Colors
| c_section=The Sugar Interface | c_page=Text and Fonts
| n_page=Toolbars}}

{{anchor|Fonts}}

==={{:OLPC Human Interface Guidelines/The Sugar Interface/Text and Fonts/lang-es/title}}===

[http://dejavu.sourceforge.net/wiki/index.php/Main_Page DejaVu LGS Sans]

{{anchor|Sizes}}
=====Tamaños=====

[[Image:Sugar-font.png|thumb|218px|right|Tipografía de los menús de Sugar]]
[[Image:Sugar-font.png|thumb|218px|right|The font used in Sugar menus]]

La pantalla de la OLPC es de 200PPP (''DPI''); por lo tanto un punto—1/72 de pulgada o 0.035cm—es justo un poco menos de 3 píxeles (2.78 píxeles). Por lo tanto una tipografía de 12 puntos tiene aproximadamente 33 píxeles. Estamos adoptando un tamaño estándar de 7pts. para la interfaz de Sugar (usando [http://dejavu.sourceforge.net/wiki/index.php/Main_Page DejaVu LGS Sans]). Es bastante legible. Esto se traduce en un tamaño de letras aproximadamente de 19.45 pt en Adobe Illustrator, que basa sus unidades en la pantalla tradicional de 72PPP. Cuando se preparen simulacros de pantallas, siempre se debe recordar el hacer la conversión a la resolución de la pantalla de la laptop multiplicando por el valor constante de 0.36.

Estaremos estudiando otras tipografías, ej. Arábigas y Tailandesas, y también buscando un versión más grande para el uso con chicos mas jóvenes en la interfaz.
{{ Translated text |
The OLPC display is 200DPI; therefore one point—1/72 inch—is just less than 3 pixels (2.78 pixels). We are settling on a default font size of 7pts. for the Sugar UI (using [http://dejavu.sourceforge.net/wiki/index.php/Main_Page DejaVu LGS Sans]). It is quite legible. This translates to a font size of approximately 19.45 pt in Adobe Illustrator, which bases its units on the traditional 72DPI display. For the purposes of preparing activity GUI mockups, you must always remember to make the conversion to the laptops' display resolution by multiplying by a constant factor of 0.36.

We will be looking at other faces, e.g., Arabic and Thai, and also looking into a large-type version of the interface for the younger children.
| display = block }}
<br clear="all"/>

{{anchor|Readability}}
=====Legibilidad=====

Dadas las particularidades únicas de la pantalla de la OLPC, técnicas específicas para el trazado de texto brindaran resultados mucho mejores que otros. El modo dual de la pantalla tiene una resolución de 1200x900 (200ppp) en modo no iluminado (escala de grises), pero solamente ~800x600 (133ppp) en modo cromático. Por lo tanto, de no ser lo suficientemente grandes, las tipografías dibujadas en modo no iluminado y sin valores cromáticos aparecerán más nítidas y legibles.

Adicionalmente, la pantalla tiene una mayor resolución de píxeles negros que blancos. Esto resulta así del hecho que cada píxel tiene una parte de color que contiene la información solamente del rojo, verde o azul. Para lograr el blanco, la parte roja, verde y azul deben trabajar conjuntamente; si están apagadas, el color de la parte es negro de por si. Aún más, un fondo gris limita la legibilidad de la pantalla bajo el sol. Por lo tanto, recomendamos el uso de texto negro sobre un fondo blanco para una mayor legibilidad del texto pequeño, y color sobre blanco para letras más grandes.
{{ Translated text |
Due to the unique design of the OLPC display, particular techniques for text rendering will provide much better results than others. The dual mode display has a resolution of 1200x900 (200 dpi) in luminance mode, but only ~800x600 (133 dpi) in chrominance mode. Therefore, unless they are sufficiently large, fonts rendered with luminance and no chroma will appear sharper and more readable.

Additionally, the display has higher resolution in black pixels than in white pixels. This results from the fact that each pixel has a color part which contains either red, green, or blue information. In order to create white, red, green and blue parts must all work together; when off, each of the color parts is black on its own. Furthermore, a grey background limits the readability of the display in sunlight. Therefore, we recommend the use of black text on a white background for best readability of fine text, and color on white for larger print.
| display = block }}

{{hig-subnav-intra-lang | lang=es
| p_page=Colors
| c_section=The Sugar Interface | c_page=Text and Fonts
| n_page=Toolbars}}

Human Interface Guidelines/The Sugar Interface/lang-ko

2007-11-09T21:59:37Z

Leejc: Reverted edits by 195.87.102.7 (Talk); changed back to last version by MitchellNCharity

<noinclude><div style="background-color: #F5F5F5;">
{{OLPC}}
{{Translation | lang = ko | source = OLPC Human Interface Guidelines/The Sugar Interface | version = 32372 | source_display = OLPC-HIG-The Sugar Interface}}
</noinclude>
<div style="background-color: #FFF; margin-left:auto; margin-right: auto; border-left:1px solid #888; border-right:1px solid #888; width: 95%;">
{{hig-nav-lang|prev=Security|curr=The Sugar Interface|next=The Sugar Interface | lang=ko}}
<div style="margin: 8px;">

{{anchor|The Sugar Interface}}

=={{:OLPC Human Interface Guidelines/The Sugar Interface/lang-ko/title}}==

{{:OLPC Human Interface Guidelines/The Sugar Interface/Input Systems/lang-ko}}

{{:OLPC Human Interface Guidelines/The Sugar Interface/Layout Guidelines/lang-ko}}

{{:OLPC Human Interface Guidelines/The Sugar Interface/Icons/lang-ko}}

{{:OLPC Human Interface Guidelines/The Sugar Interface/Colors/lang-ko}}

{{:OLPC Human Interface Guidelines/The Sugar Interface/Text and Fonts/lang-ko}}

{{:OLPC Human Interface Guidelines/The Sugar Interface/Toolbars/lang-ko}}

{{:OLPC Human Interface Guidelines/The Sugar Interface/Rollovers/lang-ko}}

{{:OLPC Human Interface Guidelines/The Sugar Interface/Controls/lang-ko}}

{{:OLPC Human Interface Guidelines/The Sugar Interface/Cursor/lang-ko}}

</div>
{{hig-nav-lang|prev=Security|curr=The Sugar Interface|next=The Sugar Interface | lang=ko}}
</div>
<noinclude></div></noinclude>

Human Interface Guidelines/The Sugar Interface/Controls/Adjustment Controls/translations

2007-10-31T21:59:24Z

Leejc: rv vandalism

[[OLPC Human Interface Guidelines/The Sugar Interface/Controls/Adjustment Controls|english]] | [[OLPC Human Interface Guidelines/The Sugar Interface/Controls/Adjustment Controls/lang-es|español]] | [[OLPC Human Interface Guidelines/The Sugar Interface/Controls/Adjustment Controls/lang-ko|한국어]]

Template:Translation/changes/lang-pt

2007-10-29T01:26:40Z

Leejc:

alterações

Template:Translation/changes/lang-pt

2007-10-29T01:21:09Z

Leejc: Reverted edits by 87.196.97.146 (Talk); changed back to last version by Xavi

mudanças

Development Team/Almanac/Code Snippets

2007-10-23T01:59:13Z

Leejc: Added process info from mailing list

{{OLPC}}
{{Translations}}
== Toolbar ==

=== Toolbar icons ===

button = sugar.graphics.toolbutton.ToolButton("some-icon-name")
button.show()
toolbar.insert(button,-1)

In addition to the standard icons in /usr/share/icons/sugar/scalable/ (eg, "go-next"), you can create additional icons by putting an svg in your activity's icons/ directory. Eg,
icons/my-icon.svg

=== Other notes ===
*Do ''not'' use sugar.graphics.toolbar and its Toolbar. It is old broken left-over code, now deleted. [[User:MitchellNCharity|MitchellNCharity]] 17:06, 21 June 2007 (EDT)

== Files ==

This snippet shows how to get a [http://mailman.laptop.org/pipermail/sugar/2007-February/001459.html path to files in the running Activity]:

from sugar.activity import activity
bundle_path = activity.get_bundle_path()

== Images ==

* [http://mailman.laptop.org/pipermail/sugar/2007-February/001528.html Loading an SVG file onto a surface with a transparent background]:

target = ctx.get_target()
buf = target.create_similar(cairo.CONTENT_COLOR_ALPHA, w, h)
ctx.set_source_surface(buf, x, y)
ctx.paint()

* [http://mailman.laptop.org/pipermail/sugar/2007-February/001547.html Measuring an SVG file's original dimensions]

width, height = handle.get_dimension_data()

* Loading a JPEG file onto a surface:

pixbuf = gtk.gdk.pixbuf_new_from_file("foo.jpg")
ctx = # a cairo context
ctx.set_source_pixbuf(pixbuf, 0, 0)
ctx.paint()

libjpeg is said to be an alternative to using pixbuf. Which is better? Perhaps Sugar/[[HippoCanvas]] provides an easier way to do this?

[[Cairo]] image expansion is good quality, but expensive. Shrinking is fine and notably faster. So for images rendered large (ie, screen-size), you might want to start with a big image, rather than expanding a small one. A speed/space tradeoff. And use SVG instead if appropriate, of course. [[User:MitchellNCharity|MitchellNCharity]] 10:37, 10 May 2007 (EDT)

== Audio ==

* [http://lists.laptop.org/pipermail/sugar/2007-October/003480.html Playing a sound via csound]:

import sys
sys.path.append('/usr/share/activities/Pippy.activity/sound')
from sound import *
playWave(sound='triangle')
audioOut()

== Processes ==

* [http://lists.laptop.org/pipermail/sugar/2007-October/003596.html Starting an external process]

: Use Python's [http://docs.python.org/lib/module-subprocess.html subprocess module].

* [http://lists.laptop.org/pipermail/sugar/2007-October/003597.html Starting a binary activity instead of a Python activity]

: Set the "exec" property of the <tt>activity.info</tt> file to your binary.

== Not yet sorted ==

* [http://mailman.laptop.org/pipermail/sugar/2007-March/002028.html Getting a unique ID for the XO user]:

from sugar import profile

key = profile.get_pubkey()

# If you want a shorter key, you can hash that like:

from sugar import util

key_hash = util._sha_data(key)
hashed_key = util.printable_hash(key_hash)

* Avoid memory exhaustion from large dead pgtk objects by using

import gc

gc.collect()

Not all trash pygtk objects are garbage collected promptly. If you are throwing away large pixmaps, for instance, this can be deadly. gc.collect() forces a garbage collection pass.

== Performance Tips ==
''This section belongs on a different, as yet non-existent page. But a good organization for software development tips is currently unclear to me, so I'll stash this here for now.'' [[User:MitchellNCharity|MitchellNCharity]] 14:05, 10 May 2007 (EDT)

* ctx.stroke() several lines at once. stroke() currently has significant overhead. So it is faster to stroke several, than to stroke them individually. They need not be contiguous. [[User:MitchellNCharity|MitchellNCharity]] 14:05, 10 May 2007 (EDT)

== Old snippets which need to be overhauled ==
=== Toolbar ===

This snippet shows how an activity would have a toolbar with a button and a gtk.TextView widget embedded in a hippo Canvas:

import logging
import hippo
import gtk

from gettext import gettext as _

from sugar.activity import activity
from sugar.graphics.toolbar import Toolbar
from sugar.graphics.iconbutton import IconButton
from sugar.graphics.entry import Entry
from sugar.graphics.optionmenu import OptionMenu
from sugar.graphics.menu import MenuItem

class FooActivity(activity.Activity):

_ACTION_ANYTHING = 1
_ACTION_APPLES = 2
_ACTION_ORANGES = 3

def __init__(self, handle):
activity.Activity.__init__(self, handle)

vbox = hippo.CanvasBox()
self.set_root(vbox)

toolbar = Toolbar()
vbox.append(toolbar)

button = IconButton(icon_name='theme:stock-close')
button.connect("activated", self._button_activated_cb)
toolbar.append(button)

entry = Entry()
button.connect("activated", self._entry_activated_cb)
toolbar.append(entry)

option_menu = OptionMenu()
option_menu.add_item(MenuItem(self._ACTION_ANYTHING, _('Anything')))
option_menu.add_item(MenuItem(self._ACTION_APPLES, _('Apples'),
'theme:stock-close'))
option_menu.add_item(MenuItem(self._ACTION_ORANGES, _('Oranges')))
option_menu.add_separator()
toolbar.append(option_menu)

text_view_widget = hippo.CanvasWidget()
vbox.append(text_view_widget, hippo.PACK_EXPAND)

text_view = gtk.TextView()
text_view.get_buffer().set_text('Write here!', -1)
text_view_widget.props.widget = text_view

def _button_activated_cb(self, button):
logging.debug('FooActivity._button_activated_cb')

def _entry_activated_cb(self, entry):
logging.debug('FooActivity._entry_activated_cb')

:In build 443 (June '07), <tt>from sugar.graphics.entry import Entry</tt> yields ''ImportError: No module named entry''. [[User:MitchellNCharity|MitchellNCharity]] 19:52, 15 June 2007 (EDT)
:And obsolete, now deleted code like sugar.graphics.toolbar is being used. Snippet needs to be overhauled. [[User:MitchellNCharity|MitchellNCharity]] 18:04, 21 June 2007 (EDT)

[[Category:HowTo]]
[[Category:Sugar]]

Human Interface Guidelines/The Laptop Experience/Global Search/translations

2007-10-19T17:52:18Z

Leejc: Reverted edits by 200.226.134.53 (Talk); changed back to last version by XaviBot

[[OLPC Human Interface Guidelines/The Laptop Experience/Global Search|english]] | [[OLPC Human Interface Guidelines/The Laptop Experience/Global Search/lang-es|español]] | [[OLPC Human Interface Guidelines/The Laptop Experience/Global Search/lang-ko|한국어]]

Human Interface Guidelines/The Laptop Experience/The Journal

2007-10-19T17:52:09Z

Leejc: Reverted edits by 200.226.134.53 (Talk); changed back to last version by 129.61.46.60

<div style="background-color: #FFF; margin-left:auto; margin-right: auto; width: 95%;">
<noinclude>{{Translations}}</noinclude>
{{hig-subnav-intra|p_page=View Source|c_section=The Laptop Experience|c_page=The Journal|n_page=Global Search}}

===The Journal===

====The Notion of "Keeping"====
The traditional "open" and "save" model commonly used for files will fade into abstraction on the laptops, and with it the customary floppy disk icon, as not only will the laptops not have floppy drives, but most likely the children will never see one of these largely obsolete devices. Instead, a much more general notion of what it means to want to keep things prevails. Generally speaking, we keep things that we want to hold on to, and the rest just fades with time. Appropriately, the Journal's primary function as a time based view of the activities a child has done and the objects she's kept reinforces this idea.

Most of us recognize the "save early, save often" mantra; most of us have failed to live it and incurred the consequences. The laptops aim to eliminate constant concern for this type of technicality, making automatic and incremental backups and allowing the children to focus on the activity itself. These incremental backups will occur at regular time intervals, and activity events such as changes in scope, new participants, among others can trigger them as well. In order to cater to the needs of many types of editing environments, activities can also specify "keep-hints" which prompt the system to keep a copy. For instance, a drawing activity may trigger a keep-hint before executing an "erase" operation immediately preceded by a "select all". Of course, a child itself may choose to invoke a keep-hint by selecting the "keep in journal" button, but adequate adoption of this new notion of keeping from activities should virtually eliminate need for this.

Based on the Object model associated with files, each kept Object is, technically speaking, a separate instance of the activity which created it. This eliminates the need to "open" a file from within an activity, replacing the act of opening with the act of resuming a previous activity instance. Of course, a child will have the option to resume a drawing with a different set of brushes, or resume an essay with a different pen, providing "open with" style functionality, but no substitute for an "open" command will exist within an activity's interface.

====Deprecating Hierarchy====

=====Temporal Organization=====
Along with the idea of implicit keeping, the laptops will drastically minimize the hierarchical filesystem as a means for organization, replacing it with a temporally organized list of activities and events, furthering the Journal metaphor. This drastically simplifies the auto-keeping behavior, since it eliminates the need to specify a location in which a newly started activity should be kept; naturally, the newly started activity will appear as the most recent entry in the journal.

Temporal organization functions naturally in the absence of explicit or hierarchical methods, since humankind's intrinsic relationship to time gives them, at the very least, a relative notion of "how long ago" something happened. By moving back through the Journal, a child can simply locate the period in time within which she knows she made something, and then employ additional use of searching, filtering, and sorting to pinpoint exactly what she's looking for.

=====Falloff=====

Due to the laptops' limitations in storage capacity, the potential exists for the Journal to contain so many entries that no more may be written. However, the frequency of such occurrences is limited by temporal falloff, which tidies up the Journal contents and keeps space available for new entries. One might think of this as an intelligent combination of garbage collection and disk defragmentation.

The driving principle here is that of temporal granularity, derived directly from our very capacity for human memory. Our minds, generally speaking, maintain a high level of granularity with respect to very recent events, but only a low granularity for events from several years ago. Moreover, this granularity tends to follow a logarithmic curve, where the past few minutes remain quite clear, the past few hours more blurry, and by last month quite vague. When we look years into the past, only specifically memorable events stand out in our minds.

On the laptops the policies are a bit more strict, but the principle remains the same. With a finite amount of memory, some means of managing what's remembered, or kept, and what's forgotten, or erased must exist. An intelligent algorithm will assist children in identifying "forgotten" entries. Taking into account how old an entry is, how many times she's viewed it, how recently she's worked on it, how many hours she's worked on it, how many people she's worked on it with, its tags, and even more forms of automatically generated metadata, the Journal can suggest to her those entries which it feels can be erased. She will then have the opportunity to review those items prior to their erasure, if she wishes, and can keep any she still feels attached to.

In a time where gigabytes have become cheap, many of us still manage to fill our hard drives. Excepting the cases of multimedia collections of audio or video files, much of that space is consumed by files we either don't remember we ever made, or will never open again. On the laptops, where space is precious, so too will be the objects and entries that remain in the journal years down the road. The temporary, the experimental, the duplicate, and the unwanted files will naturally fall off the bottom, maintaining a browsable history of those that remain important to the children.

====Journal Entries====

=====Implicit=====

Implicit journal entries will be the most common. These appear as the result of many kinds of a child's interactions with her machine, but most commonly when engaging in an activity. Other implicit entries might appear when she takes a photo, or receives a note from a friend, or downloads a file from the Web. In all of these cases, the journal entry itself has a basic format which conveys important information about the event which created it. Most importantly, the associated Object - the photo, the message, the drawing, the story - becomes embedded within the entry. It also includes key metadata, such as its name, when it was made, and who collaborated on it.

The journal entry also provides some means to interact with it. For instance, each entry has a description field where a child can tag it with meaningful related words which will make searching for it in the future a breeze. This field will automatically receive any tags that the activity itself associates with the entry. In addition to this tag field, several buttons will allow direct manipulation of the Object, making it possible to resume the activity, place the Object on the clipboard, send it to a friend, print it, or erase it, among others.

=====Note=====

In addition to implicit ones, children have the opportunity to create several special kinds of entries on their own. The first of these, the Note, has the simplest form. Taking a cue from a traditional journal, a Note entry simply provides a large text entry field. This freeform entry allows the children to write down short descriptions of their day to day experiences, just as one would within a real journal. Providing this layer of personalized entries further emphasizes the idea that the Journal really does provide more than a filesystem, as an actual record of events and interactions of the children with the laptop and with their peers.

In practice, children may also use this feature as a means of jotting down a note to themselves - a reminder. In these instances, a simple control within the entry will turn the note into a "to-do" note. As a to-do entry, it will have a checkbox indicating its completion status. By filtering the Journal to show only these entries, it doubles as a basic to-do list, providing another useful tool for learning organizational skills.

=====Clipping=====

Clippings serve a slightly different purpose in the journal. Similar in spirit to notes, a child can create a clipping from anywhere, or from within any activity on their laptop. As an extension of the copy to clipboard idea, clippings copy a selection - some text from a chat session with a friend, an image from a web page, etc. - directly to the journal for safekeeping. This provides a quick and easy way to keep a quick record of anything that you might want to keep around for future reference: a phone number, a link, a password, etc.

=====Event=====

Taking the temporal aspect of the Journal one step further, Events act like "future" journal entries. By specifying a name for the event, a brief description, and a time, these Journal entries serve as a basic planning system. A control within the entry also enables an audible alert, so that Events can act as alarms. Events also tie in closely with some implicit actions of the laptops. For instance, a child might want to go on a photo safari with her friend after school. While still in class, she sends him an invitation to join a photo capture activity, but schedules a time of 3:00. He then receives an invitation, as usual, but upon accepting it receives an Event entry in the journal, with a reference to the scheduled activity, instead of immediately entering it. When 3:00 arrives, both children receive notifications that their scheduled event is about to start, and join each other both physically outside and virtually in the referenced capture activity.

=====Progress Indicator=====

In many cases, entries will appear at one point in time but the desired result of the entry won't be immediate. This might occur, for instance, when downloading a file from the Web, receiving a file from a friend, restoring a file from the server, or saving a large Object such as video or audio data. All of these processes take some non-trivial length of time, and so when necessary, Journal entries will provide a progress indicator stage. When the download, transfer, or task begins an entry will be created in the journal to indicate that. This entry will include a progress bar with estimated time until completion; once completed, it will transition to a standard entry. This makes the Journal a consistent place to keep track of progress, and also provides an easy means to pause and resume transfers, which will prove extremely useful when in areas with intermittent connectivity.

====The Power of Metadata====

Despite the flatness of the Journal, finding past entries shouldn't prove difficult thanks to a tagging structure built from the ground up for the laptops. By associating relevant descriptive words with each journal entry, searching for an entry becomes as easy as describing it. These descriptions will manifest in two ways, tagging and metadata. The former provide a straightforward manner for the children to describe and organize their stuff, while the latter provides a more technical means by which activities can associate relevant data and tags with all Journal entries they create.

=====Tagging=====

Tagging will become a fundamental process for all types of data and activities on the laptops. Fortunately, children have a natural inclination to describe their world and the things they see and do. This actually aids kids in learning, as they will enjoy describing the drawing they've made, the stories they've written, or the composition they produced, and can learn new vocabulary in doing so. Of course, the kid-like desire to describe things doesn't detract from the usefulness of this tag-based system as they grow older.

As such an integral part of the system, the tagging interface will be exposed in various places. Of course, as mentioned, each journal entry will have a field for tags. Likewise, each open activity instance will have a tag field adjacent to its name field, so that the act of naming a particular activity or Object becomes associated with describing it in their minds. Additionally, activities could offer specific places within the interface for tagging to occur, such as in the description field for a photo the child just took.

=====Metadata=====

Metadata adds an additional level of sophistication to the tagging model. Rather than thinking of this as data about data, consider it a means of tagging tags. Metadata on the laptops will be an extension of the basic tagging model where the tag itself consists of a key:value pair. Or, you could simply consider a tag to be a metadata pair with a null key. Whichever way you look at it, this categorization of tags has powerful implications when it comes to organizing and categorizing data.

The Journal itself assigns a variety of useful metadata tags to entries as they appear. These include the time of the entry, its sharing scope, who participated in the activity, its size, and more. The Journal will also keep track of other useful metadata, such as the number of times a child views a particular entry, the number of revisions an entry has gone through, etc. Likewise, activities will deal primarily with metadata rather than simple tags. This allows activities to define specific parameters, or keys, that make sense for the Objects they produce, and then assign values to those dynamically. In a music composition activity, for instance, potential keys might be beats per minute, the key the composition is written in, the length of the track, and the composer, among others. See the sorting section to fully understand the usefulness of this metadata within the Journal.

Of course, since tags and metadata both follow a very basic format, children can assign their own metadata associations with Journal entries once they have enough experience simply by typing key:value pairs into the description field.

====Powerful Search, Filter & Sort====

=====Searching=====

The search field provides the most direct means of locating a particular Journal entry, returning instant results as the search is typed, and offering auto-completion for popular tags. In order to find anything on their laptop, a child need merely describe it, since the tags she's associated with it already appear within its description field. Her searches also apply to the metadata associated with the entry by either the Journal or the activity that created it, making it even easier to find things.

For simplicity, the search field will employ OR logic to all terms entered, which ensures the least amount of confusion when used by children who don't yet understand boolean logic. As such, a search for "orange cat" will return a list of everything orange and also every cat. Of course, any entries tagged with both orange and with cat will match more strongly, and will automatically filter to the top of the results. However, in keeping with a primary goal of the laptops, this won't eliminate the possibility for more complex boolean searches. Full support for AND, OR, NOT, and parenthetical grouping of terms will be built into the search engine, providing advanced functionality for those who desire to enter more complex queries.

Since the laptops will find themselves in the hands of many children, additional modifications to the search algorithm will assist them as they grow. The youngest children who receive them will still be learning how to spell, and those that can may still require some time to learn typing skills. For these reasons, a fuzzy match algorithm will assist the children, returning some results even when the corresponding tags don't match what they typed exactly. This algorithm is adaptive, and so as they become more comfortable with their language and with using the technology, the extent of the fuzziness and therefore the number of fuzzy results returned will lessen, preventing false matches from aggravating more advanced users. Several other kinds of fuzziness could also be applied, though such possibilities are only speculation at this point. For instance, fuzzy matches based on thesaurus entries could turn up items tagged with "funny" even when the child searches for "humorous". Likewise, translation fuzziness could return an entry tagged with "cat", even though the child searched for "gato." These advanced fuzziness algorithms could prove invaluable in a laptop community that has been built with sharing and collaboration in mind.

=====Filtering=====

Support for basic filtering also exists within the journal. The search and filter functionality appear together in the toolbar, since searching could also be interpreted as filtering by tags. Additionally, their appearance together allows an easy method for the children to visually construct their query in a sentence-like format, with relevant parts of their query displayed as icons — just as those within the entries themselves — for visual reinforcement.

Several fundamental filters exist. First and foremost, there is an advanced date filter, which can only be expected in a Journal organized temporally by default. This control will present a timeline to the child, with visual indication over the length of the timeline of the number of entries present in the Journal from any given point in time. By expanding and contracting the selected area she can select anything from a single day to all time, and by sliding the selection through time, she can filter out all entries that don't lie within the specified range. Other basic filters include the activity that the entry represent, and the activity participants.

Other available filters allow children to locate specific kinds of entries. For instance, a child may want to view all entries that have been tagged by the Journal for possible removal when memory becomes low. They may also want to see all their notes, or to-dos, or events. They could also show only starred items, or in progress items, and more. The system will provide adequate flexibility for finding anything in the Journal nearly instantaneously.

=====Sorting=====

Whereas searching and filtering provide a means of defining what entries get shown in the list of results, sorting determines how those entries are organized. A unique approach to sorting on the laptops makes the metadata associated with entries even more valuable. The sort bar, which the child can expand in order to more precisely control their view of the journal, offers a popup menu from which a number of options such as date, title, activity, size, participants, and others may be chosen. In addition to this fixed list, a dynamic list of options also appears, providing a list of metadata keys that are present in the majority of the entries within the results list, the utility of which will become apparent below.

The true functionality of the system arises from "then by" sorting. When desired, a child can specify up to three levels of sorting hierarchy. This feature shouldn't be overlooked, since it serves as an extraordinarily powerful means of viewing and organizing data hierarchically, even when no hard hierarchy exists. In fact, when used to its full advantage this approach can be more useful than a hard hierarchy, since the order of the hierarchy can be adjusted dynamically to suit the child's needs at the time. And, in conjunction with the intelligently compiled list of metadata keys on which to sort, children can not only find what they're looking for, but can browse through their journal in any way that suits them. Consider, for instance, that a child filters her journal so that all of her music appears in the results. Since nearly every song Object in her Journal has metadata keys for artist, album, track, and year, she could sort by these keys to arrange her music collection for browsing. Sorting by artist, then album, then track she can obtain a traditional view of her music. In order to view a discography for each artist, on the other hand, she could sort by artist, then by album, then by track. Or, to see a timeline of her music, she could sort by year, then by artist.

This powerful sorting method isn't necessarily limited solely to a bunch of songs, or pictures, or other specific type of data. Since many forms of metadata will apply across Object types, the possibilities are nearly limitless.

====Implicit Versioning System====

As mentioned before, the laptops automatically save, or "keep", Objects in the Journal at regular intervals. This eliminates the need for the children to constantly worry about saving, and reduces the chances that an unexpected circumstance will cause data loss. These individual keep events are incremental, meaning that the changes within the file are kept in a nondestructive manner. Therefore, the Journal not only stores Objects as children create them, but also keeps track of the revision history for each one. This allows the Journal to function as a versioned filesystem.

The space limitations on the laptop cause some concern with the mention of revision history. However, the differences between revisions will often be small. Additionally, Objects with large revision histories provide one easy way for the journal to regain valuable space when memory becomes tight, since it can collapse the history, storing only every few automatic revisions in addition to those explicitly kept by the child.

====Automatic Backup and Restore====

=====Backup=====

In most locations where laptops deploy, a nearby school equipped with a server will provide additional functionality when children brings their laptops within range. This server has one major implication for the Journal: backup. Due to limited storage space on the laptops, children will have to choose to erase older entries to make way for new ones. The automated backup system will ensure that, even once their creations leave their own laptops, they will remain available on the school server. This process will happen in the background, fully automatically, anytime the child comes within range and bandwidth allows. Her Journal will keep track of which entries have and have not yet been backed up, taking this into account when recommending items for removal.

=====Restore=====

The backup service provided by the server will allow several types of restoration, based upon the child's needs.

Full restore functionality provides a fail-safe for the children. Though the ruggedness of the laptops should minimize the need for a full restore, any event which causes permanent loss of any or all data on a laptop can be recovered from nearly completely from the backup files. These files also provide a means of restoring the child's settings and data should they for any reason ever need a new laptop. In practice, this is a temporal restoration, recovering all files stored on the backup server within a given time period from the present.

The backup server will also provide partial restores, which allows children to select individual objects and entries to recover. Any recovered items will appear as a new Journal entry on the date of recovery. This form of restoration will occur with much greater frequency, purposed mainly to restore an accidentally deleted entry from a week or so ago, while flexible enough to restore any entry ever backed up on the server.

In addition to these hard restoration methods which physically copy the data back onto the children's laptops, the server will also provide soft restore functionality, allowing children to browse through the backups on the server directly from within their Journals. Since this browsing functionality will integrate cleanly with the entries stored on their own laptops, the children will be able to search, filter, sort, and view anything they ever without having to think about the technicalities of the data's physical location. Apart from a visual indication within the entry, the experience of browsing through backups will be seamless. Using the temporary restore method, children can browse through their past creations, much as we might browse through a photo album. They will have full ability to resume any instance of an activity, to view its contents. A copy-on-write approach will be taken, so that if a child attempts to modify a temporarily restored item, it will behave identically to a partial restore for that Object, writing the modified revision into a new journal entry.

{{hig-subnav-intra|p_page=View Source|c_section=The Laptop Experience|c_page=The Journal|n_page=Global Search}}

Human Interface Guidelines/The Laptop Experience/The Journal/translations

2007-10-19T17:52:03Z

Leejc: Reverted edits by 200.226.134.53 (Talk); changed back to last version by Xavi

Development Team/Almanac/Code Snippets

2007-10-07T02:48:43Z

Leejc: Added csound snippet from mailing list

{{OLPC}}
{{Translations}}
== Toolbar ==

=== Toolbar icons ===

button = sugar.graphics.toolbutton.ToolButton("some-icon-name")
button.show()
toolbar.insert(button,-1)

In addition to the standard icons in /usr/share/icons/sugar/scalable/ (eg, "go-next"), you can create additional icons by putting an svg in your activity's icons/ directory. Eg,
icons/my-icon.svg

=== Other notes ===
*Do ''not'' use sugar.graphics.toolbar and its Toolbar. It is old broken left-over code, now deleted. [[User:MitchellNCharity|MitchellNCharity]] 17:06, 21 June 2007 (EDT)

== Files ==

This snippet shows how to get a [http://mailman.laptop.org/pipermail/sugar/2007-February/001459.html path to files in the running Activity]:

from sugar.activity import activity
bundle_path = activity.get_bundle_path()

== Images ==

* [http://mailman.laptop.org/pipermail/sugar/2007-February/001528.html Loading an SVG file onto a surface with a transparent background]:

target = ctx.get_target()
buf = target.create_similar(cairo.CONTENT_COLOR_ALPHA, w, h)
ctx.set_source_surface(buf, x, y)
ctx.paint()

* [http://mailman.laptop.org/pipermail/sugar/2007-February/001547.html Measuring an SVG file's original dimensions]

width, height = handle.get_dimension_data()

* Loading a JPEG file onto a surface:

pixbuf = gtk.gdk.pixbuf_new_from_file("foo.jpg")
ctx = # a cairo context
ctx.set_source_pixbuf(pixbuf, 0, 0)
ctx.paint()

libjpeg is said to be an alternative to using pixbuf. Which is better? Perhaps Sugar/[[HippoCanvas]] provides an easier way to do this?

[[Cairo]] image expansion is good quality, but expensive. Shrinking is fine and notably faster. So for images rendered large (ie, screen-size), you might want to start with a big image, rather than expanding a small one. A speed/space tradeoff. And use SVG instead if appropriate, of course. [[User:MitchellNCharity|MitchellNCharity]] 10:37, 10 May 2007 (EDT)

== Audio ==

* [http://lists.laptop.org/pipermail/sugar/2007-October/003480.html Playing a sound via csound]:

import sys
sys.path.append('/usr/share/activities/Pippy.activity/sound')
from sound import *
playWave(sound='triangle')
audioOut()

== Not yet sorted ==

* [http://mailman.laptop.org/pipermail/sugar/2007-March/002028.html Getting a unique ID for the XO user]:

from sugar import profile

key = profile.get_pubkey()

# If you want a shorter key, you can hash that like:

from sugar import util

key_hash = util._sha_data(key)
hashed_key = util.printable_hash(key_hash)

* Avoid memory exhaustion from large dead pgtk objects by using

import gc

gc.collect()

Not all trash pygtk objects are garbage collected promptly. If you are throwing away large pixmaps, for instance, this can be deadly. gc.collect() forces a garbage collection pass.

== Performance Tips ==
''This section belongs on a different, as yet non-existent page. But a good organization for software development tips is currently unclear to me, so I'll stash this here for now.'' [[User:MitchellNCharity|MitchellNCharity]] 14:05, 10 May 2007 (EDT)

* ctx.stroke() several lines at once. stroke() currently has significant overhead. So it is faster to stroke several, than to stroke them individually. They need not be contiguous. [[User:MitchellNCharity|MitchellNCharity]] 14:05, 10 May 2007 (EDT)

== Old snippets which need to be overhauled ==
=== Toolbar ===

This snippet shows how an activity would have a toolbar with a button and a gtk.TextView widget embedded in a hippo Canvas:

import logging
import hippo
import gtk

from gettext import gettext as _

from sugar.activity import activity
from sugar.graphics.toolbar import Toolbar
from sugar.graphics.iconbutton import IconButton
from sugar.graphics.entry import Entry
from sugar.graphics.optionmenu import OptionMenu
from sugar.graphics.menu import MenuItem

class FooActivity(activity.Activity):

_ACTION_ANYTHING = 1
_ACTION_APPLES = 2
_ACTION_ORANGES = 3

def __init__(self, handle):
activity.Activity.__init__(self, handle)

vbox = hippo.CanvasBox()
self.set_root(vbox)

toolbar = Toolbar()
vbox.append(toolbar)

button = IconButton(icon_name='theme:stock-close')
button.connect("activated", self._button_activated_cb)
toolbar.append(button)

entry = Entry()
button.connect("activated", self._entry_activated_cb)
toolbar.append(entry)

option_menu = OptionMenu()
option_menu.add_item(MenuItem(self._ACTION_ANYTHING, _('Anything')))
option_menu.add_item(MenuItem(self._ACTION_APPLES, _('Apples'),
'theme:stock-close'))
option_menu.add_item(MenuItem(self._ACTION_ORANGES, _('Oranges')))
option_menu.add_separator()
toolbar.append(option_menu)

text_view_widget = hippo.CanvasWidget()
vbox.append(text_view_widget, hippo.PACK_EXPAND)

text_view = gtk.TextView()
text_view.get_buffer().set_text('Write here!', -1)
text_view_widget.props.widget = text_view

def _button_activated_cb(self, button):
logging.debug('FooActivity._button_activated_cb')

def _entry_activated_cb(self, entry):
logging.debug('FooActivity._entry_activated_cb')

:In build 443 (June '07), <tt>from sugar.graphics.entry import Entry</tt> yields ''ImportError: No module named entry''. [[User:MitchellNCharity|MitchellNCharity]] 19:52, 15 June 2007 (EDT)
:And obsolete, now deleted code like sugar.graphics.toolbar is being used. Snippet needs to be overhauled. [[User:MitchellNCharity|MitchellNCharity]] 18:04, 21 June 2007 (EDT)

[[Category:HowTo]]
[[Category:Sugar]]

Human Interface Guidelines/Design Fundamentals/translations

2007-10-07T02:31:13Z

Leejc: Undo revision 68837 by 70.87.7.56 (Talk) -- reverting vandalism

Template:Hig-nav

2007-09-03T13:35:15Z

Leejc: Undo revision 63273 by 83.149.19.6 (Talk) -- reverting ampersand truncation

<div style="border-top:1px solid #888888; border-bottom:1px solid #888888; margin:0px;">
{| width="100%" cellpadding="0" cellspacing="0"
|-
|width=25% align=left bgcolor=#C3D9FF|← '''[[OLPC Human Interface Guidelines/{{{prev}}}|{{{prev}}}]]'''
|width=50% align=center bgcolor=#C3D9FF|'''[[OLPC Human Interface Guidelines/{{{curr}}}|{{{curr}}}]] [[{{NAMESPACE}} talk:OLPC Human Interface Guidelines/{{{curr}}}|<font color="white"><b>(discussion)</b></font>]]'''
|width=25% align=right bgcolor=#C3D9FF| '''[[OLPC Human Interface Guidelines/{{{next}}}|{{{next}}}]]''' →
|}
</div>

Human Interface Guidelines/Activities/Activity Bundles

2007-06-12T19:29:09Z

Leejc: Reverted changes by 199.164.125.138 (Talk) to last version from Xavi

<div style="background-color: #FFF; margin-left:auto; margin-right: auto; width: 95%;">
<noinclude>{{Translations}}</noinclude>
{{hig-subnav-inter|p_link=Activities/Activity Basics|p_label=Activity Basics|c_section=Activities|c_page=Activity Bundles|n_link=Security|n_label=Security}}

===The Activity Bundle===

{|border=1 cellpadding=1 cellspacing=0 style="float: right; width: 175px; border: 1px #666666 solid; border-collapse: collapse; background: #f9f9f9;"
!style="background:#D6784C"|API Reference
|-
|[[Activity Bundles|Activity Bundle technical specifications]]
|}
Activities will exist in the form of bundles. These bundles will manifest as groups of related files—source code, images, documentation, etc—that compose a given activity. As self-contained modules, the distribution and installation of an activity distills to a simple transfer of the activity bundle to a laptop. Properties stored within a bundle provide information about its version and its creator(s).

====Bundle Types====
OLPC will support a signed "official" bundle type. Signed bundles have been tested and verified by an authority such as laptop.org or any other organization through which children obtain bundles in some official capacity, such as a country's official repository. This system may support a trickle-up metaphor through which locally signed bundles propagate upward to higher authorities, allowing wider distribution of newly created activities and content to other regions and countries.

Personal bundles, on the other hand, have been created or modified by an individual among the laptop community. A personal bundle isn't signed or verified by an official source; instead, it is signed or watermarked with the identity of the individual who modified it. This watermark remains attached to the bundle throughout its lifetime. As others modify or change it, their own watermark should be appended to the bundle. This gives a personal bundle some sense of origin and a means through which it is possible to give credit or responsibility.

====Bundle Versions====
Bundles always automatically update to the latest officially signed version present within the laptop's network. If a child's friend has a more recent version of a signed bundle, Sugar will download that newer version and update the laptop automatically. This requires bundles to communicate a unique bundle identifier and version, as well as their signature if they have one.

====Naming Activities====

OLPC aims to provide a platform which encourages expression through creation. In support of this idea, activities — not applications — provide the main tools through which objects are created. Whenever possible, activities should be named with descriptive verbs, or suitable pseudo-verbs, in order to emphasize their function as ''things you do.''

=====Activities as Verbs=====

Activities ''are'' verbs. As such, the phrase "<activity> with my friends" should make sense. For instance "draw with my friends," "browse with my friends", "chat with my friends" and "edit text with my friends" all make much more sense than "text editor with my friends." Similarly, "Tam-tam with my friends" reads as an action, even though you may have never heard "tam-tam" before. Treating the activity as an action (verb) and not as a thing (noun) maintains the interaction model that the laptop tries to embody.

=====Meaningful Naming=====

Of course, we don't mean to impose arbitrary limits on the types and number of activities that the platform has the potential to support. Just because there is a "Draw" activity doesn't mean that one must either find a synonym or come up with a different activity. (However, note that the former can be a very reasonable approach, as a synonym might actually have subtly different connotations which better support the concept of the activity. For instance, drawing and painting typically imply two very different types of media, dry and wet respectively. Much is gained when these types of differences are reflected in the nature of the activity, and are not simply arbitrary.) In modern language, [http://en.wikipedia.org/wiki/Verbing verbification] has become common practice in speech. Many words function as both nouns and as verbs, indicating the action of creation and the resulting product of that action; additionally, many nouns can also function as verbs. For instance, you've probably "Googled" something in the past few days. Many nouns, not just proper ones, can be used in a similar manner.

Additionally, while straightforward names can simplify the interface and provide a means of understanding an activity before entering it, compound names may also be used. Providing a modifier, such as an adjective, can personalize the activity and provide that extra bit of information which differentiates it from similar ones. For instance: "Finger Paint." However, please refrain from resorting to simple one-upsmanship in the form of "Super Sketch" or "Ultra Paint," especially if another activity already uses the modified base. Such names only serve to indicate superiority, and don't provide any useful feedback about the particular activity which makes it unique or useful. Providing a meaningful name goes a long way to making the activity intuitive and enticing to the children using it.

=====Credit=====

Finally, please avoid integrating the name of yourself or of your company into the name of your activity. As an open-source initiative we fully believe in giving due credit, but the name of your activity doesn't provide the appropriate place for accreditation.

====Activity Tags====

Though not yet supported, the .info file for an activity will require a list of associated tags. These tags provide additional information about the context of a specific activity, enabling powerful searching on the Mesh for generalizations or categories of activities. For instance, searching for "game" should return the "Memory," "Chess," and "Tic-Tac-Toe" activities. Likewise, searching for "drawing" should return any activities that relate to drawing, painting, sketching, etc.

====Obtaining Activity Bundles====

Officially signed bundles should spread freely across the mesh Neighborhood; their information and the bundles themselves should be readily available to anyone within communication range. Installation and updates should occur implicitly.

While personal bundles are slightly more restricted, current thinking would limit distribution of personal bundles amongst a child's friends only. This should help limit the destructive power of a malicious bundle from spreading across the Neighborhood, yet still allow people to open up their bundle source code, improve it and share it explicitly.

=====Implicit Bundle Sharing=====
Implicit bundle sharing will automatically update signed bundles on a child's machine when the network allows. If a child finds an interesting activity running on the mesh Neighborhood, she will implicitly download and install the activity on her own machine when she joins that activity. Additionally, this provides a means of obtaining completely new bundles, since she doesn't necessarily need to have an older version of the bundle installed prior to joining. Of course, since there will likely be some download time before the activity can begin, a visual indication of the progress will appear during launch.

In cases where a child joins a group running an older version of an activity she has a newer version of, the same will happen. Her laptop will silently download the older version of the activity so that when she joins, her active instance is service and communication level compatible. However, in such instances the old version will not overwrite the newer version, and will instead remain a transparent detail for compatibility reasons. The newer will remain present on her machine, so that future activities which she initiates begin with the new version, ultimately encouraging the spread of newer bundles.

We might need some kind of warning when joining an activity on the mesh whose bundle is not signed...

=====Explicit Bundle Sharing=====
In the case of personal bundles, explicit sharing will be required. This results from the fact that many children may ultimately edit and redistribute new and altered bundle versions of a variety of software; automatic distribution of such modifications is neither secure nor efficient.

In these cases, activities may be posted to private Bulletin Boards, or distributed directly to a child's friends through the drag and drop metaphors used elsewhere in the interface.

====Where Are Bundles Stored?====
The Journal keeps a record of all bundles on the laptop. Installing a bundle creates an entry that indicates who the child downloaded the bundle from and its version. If she installed the bundle through the joining of an activity, the activity entry in the journal will reference the newly updated bundle. Of course, once stored within the journal, the Bundle will be available for activation within the Actions section of the Frame.

====Removing Bundles====
The journal entry for an activity bundle also allows for its removal; it is deleted in the same way one would remove any other item from the Journal.

{{hig-subnav-inter|p_link=Activities/Activity Basics|p_label=Activity Basics|c_section=Activities|c_page=Activity Bundles|n_link=Security|n_label=Security}}

Development Team/Almanac/Code Snippets

2007-03-11T05:10:02Z

Leejc: /* Toolbar */ Fixed code formatting

{{OLPC}}

= Toolbar =

This snippet shows how an activity would have a toolbar with a button and a gtk.TextView widget embedded in a hippo Canvas:

import logging
import hippo
import gtk

from gettext import gettext as _

from sugar.activity import activity
from sugar.graphics.toolbar import Toolbar
from sugar.graphics.iconbutton import IconButton
from sugar.graphics.entry import Entry
from sugar.graphics.optionmenu import OptionMenu
from sugar.graphics.menu import MenuItem

class FooActivity(activity.Activity):

_ACTION_ANYTHING = 1
_ACTION_APPLES = 2
_ACTION_ORANGES = 3

def __init__(self, handle):
activity.Activity.__init__(self, handle)

vbox = hippo.CanvasBox()
self.set_root(vbox)

toolbar = Toolbar()
vbox.append(toolbar)

button = IconButton(icon_name='theme:stock-close')
button.connect("activated", self._button_activated_cb)
toolbar.append(button)

entry = Entry()
button.connect("activated", self._entry_activated_cb)
toolbar.append(entry)

option_menu = OptionMenu()
option_menu.add_item(MenuItem(self._ACTION_ANYTHING, _('Anything')))
option_menu.add_item(MenuItem(self._ACTION_APPLES, _('Apples'),
'theme:stock-close'))
option_menu.add_item(MenuItem(self._ACTION_ORANGES, _('Oranges')))
option_menu.add_separator()
toolbar.append(option_menu)

text_view_widget = hippo.CanvasWidget()
vbox.append(text_view_widget, hippo.PACK_EXPAND)

text_view = gtk.TextView()
text_view.get_buffer().set_text('Write here!', -1)
text_view_widget.props.widget = text_view

def _button_activated_cb(self, button):
logging.debug('FooActivity._button_activated_cb')

def _entry_activated_cb(self, entry):
logging.debug('FooActivity._entry_activated_cb')

= Files =

This snippet shows how to get a [http://mailman.laptop.org/pipermail/sugar/2007-February/001459.html path to files in the running Activity]:

from sugar.activity import activity
bundle_path = activity.get_bundle_path()

[[Category:HowTo]]
[[Category:Sugar]]

Development Team/Jhbuild

2007-03-10T00:05:36Z

Leejc: /* Run an individual activity */

One of the easiest ways to install [[Sugar]] is to use sugar-jhbuild.

Sugar-jhbuild will automatically download the latest of Sugar's dependencies as well as Sugar itself directly from their source repositories, rather than relying on source packages that may have become stale. Below are generic instructions on how to use sugar-jhbuild to get up and running with Sugar.

'''Note:''' Some Linux distributions may need or have special procedures; you can check the pages on [[:Category:Installing Sugar|installing Sugar]] to see if they are available.

==Checkout sugar-jhbuild==

git-clone git://dev.laptop.org/sugar-jhbuild

==Build sugar base system and its dependencies==

Change directory and start the build.

cd sugar-jhbuild
./sugar-jhbuild update
./sugar-jhbuild build-base
./sugar-jhbuild build

For the base packages (i.e. <tt>build-base</tt>), you may be able to use the binary packages from your GNU distribution instead of building them from scratch. Check the [[:Category:Installing Sugar|Installing]] or [[:Category:Linux distributions|Linux]] categories for specific distro info.

==Run Sugar==

This command launches the Sugar emulator:

./sugar-jhbuild run

To exit the emulator, press Alt-Q.

== Run an individual activity ==

Within the sugar shell (./sugar-jhbuild shell), this command launches an individual activity for testing (from the [http://mailman.laptop.org/pipermail/sugar/2007-March/001720.html mailing list]):

sugar-activity [bundle name]

== Other commands ==

JHBuild has several other commands that can be useful for development. You can get an overview with:

./sugar-jhbuild --help-commands

A useful sequence of commands for building Sugar, from the [http://mailman.laptop.org/pipermail/sugar/2007-February/001352.html Sugar mailing list]:

./sugar-jhbuild update
./sugar-jhbuild build-base
./sugar-jhbuild build
./sugar-jhbuild run

== Customize ==

To customize the build create a configuration file, named .olpc.jhbuildrc, in your home directory.

=== Write access to the repositories ===

If you have write access to the repositories you can add:
repos['gnome.org'] = ':ext:marco@cvs.gnome.org:/cvs/gnome'
repos['mozilla.org'] = ':ext:marco%gnome.org@cvs.mozilla.org:/cvsroot'
repos['git.laptop.org'] = 'git+ssh://dev.laptop.org/git/artwork'

==External links==

* [http://www.gnome.org/~jamesh/jhbuild.html JHBuild manual]
* [http://www.redhatmagazine.com/2007/02/23/building-the-xo-introducing-sugar/ Red Hat Magazine article: Introducing Sugar]

[[Category:Installing Sugar]]

Development Team/Jhbuild

2007-03-10T00:05:11Z

Leejc: Added note on running individual activity

One of the easiest ways to install [[Sugar]] is to use sugar-jhbuild.

Sugar-jhbuild will automatically download the latest of Sugar's dependencies as well as Sugar itself directly from their source repositories, rather than relying on source packages that may have become stale. Below are generic instructions on how to use sugar-jhbuild to get up and running with Sugar.

'''Note:''' Some Linux distributions may need or have special procedures; you can check the pages on [[:Category:Installing Sugar|installing Sugar]] to see if they are available.

==Checkout sugar-jhbuild==

git-clone git://dev.laptop.org/sugar-jhbuild

==Build sugar base system and its dependencies==

Change directory and start the build.

cd sugar-jhbuild
./sugar-jhbuild update
./sugar-jhbuild build-base
./sugar-jhbuild build

For the base packages (i.e. <tt>build-base</tt>), you may be able to use the binary packages from your GNU distribution instead of building them from scratch. Check the [[:Category:Installing Sugar|Installing]] or [[:Category:Linux distributions|Linux]] categories for specific distro info.

==Run Sugar==

This command launches the Sugar emulator:

./sugar-jhbuild run

To exit the emulator, press Alt-Q.

== Run an individual activity ==

Within the sugar shell (./sugar-jhbuild shell), this command launches an individual activity for testing (from the [http://mailman.laptop.org/pipermail/sugar/2007-March/001720.html mailing list]):

./sugar-activity [bundle name]

== Other commands ==

JHBuild has several other commands that can be useful for development. You can get an overview with:

./sugar-jhbuild --help-commands

A useful sequence of commands for building Sugar, from the [http://mailman.laptop.org/pipermail/sugar/2007-February/001352.html Sugar mailing list]:

./sugar-jhbuild update
./sugar-jhbuild build-base
./sugar-jhbuild build
./sugar-jhbuild run

== Customize ==

To customize the build create a configuration file, named .olpc.jhbuildrc, in your home directory.

=== Write access to the repositories ===

If you have write access to the repositories you can add:
repos['gnome.org'] = ':ext:marco@cvs.gnome.org:/cvs/gnome'
repos['mozilla.org'] = ':ext:marco%gnome.org@cvs.mozilla.org:/cvsroot'
repos['git.laptop.org'] = 'git+ssh://dev.laptop.org/git/artwork'

==External links==

* [http://www.gnome.org/~jamesh/jhbuild.html JHBuild manual]
* [http://www.redhatmagazine.com/2007/02/23/building-the-xo-introducing-sugar/ Red Hat Magazine article: Introducing Sugar]

[[Category:Installing Sugar]]

Development Team/Almanac/Code Snippets

2007-02-27T00:23:08Z

Leejc: /* Files */

Other snippets might be found on the [http://dev.laptop.org/wiki/Code development wiki].

= Toolbar =

This snippet shows how an activity would have a toolbar with a button and a gtk.TextView widget embedded in a hippo Canvas:

import logging
import hippo
import gtk

from sugar.activity import activity
from sugar.graphics.toolbar import Toolbar
from sugar.graphics.iconbutton import IconButton
from sugar.graphics.entry import Entry
from sugar.graphics.optionmenu import OptionMenu
from sugar.graphics.menu import MenuItem

class FooActivity(activity.Activity):

_ACTION_ANYTHING = 1
_ACTION_APPLES = 2
_ACTION_ORANGES = 3

def __init__(self, handle):
activity.Activity.__init__(self, handle)

canvas = hippo.Canvas()
self.add(canvas)
canvas.show()

vbox = hippo.CanvasBox()
canvas.set_root(vbox)

toolbar = Toolbar()
vbox.append(toolbar)

button = IconButton(icon_name='theme:stock-close')
button.connect("activated", self._button_activated_cb)
toolbar.append(button)

entry = Entry()
button.connect("activated", self._entry_activated_cb)
toolbar.append(entry)

option_menu = OptionMenu()
option_menu.add_item(MenuItem(self._ACTION_ANYTHING, _('Anything')))
option_menu.add_item(MenuItem(self._ACTION_APPLES, _('Apples'),
'theme:stock-close'))
option_menu.add_item(MenuItem(self._ACTION_ORANGES, _('Oranges')))
option_menu.add_separator()
toolbar.append(option_menu)

text_view_widget = hippo.CanvasWidget()
vbox.append(text_view_widget, hippo.PACK_EXPAND)

text_view = gtk.TextView()
text_view.get_buffer().set_text('Write here!', -1)
text_view_widget.props.widget = text_view

def _button_activated_cb(self, button):
logging.debug('FooActivity._button_activated_cb')

def _entry_activated_cb(self, entry):
logging.debug('FooActivity._entry_activated_cb')

= Files =

This snippet shows how to get a [http://mailman.laptop.org/pipermail/sugar/2007-February/001459.html path to files in the running Activity]:

from sugar.activity import activity
bundle_path = activity.get_bundle_path()

= Profiling =

:''See [[Sugar Performance]] for a profiling snippet''

[[Category:HowTo]]
[[Category:Sugar]]

Development Team/Almanac/Code Snippets

2007-02-20T19:52:04Z

Leejc: Added profiling link

Development Team/Jhbuild

2007-02-18T17:03:58Z

Leejc: /* Run Sugar */ Added emulator quit command

One of the easiest ways to install [[Sugar]] is to use sugar-jhbuild.

Sugar-jhbuild will automatically download the latest of Sugar's dependencies as well as Sugar itself directly from their source repositories, rather than relying on source packages that may have become stale. Below are generic instructions on how to use sugar-jhbuild to get up and running with Sugar.

'''Note:''' Some Linux distributions may need or have special procedures; you can check the pages on [[:Category:Installing Sugar|installing Sugar]] to see if they are available.

==Checkout sugar-jhbuild==

git-clone git://dev.laptop.org/sugar-jhbuild

==Build sugar base system and its dependencies==

Change directory and start the build.

cd sugar-jhbuild
./sugar-jhbuild build

For the base packages (i.e. <tt>build-base</tt>),
you should be able to use the binary packages from your GNU distribution
instead of building them from scratch. Distribution specific hints here:
[[Suger-base:Debian]]

==Run Sugar==

This command launches the Sugar emulator:

./sugar-jhbuild run

To exit the emulator, press Alt-Q.

== Other commands ==

JHBuild has several other commands that can be useful for development. You can get an overview with:

./sugar-jhbuild --help-commands

A useful sequence of commands for building Sugar, from the [http://mailman.laptop.org/pipermail/sugar/2007-February/001352.html Sugar mailing list]:

./sugar-jhbuild update
./sugar-jhbuild build-base
./sugar-jhbuild build
./sugar-jhbuild run

== Customize ==

To customize the build create a configuration file, named .olpc.jhbuildrc, in your home directory.

=== Write access to the repositories ===

If you have write access to the repositories you can add:
repos['gnome.org'] = ':ext:marco@cvs.gnome.org:/cvs/gnome'
repos['mozilla.org'] = ':ext:marco%gnome.org@cvs.mozilla.org:/cvsroot'
repos['git.laptop.org'] = 'git+ssh://dev.laptop.org/git/artwork'

==External links==

* [http://www.gnome.org/~jamesh/jhbuild.html JHBuild manual]

[[Category:Installing Sugar]]

Development Team/Almanac/Code Snippets

2007-02-16T19:45:17Z

Leejc:

Development Team/Jhbuild

2007-02-16T04:40:00Z

Leejc: /* Other commands */

Development Team/Almanac/Code Snippets

2007-02-16T03:39:38Z

Leejc: Added development wiki link