sugar3.presence.wrapper module

The wrapper module provides an abstraction over the sugar collaboration system.

Using CollabWrapper

1. Implement the get_data and set_data methods in your activity class:

   def get_data(self):
       # return plain python objects - things that can be encoded
       # using the json module
       return dict(
           text=self._entry.get_text()
       )
   
   def set_data(self, data):
       # data will be the same object returned by get_data
       self._entry.set_text(data.get('text'))
   

2. Make your CollabWrapper instance:

   def __init__(self, handle):
       sugar3.activity.activity.Activity.__init__(self, handle)
       self._collab = CollabWrapper(self)
       self._collab.connect('message', self.__message_cb)
   
       # setup your activity
   
       self._collab.setup()
   

3. Post any changes to the CollabWrapper. The changes will be sent to other users if any are connected:

   def __entry_changed_cb(self, *args):
       self._collab.post(dict(
           action='entry_changed',
           new_text=self._entry.get_text()
       ))
   

4. Handle incoming messages:

   def __message_cb(self, collab, buddy, message):
       action = msg.get('action')
       if action == 'entry_changed':
           self._entry.set_text(msg.get('new_text'))
   

class sugar3.presence.wrapper.CollabWrapper(activity)

Bases: gi.overrides.GObject.Object

The collaboration wrapper provides a high level abstraction over the collaboration system. The wrapper deals with setting up the channels, encoding and decoding messages, initialization and alerting the user to the status.

When a user joins the activity, it will query the leader for the contents. The leader will return the result of the activity’s get_data function which will be passed to the set_data function on the new user’s computer.

The message signal is called when a message is received from a buddy. It has 2 arguments. The first is the buddy, as a sugar3.presence.buddy.Buddy. The second is the decoded content of the message, same as that posted by the other instance.

The joined signal is emitted when the buddy joins a running activity. If the user shares and activity, the joined signal is not emitted. By the time this signal is emitted, the channels will be setup so all messages will flow through.

The buddy_joined and buddy_left signals are emitted when another user joins or leaves the activity. They both a sugar3.presence.buddy.Buddy as their only argument.

buddy_joined

buddy_left

joined

message

post(msg)

Broadcast a message to the other buddies if the activity is shared. If it is not shared, the message will not be send at all.

Parameters:msg (object) – json encodable object to send to the other buddies, eg. dict or str.

setup()

Setup must be called to so that the activity can join or share if appropriate.

Note

As soon as setup is called, any signal, get_data or set_data call must be made. This means that your activity must have set up enough so these functions can work.