Sugar Labs - User contributions [en]

Development Team/Almanac/Sugar.presence

2008-11-24T22:52:52Z

Jedierikb: /* Which threading patterns are most appropriate for use on the sugar platform? */

{{Sugar Almanac}}
=== How do I setup a D-Bus Tube? ===

Let's first look at what conceptually happens to make activity sharing work. The diagram below shows two instances of the same activity: the "Sharing Activity" and the "Joining Activity". The sharing activity is the activity that is initially run and shared with other buddies. The "Joining Activity" refers to other instances of the activity that are created once buddies decide to join an activity that has been shared. You can allow an activity to be shared (making it a sharing activity) by [[Sugar.presence.presenceservice#How do I share an activity with other buddies in my neighborhood? | including the standard Sugar Activity Toolbar]].

[[Image:tube-setup.jpg | How Tubes are Setup]]

Once the user decides to share his activity with others, that activity becomes the sharing activity. The activity will receive a "shared" signal from the connection manager indicating the activity has been shared. The sharing activity must then save information about the channel on which the tube will exist and call the OfferDBusTube() method to offer a tube that can be accessed by other XOs that join the activity. The process is similar for XOs that join an activity except they will need to call the ListTubes() method instead of OfferDBusTubes() to find a tube that has been offered by the sharing activity.

Once a tube has been set up by the underlying connection manager, both the sharing and joining XOs get a "NewTube" signal. Upon receiving this signal, each tube can instantiate a new Tube class that has been designed and implemented for the needs of each specific activity. The code example below shows how all of the steps above are actually accomplished (only the code directly relevant to tube setup has been included).

<pre>
...
import telepathy
from dbus.service import method, signal
from dbus.gobject_service import ExportedGObject
from sugar.presence import presenceservice
from sugar.presence.tubeconn import TubeConnection
from sugar import profile
...

SERVICE = "org.laptop.Sample"
IFACE = SERVICE
PATH = "/org/laptop/Sample"

class SampleActivity(activity.Activity):

_ps = presenceservice.get_instance()

############################ METHODS INVOLVED IN TUBE SETUP ##########################################

#### Method: __init__, initialize this SampleActivity instance
def __init__(self, handle):
activity.Activity.__init__(self, handle)
...
#When you initialize your activity, wait for receipt of "joined" or "shared" signals
#and also keep a variable called self.initiating to indicating whether this instance
#is the sharing or joining activity.
self.initiating = None #indicates whether this instance initiated sharing.
self.connect('shared', self._shared_cb)
self.connect('joined', self._joined_cb)

#### Method self._shared_cb, which is called whenever this activity has been successfully
# shared with other XOs on the mesh
def _shared_cb(self, activity):

#Ensure that this activity is indeed being shared
if self._shared_activity is None:
_logger.error("Failed to share or join activity ... _shared_activity is null in _shared_cb()")
return

#This activity initiated sharing, so set self.initiating to be true
self.initiating = True

#Save information about the telepathy connection, telepathy tubes channel and the text channel
#associated with this shared activity
self.conn = self._shared_activity.telepathy_conn
self.tubes_chan = self._shared_activity.telepathy_tubes_chan
self.text_chan = self._shared_activity.telepathy_text_chan

#Set up a callback for when we receive the "NewTube" signal later on
self.tubes_chan[telepathy.CHANNEL_TYPE_TUBES].connect_to_signal(
'NewTube', self._new_tube_cb)

#Call the OfferDBusTubes() method
_id = self.tubes_chan[telepathy.CHANNEL_TYPE_TUBES].OfferDBusTube(SERVICE, {})

#### Method self._joined_cb, which is called whenever this XO has successfully joined another
# activity.
def _joined_cb(self, activity):

#Ensure that this activity is indeed being shared
if self._shared_activity is None:
_logger.error("Failed to share or join activity ... _shared_activity is null in _shared_cb()")
return

#This activity joined an existing shared activity, so set self.initiating to False
self.initiating = False

#Save information about the telepathy connection, telepathy tubes channel and the text channel
#associated with this shared activity
self.conn = self._shared_activity.telepathy_conn
self.tubes_chan = self._shared_activity.telepathy_tubes_chan
self.text_chan = self._shared_activity.telepathy_text_chan

#Set up a callback for when we receive the "NewTube" signal later on
self.tubes_chan[telepathy.CHANNEL_TYPE_TUBES].connect_to_signal(
'NewTube', self._new_tube_cb)

#For joining activities, call ListTubes and connect to a callback once a set
#shared tubes have been found (list_tubes_reply_cb).
self.tubes_chan[telepathy.CHANNEL_TYPE_TUBES].ListTubes(reply_handler=self._list_tubes_reply_cb, error_handler=self._list_tubes_error_cb)

#### Method _list_tubes_reply_cb, which is called once ListTubes successfully finds
# tubes available for a joining activity.
def _list_tubes_reply_cb(self, tubes):
for tube_info in tubes:
self._new_tube_cb(*tube_info)

#### Method _list_tubes_error_cb, which is needed in case there was some error in ListTubes
# for the joining activity.
def _list_tubes_error_cb(self, e):
print "Error" + str(e)

#### Method _new_tube_cb, which is called for both joining and sharing activities once a tube
# is available in the underlying presence system for communication. Several parameters will be
# passed to this callback with information about the tube that has been set up.
def _new_tube_cb(self, id, initiator, type, service, params, state):

if (type == telepathy.TUBE_TYPE_DBUS and service == SERVICE):
if state == telepathy.TUBE_STATE_LOCAL_PENDING:
#Accept the new tube that has been created
self.tubes_chan[telepathy.CHANNEL_TYPE_TUBES].AcceptDBusTube(id)

# The tube connection object gives a handle to the new tube.
tube_conn = TubeConnection(self.conn, self.tubes_chan[telepathy.CHANNEL_TYPE_TUBES], id, group_iface=self.text_chan[telepathy.CHANNEL_INTERFACE_GROUP])

# Using the handle saved above, create an instance of your own customized Tube wrapper that
# will handle sending and receiving text from the underlying tube conneciton (ChatTube is defined
# at the end below this activity class).
self.chattube = ChatTube(tube_conn, self.initiating, self.text_received_cb)

...
...
############################# METHODS USED ONCE TUBE IS SET UP ###################################

#### Method text_received_cb, which is called once a ChatTube instance is set up and that class
# receives any text over the tube. You will pass this method as an argument to ChatTube.__init__()
# (see _new_tube_cb() method above).
def text_received_cb(self, text):
self._chat += "\nSomeone Else" + ":: " + text + "\n"
self._chat_buffer.set_text(self._chat)

#### Method: _speak_cb, which is called whenever user decides to send whatever chat text
# he has written in self._chat_input to the public room.
def _speak_cb(self, widget, entry):
nick = profile.get_nick_name()
nick = nick.upper()
self._chat += "\n" + nick + ":: " + entry.get_text() + "\n"
self._chat_buffer.set_text(self._chat)
if self.chattube is not None:
self.chattube.SendText(entry.get_text())
entry.set_text("")

######################## CHATTUBE CLASS - WRAPS LOGIC FOR TUBE COMMUNICATION #####################
class ChatTube(ExportedGObject):
#### Method __init__, which sets up a new ChatTube instance given the underlying tube connection
# object (tube).
def __init__(self, tube, is_initiator, text_received_cb):
super(ChatTube, self).__init__(tube, PATH)
self.tube = tube
self.is_initiator = is_initiator #is this the sharing or joining activity?
self.text_received_cb = text_received_cb #callback in main activity when text is received
self.text = ''

#The sendtext_cb method is called once someone else has sent text to this end of the tube.
self.tube.add_signal_receiver(self.sendtext_cb, 'SendText', IFACE, path=PATH, sender_keyword='sender')

#### Method sendtext_cb, which is called once this tube receives text that is
# sent by someone else
def sendtext_cb(self, text, sender=None):
if sender == self.tube.get_unique_name():
return
self.text = text
self.text_received_cb(text)

#### Method SendText, which uses a DBus signal to actually send text to others over the tube.
@signal(dbus_interface=IFACE, signature='s')
def SendText(self, text):
self.text = text

</pre>

=== How is data shared between activities through a D-Bus tube? ===

Communication in Sugar is achieved through several layers of technologies, including Sugar's own Presence Service, the D-Bus service for process communication, and various implementations of the telepathy system used for real time conversations. In order to get activity communication working between activities, your goal is to ultimately create a D-Bus tube that will handle text messaging between activities (there are also stream tubes which are discussed elsewhere).

The figure below shows a simplified conceptualization of what happens after you set up a D-Bus tube correctly.

[[Image:tubes-all-setup.jpg | How things work once the tubes are set up. ]]

The activity code for each XO should handle sending text to the tube and also receiving text through a callback method that is supplied to the tube. The Activity developer will also need to define the Tube Object itself, which should be designed to send and receive text appropriately based on the type of sharing that is desired.

Let's consider a simple, but concrete example of how a D-Bus tube is used (assuming it has already been setup correctly). The code below is from a chat application where users type text and send it to others who are sharing the activity. Only the minimal code needed to send and receive text is included for clarity. If you want to know how the tube is set up from start to finish, then read the section on [[#How do I setup a D-Bus Tube? | setting up a D-Bus tube]]. The comments should make clear what code does what in this example.

<pre>

import telepathy
from dbus.service import method, signal
from dbus.gobject_service import ExportedGObject
from sugar.presence import presenceservice
from sugar.presence.tubeconn import TubeConnection
...
SERVICE = "org.laptop.Sample"
IFACE = SERVICE
PATH = "/org/laptop/Sample"

############## MAIN ACTIVITY CLASS ####################
class SampleActivity(activity.Activity):
...
# Callback method for text received from tube -- update activity state
def text_received_cb(self, text):
self._chat += "\nSomeone Else Said" + ":: " + text + "\n"
self._chat_buffer.set_text(self._chat)

#### Method: _speak_cb, which is called whenever user decides to send whatever chat text
# he has written in self._chat_input to the public.
def _speak_cb(self, widget, entry):
nick = profile.get_nick_name()
nick = nick.upper()
self._chat += "\n" + nick + ":: " + entry.get_text() + "\n"
self._chat_buffer.set_text(self._chat)
if self.chattube is not None:
self.chattube.SendText(entry.get_text())
entry.set_text("")

...

###################### TUBE CLASS ######################
class ChatTube(ExportedGObject):

def __init__(self, tube, is_initiator, text_received_cb):
super(ChatTube, self).__init__(tube, PATH)
...
self.text_received_cb = text_received_cb
self.text = ''
self.tube.add_signal_receiver(self.sendtext_cb, 'SendText', IFACE, path=PATH, sender_keyword='sender')
...

# This method is called when the XO receives some text through the D-bus tube
def sendtext_cb(self, text, sender=None):
# Ignore any text that this XO sent to itself.
if sender == self.tube.get_unique_name():
return

self.text = text
self.text_received_cb(text)

# This method is used to actually send text to all other XO's who are sharing.
@signal(dbus_interface=IFACE, signature='s')
def SendText(self, text):
self.text = text

</pre>

=== How do I set up a simple stream tube that can send data one-way between two instances of an activity? ===

As with D-Bus tubes, there are a series of coordinated steps that must happen between a sharing and joining activity before data can be shared over a tube. The example we discuss here specifically concerns sharing data one way - from a "sharing" activity to a "joining" activity. Stream tubes are especially useful if you want to share non-text data or if you want to take advantage of communication protocols like TCP/IP and UDP to transfer data between instances of an activity running on separate XOs.

==== Step 1: Understand how to architect your stream tubes to achieve the goals of your activity. ====

Before trying to create any working code, you should understand exactly what you want your stream tube to do - when and how will sharing of data occur over the tube during the life of your activity? The example we discuss below is predicated on a specific model of communication.

In particular, the code we use in this section is adapted from the [http://wiki.laptop.org/go/Read Read activity], but it has been incorporated in to an example activity called "Annotate". In activities like Read or Annotate, the goal is to set up a one way communication between the "sharing" activity and the "joining" activity so that the joining activity can download and take part in whatever document is being edited by the sharer. The document to be sent over the stream tube is shared immediately upon startup and requires no user action to initiate it.

Given such a paradigm for using our stream tube, we can draw a rough picture of what our communication architecture will look like in this case:

[[Image:stream-tube-in-annotate-activity.jpg | How annotate's stream tube will be used]]

Notice that the stream tube exists on top of the [http://en.wikipedia.org/wiki/Internet_socket socket architecture] used by Unix systems to facilitate internet communication.

==== Step 2: Define or identify the classes you will use to serve data and receive data through your stream tube. ====

In our case, we want the sharing activity to behave like a one-time server while the joining activity is a client that downloads any document it needs on startup. To accomplish serving, we create the following two classes:

<pre>
...
import telepathy
from dbus.service import method, signal
from dbus.gobject_service import ExportedGObject
from sugar.presence import presenceservice
from sugar.presence.tubeconn import TubeConnection
from sugar import network
...

SERVICE = "org.laptop.Annotate"
IFACE = SERVICE
PATH = "/org/laptop/Annotate"

##########################################################################
REQUESTHANDLER AND HTTPSERVER WORK TOGETHER TO SERVE DATA OVER STREAM TUBE
##########################################################################
class AnnotateHTTPRequestHandler(network.ChunkedGlibHTTPRequestHandler):
#### Method translate_path, which, for our simple activity, just returns the same
# filepath for a document that will be shared.
def translate_path(self, path):
return self.server._filepath

class AnnotateHTTPServer(network.GlibTCPServer):
def __init__(self, server_address, filepath):
self._filepath = filepath
network.GlibTCPServer.__init__(self, server_address, AnnotateHTTPRequestHandler)

</pre>

In the example code above, most of the work is done by the superclasses defined in sugar.network, namely ChunkedGlibHTTPRequestHandler and GLibTCPServer. However, if you want some custom behavior in how data is served, then it is a good idea to subclass those or other Server and RequestHandler classes.

On the client side, there must be a class that handles receiving data from a server. In Annotate, this is accomplished with the standard sugar.network.GlibURLDownloader class.

==== Step 3: Coordinate sharing and joining in your activity using stream tubes and the client/server classes defined above. ====

On the sharing instance, the following must happen:
* Once the activity has been shared by the user, the sharing instance should detect the "shared" signal and setup for sharing.
* To setup for sharing, the sharing instance needs to instantiate a new server (in Annotate, this is an AnnotateHTTPServer) that will deliver content to any client activities.
* The newly instantiated server should listen on a given port and that port should be connected to a new stream tube. The stream tube can be created by calling the iface.OfferStreamTube() method.

For the joining activity, it must coordinate several steps once the "joined" signal has been detected:
* The joining activity needs to wait for a valid stream tube that is provided under the service ANNOTATE_STREAM_SERVICE.
* When such a tube is available, the joining activity should specify the path where the downloaded data will be saved.
* Create a listening client on the address and port associated with the stream tube that has been found. In our case, we create a sugar.network.GlibURLDownloader instance that will manage downloading from the stream tube.

<pre>
ANNOTATE_STREAM_SERVICE = 'annotate-activity-http'

class AnnotateActivity(activity.Activity):

#### Method: __init__, initialize this AnnotateActivity instance
def __init__(self, handle):

...

#Joining activity needs to know which stream tubes are available for downloading
#and if it still needs to download document.
self.unused_download_tubes = set()
self._want_document = True

#Set the port number on which sharing activity will serve data
h = hash(self._activity_id)
self.port = 1024 + (h % 64511)

self.connect('shared', self._shared_cb)
if self._shared_activity:
# We're joining
if self.get_shared():
# Already joined for some reason, just get the document
self._joined_cb(self)
else:
# Wait for a successful join before trying to get the document
self.connect("joined", self._joined_cb)

...

######################## SETUP SERVER ON SHARING ACTIVITY ####################################

#### Method _shared_cb, which is called when this activity is successfully
# shared on a mesh channel.
def _shared_cb(self, activity):
# We initiated this activity and have now shared it, so by
# definition we have the file.
_logger.debug('SYSTEM:', '_shared_cb(): Activity being shared')
self._want_document = False;
self._share_document()

#### Method: _share_document, which sets up an http server that will serve a specific file to
# any joining activities.
def _share_document(self):
_logger.debug('SYSTEM', '_share_document() -- sharing file ' + str(object_path))
object_path = os.path.join(self.get_activity_root(), 'data', 'sample-shared-file.doc')

_logger.debug('SYSTEM', '_share_document() -- Starting HTTP server on port '+str(self.port))
self._fileserver = AnnotateHTTPServer(("", self.port), object_path)

# Make a tube for the server
chan = self._shared_activity.telepathy_tubes_chan
iface = chan[telepathy.CHANNEL_TYPE_TUBES]
self._fileserver_tube_id = iface.OfferStreamTube(ANNOTATE_STREAM_SERVICE,
{},
telepathy.SOCKET_ADDRESS_TYPE_IPV4,
('127.0.0.1', dbus.UInt16(self.port)),
telepathy.SOCKET_ACCESS_CONTROL_LOCALHOST, 0)

################### COORDINATE TUBE CREATION AND DOWNLOAD IN JOINING ACTIVITY ##################

#### Method _joined_cb, which is called when this activity joins another
# instance
def _joined_cb(self, also_self):
self.watch_for_tubes()
self._want_document = True;
gobject.idle_add(self._get_document)

#### Method watch_for_tubes, which sets up a callback to _new_tube_cb once
# a stream tube is made available.
def watch_for_tubes(self):
tubes_chan = self._shared_activity.telepathy_tubes_chan

tubes_chan[telepathy.CHANNEL_TYPE_TUBES].connect_to_signal('NewTube',
self._new_tube_cb)
tubes_chan[telepathy.CHANNEL_TYPE_TUBES].ListTubes(
reply_handler=self._list_tubes_reply_cb,
error_handler=self._list_tubes_error_cb)

def _list_tubes_reply_cb(self, tubes):
for tube_info in tubes:
self._new_tube_cb(*tube_info)

def _list_tubes_error_cb(self, e):

#### Method _new_tube_cb, which is called once a stream tube is available
# to download from
def _new_tube_cb(self, tube_id, initiator, tube_type, service, params,
state):
# If the available tube is the stream tube we set up in sharing activity, then
# let's download from it.
if service == ANNOTATE_STREAM_SERVICE:
# Add the newly found stream tube to the available tubes we can download from
self.unused_download_tubes.add(tube_id)

# if no download is in progress, let's fetch the document
if self._want_document:
gobject.idle_add(self._get_document)

#### Method _get_document, which sets this activity instance up to start downloading
# the document from the sharing activity. It is called once a stream tube has been
# obtained and saved in self.unused_download_tubes.
def _get_document(self):
if not self._want_document:
return False

# Assign a file path to download to -- where downloaded doc will be saved.
path = os.path.join(self.get_activity_root(), 'instance',
'%i' % time.time())

# Pick an available tube we can try to download the document from
try:
tube_id = self.unused_download_tubes.pop()
except (ValueError, KeyError), e:
return False

# Avoid trying to download the document multiple times at once
self._want_document = False
gobject.idle_add(self._download_document, tube_id, path)
return False

#### Method _download_result_cb, which is called once downloading is complete.
def _download_result_cb(self, getter, tempfile, suggested_name, tube_id):
del self.unused_download_tubes
self.save()

#### Method _download_progress_cb, which is called as the file is being downloaded.
def _download_progress_cb(self, getter, bytes_downloaded, tube_id):
# FIXME: signal the expected size somehow, so we can draw a progress
# bar
return True;

#### Method _download_error_cb, which is called if there was an error downloading.
def _download_error_cb(self, getter, err, tube_id):
_logger.debug("Error getting document from tube %u: %s",
tube_id, err)
self._want_document = True
gobject.idle_add(self._get_document)

def _download_document(self, tube_id, path):
# FIXME: should ideally have the CM listen on a Unix socket
# instead of IPv4 (might be more compatible with Rainbow)
chan = self._shared_activity.telepathy_tubes_chan
iface = chan[telepathy.CHANNEL_TYPE_TUBES]
addr = iface.AcceptStreamTube(tube_id,
telepathy.SOCKET_ADDRESS_TYPE_IPV4,
telepathy.SOCKET_ACCESS_CONTROL_LOCALHOST, 0,
utf8_strings=True)
_logger.debug('Accepted stream tube: listening address is %r', addr)
# SOCKET_ADDRESS_TYPE_IPV4 is defined to have addresses of type '(sq)'
assert isinstance(addr, dbus.Struct)
assert len(addr) == 2
assert isinstance(addr[0], str)
assert isinstance(addr[1], (int, long))
assert addr[1] > 0 and addr[1] < 65536
port = int(addr[1])

getter = network.GlibURLDownloader("http://%s:%d/document"
% (addr[0], port))
getter.connect("finished", self._download_result_cb, tube_id)
getter.connect("progress", self._download_progress_cb, tube_id)
getter.connect("error", self._download_error_cb, tube_id)
getter.start(path)
return False

</pre>

=== When downloading data from a stream tube, how can I show the download progress? ===

=== How do I control the file and path where data is saved when sharing through a stream tube? ===

=== Where do I get more information regarding sugar activity sharing and the technologies that support it? ===
* A [[Shared_Sugar_Activities | brief tutorial]] on activity sharing for the OLPC laptop.

=== I can't get tubes to work. Are there unresolved issues? ===

==== Which threading patterns are most appropriate for use on the sugar platform? ====


There are issues regarding the best way to create activities that support media sharing. In particular, the structure of DBus tubes makes it easy to customize the communication process between activity instances running on multiple XOs. However, stream tubes seem to be tied closely to a client server architecture - the servers and handlers provided in sugar.network package are some form of client/server arrangement.



Setting up more advanced stream tubes functionality that would allow sharing of non-text data (eg. binary files, images, etc.) in a continuous manner in the way dbus tubes enable text communication is complicated. To allow activities to communicate constantly over a stream tube, one needs to set up both a client and server side on each activity and coordinate communication between them. Furthermore, most activities would require threading as well, which means resolving best practices for threading. Ultimately, it seems that the existing servers/handlers to support stream tubes may not be adequate to support easy and relatively painless sharing of data between activities on a continuous basis. The code that is on the Almanac right now guides a user through the basic process of setting up a stream tube and allowing communication one time between the server and client. This is useful for sharing/joining activities that require sending binary files (which is why Record and Read use this). However, it does not extend easily to peer to peer communication.



One solution to sending non-text data between activities is to just use the DBus tube and take advantage of its flexibility. It's not clear how well these tubes will support binary data, however and whether they work well with larger media files. It would be helpful to get insight from sugar developers regarding how such communication should work and what facilities sugar needs to add to support this (perhaps more functionality for stream tubes in sugar.network). Given that peer to peer networking through mesh is probably one of the standout features of XO laptops, I think having better functionality (and better documentation) for developers to build rich communicative applications is a high priority.

Development Team/Almanac

2008-11-24T22:47:45Z

Jedierikb: /* My Python activity wants to use threads; how do I do that? */

{{Sugar Almanac}}
{{Sugar Almanac TOC}}
== How do I get additional help beyond this almanac? ==
* Looking to get started with the basics of Sugar development? Check out Christoph Derndorfer's [http://www.olpcaustria.org/mediawiki/index.php/Activity_handbook Activity Handbook].
* See also [[Sugar Code Snippets]]

Now, on to the actual almanac ...

== Where can I see API changes? ==
API changes between OLPC releases can be seen here: [[API changes]]

== Getting Started ==
=== How do I structure my files so that they are a valid sugar activity? ===
Information on activity bundle structure can be found here: [[Activity bundles]]

=== How do I make an icon for my activity? ===
Information on what you need to do can be found here: [[Making Sugar Icons]]

== Package: sugar ==
* [[sugar.env]]
* [[sugar.profile]]
* [[sugar.mime]]
* [[sugar.logger]]

== Package: sugar.activity ==
* [[sugar.activity.activity]]
* [[sugar.activity.activityfactory]]
* [[sugar.activity.registry]]

== Package: sugar.datastore ==
* [[sugar.datastore.datastore]]

== Package: sugar.graphics ==
* [[sugar.graphics.alert]]
* [[sugar.graphics.icon]]
* [[sugar.graphics.notebook]]
* [[sugar.graphics.toolbutton]]
* [[sugar.graphics.toolbox]]
* [[sugar.graphics.style]]

== Package: sugar.presence ==
* [[sugar.presence]]
* [[sugar.presence.activity]]
* [[sugar.presence.buddy]]
* [[sugar.presence.presenceservice]]

== Clipboard ==
* Notes on using [[GTK's Clipboard Module in Sugar]]

== Logging ==
* [[sugar.logger]]
* Notes on using [[Python Standard Logging in Sugar]]

== Internationalization ==
*[[Internationalization in Sugar]]

== Text and Graphics for Sugar Activities ==
* [[Pango]]

== Audio & Video ==
* [[Sugar Almanac GStreamer]]

== Mouse ==
=== How do I change the mouse cursor in my activity to the wait cursor? ===
In your activity subclass:

<pre>
self.window.set_cursor( gtk.gdk.Cursor(gtk.gdk.WATCH) )
</pre>

and to switch it back to the default:

<pre>
self.window.set_cursor( None );
</pre>

=== How do I track the position of the mouse? ===
There are many different reasons you might want to track the position of the mouse in your activity, ranging from the entertaining ([[http://en.wikipedia.org/wiki/Xeyes]]) to the functional (hiding certain windows when the mouse hasn't moved for a couple of seconds and making those ui elements re-appear when the mouse has moved again). Here is one way you can implement this functionality:

<pre>

...
self.hideWidgetsTime = time.time()
self.mx = -1
self.my = -1
self.HIDE_WIDGET_TIMEOUT_ID = gobject.timeout_add( 500, self.mouseMightHaveMovedCb )

def _mouseMightHaveMovedCb( self ):
x, y = self.get_pointer()
passedTime = 0

if (x != self.mx or y != self.my):
self.hideWidgetsTime = time.time()
if (self.hiddenWidgets):
self.showWidgets()
self.hiddenWidgets = False
else:
passedTime = time.time() - self.hideWidgetsTime

if (passedTime >= 3):
if (not self.hiddenWidgets):
self.hideWidgets()
self.hiddenWidgets = True

self.mx = x
self.my = y
return True

</pre>

== Miscellaneous==

The tasks below are random useful techniques that have come up as I write code and documentation for this reference. They have yet to be categorized, but will be as a sufficient set of related entries are written.

=== How do I know when my activity is "active" or not? ===

You can set an event using the VISIBILITY_NOTIFY_MASK constant in order to know when your activity changes visibility. Then in the callback for this event, you simply compare the event's state to gtk-defined variables for activity visibility. See the [http://www.pygtk.org/docs/pygtk/gdk-constants.html#gdk-visibility-state-constants GDK Visibility State Constants] section of gtk.gdk.Constants for more information.

<pre>
# Notify when the visibility state changes by calling self.__visibility_notify_cb
# (PUT THIS IN YOUR ACTIVITY CODE - EG. THE __init__() METHOD)
self.add_events(gtk.gdk.VISIBILITY_NOTIFY_MASK)
self.connect("visibility-notify-event", self.__visibility_notify_cb)
...
# Callback method for when the activity's visibility changes
def __visibility_notify_cb(self, window, event):
if event.state == gtk.gdk.VISIBILITY_FULLY_OBSCURED:
print "I am not visible"
elif event.state in [gtk.gdk.VISIBILITY_UNOBSCURED, gtk.gdk.VISIBILITY_PARTIAL]:
print "I am visible"
</pre>

=== How do I get the amount of free space available on disk under the /home directory tree? ===
The following function uses the [http://docs.python.org/lib/module-statvfs.html statvfs] module. The following code demonstrates how to get the total amount of free space under /home.

<pre>
#### Method: getFreespaceKb, returns the available freespace in kilobytes.
def getFreespaceKb(self):
stat = os.statvfs("/home")
freebytes = stat[statvfs.F_BSIZE] * stat[statvfs.F_BAVAIL]
freekb = freebytes / 1024
return freekb
</pre>

Note, however, that assuming anything about "/home" is a bad idea, better use os.environ['HOME'] instead. Rainbow will put your actual files elsewhere,
some on ramdisks, some on flash. Be clear about which filesystem's free space you actually care about.

=== How do I know whether my activity is running on a physical XO? ===
Sugar runs on ordinary computers as well as on XO's. While your activity is typically going to be run on a real XO, some people will indeed run it elsewhere. Normally you shouldn't write your activity to care whether it's on an XO or not. If for some odd reason, you need to care, the easiest way to tell if you are on a physical XO is to check whether /sys/power/olpc-pm, an essential power management file for the XO, exists. <ref>[http://lists.laptop.org/pipermail/devel/2008-June/015923.html reliably detecting if running on an XO]</ref> <ref>OLPC [[Power Management Interface]]</ref>

<pre>
import os
...
#Print out a boolean value that tells us whether we are on an XO or not.
print os.path.exists('/sys/power/olpc-pm')
</pre>

=== How do I know the current language setting on my XO? ===
The system variable 'LANG' tells you which language is currently active on the XO. The following code shows how to look at the value of this variable.

<pre>
import os
...
_logger.debug(os.environ['LANG'])
</pre>

=== How do I repeatedly call a specific method after N number of seconds? ===
The gobject.timeout_add() function allows you to invoke a callback method after a certain amount of time. If you want to repeatedly call a method, simply keep invoking the gobject.timeout_add function in your callback itself. The code below is a simple example, where the callback function is named repeatedly_call. Note that the timing of the callbacks are approximate. To get the process going, you should make an initial call to repeatedly_call() somewhere in your code.

You can see a more substantive example of this pattern in use when we [[Pango#How_do_I_dynamically_set_the_text_in_a_pango_layout.3F | regularly update the time displayed on a pango layout object]].

<pre>

#This method calls itself ROUGHLY every 1 second
def repeatedly_call(self):
now = datetime.datetime.now()
gobject.timeout_add(self.repeat_period_msec, self.repeatedly_update_time)
</pre>

=== How do I update the current build version of code that is running on my XO? ===

There are several pages that give you instructions on how to install/update your current build.

* If you already have a working build installed and an internet connection, first try [[olpc-update]].
* If that doesn't work, you can look at instructions for an [[Activated upgrade]] that can be done via USB] boot.

As the instructions on the pages linked above note, make sure to install your activities separately after you have upgraded to a specific base build.

=== I am developing on an XO laptop, but my keyboard and language settings are not ideal. How can I change them? ===

Internationalized laptops will often have settings that might slow you down while developing. To change around the language settings so you can better understand environment messages, use the [[Sugar Control Panel]]

Keyboard settings on internationalized laptops<ref>[[Keyboard layouts#OLPC keyboard layouts]]</ref> can also be suboptimal, especially as characters like "-" and "/" are in unfamiliar positions. You can use the <tt>setxkbmap</tt> command in the [[Terminal Activity]] to reset the type of keyboard input used and then attach a standard U.S. keyboard that will allow you to type normally. The command below sets the keyboard to the US mapping (it will reset to the default internationalized mapping upon restart).

setxkbmap us

=== My Python activity wants to use threads; how do I do that? ===

A question that has been answered with limited success is which threading patterns are most appropriate for use in Sugar. The following pattern of code to work fine in basic instances:

<pre>
#### Method: __init__, initialize this AnnotateActivity instance
def __init__(self, handle):
...
self.sample_thread = Thread(target=self.announce_thread, args=())
self.sample_thread.setDaemon(0)
self.sample_thread.start()
...

def announce_thread(self):
while (self.Running):
time.sleep(1)
print "thread running"
self._update_chat_text("Thread", "In here")
</pre>

This is the basic series of steps that most online documentation on python suggests to use when trying to work with threads in python. The problem is that it is unclear how this pattern relates to code that worked in the SimCity activity:

<pre>
import gobject
gobject.threads_init()
#import dbus.mainloop.glib
#dbus.mainloop.glib.threads_init()
</pre>

It should be noted that in the SimCity activity the pygame sound player would not produce sound reliably unless this setup was done.



Should the two patterns always be used in tandem? It seems that the latter code is mainly to initiate gobject and other libraries to work with threading, but it is unclear what restrictions there are with using threading with these libraries. Does one take precedence over the other? It is not clear if there is any problem with using the standard python threading code on the sugar technology stack.





In fact, experiments with threading on sugar leads to several different problems. For one thing, thread termination was tricky - using the can_close() method for sugar activities to terminate an activity only killed threads in some circumstances. It did not properly handle terminating threads in the case of CTRL-C or terminal interrupts. You can try to catch signals (SIGINT, SIGTERM or SIGHUP), but you will still be running in to errors in terminating child threads using these as well.





Another set of errors with threading comes up when trying to combine with stream tubes. The bottom line is that it is unclear what the scope of threading in a Sugar activity should be - should it simply work if you do the standard python threading pattern, is the use of the glib.threads_init and gobject.threads_init calls necessary, are there other interactions with threads and dbus that need to be accounted for? With more clarity from sugar developers on how the platform envisions threading to work in an activity, we can be more comfortable writing entries in the Almanac to help developers write error-free code.



=== How do I customize the title that is displayed for each instance of my activity? ===

By default, activity titles are just the generic activity names that you specify in your activity.info file. In some applications, you may want the activity title to be more dynamic.

For example, it makes sense to set the title for different browser sessions to the active web page being visited. That way, when you look back in the journal at the different browser sessions you have run in the previous few days, you can identify unique sessions based on the website you happened to be visiting at the time.

The code below shows how you can set the metadata for your activity to reflect a dynamic title based on whatever session criteria you feel is important. This example is adapted from the Browse activity, which sets activity instance titles based on the title of the current web page being visited.

<pre>
if self.metadata['mime_type'] == 'text/plain':
if not self._jobject.metadata['title_set_by_user'] == '1':
if self._browser.props.title:
# Set the title of this activity to be the current
# title of the page being visited by the browser.
self.metadata['title'] = self._browser.props.title
</pre>

=== What packages are available on sugar to support game development? ===

If your activity will require tools that are typically needed to develop robust and clean video games, then you should utilize the [http://www.pygame.org/ pygame package]. It can be readily imported into any activity:

<pre>
import pygame
...
</pre>

=== How do I detect when one of the game buttons on the laptop have been pressed? ===

The laptop game buttons (the circle, square, x, and check buttons next to the LCD) are encoded as page up, home, page down and end respectively. So, you can detect their press by listening for these specific events. For example, the code below listens for button presses and then just writes to an output widget which button was pressed.

<pre>
...
#### Initialize this activity.
def __init__(self, handle):
...
self.connect('key-press-event', self._keyPressCb)
...

#### Method _keyPressCb, which catches any presses of the game buttons.
def _keyPressCb(self, widget, event):

keyname = gtk.gdk.keyval_name(event.keyval)

if (keyname == 'KP_Page_Up'):
self._chat += "\nCircle Pressed!"
self._chat_buffer.set_text(self._chat)
elif (keyname == 'KP_Page_Down'):
self._chat += "\nX Pressed!"
self._chat_buffer.set_text(self._chat)
elif (keyname == 'KP_Home'):
self._chat += "\nSquare Pressed!"
self._chat_buffer.set_text(self._chat)
elif (keyname == 'KP_End'):
self._chat += "\nCheck Pressed!"
self._chat_buffer.set_text(self._chat)

return False;
</pre>

=== How do I detect if one of the joystick buttons has been pressed? ===

This is the same process as detecting game buttons, except with different names for the keys. Again, you listen for "key-press-event" signals and then in your callback you check to see if the pressed button was one of the joystick keys.

<pre>
#### Initialize this activity.
def __init__(self, handle):
...
self.connect('key-press-event', self._keyPressCb)
...

#### Method _keyPressCb, which catches any presses of the game buttons.
def _keyPressCb(self, widget, event):

keyname = gtk.gdk.keyval_name(event.keyval)

if (keyname == 'KP_Up'):
self._chat += "\nUp Pressed!"
self._chat_buffer.set_text(self._chat)
elif (keyname == 'KP_Down'):
self._chat += "\nDown Pressed!"
self._chat_buffer.set_text(self._chat)
elif (keyname == 'KP_Left'):
self._chat += "\nLeft Pressed!"
self._chat_buffer.set_text(self._chat)
elif (keyname == 'KP_Right'):
self._chat += "\nRight Pressed!"
self._chat_buffer.set_text(self._chat)

return False;
</pre>

== Notes ==
<references />

[[Category:Documentation]]

Development Team/Almanac

2008-11-24T22:47:16Z

Jedierikb: /* My Python activity wants to use threads; how do I do that? */

{{Sugar Almanac}}
{{Sugar Almanac TOC}}
== How do I get additional help beyond this almanac? ==
* Looking to get started with the basics of Sugar development? Check out Christoph Derndorfer's [http://www.olpcaustria.org/mediawiki/index.php/Activity_handbook Activity Handbook].
* See also [[Sugar Code Snippets]]

Now, on to the actual almanac ...

== Where can I see API changes? ==
API changes between OLPC releases can be seen here: [[API changes]]

== Getting Started ==
=== How do I structure my files so that they are a valid sugar activity? ===
Information on activity bundle structure can be found here: [[Activity bundles]]

=== How do I make an icon for my activity? ===
Information on what you need to do can be found here: [[Making Sugar Icons]]

== Package: sugar ==
* [[sugar.env]]
* [[sugar.profile]]
* [[sugar.mime]]
* [[sugar.logger]]

== Package: sugar.activity ==
* [[sugar.activity.activity]]
* [[sugar.activity.activityfactory]]
* [[sugar.activity.registry]]

== Package: sugar.datastore ==
* [[sugar.datastore.datastore]]

== Package: sugar.graphics ==
* [[sugar.graphics.alert]]
* [[sugar.graphics.icon]]
* [[sugar.graphics.notebook]]
* [[sugar.graphics.toolbutton]]
* [[sugar.graphics.toolbox]]
* [[sugar.graphics.style]]

== Package: sugar.presence ==
* [[sugar.presence]]
* [[sugar.presence.activity]]
* [[sugar.presence.buddy]]
* [[sugar.presence.presenceservice]]

== Clipboard ==
* Notes on using [[GTK's Clipboard Module in Sugar]]

== Logging ==
* [[sugar.logger]]
* Notes on using [[Python Standard Logging in Sugar]]

== Internationalization ==
*[[Internationalization in Sugar]]

== Text and Graphics for Sugar Activities ==
* [[Pango]]

== Audio & Video ==
* [[Sugar Almanac GStreamer]]

== Mouse ==
=== How do I change the mouse cursor in my activity to the wait cursor? ===
In your activity subclass:

<pre>
self.window.set_cursor( gtk.gdk.Cursor(gtk.gdk.WATCH) )
</pre>

and to switch it back to the default:

<pre>
self.window.set_cursor( None );
</pre>

=== How do I track the position of the mouse? ===
There are many different reasons you might want to track the position of the mouse in your activity, ranging from the entertaining ([[http://en.wikipedia.org/wiki/Xeyes]]) to the functional (hiding certain windows when the mouse hasn't moved for a couple of seconds and making those ui elements re-appear when the mouse has moved again). Here is one way you can implement this functionality:

<pre>

...
self.hideWidgetsTime = time.time()
self.mx = -1
self.my = -1
self.HIDE_WIDGET_TIMEOUT_ID = gobject.timeout_add( 500, self.mouseMightHaveMovedCb )

def _mouseMightHaveMovedCb( self ):
x, y = self.get_pointer()
passedTime = 0

if (x != self.mx or y != self.my):
self.hideWidgetsTime = time.time()
if (self.hiddenWidgets):
self.showWidgets()
self.hiddenWidgets = False
else:
passedTime = time.time() - self.hideWidgetsTime

if (passedTime >= 3):
if (not self.hiddenWidgets):
self.hideWidgets()
self.hiddenWidgets = True

self.mx = x
self.my = y
return True

</pre>

== Miscellaneous==

The tasks below are random useful techniques that have come up as I write code and documentation for this reference. They have yet to be categorized, but will be as a sufficient set of related entries are written.

=== How do I know when my activity is "active" or not? ===

You can set an event using the VISIBILITY_NOTIFY_MASK constant in order to know when your activity changes visibility. Then in the callback for this event, you simply compare the event's state to gtk-defined variables for activity visibility. See the [http://www.pygtk.org/docs/pygtk/gdk-constants.html#gdk-visibility-state-constants GDK Visibility State Constants] section of gtk.gdk.Constants for more information.

<pre>
# Notify when the visibility state changes by calling self.__visibility_notify_cb
# (PUT THIS IN YOUR ACTIVITY CODE - EG. THE __init__() METHOD)
self.add_events(gtk.gdk.VISIBILITY_NOTIFY_MASK)
self.connect("visibility-notify-event", self.__visibility_notify_cb)
...
# Callback method for when the activity's visibility changes
def __visibility_notify_cb(self, window, event):
if event.state == gtk.gdk.VISIBILITY_FULLY_OBSCURED:
print "I am not visible"
elif event.state in [gtk.gdk.VISIBILITY_UNOBSCURED, gtk.gdk.VISIBILITY_PARTIAL]:
print "I am visible"
</pre>

=== How do I get the amount of free space available on disk under the /home directory tree? ===
The following function uses the [http://docs.python.org/lib/module-statvfs.html statvfs] module. The following code demonstrates how to get the total amount of free space under /home.

<pre>
#### Method: getFreespaceKb, returns the available freespace in kilobytes.
def getFreespaceKb(self):
stat = os.statvfs("/home")
freebytes = stat[statvfs.F_BSIZE] * stat[statvfs.F_BAVAIL]
freekb = freebytes / 1024
return freekb
</pre>

Note, however, that assuming anything about "/home" is a bad idea, better use os.environ['HOME'] instead. Rainbow will put your actual files elsewhere,
some on ramdisks, some on flash. Be clear about which filesystem's free space you actually care about.

=== How do I know whether my activity is running on a physical XO? ===
Sugar runs on ordinary computers as well as on XO's. While your activity is typically going to be run on a real XO, some people will indeed run it elsewhere. Normally you shouldn't write your activity to care whether it's on an XO or not. If for some odd reason, you need to care, the easiest way to tell if you are on a physical XO is to check whether /sys/power/olpc-pm, an essential power management file for the XO, exists. <ref>[http://lists.laptop.org/pipermail/devel/2008-June/015923.html reliably detecting if running on an XO]</ref> <ref>OLPC [[Power Management Interface]]</ref>

<pre>
import os
...
#Print out a boolean value that tells us whether we are on an XO or not.
print os.path.exists('/sys/power/olpc-pm')
</pre>

=== How do I know the current language setting on my XO? ===
The system variable 'LANG' tells you which language is currently active on the XO. The following code shows how to look at the value of this variable.

<pre>
import os
...
_logger.debug(os.environ['LANG'])
</pre>

=== How do I repeatedly call a specific method after N number of seconds? ===
The gobject.timeout_add() function allows you to invoke a callback method after a certain amount of time. If you want to repeatedly call a method, simply keep invoking the gobject.timeout_add function in your callback itself. The code below is a simple example, where the callback function is named repeatedly_call. Note that the timing of the callbacks are approximate. To get the process going, you should make an initial call to repeatedly_call() somewhere in your code.

You can see a more substantive example of this pattern in use when we [[Pango#How_do_I_dynamically_set_the_text_in_a_pango_layout.3F | regularly update the time displayed on a pango layout object]].

<pre>

#This method calls itself ROUGHLY every 1 second
def repeatedly_call(self):
now = datetime.datetime.now()
gobject.timeout_add(self.repeat_period_msec, self.repeatedly_update_time)
</pre>

=== How do I update the current build version of code that is running on my XO? ===

There are several pages that give you instructions on how to install/update your current build.

* If you already have a working build installed and an internet connection, first try [[olpc-update]].
* If that doesn't work, you can look at instructions for an [[Activated upgrade]] that can be done via USB] boot.

As the instructions on the pages linked above note, make sure to install your activities separately after you have upgraded to a specific base build.

=== I am developing on an XO laptop, but my keyboard and language settings are not ideal. How can I change them? ===

Internationalized laptops will often have settings that might slow you down while developing. To change around the language settings so you can better understand environment messages, use the [[Sugar Control Panel]]

Keyboard settings on internationalized laptops<ref>[[Keyboard layouts#OLPC keyboard layouts]]</ref> can also be suboptimal, especially as characters like "-" and "/" are in unfamiliar positions. You can use the <tt>setxkbmap</tt> command in the [[Terminal Activity]] to reset the type of keyboard input used and then attach a standard U.S. keyboard that will allow you to type normally. The command below sets the keyboard to the US mapping (it will reset to the default internationalized mapping upon restart).

setxkbmap us

=== My Python activity wants to use threads; how do I do that? ===

A question that has been answered with limited success is which threading patterns are most appropriate for use in Sugar. The following pattern of code to work fine in basic instances:

<pre>
#### Method: __init__, initialize this AnnotateActivity instance
def __init__(self, handle):
...
self.sample_thread = Thread(target=self.announce_thread, args=())
self.sample_thread.setDaemon(0)
self.sample_thread.start()
...

def announce_thread(self):
while (self.Running):
time.sleep(1)
print "thread running"
self._update_chat_text("Thread", "In here")
</pre>

This is the basic series of steps that most online documentation on python suggests to use when trying to work with threads in python. The problem is that it is unclear how this pattern relates to code that worked in the SimCity activity:

<pre>
import gobject
gobject.threads_init()
#import dbus.mainloop.glib
#dbus.mainloop.glib.threads_init()
</pre>

It should be noted that in the SimCity activity the pygame sound player would not produce sound reliably unless this setup was done.



Should the two patterns always be used in tandem? It seems that the latter code is mainly to initiate gobject and other libraries to work with threading, but it is unclear what restrictions there are with using threading with these libraries. Does one take precedence over the other? It is not clear if there is any problem with using the standard python threading code on the sugar technology stack.





In fact, experiments with threading on sugar leads to several different problems. For one thing, thread termination was tricky - using the can_close() method for sugar activities to terminate an activity only killed threads in some circumstances. It did not properly handle terminating threads in the case of CTRL-C or terminal interrupts. You can try to catch signals (SIGINT, SIGTERM or SIGHUP), but you will still be running in to errors in terminating child threads using these as well.





Another set of errors with threading comes up when trying to combine with stream tubes. The bottom line is that it is unclear what the scope of threading in a Sugar activity should be - should it simply work if you do the standard python threading pattern, is the use of the glib.threads_init and gobject.threads_init calls necessary, are there other interactions with threads and dbus that need to be accounted for? With more clarity from sugar developers on how the platform envisions threading to work in an activity, we can be more comfortable writing entries in the Almanac to help developers write error-free code.

=== How do I customize the title that is displayed for each instance of my activity? ===

By default, activity titles are just the generic activity names that you specify in your activity.info file. In some applications, you may want the activity title to be more dynamic.

For example, it makes sense to set the title for different browser sessions to the active web page being visited. That way, when you look back in the journal at the different browser sessions you have run in the previous few days, you can identify unique sessions based on the website you happened to be visiting at the time.

The code below shows how you can set the metadata for your activity to reflect a dynamic title based on whatever session criteria you feel is important. This example is adapted from the Browse activity, which sets activity instance titles based on the title of the current web page being visited.

<pre>
if self.metadata['mime_type'] == 'text/plain':
if not self._jobject.metadata['title_set_by_user'] == '1':
if self._browser.props.title:
# Set the title of this activity to be the current
# title of the page being visited by the browser.
self.metadata['title'] = self._browser.props.title
</pre>

=== What packages are available on sugar to support game development? ===

If your activity will require tools that are typically needed to develop robust and clean video games, then you should utilize the [http://www.pygame.org/ pygame package]. It can be readily imported into any activity:

<pre>
import pygame
...
</pre>

=== How do I detect when one of the game buttons on the laptop have been pressed? ===

The laptop game buttons (the circle, square, x, and check buttons next to the LCD) are encoded as page up, home, page down and end respectively. So, you can detect their press by listening for these specific events. For example, the code below listens for button presses and then just writes to an output widget which button was pressed.

<pre>
...
#### Initialize this activity.
def __init__(self, handle):
...
self.connect('key-press-event', self._keyPressCb)
...

#### Method _keyPressCb, which catches any presses of the game buttons.
def _keyPressCb(self, widget, event):

keyname = gtk.gdk.keyval_name(event.keyval)

if (keyname == 'KP_Page_Up'):
self._chat += "\nCircle Pressed!"
self._chat_buffer.set_text(self._chat)
elif (keyname == 'KP_Page_Down'):
self._chat += "\nX Pressed!"
self._chat_buffer.set_text(self._chat)
elif (keyname == 'KP_Home'):
self._chat += "\nSquare Pressed!"
self._chat_buffer.set_text(self._chat)
elif (keyname == 'KP_End'):
self._chat += "\nCheck Pressed!"
self._chat_buffer.set_text(self._chat)

return False;
</pre>

=== How do I detect if one of the joystick buttons has been pressed? ===

This is the same process as detecting game buttons, except with different names for the keys. Again, you listen for "key-press-event" signals and then in your callback you check to see if the pressed button was one of the joystick keys.

<pre>
#### Initialize this activity.
def __init__(self, handle):
...
self.connect('key-press-event', self._keyPressCb)
...

#### Method _keyPressCb, which catches any presses of the game buttons.
def _keyPressCb(self, widget, event):

keyname = gtk.gdk.keyval_name(event.keyval)

if (keyname == 'KP_Up'):
self._chat += "\nUp Pressed!"
self._chat_buffer.set_text(self._chat)
elif (keyname == 'KP_Down'):
self._chat += "\nDown Pressed!"
self._chat_buffer.set_text(self._chat)
elif (keyname == 'KP_Left'):
self._chat += "\nLeft Pressed!"
self._chat_buffer.set_text(self._chat)
elif (keyname == 'KP_Right'):
self._chat += "\nRight Pressed!"
self._chat_buffer.set_text(self._chat)

return False;
</pre>

== Notes ==
<references />

[[Category:Documentation]]

Development Team/Almanac

2008-11-24T22:45:00Z

Jedierikb: /* My Python activity wants to use threads; how do I do that? */

{{Sugar Almanac}}
{{Sugar Almanac TOC}}
== How do I get additional help beyond this almanac? ==
* Looking to get started with the basics of Sugar development? Check out Christoph Derndorfer's [http://www.olpcaustria.org/mediawiki/index.php/Activity_handbook Activity Handbook].
* See also [[Sugar Code Snippets]]

Now, on to the actual almanac ...

== Where can I see API changes? ==
API changes between OLPC releases can be seen here: [[API changes]]

== Getting Started ==
=== How do I structure my files so that they are a valid sugar activity? ===
Information on activity bundle structure can be found here: [[Activity bundles]]

=== How do I make an icon for my activity? ===
Information on what you need to do can be found here: [[Making Sugar Icons]]

== Package: sugar ==
* [[sugar.env]]
* [[sugar.profile]]
* [[sugar.mime]]
* [[sugar.logger]]

== Package: sugar.activity ==
* [[sugar.activity.activity]]
* [[sugar.activity.activityfactory]]
* [[sugar.activity.registry]]

== Package: sugar.datastore ==
* [[sugar.datastore.datastore]]

== Package: sugar.graphics ==
* [[sugar.graphics.alert]]
* [[sugar.graphics.icon]]
* [[sugar.graphics.notebook]]
* [[sugar.graphics.toolbutton]]
* [[sugar.graphics.toolbox]]
* [[sugar.graphics.style]]

== Package: sugar.presence ==
* [[sugar.presence]]
* [[sugar.presence.activity]]
* [[sugar.presence.buddy]]
* [[sugar.presence.presenceservice]]

== Clipboard ==
* Notes on using [[GTK's Clipboard Module in Sugar]]

== Logging ==
* [[sugar.logger]]
* Notes on using [[Python Standard Logging in Sugar]]

== Internationalization ==
*[[Internationalization in Sugar]]

== Text and Graphics for Sugar Activities ==
* [[Pango]]

== Audio & Video ==
* [[Sugar Almanac GStreamer]]

== Mouse ==
=== How do I change the mouse cursor in my activity to the wait cursor? ===
In your activity subclass:

<pre>
self.window.set_cursor( gtk.gdk.Cursor(gtk.gdk.WATCH) )
</pre>

and to switch it back to the default:

<pre>
self.window.set_cursor( None );
</pre>

=== How do I track the position of the mouse? ===
There are many different reasons you might want to track the position of the mouse in your activity, ranging from the entertaining ([[http://en.wikipedia.org/wiki/Xeyes]]) to the functional (hiding certain windows when the mouse hasn't moved for a couple of seconds and making those ui elements re-appear when the mouse has moved again). Here is one way you can implement this functionality:

<pre>

...
self.hideWidgetsTime = time.time()
self.mx = -1
self.my = -1
self.HIDE_WIDGET_TIMEOUT_ID = gobject.timeout_add( 500, self.mouseMightHaveMovedCb )

def _mouseMightHaveMovedCb( self ):
x, y = self.get_pointer()
passedTime = 0

if (x != self.mx or y != self.my):
self.hideWidgetsTime = time.time()
if (self.hiddenWidgets):
self.showWidgets()
self.hiddenWidgets = False
else:
passedTime = time.time() - self.hideWidgetsTime

if (passedTime >= 3):
if (not self.hiddenWidgets):
self.hideWidgets()
self.hiddenWidgets = True

self.mx = x
self.my = y
return True

</pre>

== Miscellaneous==

The tasks below are random useful techniques that have come up as I write code and documentation for this reference. They have yet to be categorized, but will be as a sufficient set of related entries are written.

=== How do I know when my activity is "active" or not? ===

You can set an event using the VISIBILITY_NOTIFY_MASK constant in order to know when your activity changes visibility. Then in the callback for this event, you simply compare the event's state to gtk-defined variables for activity visibility. See the [http://www.pygtk.org/docs/pygtk/gdk-constants.html#gdk-visibility-state-constants GDK Visibility State Constants] section of gtk.gdk.Constants for more information.

<pre>
# Notify when the visibility state changes by calling self.__visibility_notify_cb
# (PUT THIS IN YOUR ACTIVITY CODE - EG. THE __init__() METHOD)
self.add_events(gtk.gdk.VISIBILITY_NOTIFY_MASK)
self.connect("visibility-notify-event", self.__visibility_notify_cb)
...
# Callback method for when the activity's visibility changes
def __visibility_notify_cb(self, window, event):
if event.state == gtk.gdk.VISIBILITY_FULLY_OBSCURED:
print "I am not visible"
elif event.state in [gtk.gdk.VISIBILITY_UNOBSCURED, gtk.gdk.VISIBILITY_PARTIAL]:
print "I am visible"
</pre>

=== How do I get the amount of free space available on disk under the /home directory tree? ===
The following function uses the [http://docs.python.org/lib/module-statvfs.html statvfs] module. The following code demonstrates how to get the total amount of free space under /home.

<pre>
#### Method: getFreespaceKb, returns the available freespace in kilobytes.
def getFreespaceKb(self):
stat = os.statvfs("/home")
freebytes = stat[statvfs.F_BSIZE] * stat[statvfs.F_BAVAIL]
freekb = freebytes / 1024
return freekb
</pre>

Note, however, that assuming anything about "/home" is a bad idea, better use os.environ['HOME'] instead. Rainbow will put your actual files elsewhere,
some on ramdisks, some on flash. Be clear about which filesystem's free space you actually care about.

=== How do I know whether my activity is running on a physical XO? ===
Sugar runs on ordinary computers as well as on XO's. While your activity is typically going to be run on a real XO, some people will indeed run it elsewhere. Normally you shouldn't write your activity to care whether it's on an XO or not. If for some odd reason, you need to care, the easiest way to tell if you are on a physical XO is to check whether /sys/power/olpc-pm, an essential power management file for the XO, exists. <ref>[http://lists.laptop.org/pipermail/devel/2008-June/015923.html reliably detecting if running on an XO]</ref> <ref>OLPC [[Power Management Interface]]</ref>

<pre>
import os
...
#Print out a boolean value that tells us whether we are on an XO or not.
print os.path.exists('/sys/power/olpc-pm')
</pre>

=== How do I know the current language setting on my XO? ===
The system variable 'LANG' tells you which language is currently active on the XO. The following code shows how to look at the value of this variable.

<pre>
import os
...
_logger.debug(os.environ['LANG'])
</pre>

=== How do I repeatedly call a specific method after N number of seconds? ===
The gobject.timeout_add() function allows you to invoke a callback method after a certain amount of time. If you want to repeatedly call a method, simply keep invoking the gobject.timeout_add function in your callback itself. The code below is a simple example, where the callback function is named repeatedly_call. Note that the timing of the callbacks are approximate. To get the process going, you should make an initial call to repeatedly_call() somewhere in your code.

You can see a more substantive example of this pattern in use when we [[Pango#How_do_I_dynamically_set_the_text_in_a_pango_layout.3F | regularly update the time displayed on a pango layout object]].

<pre>

#This method calls itself ROUGHLY every 1 second
def repeatedly_call(self):
now = datetime.datetime.now()
gobject.timeout_add(self.repeat_period_msec, self.repeatedly_update_time)
</pre>

=== How do I update the current build version of code that is running on my XO? ===

There are several pages that give you instructions on how to install/update your current build.

* If you already have a working build installed and an internet connection, first try [[olpc-update]].
* If that doesn't work, you can look at instructions for an [[Activated upgrade]] that can be done via USB] boot.

As the instructions on the pages linked above note, make sure to install your activities separately after you have upgraded to a specific base build.

=== I am developing on an XO laptop, but my keyboard and language settings are not ideal. How can I change them? ===

Internationalized laptops will often have settings that might slow you down while developing. To change around the language settings so you can better understand environment messages, use the [[Sugar Control Panel]]

Keyboard settings on internationalized laptops<ref>[[Keyboard layouts#OLPC keyboard layouts]]</ref> can also be suboptimal, especially as characters like "-" and "/" are in unfamiliar positions. You can use the <tt>setxkbmap</tt> command in the [[Terminal Activity]] to reset the type of keyboard input used and then attach a standard U.S. keyboard that will allow you to type normally. The command below sets the keyboard to the US mapping (it will reset to the default internationalized mapping upon restart).

setxkbmap us

=== My Python activity wants to use threads; how do I do that? ===

A question that has been answered with limited success is which threading patterns are most appropriate for use in Sugar. The following pattern of code to work fine in basic instances:

<pre>
#### Method: __init__, initialize this AnnotateActivity instance
def __init__(self, handle):
...
self.sample_thread = Thread(target=self.announce_thread, args=())
self.sample_thread.setDaemon(0)
self.sample_thread.start()
...

def announce_thread(self):
while (self.Running):
time.sleep(1)
print "thread running"
self._update_chat_text("Thread", "In here")
</pre>

This is the basic series of steps that most online documentation on python suggests to use when trying to work with threads in python. The problem is that it is unclear how this pattern relates to code that worked in the SimCity activity:

<pre>
import gobject
gobject.threads_init()
#import dbus.mainloop.glib
#dbus.mainloop.glib.threads_init()
</pre>

It should be noted that in the SimCity activity the pygame sound player would not produce sound reliably unless this setup was done.



Should the two patterns always be used in tandem? It seems that the latter code is mainly to initiate gobject and other libraries to work with threading, but it is unclear what restrictions there are with using threading with these libraries. Does one take precedence over the other? It is not clear if there is any problem with using the standard python threading code on the sugar technology stack.



In fact, experiments with threading on sugar leads to several different problems. For one thing, thread termination was tricky - using the can_close() method for sugar activities to terminate an activity only killed threads in some circumstances. It did not properly handle terminating threads in the case of CTRL-C or terminal interrupts. You can try to catch signals (SIGINT, SIGTERM or SIGHUP), but you will still be running in to errors in terminating child threads using these as well.



Another set of errors with threading comes up when trying to combine with stream tubes. The bottom line is that it is unclear what the scope of threading in a Sugar activity should be - should it simply work if you do the standard python threading pattern, is the use of the glib.threads_init and gobject.threads_init calls necessary, are there other interactions with threads and dbus that need to be accounted for? With more clarity from sugar developers on how the platform envisions threading to work in an activity, we can be more comfortable writing entries in the Almanac to help developers write error-free code.

=== How do I customize the title that is displayed for each instance of my activity? ===

By default, activity titles are just the generic activity names that you specify in your activity.info file. In some applications, you may want the activity title to be more dynamic.

For example, it makes sense to set the title for different browser sessions to the active web page being visited. That way, when you look back in the journal at the different browser sessions you have run in the previous few days, you can identify unique sessions based on the website you happened to be visiting at the time.

The code below shows how you can set the metadata for your activity to reflect a dynamic title based on whatever session criteria you feel is important. This example is adapted from the Browse activity, which sets activity instance titles based on the title of the current web page being visited.

<pre>
if self.metadata['mime_type'] == 'text/plain':
if not self._jobject.metadata['title_set_by_user'] == '1':
if self._browser.props.title:
# Set the title of this activity to be the current
# title of the page being visited by the browser.
self.metadata['title'] = self._browser.props.title
</pre>

=== What packages are available on sugar to support game development? ===

If your activity will require tools that are typically needed to develop robust and clean video games, then you should utilize the [http://www.pygame.org/ pygame package]. It can be readily imported into any activity:

<pre>
import pygame
...
</pre>

=== How do I detect when one of the game buttons on the laptop have been pressed? ===

The laptop game buttons (the circle, square, x, and check buttons next to the LCD) are encoded as page up, home, page down and end respectively. So, you can detect their press by listening for these specific events. For example, the code below listens for button presses and then just writes to an output widget which button was pressed.

<pre>
...
#### Initialize this activity.
def __init__(self, handle):
...
self.connect('key-press-event', self._keyPressCb)
...

#### Method _keyPressCb, which catches any presses of the game buttons.
def _keyPressCb(self, widget, event):

keyname = gtk.gdk.keyval_name(event.keyval)

if (keyname == 'KP_Page_Up'):
self._chat += "\nCircle Pressed!"
self._chat_buffer.set_text(self._chat)
elif (keyname == 'KP_Page_Down'):
self._chat += "\nX Pressed!"
self._chat_buffer.set_text(self._chat)
elif (keyname == 'KP_Home'):
self._chat += "\nSquare Pressed!"
self._chat_buffer.set_text(self._chat)
elif (keyname == 'KP_End'):
self._chat += "\nCheck Pressed!"
self._chat_buffer.set_text(self._chat)

return False;
</pre>

=== How do I detect if one of the joystick buttons has been pressed? ===

This is the same process as detecting game buttons, except with different names for the keys. Again, you listen for "key-press-event" signals and then in your callback you check to see if the pressed button was one of the joystick keys.

<pre>
#### Initialize this activity.
def __init__(self, handle):
...
self.connect('key-press-event', self._keyPressCb)
...

#### Method _keyPressCb, which catches any presses of the game buttons.
def _keyPressCb(self, widget, event):

keyname = gtk.gdk.keyval_name(event.keyval)

if (keyname == 'KP_Up'):
self._chat += "\nUp Pressed!"
self._chat_buffer.set_text(self._chat)
elif (keyname == 'KP_Down'):
self._chat += "\nDown Pressed!"
self._chat_buffer.set_text(self._chat)
elif (keyname == 'KP_Left'):
self._chat += "\nLeft Pressed!"
self._chat_buffer.set_text(self._chat)
elif (keyname == 'KP_Right'):
self._chat += "\nRight Pressed!"
self._chat_buffer.set_text(self._chat)

return False;
</pre>

== Notes ==
<references />

[[Category:Documentation]]

Development Team/Almanac

2008-11-24T22:44:33Z

Jedierikb: /* Miscellaneous */

{{Sugar Almanac}}
{{Sugar Almanac TOC}}
== How do I get additional help beyond this almanac? ==
* Looking to get started with the basics of Sugar development? Check out Christoph Derndorfer's [http://www.olpcaustria.org/mediawiki/index.php/Activity_handbook Activity Handbook].
* See also [[Sugar Code Snippets]]

Now, on to the actual almanac ...

== Where can I see API changes? ==
API changes between OLPC releases can be seen here: [[API changes]]

== Getting Started ==
=== How do I structure my files so that they are a valid sugar activity? ===
Information on activity bundle structure can be found here: [[Activity bundles]]

=== How do I make an icon for my activity? ===
Information on what you need to do can be found here: [[Making Sugar Icons]]

== Package: sugar ==
* [[sugar.env]]
* [[sugar.profile]]
* [[sugar.mime]]
* [[sugar.logger]]

== Package: sugar.activity ==
* [[sugar.activity.activity]]
* [[sugar.activity.activityfactory]]
* [[sugar.activity.registry]]

== Package: sugar.datastore ==
* [[sugar.datastore.datastore]]

== Package: sugar.graphics ==
* [[sugar.graphics.alert]]
* [[sugar.graphics.icon]]
* [[sugar.graphics.notebook]]
* [[sugar.graphics.toolbutton]]
* [[sugar.graphics.toolbox]]
* [[sugar.graphics.style]]

== Package: sugar.presence ==
* [[sugar.presence]]
* [[sugar.presence.activity]]
* [[sugar.presence.buddy]]
* [[sugar.presence.presenceservice]]

== Clipboard ==
* Notes on using [[GTK's Clipboard Module in Sugar]]

== Logging ==
* [[sugar.logger]]
* Notes on using [[Python Standard Logging in Sugar]]

== Internationalization ==
*[[Internationalization in Sugar]]

== Text and Graphics for Sugar Activities ==
* [[Pango]]

== Audio & Video ==
* [[Sugar Almanac GStreamer]]

== Mouse ==
=== How do I change the mouse cursor in my activity to the wait cursor? ===
In your activity subclass:

<pre>
self.window.set_cursor( gtk.gdk.Cursor(gtk.gdk.WATCH) )
</pre>

and to switch it back to the default:

<pre>
self.window.set_cursor( None );
</pre>

=== How do I track the position of the mouse? ===
There are many different reasons you might want to track the position of the mouse in your activity, ranging from the entertaining ([[http://en.wikipedia.org/wiki/Xeyes]]) to the functional (hiding certain windows when the mouse hasn't moved for a couple of seconds and making those ui elements re-appear when the mouse has moved again). Here is one way you can implement this functionality:

<pre>

...
self.hideWidgetsTime = time.time()
self.mx = -1
self.my = -1
self.HIDE_WIDGET_TIMEOUT_ID = gobject.timeout_add( 500, self.mouseMightHaveMovedCb )

def _mouseMightHaveMovedCb( self ):
x, y = self.get_pointer()
passedTime = 0

if (x != self.mx or y != self.my):
self.hideWidgetsTime = time.time()
if (self.hiddenWidgets):
self.showWidgets()
self.hiddenWidgets = False
else:
passedTime = time.time() - self.hideWidgetsTime

if (passedTime >= 3):
if (not self.hiddenWidgets):
self.hideWidgets()
self.hiddenWidgets = True

self.mx = x
self.my = y
return True

</pre>

== Miscellaneous==

The tasks below are random useful techniques that have come up as I write code and documentation for this reference. They have yet to be categorized, but will be as a sufficient set of related entries are written.

=== How do I know when my activity is "active" or not? ===

You can set an event using the VISIBILITY_NOTIFY_MASK constant in order to know when your activity changes visibility. Then in the callback for this event, you simply compare the event's state to gtk-defined variables for activity visibility. See the [http://www.pygtk.org/docs/pygtk/gdk-constants.html#gdk-visibility-state-constants GDK Visibility State Constants] section of gtk.gdk.Constants for more information.

<pre>
# Notify when the visibility state changes by calling self.__visibility_notify_cb
# (PUT THIS IN YOUR ACTIVITY CODE - EG. THE __init__() METHOD)
self.add_events(gtk.gdk.VISIBILITY_NOTIFY_MASK)
self.connect("visibility-notify-event", self.__visibility_notify_cb)
...
# Callback method for when the activity's visibility changes
def __visibility_notify_cb(self, window, event):
if event.state == gtk.gdk.VISIBILITY_FULLY_OBSCURED:
print "I am not visible"
elif event.state in [gtk.gdk.VISIBILITY_UNOBSCURED, gtk.gdk.VISIBILITY_PARTIAL]:
print "I am visible"
</pre>

=== How do I get the amount of free space available on disk under the /home directory tree? ===
The following function uses the [http://docs.python.org/lib/module-statvfs.html statvfs] module. The following code demonstrates how to get the total amount of free space under /home.

<pre>
#### Method: getFreespaceKb, returns the available freespace in kilobytes.
def getFreespaceKb(self):
stat = os.statvfs("/home")
freebytes = stat[statvfs.F_BSIZE] * stat[statvfs.F_BAVAIL]
freekb = freebytes / 1024
return freekb
</pre>

Note, however, that assuming anything about "/home" is a bad idea, better use os.environ['HOME'] instead. Rainbow will put your actual files elsewhere,
some on ramdisks, some on flash. Be clear about which filesystem's free space you actually care about.

=== How do I know whether my activity is running on a physical XO? ===
Sugar runs on ordinary computers as well as on XO's. While your activity is typically going to be run on a real XO, some people will indeed run it elsewhere. Normally you shouldn't write your activity to care whether it's on an XO or not. If for some odd reason, you need to care, the easiest way to tell if you are on a physical XO is to check whether /sys/power/olpc-pm, an essential power management file for the XO, exists. <ref>[http://lists.laptop.org/pipermail/devel/2008-June/015923.html reliably detecting if running on an XO]</ref> <ref>OLPC [[Power Management Interface]]</ref>

<pre>
import os
...
#Print out a boolean value that tells us whether we are on an XO or not.
print os.path.exists('/sys/power/olpc-pm')
</pre>

=== How do I know the current language setting on my XO? ===
The system variable 'LANG' tells you which language is currently active on the XO. The following code shows how to look at the value of this variable.

<pre>
import os
...
_logger.debug(os.environ['LANG'])
</pre>

=== How do I repeatedly call a specific method after N number of seconds? ===
The gobject.timeout_add() function allows you to invoke a callback method after a certain amount of time. If you want to repeatedly call a method, simply keep invoking the gobject.timeout_add function in your callback itself. The code below is a simple example, where the callback function is named repeatedly_call. Note that the timing of the callbacks are approximate. To get the process going, you should make an initial call to repeatedly_call() somewhere in your code.

You can see a more substantive example of this pattern in use when we [[Pango#How_do_I_dynamically_set_the_text_in_a_pango_layout.3F | regularly update the time displayed on a pango layout object]].

<pre>

#This method calls itself ROUGHLY every 1 second
def repeatedly_call(self):
now = datetime.datetime.now()
gobject.timeout_add(self.repeat_period_msec, self.repeatedly_update_time)
</pre>

=== How do I update the current build version of code that is running on my XO? ===

There are several pages that give you instructions on how to install/update your current build.

* If you already have a working build installed and an internet connection, first try [[olpc-update]].
* If that doesn't work, you can look at instructions for an [[Activated upgrade]] that can be done via USB] boot.

As the instructions on the pages linked above note, make sure to install your activities separately after you have upgraded to a specific base build.

=== I am developing on an XO laptop, but my keyboard and language settings are not ideal. How can I change them? ===

Internationalized laptops will often have settings that might slow you down while developing. To change around the language settings so you can better understand environment messages, use the [[Sugar Control Panel]]

Keyboard settings on internationalized laptops<ref>[[Keyboard layouts#OLPC keyboard layouts]]</ref> can also be suboptimal, especially as characters like "-" and "/" are in unfamiliar positions. You can use the <tt>setxkbmap</tt> command in the [[Terminal Activity]] to reset the type of keyboard input used and then attach a standard U.S. keyboard that will allow you to type normally. The command below sets the keyboard to the US mapping (it will reset to the default internationalized mapping upon restart).

setxkbmap us

=== My Python activity wants to use threads; how do I do that? ===

A question that has been answered with limited success is which threading patterns are most appropriate for use in Sugar. The following pattern of code to work fine in basic instances:

<pre>
#### Method: __init__, initialize this AnnotateActivity instance
def __init__(self, handle):
...
self.sample_thread = Thread(target=self.announce_thread, args=())
self.sample_thread.setDaemon(0)
self.sample_thread.start()
...

def announce_thread(self):
while (self.Running):
time.sleep(1)
print "thread running"
self._update_chat_text("Thread", "In here")
</pre>

This is the basic series of steps that most online documentation on python suggests to use when trying to work with threads in python. The problem is that it is unclear how this pattern relates to code that worked in the SimCity activity:

<pre>
import gobject
gobject.threads_init()
#import dbus.mainloop.glib
#dbus.mainloop.glib.threads_init()
</pre>

It should be noted that in the SimCity activity the pygame sound player would not produce sound reliably unless this setup was done.



Should the two patterns always be used in tandem? It seems that the latter code is mainly to initiate gobject and other libraries to work with threading, but it is unclear what restrictions there are with using threading with these libraries. Does one take precedence over the other? It is not clear if there is any problem with using the standard python threading code on the sugar technology stack.



In fact, experiments with threading on sugar leads to several different problems. For one thing, thread termination was tricky - using the can_close() method for sugar activities to terminate an activity only killed threads in some circumstances. It did not properly handle terminating threads in the case of CTRL-C or terminal interrupts. You can try to catch signals (SIGINT, SIGTERM or SIGHUP), but you will still be running in to errors in terminating child threads using these as well.



Another set of errors with threading comes up when trying to combine with stream tubes. The bottom line is that it is unclear what the scope of threading in a Sugar activity should be - should it simply work if you do the standard python threading pattern, is the use of the glib.threads_init and gobject.threads_init calls necessary, are there other interactions with threads and dbus that need to be accounted for? With more clarity from sugar developers on how the platform envisions threading to work in an activity, we can be more comfortable writing entries in the Almanac to help developers write error-free code.

=== How do I customize the title that is displayed for each instance of my activity? ===

By default, activity titles are just the generic activity names that you specify in your activity.info file. In some applications, you may want the activity title to be more dynamic.

For example, it makes sense to set the title for different browser sessions to the active web page being visited. That way, when you look back in the journal at the different browser sessions you have run in the previous few days, you can identify unique sessions based on the website you happened to be visiting at the time.

The code below shows how you can set the metadata for your activity to reflect a dynamic title based on whatever session criteria you feel is important. This example is adapted from the Browse activity, which sets activity instance titles based on the title of the current web page being visited.

<pre>
if self.metadata['mime_type'] == 'text/plain':
if not self._jobject.metadata['title_set_by_user'] == '1':
if self._browser.props.title:
# Set the title of this activity to be the current
# title of the page being visited by the browser.
self.metadata['title'] = self._browser.props.title
</pre>

=== What packages are available on sugar to support game development? ===

If your activity will require tools that are typically needed to develop robust and clean video games, then you should utilize the [http://www.pygame.org/ pygame package]. It can be readily imported into any activity:

<pre>
import pygame
...
</pre>

=== How do I detect when one of the game buttons on the laptop have been pressed? ===

The laptop game buttons (the circle, square, x, and check buttons next to the LCD) are encoded as page up, home, page down and end respectively. So, you can detect their press by listening for these specific events. For example, the code below listens for button presses and then just writes to an output widget which button was pressed.

<pre>
...
#### Initialize this activity.
def __init__(self, handle):
...
self.connect('key-press-event', self._keyPressCb)
...

#### Method _keyPressCb, which catches any presses of the game buttons.
def _keyPressCb(self, widget, event):

keyname = gtk.gdk.keyval_name(event.keyval)

if (keyname == 'KP_Page_Up'):
self._chat += "\nCircle Pressed!"
self._chat_buffer.set_text(self._chat)
elif (keyname == 'KP_Page_Down'):
self._chat += "\nX Pressed!"
self._chat_buffer.set_text(self._chat)
elif (keyname == 'KP_Home'):
self._chat += "\nSquare Pressed!"
self._chat_buffer.set_text(self._chat)
elif (keyname == 'KP_End'):
self._chat += "\nCheck Pressed!"
self._chat_buffer.set_text(self._chat)

return False;
</pre>

=== How do I detect if one of the joystick buttons has been pressed? ===

This is the same process as detecting game buttons, except with different names for the keys. Again, you listen for "key-press-event" signals and then in your callback you check to see if the pressed button was one of the joystick keys.

<pre>
#### Initialize this activity.
def __init__(self, handle):
...
self.connect('key-press-event', self._keyPressCb)
...

#### Method _keyPressCb, which catches any presses of the game buttons.
def _keyPressCb(self, widget, event):

keyname = gtk.gdk.keyval_name(event.keyval)

if (keyname == 'KP_Up'):
self._chat += "\nUp Pressed!"
self._chat_buffer.set_text(self._chat)
elif (keyname == 'KP_Down'):
self._chat += "\nDown Pressed!"
self._chat_buffer.set_text(self._chat)
elif (keyname == 'KP_Left'):
self._chat += "\nLeft Pressed!"
self._chat_buffer.set_text(self._chat)
elif (keyname == 'KP_Right'):
self._chat += "\nRight Pressed!"
self._chat_buffer.set_text(self._chat)

return False;
</pre>

== Notes ==
<references />

[[Category:Documentation]]

Development Team/Almanac/Sugar.presence

2008-11-24T22:09:48Z

Jedierikb: /* I can't get tubes to work. Are there unresolved issues? */

Development Team/Almanac/Sugar.presence

2008-11-24T22:08:20Z

Jedierikb: new heading for unanswered

Marketing Team/Events/Sugarcamp Boston 2008/hackathon

2008-11-18T03:47:41Z

Jedierikb: adding myself to attendees

== Details ==

* Monday, November 17, 2008
* 6:30pm - 10pm (we will order food together at the beginning; bring your own $ for dinner)
* One Broadway, Cambridge MA 02142 (at the corner of Broadway and 3rd, by the Kendall T stop)
* Call [[User:Mchua|Mel Chua]] to be let in when you arrive - 847.970.8484

== About ==

=== For developers ===

This is a "new Sugar coders hackfest" evening, where people can come to learn about making Activities - bring a project you want to work on, and we'll have people from the core Sugar team around to help, teach, answer questions, run impromptu tutorials, and make tools/patches as needed to ease the entry route for new coders.

=== For non-developers ===

We're also looking for people who ''won't'' be coding that night to sprint with David Farning on community infrastructure setup. Problems to tackle include building a Newbie Welcome Wagon package, handling [http://dev.laptop.org/ticket/8630 licensing] of both content and Activity bundles, documentation and testing systems, and more.

== Attendees ==

Sign up if you're coming, so we know how many to expect- tentatives and drop-ins are ok, but make things much harder to plan for. Also let us know (in parentheses) what you'll be doing!

* Marco (on-site mentor, Sugar Activity development)
* Tomeu (on-site mentor, Sugar Activity development)
* [[User:Dfarning|Dfarning]] (on-site mentor, infrastructure and documentation)
* [[User:Mchua|Mchua]] (hackathon coordinator, working on Larry, a language-learning Activity)
* Yifan + others from Olin, may drop by to check things out
* Owen Williams (PenguinTV, may be a little late)
* Tom Boyle (StarChart, focusing on localization)
* [[User:Wade|Wade]] (Sugar Activity development)
* Brian Jordan (Sugar Activity development, Pippy love)
* Amanda Peyton (MIT Sloan project looking at the SugarLabs organizational structure)
* Ryan Kabir (new development contributor to Sugar, looking for a place to start)
* Brendan Powers (new contributor,looking for something simple to get used to the project)
* Chris Ball (from 7:30)
* Erik Blankinship (updating the Map Activity)

== Stuff to hack on ==

* Spreadsheet activity: http://lists.laptop.org/pipermail/sugar/2008-February/004225.html
* Mind mapping activity: http://lists.laptop.org/pipermail/olpc-sur/2008-November/001173.html
* Make the Sugar shell react to changes in the ~/Activities dir using inotify.
* A quiz game with competitive collaboration (cjb) -- e.g. generate arithmetic problems, have a shared countdown, and then the first person to answer correctly gets the most points. Generalizable to quizes about non-math stuff too.

== To do ==

Let [[User:Mchua|Mchua]] (mel at laptop dot org) know if you can help!

* <s>Get a location with wifi, projectors, and ready access to food (which probably means "order pizza, then ask everyone if they can chip in a few dollars when it comes).</s>
* <s>make invitations and send them out</s>
* <s>find some way to make nametags for everybody</s> (Actually, we probably won't need these - we're small enough.)
* make sure that the location gets set up (chairs, tables, etc.) and taken down/cleaned-up afterwards
* send thank-you follow up emails after the event encouraging people to come to the rest of Sugarcamp

Development Team/Almanac/GStreamer

2008-10-03T15:55:40Z

Jedierikb: /* How can I add play/pause buttons and a scrubber to my audio or video? */

{{Sugar Almanac}}

=== Where can I get additional resources and sample code on using the camera? ===
* [[Programming_the_camera]]

=== How can I embed video files in my activity? ===
Sugar, by default, can play back audio (encoded in Vorbis) and video (encoded in Theora) files in ogg containers.

The following file will be helpful for embedding video or audio files into your activity. After the code posting is a code snippet showing how to use this.

<pre>
import gtk
import pygtk
pygtk.require('2.0')
import sys
import pygst
pygst.require('0.10')
import gst
import gst.interfaces
import gobject
import time
gobject.threads_init()

class Gplay:

def __init__(self):
self.window = None
self.playing = False

self.player = gst.element_factory_make("playbin", "playbin")
xis = gst.element_factory_make("xvimagesink", "xvimagesink")
self.player.set_property("video-sink", xis)
bus = self.player.get_bus()
bus.enable_sync_message_emission()
bus.add_signal_watch()
self.SYNC_ID = bus.connect('sync-message::element', self._onSyncMessageCb)

def _onSyncMessageCb(self, bus, message):
if message.structure is None:
return True
if message.structure.get_name() == 'prepare-xwindow-id':
self.window.set_sink(message.src)
message.src.set_property('force-aspect-ratio', True)
return True

def setFile(self, path):
uri = "file://" + str( path )
if (self.player.get_property('uri') == uri):
self.seek(gst.SECOND*0)
return

self.player.set_state(gst.STATE_READY)
self.player.set_property('uri', uri)
ext = uri[len(uri)-3:]
if (ext == "jpg"):
self.pause()
else:
self.play()

def queryPosition(self):
#"Returns a (position, duration) tuple"
try:
position, format = self.player.query_position(gst.FORMAT_TIME)
except:
position = gst.CLOCK_TIME_NONE

try:
duration, format = self.player.query_duration(gst.FORMAT_TIME)
except:
duration = gst.CLOCK_TIME_NONE

return (position, duration)

def seek(self, time):
event = gst.event_new_seek(1.0, gst.FORMAT_TIME, gst.SEEK_FLAG_FLUSH | gst.SEEK_FLAG_ACCURATE, gst.SEEK_TYPE_SET, time, gst.SEEK_TYPE_NONE, 0)
res = self.player.send_event(event)
if res:
self.player.set_new_stream_time(0L)

def pause(self):
self.playing = False
self.player.set_state(gst.STATE_PAUSED)

def play(self):
self.playing = True
self.player.set_state(gst.STATE_PLAYING)

def stop(self):
self.playing = False
self.player.set_state(gst.STATE_NULL)
self.nextMovie()

def get_state(self, timeout=1):
return self.player.get_state(timeout=timeout)

def is_playing(self):
return self.playing

class PlayVideoWindow(gtk.Window):
def __init__(self):
gtk.Window.__init__(self)

self.imagesink = None
self.unset_flags(gtk.DOUBLE_BUFFERED)
self.set_flags(gtk.APP_PAINTABLE)

def set_sink(self, sink):
if (self.imagesink != None):
assert self.window.xid
self.imagesink = None
del self.imagesink

self.imagesink = sink
self.imagesink.set_xwindow_id(self.window.xid)

</pre>

And here is a code snippet showing how you would use this file to embed media playback in your activity:

<pre>
#this is our video playback window
self.gplay = Gplay( )
self.gplayWin = PlayVideoWindow( )
self.gplay.window = self.gplayWin

self.gplayWin.set_type_hint( gtk.gdk.WINDOW_TYPE_HINT_DIALOG )
self.gplayWin.set_decorated( False )
self.gplayWin.set_transient_for( self ) #activity subclass
self.gplayWin.move( 100, 100 )
self.gplayWin.resize( 300, 400 )
self.gplayWin.show_all( )
</pre>

=== How can I add play/pause buttons and a scrubber to my audio or video? ===

The widget below is pre-configured to work with the gplay class above. This widget takes two gtk.Images in its constructor.

<pre>
import gtk
import pygtk
pygtk.require('2.0')
import pygst
pygst.require('0.10')
import gst
import gst.interfaces
import gobject

import sugar.graphics.style

class GScrub(gtk.Window):

def __init__(self, gplay, playImg, pauseImg):
gtk.Window.__init__(self)
self._gplay = gplay
self._playImg = playImg
self._pauseImg = pauseImg

self.UPDATE_INTERVAL = 500
self.UPDATE_SCALE_ID = 0
self.CHANGED_ID = 0
self.was_playing = False
self.p_position = gst.CLOCK_TIME_NONE
self.p_duration = gst.CLOCK_TIME_NONE

self.hbox = gtk.HBox()
self.hbox.modify_bg( gtk.STATE_NORMAL, sugar.graphics.style.COLOR_BLACK.get_gdk_color() )
self.hbox.modify_bg( gtk.STATE_INSENSITIVE, sugar.graphics.style.COLOR_BLACK.get_gdk_color() )
self.add( self.hbox )

self.button = gtk.Button()
buttBox = gtk.EventBox()
buttBox.add(self.button)
buttBox.modify_bg( gtk.STATE_NORMAL, sugar.graphics.style.COLOR_BLACK.get_gdk_color() )
self.button.set_image( self._playImg )
self.button.set_property('can-default', True)
self.button.set_relief(gtk.RELIEF_NONE)
self.button.set_size_request( 55, 55 )
buttBox.set_size_request( 55, 55 )
self.button.show()

buttBox.modify_bg( gtk.STATE_NORMAL, sugar.graphics.style.COLOR_BLACK.get_gdk_color() )
self.button.modify_bg( gtk.STATE_ACTIVE, sugar.graphics.style.COLOR_BLACK.get_gdk_color() )

self.button.connect('clicked', self._buttonClickedCb)
self.hbox.pack_start(buttBox, expand=False)

self.adjustment = gtk.Adjustment(0.0, 0.00, 100.0, 0.1, 1.0, 1.0)
self.hscale = gtk.HScale(self.adjustment)
self.hscale.set_draw_value(False)
self.hscale.set_update_policy(gtk.UPDATE_CONTINUOUS)
hscaleBox = gtk.EventBox()
hscaleBox.modify_bg( gtk.STATE_NORMAL, sugar.graphics.style.COLOR_BLACK.get_gdk_color() )
hscaleBox.add( self.hscale )
self.hscale.connect('button-press-event', self._scaleButtonPressCb)
self.hscale.connect('button-release-event', self._scaleButtonReleaseCb)
self.hbox.pack_start(hscaleBox, expand=True)

def removeCallbacks( self ):
if (self.UPDATE_SCALE_ID != 0):
gobject.source_remove(self.UPDATE_SCALE_ID)
self.UPDATE_SCALE_ID = 0
if (self.CHANGED_ID != 0):
gobject.source_remove(self.CHANGED_ID)
self.CHANGED_ID = 0

def reset(self):
self.adjustment.set_value(0)

def _buttonClickedCb(self, widget):
self.play_toggled()

def set_button_play(self):
self.button.set_image(self._playImg)

def set_button_pause(self):
self.button.set_image(self._pauseImg)

def play_toggled(self):
self.p_position, self.p_duration = self._gplay.queryPosition()
if (self.p_position == self.p_duration):
self._gplay.seek(0)
self._gplay.pause()

if self._gplay.is_playing():
self._gplay.pause()
self.set_button_play()
else:
#if self._gplay.error:
# #todo: check if we have "error", and also to disable everything
# self.button.set_disabled()
#else:
self.doPlay()

def doPlay(self):
self._gplay.play()
if self.UPDATE_SCALE_ID == 0:
self.UPDATE_SCALE_ID = gobject.timeout_add(self.UPDATE_INTERVAL, self._updateScaleCb)
self.set_button_pause()

def _scaleButtonPressCb(self, widget, event):
#self.button.set_sensitive(False)
self.was_playing = self._gplay.is_playing()
if self.was_playing:
self._gplay.pause()

# don't timeout-update position during seek
if self.UPDATE_SCALE_ID != 0:
gobject.source_remove(self.UPDATE_SCALE_ID)
self.UPDATE_SCALE_ID = 0

# make sure we get changed notifies
if self.CHANGED_ID == 0:
self.CHANGED_ID = self.hscale.connect('value-changed', self._scaleValueChangedCb)

def _scaleButtonReleaseCb(self, widget, event):
# see seek.cstop_seek
widget.disconnect(self.CHANGED_ID)
self.CHANGED_ID = 0

#self.button.set_sensitive(True)
if self.was_playing:
self._gplay.play()

if self.UPDATE_SCALE_ID != 0:
pass
#print('Had a previous update timeout id')
else:
self.UPDATE_SCALE_ID = gobject.timeout_add(self.UPDATE_INTERVAL, self._updateScaleCb)

def _scaleValueChangedCb(self, scale):
real = long(scale.get_value() * self.p_duration / 100) # in ns
self._gplay.seek(real)
# allow for a preroll
self._gplay.get_state(timeout=50*gst.MSECOND) # 50 ms

def _updateScaleCb(self):
self.p_position, self.p_duration = self._gplay.queryPosition()
if self.p_position != gst.CLOCK_TIME_NONE:
value = self.p_position * 100.0 / self.p_duration
if (value > 99):
value = 99
elif (value < 0):
value = 0

self.adjustment.set_value(value)

if self._gplay.is_playing() and (self.p_position == self.p_duration):
self._gplay.pause()
self.set_button_play()

return True
</pre>

Development Team/Almanac/GStreamer

2008-10-03T15:53:40Z

Jedierikb:

{{Sugar Almanac}}

=== Where can I get additional resources and sample code on using the camera? ===
* [[Programming_the_camera]]

=== How can I embed video files in my activity? ===
Sugar, by default, can play back audio (encoded in Vorbis) and video (encoded in Theora) files in ogg containers.

The following file will be helpful for embedding video or audio files into your activity. After the code posting is a code snippet showing how to use this.

<pre>
import gtk
import pygtk
pygtk.require('2.0')
import sys
import pygst
pygst.require('0.10')
import gst
import gst.interfaces
import gobject
import time
gobject.threads_init()

class Gplay:

def __init__(self):
self.window = None
self.playing = False

self.player = gst.element_factory_make("playbin", "playbin")
xis = gst.element_factory_make("xvimagesink", "xvimagesink")
self.player.set_property("video-sink", xis)
bus = self.player.get_bus()
bus.enable_sync_message_emission()
bus.add_signal_watch()
self.SYNC_ID = bus.connect('sync-message::element', self._onSyncMessageCb)

def _onSyncMessageCb(self, bus, message):
if message.structure is None:
return True
if message.structure.get_name() == 'prepare-xwindow-id':
self.window.set_sink(message.src)
message.src.set_property('force-aspect-ratio', True)
return True

def setFile(self, path):
uri = "file://" + str( path )
if (self.player.get_property('uri') == uri):
self.seek(gst.SECOND*0)
return

self.player.set_state(gst.STATE_READY)
self.player.set_property('uri', uri)
ext = uri[len(uri)-3:]
if (ext == "jpg"):
self.pause()
else:
self.play()

def queryPosition(self):
#"Returns a (position, duration) tuple"
try:
position, format = self.player.query_position(gst.FORMAT_TIME)
except:
position = gst.CLOCK_TIME_NONE

try:
duration, format = self.player.query_duration(gst.FORMAT_TIME)
except:
duration = gst.CLOCK_TIME_NONE

return (position, duration)

def seek(self, time):
event = gst.event_new_seek(1.0, gst.FORMAT_TIME, gst.SEEK_FLAG_FLUSH | gst.SEEK_FLAG_ACCURATE, gst.SEEK_TYPE_SET, time, gst.SEEK_TYPE_NONE, 0)
res = self.player.send_event(event)
if res:
self.player.set_new_stream_time(0L)

def pause(self):
self.playing = False
self.player.set_state(gst.STATE_PAUSED)

def play(self):
self.playing = True
self.player.set_state(gst.STATE_PLAYING)

def stop(self):
self.playing = False
self.player.set_state(gst.STATE_NULL)
self.nextMovie()

def get_state(self, timeout=1):
return self.player.get_state(timeout=timeout)

def is_playing(self):
return self.playing

class PlayVideoWindow(gtk.Window):
def __init__(self):
gtk.Window.__init__(self)

self.imagesink = None
self.unset_flags(gtk.DOUBLE_BUFFERED)
self.set_flags(gtk.APP_PAINTABLE)

def set_sink(self, sink):
if (self.imagesink != None):
assert self.window.xid
self.imagesink = None
del self.imagesink

self.imagesink = sink
self.imagesink.set_xwindow_id(self.window.xid)

</pre>

And here is a code snippet showing how you would use this file to embed media playback in your activity:

<pre>
#this is our video playback window
self.gplay = Gplay( )
self.gplayWin = PlayVideoWindow( )
self.gplay.window = self.gplayWin

self.gplayWin.set_type_hint( gtk.gdk.WINDOW_TYPE_HINT_DIALOG )
self.gplayWin.set_decorated( False )
self.gplayWin.set_transient_for( self ) #activity subclass
self.gplayWin.move( 100, 100 )
self.gplayWin.resize( 300, 400 )
self.gplayWin.show_all( )
</pre>

=== How can I add play/pause buttons and a scrubber to my audio or video? ===
<pre>
import gtk
import pygtk
pygtk.require('2.0')
import pygst
pygst.require('0.10')
import gst
import gst.interfaces
import gobject

import sugar.graphics.style

class GScrub(gtk.Window):

def __init__(self, gplay, playImg, pauseImg):
gtk.Window.__init__(self)
self._gplay = gplay
self._playImg = playImg
self._pauseImg = pauseImg

self.UPDATE_INTERVAL = 500
self.UPDATE_SCALE_ID = 0
self.CHANGED_ID = 0
self.was_playing = False
self.p_position = gst.CLOCK_TIME_NONE
self.p_duration = gst.CLOCK_TIME_NONE

self.hbox = gtk.HBox()
self.hbox.modify_bg( gtk.STATE_NORMAL, sugar.graphics.style.COLOR_BLACK.get_gdk_color() )
self.hbox.modify_bg( gtk.STATE_INSENSITIVE, sugar.graphics.style.COLOR_BLACK.get_gdk_color() )
self.add( self.hbox )

self.button = gtk.Button()
buttBox = gtk.EventBox()
buttBox.add(self.button)
buttBox.modify_bg( gtk.STATE_NORMAL, sugar.graphics.style.COLOR_BLACK.get_gdk_color() )
self.button.set_image( self._playImg )
self.button.set_property('can-default', True)
self.button.set_relief(gtk.RELIEF_NONE)
self.button.set_size_request( 55, 55 )
buttBox.set_size_request( 55, 55 )
self.button.show()

buttBox.modify_bg( gtk.STATE_NORMAL, sugar.graphics.style.COLOR_BLACK.get_gdk_color() )
self.button.modify_bg( gtk.STATE_ACTIVE, sugar.graphics.style.COLOR_BLACK.get_gdk_color() )

self.button.connect('clicked', self._buttonClickedCb)
self.hbox.pack_start(buttBox, expand=False)

self.adjustment = gtk.Adjustment(0.0, 0.00, 100.0, 0.1, 1.0, 1.0)
self.hscale = gtk.HScale(self.adjustment)
self.hscale.set_draw_value(False)
self.hscale.set_update_policy(gtk.UPDATE_CONTINUOUS)
hscaleBox = gtk.EventBox()
hscaleBox.modify_bg( gtk.STATE_NORMAL, sugar.graphics.style.COLOR_BLACK.get_gdk_color() )
hscaleBox.add( self.hscale )
self.hscale.connect('button-press-event', self._scaleButtonPressCb)
self.hscale.connect('button-release-event', self._scaleButtonReleaseCb)
self.hbox.pack_start(hscaleBox, expand=True)

def removeCallbacks( self ):
if (self.UPDATE_SCALE_ID != 0):
gobject.source_remove(self.UPDATE_SCALE_ID)
self.UPDATE_SCALE_ID = 0
if (self.CHANGED_ID != 0):
gobject.source_remove(self.CHANGED_ID)
self.CHANGED_ID = 0

def reset(self):
self.adjustment.set_value(0)

def _buttonClickedCb(self, widget):
self.play_toggled()

def set_button_play(self):
self.button.set_image(self._playImg)

def set_button_pause(self):
self.button.set_image(self._pauseImg)

def play_toggled(self):
self.p_position, self.p_duration = self._gplay.queryPosition()
if (self.p_position == self.p_duration):
self._gplay.seek(0)
self._gplay.pause()

if self._gplay.is_playing():
self._gplay.pause()
self.set_button_play()
else:
#if self._gplay.error:
# #todo: check if we have "error", and also to disable everything
# self.button.set_disabled()
#else:
self.doPlay()

def doPlay(self):
self._gplay.play()
if self.UPDATE_SCALE_ID == 0:
self.UPDATE_SCALE_ID = gobject.timeout_add(self.UPDATE_INTERVAL, self._updateScaleCb)
self.set_button_pause()

def _scaleButtonPressCb(self, widget, event):
#self.button.set_sensitive(False)
self.was_playing = self._gplay.is_playing()
if self.was_playing:
self._gplay.pause()

# don't timeout-update position during seek
if self.UPDATE_SCALE_ID != 0:
gobject.source_remove(self.UPDATE_SCALE_ID)
self.UPDATE_SCALE_ID = 0

# make sure we get changed notifies
if self.CHANGED_ID == 0:
self.CHANGED_ID = self.hscale.connect('value-changed', self._scaleValueChangedCb)

def _scaleButtonReleaseCb(self, widget, event):
# see seek.cstop_seek
widget.disconnect(self.CHANGED_ID)
self.CHANGED_ID = 0

#self.button.set_sensitive(True)
if self.was_playing:
self._gplay.play()

if self.UPDATE_SCALE_ID != 0:
pass
#print('Had a previous update timeout id')
else:
self.UPDATE_SCALE_ID = gobject.timeout_add(self.UPDATE_INTERVAL, self._updateScaleCb)

def _scaleValueChangedCb(self, scale):
real = long(scale.get_value() * self.p_duration / 100) # in ns
self._gplay.seek(real)
# allow for a preroll
self._gplay.get_state(timeout=50*gst.MSECOND) # 50 ms

def _updateScaleCb(self):
self.p_position, self.p_duration = self._gplay.queryPosition()
if self.p_position != gst.CLOCK_TIME_NONE:
value = self.p_position * 100.0 / self.p_duration
if (value > 99):
value = 99
elif (value < 0):
value = 0

self.adjustment.set_value(value)

if self._gplay.is_playing() and (self.p_position == self.p_duration):
self._gplay.pause()
self.set_button_play()

return True
</pre>