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.

buddy_joined

The buddy_joined signal is emitted when another user joins the activity. The only argument is a sugar3.presence.buddy.Buddy, for the buddy that joined.

buddy_left

The buddy_left signal is emitted when another user leaves the activity. The only argument is a sugar3.presence.buddy.Buddy, for the buddy that left.

get_client_name()

Get the name of the activity’s telepathy client.

Returns: str, telepathy client name

incoming_file

The incoming_file signal is emitted when a file transfer is received from another buddy. The first argument is the object representing the transfer, as a sugar3.presence.filetransfer.IncomingFileTransfer. The 2nd argument is the description, as passed to the send_file_* function by the sender.

joined

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.

message

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.

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.

send_file_file(buddy, path, description)

Send a 1-to-1 transfer from a file to a given buddy. They will get the file transfer and description through the incoming_transfer signal.

Parameters:

• buddy (sugar3.presence.buddy.Buddy) – buddy to offer the transfer to
• path (str) – path of the file to send to the buddy
• description (object) – a json encodable description for the transfer. This will be given to the incoming_transfer signal of the transfer

send_file_memory(buddy, data, description)

Send a 1-to-1 transfer from memory to a given buddy. They will get the file transfer and description through the incoming_transfer signal.

Parameters:

• buddy (sugar3.presence.buddy.Buddy) – buddy to offer the transfer to
• data (str) – the data to offer to the buddy via the transfer
• description (object) – a json encodable description for the transfer. This will be given to the incoming_transfer signal of the transfer

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. For example, place this at the end of the activity’s __init__ function.