sugarlabs/sugar-toolkit-gtk3
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Docstrings for modules all over sugar and shell.

Browse Source 
These are just the doc strings I created as I was spelunking
through to see how Sugar manages launching applications.  The
resulting auto-documentation is neither polished or finished,
but it should help people reading the code somewhat.

There are a few minor code cleanups:

  * activityhandle (replacing C idiom for initialisation with
    a Python one)
  * bundle registry (using a parameterised directory name so
    that it shows up in the documentation)
  * validate_activity_id function, use isinstance( item, (str,unicode))
    for the query, rather than two separate checks with isinstance
This commit is contained in:
Mike C. Fletcher
2007-04-09 22:47:37 -04:00
parent 508a59b99b
commit 3f10890319
15 changed files with 373 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
shell/model/homeactivity.py
+59
View File
@@ -25,6 +25,13 @@ from sugar.presence import presenceservice
from sugar import profile
class HomeActivity(gobject.GObject):
"""Activity which appears in the "Home View" of the Sugar shell
This class stores the Sugar Shell's metadata regarding a
given activity/application in the system. It interacts with
the sugar.activity.* modules extensively in order to
accomplish its tasks.
"""
__gsignals__ = {
'launch-timeout': (gobject.SIGNAL_RUN_FIRST,
gobject.TYPE_NONE,
@@ -32,6 +39,15 @@ class HomeActivity(gobject.GObject):
}
def __init__(self, bundle, activity_id):
"""Initialise the HomeActivity
bundle -- sugar.activity.bundle.Bundle instance,
provides the information required to actually
create the new instance. This is, in effect,
the "type" of activity being created.
activity_id -- unique identifier for this instance
of the activity type
"""
gobject.GObject.__init__(self)
self._window = None
self._xid = None
@@ -52,6 +68,8 @@ class HomeActivity(gobject.GObject):
self._launch_timeout_id = 0
def _launch_timeout_cb(self, user_data=None):
"""Callback for launch operation timeouts
"""
logging.debug("Activity %s (%s) launch timed out" %
(self._activity_id, self.get_type))
self._launch_timeout_id = 0
@@ -78,17 +96,33 @@ class HomeActivity(gobject.GObject):
self._service = service
def get_service(self):
"""Retrieve the application's sugar introspection service
Note that non-native Sugar applications will not have
such a service, so the return value will be None in
those cases.
"""
return self._service
def get_title(self):
"""Retrieve the application's root window's suggested title"""
if not self._launched:
raise RuntimeError("Activity is still launching.")
return self._window.get_name()
def get_icon_name(self):
"""Retrieve the bundle's icon (file) name"""
return self._bundle.get_icon()
def get_icon_color(self):
"""Retrieve the appropriate icon colour for this activity
Uses activity_id to index into the PresenceService's
set of activity colours, if the PresenceService does not
have an entry (implying that this is not a Sugar-shared application)
uses the local user's profile.get_color() to determine the
colour for the icon.
"""
pservice = presenceservice.get_instance()
activity = pservice.get_activity(self._activity_id)
if activity != None:
@@ -97,28 +131,53 @@ class HomeActivity(gobject.GObject):
return profile.get_color()
def get_activity_id(self):
"""Retrieve the "activity_id" passed in to our constructor
This is a "globally likely unique" identifier generated by
sugar.util.unique_id
"""
return self._activity_id
def get_xid(self):
"""Retrieve the X-windows ID of our root window"""
if not self._launched:
raise RuntimeError("Activity is still launching.")
return self._xid
def get_window(self):
"""Retrieve the X-windows root window of this application
This was stored by the set_window method, which was
called by HomeModel._add_activity, which was called
via a callback that looks for all 'window-opened'
events.
HomeModel currently uses a dbus service query on the
activity to determine to which HomeActivity the newly
launched window belongs.
"""
if not self._launched:
raise RuntimeError("Activity is still launching.")
return self._window
def get_type(self):
"""Retrieve bundle's "service_name" for future reference"""
return self._bundle.get_service_name()
def get_shared(self):
"""Return whether this activity is using Presence service sharing"""
if not self._launched:
raise RuntimeError("Activity is still launching.")
return self._service.get_shared()
def get_launch_time(self):
"""Return the time at which the activity was first launched
Format is floating-point time.time() value
(seconds since the epoch)
"""
return self._launch_time
def get_launched(self):
"""Return whether we have bound our top-level window yet"""
return self._launched
shell/model/homemodel.py
+23 -1
View File
@@ -28,7 +28,19 @@ _SERVICE_NAME = "org.laptop.Activity"
_SERVICE_PATH = "/org/laptop/Activity"
class HomeModel(gobject.GObject):
"""Model of the "Home" view (activity management)
The HomeModel is basically the point of registration
for all running activities within Sugar. It traps
events that tell the system there is a new activity
being created (generated by the activity factories),
or removed, as well as those which tell us that the
currently focussed activity has changed.
The HomeModel tracks a set of HomeActivity instances,
which are tracking the window to activity mappings
the activity factories have set up.
"""
__gsignals__ = {
'activity-launched': (gobject.SIGNAL_RUN_FIRST,
gobject.TYPE_NONE,
@@ -124,6 +136,16 @@ class HomeModel(gobject.GObject):
self.emit('activity-added', home_window)
def _add_activity(self, window):
"""Add the window to the set of windows we track
At the moment this requires that something somewhere
have registered a dbus service with the XID of the
new window that is used to bind the requested activity
to the window.
window -- gtk.Window instance representing a new
normal, top-level window
"""
bus = dbus.SessionBus()
xid = window.get_xid()
try: