Low-level Activity API: Difference between revisions
Jump to navigation
Jump to search
m (→Querying: typo) |
mNo edit summary |
||
| (145 intermediate revisions by 30 users not shown) | |||
| Line 1: | Line 1: | ||
{{Developers}} |
|||
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 [[#Activity Factory|factory service]] provides a <tt>org.laptop.ActivityFactory.create()</tt> method which spawns an activity instance. Each activity instance has a unique <tt>activity_id</tt> which is passed as one of the parameters to the <tt>create()</tt> method. |
|||
Each [[#Activity Instance|activity instance]] opens an X window. This window must have two string properties, <code>_SUGAR_BUNDLE_ID</code> specifying the service name and <code>_SUGAR_ACTIVITY_ID</code> which is the id that was passed to <code>create()</code>. The instance 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 (see [[#Datastore|datastore]]). |
|||
; 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.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f</tt> (where 6f7f3acacca87886332f50bdd522d805f0abbf1f is the activity id) |
|||
Object path: <tt>/org/laptop/Activity/6f7f3acacca87886332f50bdd522d805f0abbf1f</tt> (where 6f7f3acacca87886332f50bdd522d805f0abbf1f is the activity id) |
|||
Interface: <tt>org.laptop.Activity</tt> |
|||
==X Properties== |
|||
The activity instance needs to set two properties on its top-level window: |
|||
_SUGAR_BUNDLE_ID |
|||
The bundle id (e.g., <tt>my.organization.MyActivity</tt>) of type <tt>STRING</tt>. |
|||
_SUGAR_ACTIVITY_ID |
|||
The activity id (e.g., <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt>) of type <tt>STRING</tt>. |
|||
==Methods== |
|||
An activity instance needs to support the following methods: |
|||
org.laptop.Activity.set_active(active) |
|||
Activate or passivate an activity. Passive activities must release resources like sound, camera etc. |
|||
''There used to be more methods but the API evolved so only this single one is remaining for now.'' |
|||
=Datastore= |
|||
An Activity instance must store its complete state in the central datastore so it appears in the Journal and can be resumed later. It needs to connect to the datastore service: |
|||
Service name: org.laptop.sugar.DataStore |
|||
Object path: /org/laptop/sugar/DataStore |
|||
Interface: org.laptop.sugar.DataStore |
|||
==Keeping and Resuming== |
|||
An item in the datastore is referenced by an object_id, it has a dictionary of properties, and possibly a file. The properties have String keys but Variant values. Here are a few properties: |
|||
'activity': 'my.organization.MyActivity' |
|||
'activity_id': '6f7f3acacca87886332f50bdd522d805f0abbf1f' |
|||
'title': 'My new project' |
|||
'title_set_by_user': '0' |
|||
'keep': '0' |
|||
'ctime': '1972-05-12T18:41:08' #created |
|||
'mtime': '2007-06-16T03:42:33' #modified |
|||
'buddies': array of buddies #not spec'ed yet |
|||
'preview': base64(png file data, 300x225 px) #temporarily Base64, will be a ByteArray |
|||
'icon-color': '#ff0000,#ffff00' |
|||
'mime_type': 'application/x-my-activity' |
|||
'summary:text': 'text I want to be indexed' #properties with key ending in ":text" will be searched in fulltext search |
|||
To create an item in the datastore, call create(): |
|||
object_id = datastore.create(properties, filename) |
|||
If filename is not empty, the file will be copied to the datastore. The activity should delete the file once the call completes. The returned id will be a string like '4543af91-7be9-404e-b2f1-3e27cb15a15d'. |
|||
To update an item use update(): |
|||
datastore.update(object_id, properties, filename) |
|||
Again, if a filename was given, it should be deleted when the call returns. |
|||
To retrieve an object's properties and file: |
|||
properties = datastore.get_properties(object_id) |
|||
filename = datastore.get_filename(object_id) |
|||
The returned temp file should be deleted by the activity as soon as possible, latest when the activity quits. |
|||
==Querying== |
|||
Activities may query the datastore: |
|||
(results,count) = datastore.find(query) |
|||
It returns the results as array of properties and a count of matching items (the array may have less items if the query was limited). The query can be a: |
|||
: <b>string</b>: fulltext search |
|||
:: the given string is searched in all text properties |
|||
: <b>dictionary</b>: structured query |
|||
:: the key-value pairs in the dictionary specify the value (or array of values, or dictionary specifying range) for a specific property, e.g.: |
|||
::: 'title' = 'First Project' |
|||
::: 'mime_type' = ['image/png', 'image/jpeg'] |
|||
::: 'mtime' = {'start' = '2007-07-01T00:00:00', 'end' = '2007-08-01T00:00:00'} |
|||
:: also, there are a few specific keys to adjust the query: |
|||
::: 'query': fulltext search term |
|||
::: 'order_by': key (or array of keys) to order results by, to reverse order use '-key' |
|||
::: 'limit', 'offset': return only limit results starting at offset |
|||
::: 'include_files': if true, generate files as if get_filename() had been called for each item. In results, a property 'filename' will be added. |
|||
You can also retrieve an array of unique values for a field: |
|||
values = datastore.get_uniquevaluesfor(property, query) |
|||
Note that currently (2007-07-25) the query is ignored in this call, it looks for all values in all entries. |
|||
=Example= |
|||
[Activity] |
|||
name = My Activity |
|||
activity_version = 1 |
|||
host_version = 1 |
|||
service_name = my.organization.MyActivity |
|||
icon = activity-my |
|||
exec = myactivityfactory |
|||
show_launcher = yes |
|||
create factory service at my.organization.MyActivity |
|||
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') |
|||
launch new activity instance |
|||
create X window with _SUGAR_BUNDLE_ID='my.organization.MyActivity' and _SUGAR_ACTIVITY_ID='6f7f3acacca87886332f50bdd522d805f0abbf1f' |
|||
create instance dbus service at org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f |
|||
Signal /org/freedesktop/DBus org.freedesktop.DBus.NameAcquired(':1.24') |
|||
Signal /org/freedesktop/DBus org.freedesktop.DBus.NameAcquired('org.laptop.Activity6f7f3acacca87886332f50bdd522d805f0abbf1f') |
|||
[[Category:Sugar]] |
[[Category:Sugar]] |
||
[[Category:Developers]] |
|||
[[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.