From 8635a702c64f087473a1c2243bcc895bcbd8b0c4 Mon Sep 17 00:00:00 2001 From: "Mike C. Fletcher" Date: Sun, 15 Apr 2007 00:27:48 -0400 Subject: [PATCH] Documentation for the activity and buddy presence objects --- sugar/presence/activity.py | 45 +++++++++++++++++++++- sugar/presence/buddy.py | 76 +++++++++++++++++++++++++++++++++++++- 2 files changed, 119 insertions(+), 2 deletions(-) diff --git a/sugar/presence/activity.py b/sugar/presence/activity.py index 16163784..f2903682 100644 --- a/sugar/presence/activity.py +++ b/sugar/presence/activity.py @@ -1,3 +1,4 @@ +"""UI interface to an activity in the presence service""" # Copyright (C) 2007, Red Hat, Inc. # # This library is free software; you can redistribute it and/or @@ -19,7 +20,19 @@ import gobject import dbus class Activity(gobject.GObject): - + """UI interface for an Activity in the presence service + + Activities in the presence service represent other user's + shared activities and your own activities (XXX shared or + otherwise?) + + Properties: + id + color + name + type + joined + """ __gsignals__ = { 'buddy-joined': (gobject.SIGNAL_RUN_FIRST, gobject.TYPE_NONE, ([gobject.TYPE_PYOBJECT])), @@ -33,6 +46,7 @@ class Activity(gobject.GObject): _ACTIVITY_DBUS_INTERFACE = "org.laptop.Sugar.Presence.Activity" def __init__(self, bus, new_obj_cb, del_obj_cb, object_path): + """Initialse the activity interface, connecting to service""" gobject.GObject.__init__(self) self._object_path = object_path self._ps_new_object = new_obj_cb @@ -50,9 +64,11 @@ class Activity(gobject.GObject): self._joined = False def object_path(self): + """Get our dbus object path""" return self._object_path def _emit_buddy_joined_signal(self, object_path): + """Generate buddy-joined GObject signal with presence Buddy object""" self.emit('buddy-joined', self._ps_new_object(object_path)) return False @@ -60,6 +76,10 @@ class Activity(gobject.GObject): gobject.idle_add(self._emit_buddy_joined_signal, object_path) def _emit_buddy_left_signal(self, object_path): + """Generate buddy-left GObject signal with presence Buddy object + + XXX note use of _ps_new_object instead of _ps_del_object here + """ self.emit('buddy-left', self._ps_new_object(object_path)) return False @@ -67,6 +87,10 @@ class Activity(gobject.GObject): gobject.idle_add(self._emit_buddy_left_signal, object_path) def _emit_new_channel_signal(self, object_path): + """Generate new-channel GObject signal with channel object path + + New telepathy-python communications channel has been opened + """ self.emit('new-channel', object_path) return False @@ -74,27 +98,35 @@ class Activity(gobject.GObject): gobject.idle_add(self._emit_new_channel_signal, object_path) def get_id(self): + """Retrieve the unique identifier for this activity instance""" # Cache activity ID, which should never change anyway if not self._id: self._id = self._activity.GetId() return self._id def get_color(self): + """Retrieve the activity icon colour for this activity instance""" if not self._color: self._color = self._activity.GetColor() return self._color def get_name(self): + """Retrieve the activity name for this activity instance""" if not self._name: self._name = self._activity.GetName() return self._name def get_type(self): + """Retrieve the activity/bundle type for this activity instance""" if not self._type: self._type = self._activity.GetType() return self._type def get_joined_buddies(self): + """Retrieve the set of Buddy objects attached to this activity + + returns list of presence Buddy objects + """ resp = self._activity.GetJoinedBuddies() buddies = [] for item in resp: @@ -102,15 +134,26 @@ class Activity(gobject.GObject): return buddies def join(self): + """Join this activity + + XXX if these are all activities, can I join my own activity? + """ if self._joined: return self._activity.Join() self._joined = True def get_channels(self): + """Retrieve communications channel descriptions for the activity + + Returns (bus name, connection, channels) for the activity + + XXX what are those values? + """ (bus_name, connection, channels) = self._activity.GetChannels() return bus_name, connection, channels def owner_has_joined(self): + """Retrieve whether the owner of the activity is active within it""" # FIXME return False diff --git a/sugar/presence/buddy.py b/sugar/presence/buddy.py index c6f51d57..048f3ea7 100644 --- a/sugar/presence/buddy.py +++ b/sugar/presence/buddy.py @@ -1,3 +1,4 @@ +"""UI interface to a buddy in the presence service""" # Copyright (C) 2007, Red Hat, Inc. # # This library is free software; you can redistribute it and/or @@ -20,13 +21,33 @@ import gtk import dbus def _bytes_to_string(bytes): + """Convertes an short-int (char) array to a string + + returns string or None for a null sequence + """ if len(bytes): + # if there's an internal buffer, we could use + # ctypes to pull it out without this... return ''.join([chr(item) for item in bytes]) return None class Buddy(gobject.GObject): - + """UI interface for a Buddy in the presence service + + Each buddy interface tracks a set of activities and properties + that can be queried to provide UI controls for manipulating + the presence interface. + + Properties Dictionary: + 'key': public key, + 'nick': nickname , + 'color': color (XXX what format), + 'current-activity': (XXX dbus path?), + 'owner': (XXX dbus path?), + 'icon': (XXX pixel data for an icon?) + See __gproperties__ + """ __gsignals__ = { 'icon-changed': (gobject.SIGNAL_RUN_FIRST, gobject.TYPE_NONE, ([])), @@ -51,6 +72,13 @@ class Buddy(gobject.GObject): _BUDDY_DBUS_INTERFACE = "org.laptop.Sugar.Presence.Buddy" def __init__(self, bus, new_obj_cb, del_obj_cb, object_path): + """Initialise the reference to the buddy + + bus -- dbus bus object + new_obj_cb -- callback to call when this buddy joins an activity + del_obj_cb -- callback to call when this buddy leaves an activity + object_path -- path to the buddy object + """ gobject.GObject.__init__(self) self._object_path = object_path self._ps_new_object = new_obj_cb @@ -68,12 +96,19 @@ class Buddy(gobject.GObject): self._icon = None def _get_properties_helper(self): + """Retrieve the Buddy's property dictionary from the service object + """ props = self._buddy.GetProperties() if not props: return {} return props def do_get_property(self, pspec): + """Retrieve a particular property from our property dictionary + + pspec -- XXX some sort of GTK specifier object with attributes + including 'name', 'active' and 'icon-name' + """ if pspec.name == "key": return self._properties["key"] elif pspec.name == "nick": @@ -97,48 +132,79 @@ class Buddy(gobject.GObject): return self._icon def object_path(self): + """Retrieve our dbus object path""" return self._object_path def _emit_icon_changed_signal(self, bytes): + """Emit GObject signal when icon has changed""" self._icon = _bytes_to_string(bytes) self.emit('icon-changed') return False def _icon_changed_cb(self, icon_data): + """Handle dbus signal by emitting a GObject signal""" gobject.idle_add(self._emit_icon_changed_signal, icon_data) def _emit_joined_activity_signal(self, object_path): + """Emit activity joined signal with Activity object""" self.emit('joined-activity', self._ps_new_object(object_path)) return False def _joined_activity_cb(self, object_path): + """Handle dbus signal by emitting a GObject signal + + Stores the activity in activities dictionary as well + """ if not self._activities.has_key(object_path): self._activities[object_path] = self._ps_new_object(object_path) gobject.idle_add(self._emit_joined_activity_signal, object_path) def _emit_left_activity_signal(self, object_path): + """Emit activity left signal with Activity object + + XXX this calls self._ps_new_object instead of self._ps_del_object, + which would seem to be the incorrect callback? + """ self.emit('left-activity', self._ps_new_object(object_path)) return False def _left_activity_cb(self, object_path): + """Handle dbus signal by emitting a GObject signal + + Also removes from the activities dictionary + """ if self._activities.has_key(object_path): del self._activities[object_path] gobject.idle_add(self._emit_left_activity_signal, object_path) def _handle_property_changed_signal(self, prop_list): + """Emit property-changed signal with property dictionary + + Generates a property-changed signal with the results of + _get_properties_helper() + """ self._properties = self._get_properties_helper() # FIXME: don't leak unexposed property names self.emit('property-changed', prop_list) return False def _property_changed_cb(self, prop_list): + """Handle dbus signal by emitting a GObject signal""" gobject.idle_add(self._handle_property_changed_signal, prop_list) def get_icon_pixbuf(self): + """Retrieve Buddy's icon as a GTK pixel buffer + + XXX Why aren't the icons coming in as SVG? + """ if self.props.icon and len(self.props.icon): pbl = gtk.gdk.PixbufLoader() icon_data = "" for item in self.props.icon: + # XXX this is a slow way to convert the data + # under Python 2.5 and below, collect in a + # list and then join with "", see + # _bytes_to_string in this module icon_data = icon_data + chr(item) pbl.write(icon_data) pbl.close() @@ -147,6 +213,14 @@ class Buddy(gobject.GObject): return None def get_joined_activities(self): + """Retrieve the set of all activities which this buddy has joined + + Uses the GetJoinedActivities method on the service + object to produce object paths, wraps each in an + Activity object. + + returns list of presence Activity objects + """ try: resp = self._buddy.GetJoinedActivities() except dbus.exceptions.DBusException: