Low-level Activity API: Difference between revisions
Jump to navigation
Jump to search
m (→Example: expand example) |
mNo edit summary |
||
| (170 intermediate revisions by 32 users not shown) | |||
| Line 1: | Line 1: | ||
| ⚫ | |||
Most activities will use the [[Sugar Architecture/API/sugar.activity|Python API]] to implement activities. This page will document the underlying mechanism that non-Python activities need to conform to. |
|||
Sugar activities are usually written in Python using the [[API_Reference|Python Activity API]]. This page documents the underlying mechanism that all activities need to conform to. Activities can be written in any language, as long as it can connect to D-Bus and provide an X11 interface. |
|||
''This documentation effort was started by [[User:Bert|Bert]] while implementing the [[Squeak]]-based [[Etoys]] activity. Please fill in missing pieces and correct mistakes!'' |
|||
'''This page has been moved to the [http://wiki.sugarlabs.org/go/Development_Team/Low-level_Activity_API Sugar Labs Wiki].''' |
|||
=Overview= |
|||
An [[Activity Bundle]] can specify an executable in the activity.info's <tt>exec</tt> field. When installing the bundle, the path of this executable will be expanded and added to the list of DBus services in <tt>$HOME/.local/share/dbus-1/services/</tt> using the DBus service name as specified in the <tt>service_name</tt> field. When launching an activity from Sugar shell, a request to that DBus service is made, which makes DBus run the previously specified executable. The executable must create a "factory service" on the DBus using the specified service name. |
|||
The most important method the [[#Activity Factory|factory service]] must provide is <tt>org.laptop.ActivityFactory.create()</tt> which spawns an activity instance. Each activity instance has a unique <tt>activity_id</tt> which is passed as parameter to the <tt>create()</tt> method. |
|||
The [[#Activity Instance|activity instance]] opens an X window and registers a DBus object at <tt>/org/laptop/Activity/''id''</tt> where ''id'' is the decimal XID of the window. This object must implement the <tt>org.laptop.Activity</tt> interface. |
|||
When the last activity instance exits, the factory service should quit. |
|||
=Activity Factory= |
|||
Service name: <tt>my.organization.MyActivity</tt> (from activity bundle info file) |
|||
Object path: <tt>/my/organization/MyActivity</tt> (derived from service name) |
|||
Interface: <tt>org.laptop.ActivityFactory</tt> |
|||
org.laptop.ActivityFactory.create(params) |
|||
The <tt>create()</tt> method creates a new Activity instance. That instance is exposed on the DBus as <tt>/org/laptop/Activity/<i>123456</i></tt> where the number 123456 is the instance's top-level window XID. |
|||
The <tt>params</tt> dictionary can have the following entries: |
|||
; activity_id: unique id for the activity to be created |
|||
; pservice_id: identity of the sharing service for this activity in the PresenceService |
|||
; object_id: identity of the journal object associated with the activity. When you resume an activity from the journal the object_id will be passed in. |
|||
; uri: URI associated with the activity. Used when opening an external file or resource in the activity, rather than a journal object (downloads stored on the file system for example or web pages) |
|||
=Activity Instance= |
|||
Service name: <tt>org.laptop.Activity123456</tt> (where 123456 is the window's XID) |
|||
Object path: <tt>/org/laptop/Activity/123456</tt> (where 123456 is the window's XID) |
|||
Interface: <tt>org.laptop.Activity</tt> |
|||
An activity instance needs to support the following methods: |
|||
org.laptop.Activity.get_id() |
|||
Get the activity identifier as passed into <tt>create()</tt> (e.g., <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt>). |
|||
org.laptop.Activity.get_service_name() |
|||
Get the activity factory service name (e.g., <tt>my.organization.MyActivity</tt>). |
|||
org.laptop.Activity.share() |
|||
Called by the shell to request the activity to share itself on the network. |
|||
org.laptop.Activity.get_shared() |
|||
Returns True if the activity is shared on the mesh. |
|||
org.laptop.Activity.set_active(active) |
|||
Activate or passivate an activity. Passive activities must release resources like sound, camera etc. |
|||
org.laptop.Activity.execute(cmd, args[]) |
|||
Optional - execute a command defined in the activity, answer True on success. ''might be deprecated soon'' |
|||
=Example= |
|||
[Activity] |
|||
name = My Activity |
|||
activity_version = 1 |
|||
host_version = 1 |
|||
service_name = my.organization.MyActivity |
|||
icon = activity-my |
|||
exec = myactivityfactory |
|||
show_launcher = yes |
|||
Signal /org/freedesktop/DBus org.freedesktop.DBus.NameAcquired(':1.23') |
|||
Signal /org/freedesktop/DBus org.freedesktop.DBus.NameAcquired('my.organization.MyActivity') |
|||
MethodCall /my/organization/MyActivity org.freedesktop.DBus.Introspectable.Introspect() |
|||
MethodCall /my/organization/MyActivity org.laptop.ActivityFactory.create(activity_id='6f7f3acacca87886332f50bdd522d805f0abbf1f') |
|||
(create X window with ID 0xA00002 = 10485762) |
|||
Signal /org/freedesktop/DBus org.freedesktop.DBus.NameAcquired('org.laptop.Activity10485762') |
|||
MethodCall /org/laptop/Activity/10485762 org.freedesktop.DBus.Introspectable.Introspect() |
|||
MethodCall /org/laptop/Activity/10485762 org.laptop.Activity.get_id() |
|||
MethodCall /org/laptop/Activity/10485762 org.laptop.Activity.get_service_name() |
|||
[[Category:Sugar]] |
[[Category:Sugar]] |
||
| ⚫ | |||
[[Category:API]] |
[[Category:API]] |
||
[[Category:Telepathy]] |
|||
[[Category:Collaboration]] |
|||
Latest revision as of 19:05, 25 September 2010
For Developers
Sugar activities are usually written in Python using the Python Activity API. This page documents the underlying mechanism that all activities need to conform to. Activities can be written in any language, as long as it can connect to D-Bus and provide an X11 interface.
This page has been moved to the Sugar Labs Wiki.