[sugar] how does an activity connect to the journal?

[Tomeu Vizoso]

On Thu, Feb 28, 2008 at 3:10 PM, Paul Fox <pgf at foxharp.boston.ma.us> wrote:
> i wrote:
>   > where is the interface between activities and the journal
>   > documented?  i'm not coming up with anything concrete when i
>   > search the wiki.  (or alternatively, i'm coming up with too much
>   > to wade through.)
>
>  two people have suggested (offlist, presumably to save me
>  embarrassment ;-)

Sorry, have changed MUAs recently and haven't got used to the Reply to
all button yet :/ Nothing to feel embarrassed that I can see ;)

> that i look more closely at:
>
>     http://wiki.laptop.org/go/Low-level_Activity_API
>
>  certainly this page answers my questions about the X properties that
>  are being set in the preload library.
>
>  both referrers asked if there were things missing from that page.
>  i'll try and comment on what i think could help someone like me.

Thanks, that's very much needed.

>  i do feel like that there could be more of a broad-brush
>  overview, something like a "Lifetime of an Activity" section,
>  that would describe the interactions of an activity with the
>  various other sugar services, from start to finish.  this would
>  put the various piece parts of the api in context.  i've looked
>  (mostly via backlinks from this page) for such an overview, but
>  haven't found it.

Looks like a good idea. Do you have enough info for starting it? I
will be glad to answer all questions.

>  maybe much of what i need is there and i'm just not seeing it.

Don't think so, there's very little manpower available for
development, less for documentation.

>  i get more from the wiki pages every time i read them, and i'm
>  handicapped by not being a python guy -- remember that i'm
>  porting an existing non-python, non-DBUS-aware app, and just
>  trying to make it run the best it can.  but i also think it's
>  typical of a wiki that it concentrate on the details.

You are right again, non-python developers are in disadvantage because
the higher level APIs have been coded in python as is much faster to
write and easier to maintain. We would like to be able to rewrite them
in C so these APIs can be accessed from other languages.

>  the "Dbus Methods" section starts with "An activity instance
>  needs to create a DBus service", but there's no indication of
>  "why?".  what specific user or system interactions will be
>  enabled by creating this service?  what specific things won't
>  work if i don't?  (also, a link to somehere describing how to
>  [figure out how to] create this service for non-python activities
>  might be useful here.)

Yes, other people have observed before that the documentation should
also explain the rationales behind the design decisions.

>   > my activity starts (and terminates) okay, and anything it emits
>   > on stdout or stderr ends up in a log file under /home/olpc/.sugar
>   > (so some things are working), and it appears on the "ring of
>   > running apps", but it doesn't show up in the journal.
>
>  ah -- okay -- the "Datastore" section says my app must store its
>  complete state in the datastore, to let it show up in the journal.
>  but i'm not sure what "complete state" means

All the data that your activity needs to restore its UI and underlying
model as it was when it was closed.

>  -- that's pretty
>  daunting, esp. for a program that already saves a lot of state in
>  other ways.

In which other ways? Can you elaborate?

>  is there a minimum that i need to do / can do?  and
>  this is all accessed via DBUS?  that's not completely clear from
>  the page text.  (and again, a pointer to how to figure out how
>  to access the datastore/journal from non-python languages might
>  be useful.)

Some activities have already done that. One that comes to my mind is eToys.

You certainly don't need to implement state saving to the perfection.
Having something working quickly and then keep improving would make
sense.

>  back to my logs:  naively, i thought that since my messages were
>  already being stored under ~/.sugar/default/logs/org.x.RoadMap-3.log,
>  that i'd be able to access them without much trouble from the
>  Journal.  but apparently that's not the case?

The Journal is the graphical front end of the datastore. The datastore
is a service that stores data and metadata and performs queries on
that. The Journal is not supposed to access arbitrary data on the file
system. If you explain what you want to do with the logs someone might
be able to help.

>  i guess this reminds me of something else -- for someone who's
>  fairly new at this, the correspondence between the concepts of
>  "Datastore" and "Journal" isn't obvious.  the wiki pages all talk
>  about the Datastore, but what the user sees is the Journal.  (i
>  think this hampered my initial searches, both when skimming pages
>  and when actually entering searches on the wiki.)
>
>  anyway -- thanks for the pointers -- i have a much better
>  understanding of what needs to be done, even if i still don't
>  know how to go about doing it. :-)  i hope my comments have been
>  helpful -- it should be pretty clear that i'm in no position to
>  make additions or updates to the wiki myself, at this point.
>  i'll try and help where and when i can, however.