Low-level Activity API: Difference between revisions

From OLPC
Jump to navigation Jump to search
(→‎Methods: add XID explanation)
(→‎Methods: comments for methods)
Line 12: Line 12:
=Methods=
=Methods=
''These methods were collected by introspection on the DBus''
''These methods were collected by introspection on the DBus''
==Interface com.redhat.Sugar.ActivityFactory ==

/my/organization/MyActivity com.redhat.Sugar.ActivityFactory.create()
/my/organization/MyActivity com.redhat.Sugar.ActivityFactory.create()


The <tt>create()</tt> method creates a new Activity instance. That instance is exposed on the dbus as <tt>/org/laptop/Activity/123456</tt>. The number 123456 is the instance's top-level window XID. An activity instance needs to support the following methods:
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.

==Interface org.laptop.Activity==

An activity instance needs to support the following methods:


/org/laptop/Activity/123456 org.laptop.Activity.get_id()
/org/laptop/Activity/123456 org.laptop.Activity.get_id()

Get the activity identifier as passed into <tt>create()</tt> (e.g., <tt>6f7f3acacca87886332f50bdd522d805f0abbf1f</tt>).

/org/laptop/Activity/123456 org.laptop.Activity.get_service_name()
/org/laptop/Activity/123456 org.laptop.Activity.get_service_name()

Get the activity service name (e.g., <tt>my.organization.MyActivity</tt>).

/org/laptop/Activity/123456 org.laptop.Activity.share()
/org/laptop/Activity/123456 org.laptop.Activity.share()

Called by the shell to request the activity to share itself on the network.

/org/laptop/Activity/123456 org.laptop.Activity.get_shared()
/org/laptop/Activity/123456 org.laptop.Activity.get_shared()

Returns True if the activity is shared on the mesh.

/org/laptop/Activity/123456 org.laptop.Activity.set_active(active)

Activate or passivate an activity. Passive activities must release resources like sound, camera etc.

/org/laptop/Activity/123456 org.laptop.Activity.execute(cmd, args[])
/org/laptop/Activity/123456 org.laptop.Activity.execute(cmd, args[])

Optional - execute a command defined in the activity, answer True on success. ''might be deprecated soon''


=Signals=
=Signals=

Revision as of 09:57, 22 May 2007

Most activities will use the Python API to implement activities. This page will document the underlying mechanism that non-Python activities need to conform to.

This documentation effort was started by Bert while implementing the Squeak-based Etoys activity. Please fill in missing pieces and correct mistakes!

Overview

An Activity Bundle can specify an executable in the activity.info's exec field. When installing the bundle, the path of this executable will be expanded and added to the list of DBus services in $HOME/.local/share/dbus-1/services/ using the DBus service name as specified in the service_name 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 factory service must provide is com.redhat.Sugar.ActivityFactory.create() which spawns an activity instance. Each activity instance has a unique activity_id which is passed as parameter to the create() method.

When the last activity instance exits, the factory service should quit.

Methods

These methods were collected by introspection on the DBus

Interface com.redhat.Sugar.ActivityFactory

/my/organization/MyActivity com.redhat.Sugar.ActivityFactory.create()

The create() method creates a new Activity instance. That instance is exposed on the DBus as /org/laptop/Activity/123456 where the number 123456 is the instance's top-level window XID.

Interface org.laptop.Activity

An activity instance needs to support the following methods:

/org/laptop/Activity/123456 org.laptop.Activity.get_id()

Get the activity identifier as passed into create() (e.g., 6f7f3acacca87886332f50bdd522d805f0abbf1f).

/org/laptop/Activity/123456 org.laptop.Activity.get_service_name()

Get the activity service name (e.g., my.organization.MyActivity).

/org/laptop/Activity/123456 org.laptop.Activity.share()

Called by the shell to request the activity to share itself on the network.

/org/laptop/Activity/123456 org.laptop.Activity.get_shared()

Returns True if the activity is shared on the mesh.

/org/laptop/Activity/123456 org.laptop.Activity.set_active(active)

Activate or passivate an activity. Passive activities must release resources like sound, camera etc.

/org/laptop/Activity/123456 org.laptop.Activity.execute(cmd, args[])

Optional - execute a command defined in the activity, answer True on success. might be deprecated soon

Signals

todo

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 com.redhat.Sugar.ActivityFactory.create(activity_id='6f7f3acacca87886332f50bdd522d805f0abbf1f')

this is as far as I got now ... what needs to happen next? I'll find out ... -- Bert