Fun With The Journal
Introduction
By default every Activity creates and reads one Journal entry. Most Activities don't need to do any more with the Journal than that, and if your Activity is like that you won't need the information in this chapter. Chances are that someday you will want to do more than that, so if you do keep reading.
First let's review what the Journal is. The Journal is a collection of files that each have metadata (data about data) associated with them. Metadata is stored as text strings and includes such things as the Title, Description, Tags, MIME Type, and a screen shot of the Activity when it was last used.
Your Activity cannot read and write these files directly. Instead Sugar provides an API (Application Programming Interface) that gives you an indirect way to add, delete and modify entries in the Journal, as well as a way to search Journal entries and make a list of entries that meet the search criteria.
The API we'll use is in the datastore package. After version .82 of Sugar this API was rewritten, so we'll need to learn how to support both versions in the same Activity.
If you've read this far you've seen several examples where Sugar started out doing one thing and then changed to do the same thing a better way but still provided a way to create Activities that would work with either the old or the new way. You may be wondering if it is normal for a project to do this. As a professional programmer I can tell you that doing tricks like this to maintain backward compatibility is extremely common, and Sugar does no more of this than any other project. There are decisions made by Herman Hollerith when he tabulated the 1890 census using punched cards that computer programmers must live with to this day.
Introducing Sugar Commander
I am a big fan of the concept of the Journal but not so much of the Journal Activity that Sugar uses to navigate through it and maintain it. My biggest gripe against it is that it represents the contents of thumb drives and SD cards as if the files on these were also Journal entries. My feeling is that files and directories are one thing and the Journal is another, and the user interface should recognize that.
Strictly speaking the Journal Activity is and is not an Activity. It inherits code from the Activity class just like any other Activity, and it is written in Python and uses the same datastore API that other Activities use. However, it is run in a special way that gives it powers and abilities far beyond those of an ordinary Activity. In particular it can do two things:
- It can write to files on external media like thumb drives and SD cards.
- It alone can be used to resume Journal entries using other Activities.
While I would like to write a Journal Activity that does everything the original does but has a user interface more to my own taste the Sugar security model won't allow that. Recently I came to the conclusion that a more mild-mannered version of the Journal Activity might be useful. Just as Kal-El sometimes finds it more useful to be Clark Kent than Superman, my own Activity might be a worthy alternative to the built-in Journal Activity when super powers are not needed.
My Activity, which I call Sugar Commander, has two tabs. One represents the Journal and looks like this:
This tab lets you browse through the Journal sorted by Title or MIME Type, select entries and view their details, update Title, Description or Tags, and delete entries you no longer want. The other tab shows files and folders and looks like this:
This tab lets you browse through the files and folders or the regular file system, including thumb drives and SD cards. You can select a file and make a Journal entry out of it by pushing the button at the bottom of the screen.
This Activity has very little code and still manages to do everything an ordinary Activity can do with the Journal. You can download the Git repository using this command:
git clone git://git.sugarlabs.org/sugar-commander/\
mainline.git
There is only one source file, sugarcommander.py:
import logging
import os
import gtk
import pango
import zipfile
from sugar import mime
from sugar.activity import activity
from sugar.datastore import datastore
from sugar.graphics.alert import NotifyAlert
from sugar.graphics import style
from gettext import gettext as _
import gobject
import dbus
COLUMN_TITLE = 0
COLUMN_MIME = 1
COLUMN_JOBJECT = 2
DS_DBUS_SERVICE = 'org.laptop.sugar.DataStore'
DS_DBUS_INTERFACE = 'org.laptop.sugar.DataStore'
DS_DBUS_PATH = '/org/laptop/sugar/DataStore'
_logger = logging.getLogger('sugar-commander')
class SugarCommander(activity.Activity):
def __init__(self, handle, create_jobject=True):
"The entry point to the Activity"
activity.Activity.__init__(self, handle, False)
self.selected_journal_entry = None
self.selected_path = None
canvas = gtk.Notebook()
canvas.props.show_border = True
canvas.props.show_tabs = True
canvas.show()
self.ls_journal = gtk.ListStore(
gobject.TYPE_STRING,
gobject.TYPE_STRING,
gobject.TYPE_PYOBJECT)
self.tv_journal = gtk.TreeView(self.ls_journal)
self.tv_journal.set_rules_hint(True)
self.tv_journal.set_search_column(COLUMN_TITLE)
self.selection_journal = \
self.tv_journal.get_selection()
self.selection_journal.set_mode(
gtk.SELECTION_SINGLE)
self.selection_journal.connect("changed",
self.selection_journal_cb)
renderer = gtk.CellRendererText()
renderer.set_property('wrap-mode', gtk.WRAP_WORD)
renderer.set_property('wrap-width', 500)
renderer.set_property('width', 500)
self.col_journal = gtk.TreeViewColumn(_('Title'),
renderer, text=COLUMN_TITLE)
self.col_journal.set_sort_column_id(COLUMN_TITLE)
self.tv_journal.append_column(self.col_journal)
mime_renderer = gtk.CellRendererText()
mime_renderer.set_property('width', 500)
self.col_mime = gtk.TreeViewColumn(_('MIME'),
mime_renderer, text=COLUMN_MIME)
self.col_mime.set_sort_column_id(COLUMN_MIME)
self.tv_journal.append_column(self.col_mime)
self.list_scroller_journal = gtk.ScrolledWindow(
hadjustment=None, vadjustment=None)
self.list_scroller_journal.set_policy(
gtk.POLICY_AUTOMATIC, gtk.POLICY_AUTOMATIC)
self.list_scroller_journal.add(self.tv_journal)
label_attributes = pango.AttrList()
label_attributes.insert(pango.AttrSize(
14000, 0, -1))
label_attributes.insert(pango.AttrForeground(
65535, 65535, 65535, 0, -1))
tab1_label = gtk.Label(_("Journal"))
tab1_label.set_attributes(label_attributes)
tab1_label.show()
self.tv_journal.show()
self.list_scroller_journal.show()
column_table = gtk.Table(rows=1, columns=2,
homogeneous = False)
image_table = gtk.Table(rows=2, columns=2,
homogeneous=False)
self.image = gtk.Image()
image_table.attach(self.image, 0, 2, 0, 1,
xoptions=gtk.FILL|gtk.SHRINK,
yoptions=gtk.FILL|gtk.SHRINK,
xpadding=10,
ypadding=10)
self.btn_save = gtk.Button(_("Save"))
self.btn_save.connect('button_press_event',
self.save_button_press_event_cb)
image_table.attach(self.btn_save, 0, 1, 1, 2,
xoptions=gtk.SHRINK,
yoptions=gtk.SHRINK, xpadding=10,
ypadding=10)
self.btn_save.props.sensitive = False
self.btn_save.show()
self.btn_delete = gtk.Button(_("Delete"))
self.btn_delete.connect('button_press_event',
self.delete_button_press_event_cb)
image_table.attach(self.btn_delete, 1, 2, 1, 2,
xoptions=gtk.SHRINK,
yoptions=gtk.SHRINK, xpadding=10,
ypadding=10)
self.btn_delete.props.sensitive = False
self.btn_delete.show()
column_table.attach(image_table, 0, 1, 0, 1,
xoptions=gtk.FILL|gtk.SHRINK,
yoptions=gtk.SHRINK, xpadding=10,
ypadding=10)
entry_table = gtk.Table(rows=3, columns=2,
homogeneous=False)
title_label = gtk.Label(_("Title"))
entry_table.attach(title_label, 0, 1, 0, 1,
xoptions=gtk.SHRINK,
yoptions=gtk.SHRINK,
xpadding=10, ypadding=10)
title_label.show()
self.title_entry = gtk.Entry(max=0)
entry_table.attach(self.title_entry, 1, 2, 0, 1,
xoptions=gtk.FILL|gtk.SHRINK,
yoptions=gtk.SHRINK, xpadding=10, ypadding=10)
self.title_entry.connect('key_press_event',
self.key_press_event_cb)
self.title_entry.show()
description_label = gtk.Label(_("Description"))
entry_table.attach(description_label, 0, 1, 1, 2,
xoptions=gtk.SHRINK,
yoptions=gtk.SHRINK,
xpadding=10, ypadding=10)
description_label.show()
self.description_textview = gtk.TextView()
self.description_textview.set_wrap_mode(
gtk.WRAP_WORD)
entry_table.attach(self.description_textview,
1, 2, 1, 2,
xoptions=gtk.EXPAND|gtk.FILL|gtk.SHRINK,
yoptions=gtk.EXPAND|gtk.FILL|gtk.SHRINK,
xpadding=10, ypadding=10)
self.description_textview.props.accepts_tab = False
self.description_textview.connect('key_press_event',
self.key_press_event_cb)
self.description_textview.show()
tags_label = gtk.Label(_("Tags"))
entry_table.attach(tags_label, 0, 1, 2, 3,
xoptions=gtk.SHRINK,
yoptions=gtk.SHRINK,
xpadding=10, ypadding=10)
tags_label.show()
self.tags_textview = gtk.TextView()
self.tags_textview.set_wrap_mode(gtk.WRAP_WORD)
entry_table.attach(self.tags_textview, 1, 2, 2, 3,
xoptions=gtk.FILL,
yoptions=gtk.EXPAND|gtk.FILL,
xpadding=10, ypadding=10)
self.tags_textview.props.accepts_tab = False
self.tags_textview.connect('key_press_event',
self.key_press_event_cb)
self.tags_textview.show()
entry_table.show()
self.scroller_entry = gtk.ScrolledWindow(
hadjustment=None, vadjustment=None)
self.scroller_entry.set_policy(gtk.POLICY_NEVER,
gtk.POLICY_AUTOMATIC)
self.scroller_entry.add_with_viewport(entry_table)
self.scroller_entry.show()
column_table.attach(self.scroller_entry,
1, 2, 0, 1,
xoptions=gtk.FILL|gtk.EXPAND|gtk.SHRINK,
yoptions=gtk.FILL|gtk.EXPAND|gtk.SHRINK,
xpadding=10, ypadding=10)
image_table.show()
column_table.show()
vbox = gtk.VBox(homogeneous=True, spacing=5)
vbox.pack_start(column_table)
vbox.pack_end(self.list_scroller_journal)
canvas.append_page(vbox, tab1_label)
self._filechooser = gtk.FileChooserWidget(
action=gtk.FILE_CHOOSER_ACTION_OPEN,
backend=None)
self._filechooser.set_current_folder("/media")
self.copy_button = gtk.Button(
_("Copy File To The Journal"))
self.copy_button.connect('clicked',
self.create_journal_entry)
self.copy_button.show()
self._filechooser.set_extra_widget(self.copy_button)
preview = gtk.Image()
self._filechooser.set_preview_widget(preview)
self._filechooser.connect("update-preview",
self.update_preview_cb, preview)
tab2_label = gtk.Label(_("Files"))
tab2_label.set_attributes(label_attributes)
tab2_label.show()
canvas.append_page(self._filechooser, tab2_label)
self.set_canvas(canvas)
self.show_all()
toolbox = activity.ActivityToolbox(self)
activity_toolbar = toolbox.get_activity_toolbar()
activity_toolbar.keep.props.visible = False
activity_toolbar.share.props.visible = False
self.set_toolbox(toolbox)
toolbox.show()
self.load_journal_table()
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',
self.datastore_created_cb)
_datastore.connect_to_signal('Updated',
self.datastore_updated_cb)
_datastore.connect_to_signal('Deleted',
self.datastore_deleted_cb)
self.selected_journal_entry = None
def update_preview_cb(self, file_chooser, preview):
filename = file_chooser.get_preview_filename()
try:
file_mimetype = mime.get_for_file(filename)
if file_mimetype.startswith('image/'):
pixbuf = \
gtk.gdk.pixbuf_new_from_file_at_size(
filename,
style.zoom(320), style.zoom(240))
preview.set_from_pixbuf(pixbuf)
have_preview = True
elif file_mimetype == 'application/x-cbz':
fname = self.extract_image(filename)
pixbuf = \
gtk.gdk.pixbuf_new_from_file_at_size(
fname,
style.zoom(320), style.zoom(240))
preview.set_from_pixbuf(pixbuf)
have_preview = True
os.remove(fname)
else:
have_preview = False
except:
have_preview = False
file_chooser.set_preview_widget_active(
have_preview)
return
def key_press_event_cb(self, entry, event):
self.btn_save.props.sensitive = True
def save_button_press_event_cb(self, entry, event):
self.update_entry()
def delete_button_press_event_cb(self, entry, event):
datastore.delete(
self.selected_journal_entry.object_id)
def datastore_created_cb(self, uid):
new_jobject = datastore.get(uid)
iter = self.ls_journal.append()
title = new_jobject.metadata['title']
self.ls_journal.set(iter, COLUMN_TITLE, title)
mime = new_jobject.metadata['mime_type']
self.ls_journal.set(iter, COLUMN_MIME, mime)
self.ls_journal.set(iter, COLUMN_JOBJECT,
new_jobject)
def datastore_updated_cb(self, uid):
new_jobject = datastore.get(uid)
iter = self.ls_journal.get_iter_first()
for row in self.ls_journal:
jobject = row[COLUMN_JOBJECT]
if jobject.object_id == uid:
title = new_jobject.metadata['title']
self.ls_journal.set_value(iter,
COLUMN_TITLE, title)
break
iter = self.ls_journal.iter_next(iter)
object_id = self.selected_journal_entry.object_id
if object_id == uid:
self.set_form_fields(new_jobject)
def datastore_deleted_cb(self, uid):
save_path = self.selected_path
iter = self.ls_journal.get_iter_first()
for row in self.ls_journal:
jobject = row[COLUMN_JOBJECT]
if jobject.object_id == uid:
self.ls_journal.remove(iter)
break
iter = self.ls_journal.iter_next(iter)
try:
self.selection_journal.select_path(save_path)
self.tv_journal.grab_focus()
except:
self.title_entry.set_text('')
description_textbuffer = \
self.description_textview.get_buffer()
description_textbuffer.set_text('')
tags_textbuffer = \
self.tags_textview.get_buffer()
tags_textbuffer.set_text('')
self.btn_save.props.sensitive = False
self.btn_delete.props.sensitive = False
self.image.clear()
self.image.show()
def update_entry(self):
needs_update = False
if self.selected_journal_entry is None:
return
object_id = self.selected_journal_entry.object_id
jobject = datastore.get(object_id)
old_title = jobject.metadata.get('title', None)
if old_title != self.title_entry.props.text:
jobject.metadata['title'] = \
self.title_entry.props.text
jobject.metadata['title_set_by_user'] = '1'
needs_update = True
old_tags = jobject.metadata.get('tags', None)
new_tags = \
self.tags_textview.props.buffer.props.text
if old_tags != new_tags:
jobject.metadata['tags'] = new_tags
needs_update = True
old_description = jobject.metadata.get(
'description', None)
new_description = \
self.description_textview.props.buffer.props.text
if old_description != new_description:
jobject.metadata['description'] = new_description
needs_update = True
if needs_update:
datastore.write(jobject, update_mtime=False,
reply_handler=self.datastore_write_cb,
error_handler=self.datastore_write_error_cb)
self.btn_save.props.sensitive = False
def datastore_write_cb(self):
pass
def datastore_write_error_cb(self, error):
logging.error(
'sugarcommander.datastore_write_error_cb:'
' %r' % error)
def close(self, skip_save=False):
"Override the close method so we don't try to
create a Journal entry."
activity.Activity.close(self, True)
def selection_journal_cb(self, selection):
self.btn_delete.props.sensitive = True
tv = selection.get_tree_view()
model = tv.get_model()
sel = selection.get_selected()
if sel:
model, iter = sel
jobject = model.get_value(iter,COLUMN_JOBJECT)
jobject = datastore.get(jobject.object_id)
self.selected_journal_entry = jobject
self.set_form_fields(jobject)
self.selected_path = model.get_path(iter)
def set_form_fields(self, jobject):
self.title_entry.set_text(jobject.metadata['title'])
description_textbuffer = \
self.description_textview.get_buffer()
if jobject.metadata.has_key('description'):
description_textbuffer.set_text(
jobject.metadata['description'])
else:
description_textbuffer.set_text('')
tags_textbuffer = self.tags_textview.get_buffer()
if jobject.metadata.has_key('tags'):
tags_textbuffer.set_text(jobject.metadata['tags'])
else:
tags_textbuffer.set_text('')
self.create_preview(jobject.object_id)
def create_preview(self, object_id):
jobject = datastore.get(object_id)
if jobject.metadata.has_key('preview'):
preview = jobject.metadata['preview']
if preview is None or preview == '' \
or preview == 'None':
if jobject.metadata['mime_type'].startswith(
'image/'):
filename = jobject.get_file_path()
self.show_image(filename)
return
if jobject.metadata['mime_type'] == \
'application/x-cbz':
filename = jobject.get_file_path()
fname = self.extract_image(filename)
self.show_image(fname)
os.remove(fname)
return
if jobject.metadata.has_key('preview') and \
len(jobject.metadata['preview']) > 4:
if jobject.metadata['preview'][1:4] == 'PNG':
preview_data = jobject.metadata['preview']
else:
import base64
preview_data = \
base64.b64decode(
jobject.metadata['preview'])
loader = gtk.gdk.PixbufLoader()
loader.write(preview_data)
scaled_buf = loader.get_pixbuf()
loader.close()
self.image.set_from_pixbuf(scaled_buf)
self.image.show()
else:
self.image.clear()
self.image.show()
def load_journal_table(self):
self.btn_save.props.sensitive = False
self.btn_delete.props.sensitive = False
ds_mounts = datastore.mounts()
mountpoint_id = None
if len(ds_mounts) == 1 and \
ds_mounts[0]['id'] == 1:
pass
else:
for mountpoint in ds_mounts:
id = mountpoint['id']
uri = mountpoint['uri']
if uri.startswith('/home'):
mountpoint_id = id
query = {}
if mountpoint_id is not None:
query['mountpoints'] = [ mountpoint_id ]
ds_objects, num_objects = \
datastore.find(query, properties=['uid',
'title', 'mime_type'])
self.ls_journal.clear()
for i in xrange (0, num_objects, 1):
iter = self.ls_journal.append()
title = ds_objects[i].metadata['title']
self.ls_journal.set(iter, COLUMN_TITLE, title)
mime = ds_objects[i].metadata['mime_type']
self.ls_journal.set(iter, COLUMN_MIME, mime)
self.ls_journal.set(iter, COLUMN_JOBJECT,
ds_objects[i])
if not self.selected_journal_entry is None and \
self.selected_journal_entry.object_id == \
ds_objects[i].object_id:
self.selection_journal.select_iter(iter)
self.ls_journal.set_sort_column_id(COLUMN_TITLE,
gtk.SORT_ASCENDING)
v_adjustment = \
self.list_scroller_journal.get_vadjustment()
v_adjustment.value = 0
return ds_objects[0]
def create_journal_entry(self, widget, data=None):
filename = self._filechooser.get_filename()
journal_entry = datastore.create()
journal_entry.metadata['title'] = \
self.make_new_filename(filename)
journal_entry.metadata['title_set_by_user'] = '1'
journal_entry.metadata['keep'] = '0'
file_mimetype = mime.get_for_file(filename)
if not file_mimetype is None:
journal_entry.metadata['mime_type'] = \
file_mimetype
journal_entry.metadata['buddies'] = ''
if file_mimetype.startswith('image/'):
preview = \
self.create_preview_metadata(filename)
elif file_mimetype == 'application/x-cbz':
fname = self.extract_image(filename)
preview = self.create_preview_metadata(fname)
os.remove(fname)
else:
preview = ''
if not preview == '':
journal_entry.metadata['preview'] = \
dbus.ByteArray(preview)
else:
journal_entry.metadata['preview'] = ''
journal_entry.file_path = filename
datastore.write(journal_entry)
self.alert(_('Success'), _('%s added to Journal.')
% self.make_new_filename(filename))
def alert(self, title, text=None):
alert = NotifyAlert(timeout=20)
alert.props.title = title
alert.props.msg = text
self.add_alert(alert)
alert.connect('response', self.alert_cancel_cb)
alert.show()
def alert_cancel_cb(self, alert, response_id):
self.remove_alert(alert)
def show_image(self, filename):
"display a resized image in a preview"
scaled_buf = gtk.gdk.pixbuf_new_from_file_at_size(
filename,
style.zoom(320), style.zoom(240))
self.image.set_from_pixbuf(scaled_buf)
self.image.show()
def extract_image(self, filename):
zf = zipfile.ZipFile(filename, 'r')
image_files = zf.namelist()
image_files.sort()
file_to_extract = image_files[0]
extract_new_filename = self.make_new_filename(
file_to_extract)
if extract_new_filename is None or \
extract_new_filename == '':
# skip over directory name if the images
# are in a subdirectory.
file_to_extract = image_files[1]
extract_new_filename = self.make_new_filename(
file_to_extract)
if len(image_files) > 0:
if self.save_extracted_file(zf, file_to_extract):
fname = os.path.join(self.get_activity_root(),
'instance',
extract_new_filename)
return fname
def save_extracted_file(self, zipfile, filename):
"Extract the file to a temp directory for viewing"
try:
filebytes = zipfile.read(filename)
except zipfile.BadZipfile, err:
print 'Error opening the zip file: %s' % (err)
return False
except KeyError, err:
self.alert('Key Error', 'Zipfile key not found: '
+ str(filename))
return
outfn = self.make_new_filename(filename)
if (outfn == ''):
return False
fname = os.path.join(self.get_activity_root(),
'instance', outfn)
f = open(fname, 'w')
try:
f.write(filebytes)
finally:
f.close()
return True
def make_new_filename(self, filename):
partition_tuple = filename.rpartition('/')
return partition_tuple[2]
def create_preview_metadata(self, filename):
file_mimetype = mime.get_for_file(filename)
if not file_mimetype.startswith('image/'):
return ''
scaled_pixbuf = \
gtk.gdk.pixbuf_new_from_file_at_size(
filename,
style.zoom(320), style.zoom(240))
preview_data = []
def save_func(buf, data):
data.append(buf)
scaled_pixbuf.save_to_callback(save_func,
'png',
user_data=preview_data)
preview_data = ''.join(preview_data)
return preview_data
Let's look at this code one method at a time.
Adding A Journal Entry
We add a Journal entry when someone pushes a button on the gtk.FileChooser. This is the code that gets run:
def create_journal_entry(self, widget, data=None):
filename = self._filechooser.get_filename()
journal_entry = datastore.create()
journal_entry.metadata['title'] = \
self.make_new_filename(
filename)
journal_entry.metadata['title_set_by_user'] = '1'
journal_entry.metadata['keep'] = '0'
file_mimetype = mime.get_for_file(filename)
if not file_mimetype is None:
journal_entry.metadata['mime_type'] = \
file_mimetype
journal_entry.metadata['buddies'] = ''
if file_mimetype.startswith('image/'):
preview = self.create_preview_metadata(filename)
elif file_mimetype == 'application/x-cbz':
fname = self.extract_image(filename)
preview = self.create_preview_metadata(fname)
os.remove(fname)
else:
preview = ''
if not preview == '':
journal_entry.metadata['preview'] = \
dbus.ByteArray(preview)
else:
journal_entry.metadata['preview'] = ''
journal_entry.file_path = filename
datastore.write(journal_entry)
The only thing worth commenting on here is the metadata. title is what appears as #3 in the picture below. title_set_by_user is set to 1 so that the Activity won't prompt the user to change the title when the Activity closes. keep refers to the little star that appears at the beginning of the Journal entry (see #1 in the picture below). Highlight it by setting this to 1, otherwise set to 0. buddies is a list of users that collaborated on the Journal entry, and in this case there aren't any (these show up as #4 in the picture below).
preview is an image file in the PNG format that is a screenshot of the Activity in action. This is created by the Activity itself when it is run so there is no need to make one when you add a Journal entry. You can simply use an empty string ('') for this property.
Because previews are much more visible in Sugar Commander than they are in the regular Journal Activity I decided that Sugar Commander should make a preview image for image files and comic books as soon as they are added to the Journal. To do this I made a pixbuf of the image that would fit within the scaled dimensions of 320x240 pixels and made a dbus.ByteArray out of it, which is the format that the Journal uses to store preview images.
mime_type describes the format of the file and is generally assigned based on the filename suffix. For instance, files ending in .html have a MIME type of 'text/html'. Python has a package called mimetypes that takes a file name and figures out what its MIME type should be, but Sugar provides its own package to do the same thing. For most files either one would give the correct answer, but Sugar has its own MIME types for things like Activity bundles, etc. so for best results you really should use Sugar's mime package. You can import it like this:
from sugar import mime
The rest of the metadata (icon, modified time) is created automatically.
NOT Adding A Journal Entry
Sugar Activities by default create a Journal entry using the write_file() method. There will be Activities that don't need to do this. For instance, Get Internet Archive Books downloads e-books to the Journal, but has no need for a Journal entry of its own. The same thing is true of Sugar Commander. You might make a game that keeps track of high scores. You could keep those scores in a Journal entry, but that would require players to resume the game from the Journal rather than just starting it up from the Activity Ring. For that reason you might prefer to store the high scores in a file in the data directory rather than the Journal, and not leave a Journal entry behind at all.
Sugar gives you a way to do that. First you need to specify an extra argument in your Activity's __init__() method like this:
class SugarCommander(activity.Activity):
def __init__(self, handle, create_jobject=True):
"The entry point to the Activity"
activity.Activity.__init__(self, handle, False)
Second, you need to override the close() method like this:
def close(self, skip_save=False):
"Override the close method so we don't try to
create a Journal entry."
activity.Activity.close(self, True)
That's all there is to it.
Listing Out Journal Entries
If you need to list out Journal entries you can use the find() method of datastore. The find method takes an argument containing search criteria. If you want to search for image files you can search by mime-type using a statement like this:
ds_objects, num_objects = datastore.find(
{'mime_type':['image/jpeg',
'image/gif', 'image/tiff', 'image/png']},
properties=['uid',
'title', 'mime_type']))
You can use any metadata attribute to search on. If you want to list out everything in the Journal you can use an empty search criteria like this:
ds_objects, num_objects = datastore.find({},
properties=['uid',
'title', 'mime_type']))
The properties argument specifies what metadata to return for each object in the list. You should limit these to what you plan to use, but always include uid. One thing you should never include in a list is preview. This is an image file showing what the Activity for the Journal object looked like when it was last used. If for some reason you need this there is a simple way to get it for an individual Journal object, but you never want to include it in a list because it will slow down your Activity enormously.
Listing out what is in the Journal is complicated because of the datastore rewrite done for Sugar .84. Before .84 the datastore.find() method listed out both Journal entries and files on external media like thumb drives and SD cards and you need to figure out which is which. In .84 and later it only lists out Journal entries. Fortunately it is possible to write code that supports either behavior. Here is code in Sugar Commander that only lists Journal entries:
def load_journal_table(self):
self.btn_save.props.sensitive = False
self.btn_delete.props.sensitive = False
ds_mounts = datastore.mounts()
mountpoint_id = None
if len(ds_mounts) == 1 and ds_mounts[0]['id'] == 1:
pass
else:
for mountpoint in ds_mounts:
id = mountpoint['id']
uri = mountpoint['uri']
if uri.startswith('/home'):
mountpoint_id = id
query = {}
if mountpoint_id is not None:
query['mountpoints'] = [ mountpoint_id ]
ds_objects, num_objects = datastore.find(
query, properties=['uid',
'title', 'mime_type'])
self.ls_journal.clear()
for i in xrange (0, num_objects, 1):
iter = self.ls_journal.append()
title = ds_objects[i].metadata['title']
self.ls_journal.set(iter,
COLUMN_TITLE, title)
mime = ds_objects[i].metadata['mime_type']
self.ls_journal.set(iter, COLUMN_MIME, mime)
self.ls_journal.set(iter, COLUMN_JOBJECT,
ds_objects[i])
if not self.selected_journal_entry is None and \
self.selected_journal_entry.object_id == \
ds_objects[i].object_id:
self.selection_journal.select_iter(iter)
self.ls_journal.set_sort_column_id(COLUMN_TITLE,
gtk.SORT_ASCENDING)
v_adjustment = \
self.list_scroller_journal.get_vadjustment()
v_adjustment.value = 0
return ds_objects[0]
We need to use the datastore.mounts() method for two purposes:
- In Sugar .82 and below it will list out all mount points, including the place the Journal is mounted on and the places external media is mounted on. The mountpoint is a Python dictionary that contains a uri property (which is the path to the mount point) and an id property (which is a name given to the mount point). Every Journal entry has a metadata attribute named mountpoint. The Journal uri will be the only one starting with /home, so if we limit the search to Journal objects where the id of that mountpoint equals the mountpoint metadata in the Journal objects we can easily list only objects from the Journal.
- In Sugar .84 and later the datastore.mounts() method still exists but doesn't tell you anything about mountpoints. However, you can use the code above to see if there is only one mountpoint and if its id is 1. If it is you know you're dealing with the rewritten datastore of .84 and later. The other difference is that the Journal objects no longer have metadata with a key of mountpoint. If you use the code above it will account for this difference and work with either version of Sugar.
What if you want the Sugar .82 behavior, listing both Journal entries and USB files as Journal objects, in both .82 and .84 and up? I wanted to do that for View Slides and ended up using this code:
def load_journal_table(self):
ds_objects, num_objects = datastore.find(
{'mime_type':['image/jpeg',
'image/gif', 'image/tiff', 'image/png']},
properties=['uid', 'title', 'mime_type'])
self.ls_right.clear()
for i in xrange (0, num_objects, 1):
iter = self.ls_right.append()
title = ds_objects[i].metadata['title']
mime_type = ds_objects[i].metadata['mime_type']
if mime_type == 'image/jpeg' \
and not title.endswith('.jpg') \
and not title.endswith('.jpeg') \
and not title.endswith('.JPG') \
and not title.endswith('.JPEG') :
title = title + '.jpg'
if mime_type == 'image/png' \
and not title.endswith('.png') \
and not title.endswith('.PNG'):
title = title + '.png'
if mime_type == 'image/gif' \
and not title.endswith('.gif')\
and not title.endswith('.GIF'):
title = title + '.gif'
if mime_type == 'image/tiff' \
and not title.endswith('.tiff')\
and not title.endswith('.TIFF'):
title = title + '.tiff'
self.ls_right.set(iter, COLUMN_IMAGE, title)
jobject_wrapper = JobjectWrapper()
jobject_wrapper.set_jobject(ds_objects[i])
self.ls_right.set(iter, COLUMN_PATH,
jobject_wrapper)
valid_endings = ('.jpg', '.jpeg', '.JPEG',
'.JPG', '.gif', '.GIF', '.tiff',
'.TIFF', '.png', '.PNG')
ds_mounts = datastore.mounts()
if len(ds_mounts) == 1 and ds_mounts[0]['id'] == 1:
# datastore.mounts() is stubbed out,
# we're running .84 or better
for dirname, dirnames, filenames in os.walk(
'/media'):
if '.olpc.store' in dirnames:
dirnames.remove('.olpc.store')
# don't visit .olpc.store directories
for filename in filenames:
if filename.endswith(valid_endings):
iter = self.ls_right.append()
jobject_wrapper = JobjectWrapper()
jobject_wrapper.set_file_path(
os.path.join(dirname, filename))
self.ls_right.set(iter, COLUMN_IMAGE,
filename)
self.ls_right.set(iter, COLUMN_PATH,
jobject_wrapper)
self.ls_right.set_sort_column_id(COLUMN_IMAGE,
gtk.SORT_ASCENDING)
In this case I use the datastore.mounts() method to figure out what version of the datastore I have and then if I'm running .84 and later I use os.walk() to create a flat list of all files in all directories found under the directory /media (which is where USB and SD cards are always mounted). I can't make these files into directories, but what I can do is make a wrapper class that can contain either a Journal object or a file and use those objects where I would normally use Journal objects. The wrapper class looks like this:
class JobjectWrapper():
def __init__(self):
self.__jobject = None
self.__file_path = None
def set_jobject(self, jobject):
self.__jobject = jobject
def set_file_path(self, file_path):
self.__file_path = file_path
def get_file_path(self):
if self.__jobject != None:
return self.__jobject.get_file_path()
else:
return self.__file_path
Using Journal Entries
When you're ready to read a file stored in a Journal object you can use the get_file_path() method of the Journal object to get a file path and open it for reading, like this:
fname = jobject.get_file_path()
One word of caution: be aware that this path does not exist until you call get_file_path() and will not exist long after. With the Journal you work with copies of files in the Journal, not the originals. For that reason you don't want to store the return value of get_file_path() for later use because later it may not be valid. Instead, store the Journal object itself and call the method right before you need the path.
Metadata entries for Journal objects generally contain strings and work the way you would expect, with one exception, which is the preview.
def create_preview(self, object_id):
jobject = datastore.get(object_id)
if jobject.metadata.has_key('preview'):
preview = jobject.metadata['preview']
if preview is None or preview == '' or
preview == 'None':
if jobject.metadata['mime_type'].startswith(
'image/'):
filename = jobject.get_file_path()
self.show_image(filename)
return
if jobject.metadata['mime_type'] == \
'application/x-cbz':
filename = jobject.get_file_path()
fname = self.extract_image(filename)
self.show_image(fname)
os.remove(fname)
return
if jobject.metadata.has_key('preview') and \
len(jobject.metadata['preview']) > 4:
if jobject.metadata['preview'][1:4] == 'PNG':
preview_data = jobject.metadata['preview']
else:
import base64
preview_data = base64.b64decode(
jobject.metadata['preview'])
loader = gtk.gdk.PixbufLoader()
loader.write(preview_data)
scaled_buf = loader.get_pixbuf()
loader.close()
self.image.set_from_pixbuf(scaled_buf)
self.image.show()
else:
self.image.clear()
self.image.show()
The preview metadata attribute is different in two ways:
- We should never request preview as metadata to be returned in our list of Journal objects. We'll need to get a complete copy of the Journal object to get it. Since we already have a Journal object we can get the complete Journal object by getting its object id then requesting a new copy from the datastore using the id.
- The preview image is a binary object (dbus.ByteArray) but in versions of Sugar older than .82 it will be stored as a text string. To accomplish this it is base 64 encoded.
The code you would use to get a complete copy of a Journal object looks like this:
object_id = jobject.object_id
jobject = datastore.get(object_id)
Now for an explanation of base 64 encoding. You've probably heard that computers use the base two numbering system, in which the only digits used are 1 and 0. A unit of data storage that can hold either a zero or a one is called a bit. Computers need to store information besides numbers, so to accomodate this we group bits into groups of 8 (usually) and these groups are called bytes. If you only use 7 of the 8 bits in a byte you can store a letter of the Roman alphabet, a punctuation mark, or a single digit, plus things like tabs and line feed characters. Any file that can be created using only 7 bits out of the 8 is called a text file. Everything that needs all 8 bits of each byte to make, including computer programs, movies, music, and pictures of Jessica Alba is a binary. In versions of Sugar before .82 Journal object metadata can only store text strings. Somehow we need to represent 8-bit bytes in 7 bits. We do this by grouping the bytes together into a larger collection of bits and then splitting them back out into groups of 7 bits. Python has the base64 package to do this for us.
Base 64 encoding is actually a pretty common technique. If you've ever sent an email with an attached file the file was base 64 encoded.
The code above has a couple of ways of creating a preview image. If the preview metadata contains a PNG image it is loaded into a pixbuf and displayed. If there is no preview metadata but the MIME type is for an image file or a comic book zip file we create the preview from the Journal entry itself.
The code checks the first three characters of the preview metadata to see if they are 'PNG'. If so, the file is a Portable Network Graphics image stored as a binary and does not need to be converted from base 64 encoding, otherwise it does.
Updating A Journal Object
The code to update a Journal object looks like this:
def update_entry(self):
needs_update = False
if self.selected_journal_entry is None:
return
object_id = self.selected_journal_entry.object_id
jobject = datastore.get(object_id)
old_title = jobject.metadata.get('title', None)
if old_title != self.title_entry.props.text:
jobject.metadata['title'] = \
self.title_entry.props.text
jobject.metadata['title_set_by_user'] = '1'
needs_update = True
old_tags = jobject.metadata.get('tags', None)
new_tags = \
self.tags_textview.props.buffer.props.text
if old_tags != new_tags:
jobject.metadata['tags'] = new_tags
needs_update = True
old_description = \
jobject.metadata.get('description', None)
new_description = \
self.description_textview.props.buffer.props.text
if old_description != new_description:
jobject.metadata['description'] = \
new_description
needs_update = True
if needs_update:
datastore.write(jobject, update_mtime=False,
reply_handler=self.datastore_write_cb,
error_handler=self.datastore_write_error_cb)
self.btn_save.props.sensitive = False
def datastore_write_cb(self):
pass
def datastore_write_error_cb(self, error):
logging.error(
'sugarcommander.datastore_write_error_cb:'
' %r' % error)
Deleting A Journal Entry
The code to delete a Journal entry is this:
def delete_button_press_event_cb(self, entry, event):
datastore.delete(
self.selected_journal_entry.object_id)
Getting Callbacks From The Journal Using D-Bus
In the chapter on Making Shared Activities we saw how D-Bus calls sent over Telepathy Tubes could be used to send messages from an Activity running on one computer to the same Activity running on a different computer. D-Bus is not normally used that way; typically it is used to send messages between programs running on the same computer.
For example, if you're working with the Journal you can get callbacks whenever the Journal is updated. You get the callbacks whether the update was done by your Activity or elsewhere. If it is important for your Activity to know when the Journal has been updated you'll want to get these callbacks.
The first thing you need to do is define some constants and import the dbus package:
DS_DBUS_SERVICE = 'org.laptop.sugar.DataStore' DS_DBUS_INTERFACE = 'org.laptop.sugar.DataStore' DS_DBUS_PATH = '/org/laptop/sugar/DataStore' import dbus
Next, in your __init__() method put code to connect to the signals and do the callbacks:
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',
self._datastore_created_cb)
_datastore.connect_to_signal('Updated',
self._datastore_updated_cb)
_datastore.connect_to_signal('Deleted',
self._datastore_deleted_cb)
The methods being run by the callbacks might look something like this:
def datastore_created_cb(self, uid):
new_jobject = datastore.get(uid)
iter = self.ls_journal.append()
title = new_jobject.metadata['title']
self.ls_journal.set(iter,
COLUMN_TITLE, title)
mime = new_jobject.metadata['mime_type']
self.ls_journal.set(iter,
COLUMN_MIME, mime)
self.ls_journal.set(iter,
COLUMN_JOBJECT, new_jobject)
def datastore_updated_cb(self, uid):
new_jobject = datastore.get(uid)
iter = self.ls_journal.get_iter_first()
for row in self.ls_journal:
jobject = row[COLUMN_JOBJECT]
if jobject.object_id == uid:
title = new_jobject.metadata['title']
self.ls_journal.set_value(iter,
COLUMN_TITLE, title)
break
iter = self.ls_journal.iter_next(iter)
object_id = \
self.selected_journal_entry.object_id
if object_id == uid:
self.set_form_fields(new_jobject)
def datastore_deleted_cb(self, uid):
save_path = self.selected_path
iter = self.ls_journal.get_iter_first()
for row in self.ls_journal:
jobject = row[COLUMN_JOBJECT]
if jobject.object_id == uid:
self.ls_journal.remove(iter)
break
iter = self.ls_journal.iter_next(iter)
try:
self.selection_journal.select_path(
save_path)
self.tv_journal.grab_focus()
except:
self.title_entry.set_text('')
description_textbuffer = \
self.description_textview.get_buffer()
description_textbuffer.set_text('')
tags_textbuffer = \
self.tags_textview.get_buffer()
tags_textbuffer.set_text('')
self.btn_save.props.sensitive = False
self.btn_delete.props.sensitive = False
self.image.clear()
self.image.show()
The uid passed to each callback method is the object id of the Journal object that has been added, updated, or deleted. If an entry is added to the Journal I get the Journal object from the datastore by its uid, then add it to the gtk.ListStore for the gtk.TreeModel I'm using to list out Journal entries. If an entry is updated or deleted I need to account for the possibility that the Journal entry I am viewing or editing may have been updated or removed. I use the uid to figure out which row in the gtk.ListStore needs to be removed or modified by looping through the entries in the gtk.ListStore looking for a match.
Now you know everything you'll ever need to know to work with the Journal.