[Sugar-devel] New Chapter in Make Your Own Sugar Activities needs review

[Bert Freudenberg]

On 28.03.2010, at 22:26, James Simmons wrote:
> 
> This PDF has the "Fun With The Journal" chapter updated using Bert
> Freudenberg's suggestions.  I've updated Sugar Commander based on
> these suggestions and it works better than ever, and thanks to Bert I
> understand parts of my own code that were mysterious before.
> 
> http://objavi.flossmanuals.net/books/ActivitiesGuideSugar-en-2010.03.28-22.20.52.pdf
> 
> James Simmons

You shouldn't encourage me to pick nits ;)

But since you did, I'll point out that Sugar Commander should watch changes in the datastore. E.g., when you modify an entry in the Commander and switch to the Journal, the Journal updates itself. If you change an entry in the Journal, the Commander would not reflect the change. Since the signals necessary for this to work are not exposed in the higher-level datastore abstractions, you need to go down to the D-Bus level (lifted from jarabe/journal/model.py):

	DS_DBUS_SERVICE = 'org.laptop.sugar.DataStore'
	DS_DBUS_INTERFACE = 'org.laptop.sugar.DataStore'
	DS_DBUS_PATH = '/org/laptop/sugar/DataStore'
	import dbus
        bus = dbus.SessionBus()
        remote_object = bus.get_object(DS_DBUS_SERVICE, DS_DBUS_PATH)
        _datastore = dbus.Interface(remote_object, DS_DBUS_INTERFACE)
        _datastore.connect_to_signal('Created', _datastore_created_cb)
        _datastore.connect_to_signal('Updated', _datastore_updated_cb)
        _datastore.connect_to_signal('Deleted', _datastore_deleted_cb)

In fact, if you did that, you wouldn't even have to keep track of "needs_reload". Writing the entry would trigger the Created or Updated callback, which should take care of refreshing the UI.

And something else I noticed ... but feel free to ignore ;)

In "ADDING A JOURNAL ENTRY" you do not mention that typically after write() you need to remove the original file. The Commander case is atypical, since you _copy_ a file to the datastore, you _want_ it to be duplicated. Normally when creating a datastore entry, one wants to avoid such duplication. So you would create a temporary file, add it to the datastore (which copies it to its database), and then delete it. That's what happens behind the scenes in the regular write_file() method. Now of the file was large, that copying to the datastore is inefficient. Therefore the write() method has an optional "transfer_ownership" argument, defaulting to False. If you set it to True, the datastore will _move_ the file to its database instead of copying. Of course that requires the datastore to be able to delete the file for you. The activity should place the temp file in the "instance" directory - otherwise, if Rainbow security is enabled, the deleting would not work. Also, the "instance" directory is designed to be on the same filesystem as the datastore itself, so the move does not require copying but just setting a hard link. 

And if you wanted to get really fancy you could mention how to add a progress bar while creating a datastore entry. You might have noticed the Browse activity doing that - if you start downloading a file and switch to the Journal, the entry shows a progress bar. If Sugar Commander copies a large file into the Journal, it could do the same. It could even grow the ability to download from FTP servers etc. ;)

Anyway. 

Some of this is mentioned in the Almanac, but it is inaccurate/outdated in places, and not exhaustive: 
http://wiki.sugarlabs.org/go/Development_Team/Almanac/sugar.datastore.datastore

I think the most up-to-date reference is at
http://wiki.sugarlabs.org/go/Development_Team/Low-level_Activity_API
but then, I'm biased ;)

- Bert -