MAKE YOUR OWN SUGAR ACTIVITIES!
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 user interface 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.
In the early days of Sugar the Journal was and was not an Activity. It inherited code from the Activity class just like any other Activity, and it was written in Python and used the same datastore API that other Activities used. However, it was run in a special way that gave it powers and abilities far beyond those of an ordinary Activity. In particular it could do two things:
- It could write to files on external media like thumb drives and SD cards.
- It alone could be used to resume Journal entries using other Activities.
In recent versions of Sugar the Journal window no longer extends the Activity class, but it does still use the same datastore API that Activities use. In earlier versions of this book I called the Journal interface the Journal Activity, but it isn't correct to call it that anymore.
I wanted to write a Journal Activity that does everything the original did but has a user interface more to my own taste, but 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 window 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.gitThere is only one source file, sugarcommander.py:
import logging
import os
import time
from sugar3.activity import activity
from sugar3.activity.widgets import ActivityToolbar, StopButton
from gi.repository import Gtk
from gi.repository import Gdk
from gi.repository import cairo
from gi.repository import Pango
from gi.repository import PangoCairo
from gi.repository import GdkPixbuf
from sugar3.activity import widgets
from sugar3.graphics.toolbarbox import ToolbarBox
from sugar3 import mime
from sugar3.datastore import datastore
from sugar3.graphics.alert import NotifyAlert
from sugar3.graphics import style
from gettext import gettext as _
import pygame
import zipfile
from gi.repository import GObject
import dbus
COLUMN_TITLE = 0
COLUMN_SIZE = 1
COLUMN_MIME = 2
COLUMN_JOBJECT = 3
ARBITRARY_LARGE_HEIGHT = 10000
JPEG_QUALITY = 80
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)
self.selected_journal_entry = None
self.selected_path = None
self.update_log_entries = ''
self.close_requested = False
canvas = Gtk.Notebook()
canvas.props.show_border = True
canvas.props.show_tabs = True
canvas.show()
self.ls_journal = Gtk.ListStore(str, GObject.TYPE_UINT64, str, \
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.SelectionMode.SINGLE)
self.selection_journal.connect("changed", self.selection_journal_cb)
renderer = Gtk.CellRendererText()
renderer.set_property('wrap-mode', Pango.WrapMode.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)
size_renderer = Gtk.CellRendererText()
size_renderer.set_property('width', 100)
size_renderer.set_property('alignment', Pango.Alignment.RIGHT)
size_renderer.set_property('xalign', 0.8)
self.col_size = Gtk.TreeViewColumn(_('Size (KB)'), size_renderer,
text=COLUMN_SIZE)
self.col_size.set_sort_column_id(COLUMN_SIZE)
self.tv_journal.append_column(self.col_size)
mime_renderer = Gtk.CellRendererText()
mime_renderer.set_property('width', 200)
self.col_mime = Gtk.TreeViewColumn(_('MIME Type'), 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.PolicyType.AUTOMATIC, Gtk.PolicyType.AUTOMATIC)
self.list_scroller_journal.add(self.tv_journal)
tab1_label = Gtk.Label()
tab1_label.set_markup("<span foreground='#FFF'" \
" size='14000'>" +_("Journal") + "</span>")
tab1_label.show()
self.tv_journal.show()
self.list_scroller_journal.show()
column_table = Gtk.Table(2, 2, False)
column_table.set_col_spacings(10)
column_table.set_row_spacings(10)
image_table = Gtk.Table(2, 2, False)
self.btn_resize = Gtk.Button(_("Resize To Width"))
self.btn_resize.connect('button_press_event',
self.resize_button_press_event_cb)
image_table.attach(self.btn_resize, 0, 1, 2, 3)
self.resize_width_entry = Gtk.Entry()
self.resize_width_entry.set_max_length(4)
image_table.attach(self.resize_width_entry, 1, 2, 2, 3)
self.resize_width_entry.set_text('600')
self.resize_width_entry.connect('key_press_event',
self.resize_key_press_event_cb)
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, 3, 4)
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, 3, 4)
self.btn_delete.props.sensitive = False
self.btn_delete.show()
self.image = Gtk.Image()
image_table.set_col_spacings(10)
image_table.set_row_spacings(10)
image_table.attach(self.image, 0, 2, 0, 1)
self.dimension_label = Gtk.Label("")
image_table.attach(self.dimension_label, 0, 2, 1, 2)
entry_table = Gtk.Table(2, 2, False)
entry_table.set_col_spacings(10)
entry_table.set_row_spacings(10)
title_label = Gtk.Label(_("Title"))
entry_table.attach(title_label, 0, 1, 0, 1)
title_label.show()
self.title_entry = Gtk.Entry()
entry_table.attach(self.title_entry, 1, 2, 0, 1)
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)
description_label.show()
self.description_textview = Gtk.TextView()
self.description_textview.set_wrap_mode(Pango.WrapMode.WORD)
entry_table.attach(self.description_textview, 1, 2, 1, 2)
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)
tags_label.show()
self.tags_textview = Gtk.TextView()
self.tags_textview.set_wrap_mode(Pango.WrapMode.WORD)
entry_table.attach(self.tags_textview, 1, 2, 2, 3)
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()
scroller_image = Gtk.ScrolledWindow(
hadjustment=None, vadjustment=None)
scroller_image.set_hexpand(False)
scroller_image.set_vexpand(True)
scroller_image.add_with_viewport(image_table)
scroller_image.show()
self.scroller_entry = Gtk.ScrolledWindow(
hadjustment=None, vadjustment=None)
self.scroller_entry.set_hexpand(False)
self.scroller_entry.set_vexpand(True)
self.scroller_entry.add_with_viewport(entry_table)
self.scroller_entry.show()
column_table.attach(scroller_image, 0, 1, 0, 1)
column_table.attach(self.scroller_entry, 1, 2, 0, 1)
image_table.show()
column_table.show()
self.btn_resize.hide()
self.resize_width_entry.hide()
vbox = Gtk.VBox(homogeneous=True, spacing=5)
vbox.pack_start(column_table, expand=True, fill=True, padding=0)
vbox.pack_end(self.list_scroller_journal, expand=True, fill=True, \
padding=0)
canvas.append_page(vbox, tab1_label)
self._filechooser = Gtk.FileChooserWidget(
action=Gtk.FileChooserAction.OPEN)
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()
tab2_label.set_markup("<span foreground='#FFF'" \
" size='14000'>" + _("Files") + "</span>")
tab2_label.show()
canvas.append_page(self._filechooser, tab2_label)
self.set_canvas(canvas)
self.show_all()
self.btn_resize.hide()
self.resize_width_entry.hide()
self.dimension_label.hide()
toolbox = ActivityToolbar(self)
stop_button = StopButton(self)
stop_button.show()
toolbox.insert(stop_button, -1)
self.set_toolbar_box(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/') \
and file_mimetype != 'image/vnd.djvu':
pixbuf = GdkPixbuf.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 = GdkPixbuf.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 resize_key_press_event_cb(self, entry, event):
keyname = Gtk.Gdk.keyval_name(event.keyval)
if ((keyname < '0' or keyname > '9') and keyname != 'BackSpace'
and keyname != 'Left' and keyname != 'Right'
and keyname != 'KP_Left' and keyname != 'KP_Right'
and keyname != 'Delete' and keyname != 'End'
and keyname != 'KP_End' and keyname != 'Home'
and keyname != 'KP_Home' and keyname != 'KP_Delete'):
return True
else:
return False
def resize_button_press_event_cb(self, entry, event):
jobject = self.selected_journal_entry
filename = jobject.get_file_path()
im = pygame.image.load(filename)
image_width, image_height = im.get_size()
resize_to_width = int(self.resize_width_entry.get_text())
if (image_width < resize_to_width):
self.alert(_('Error'), \
_('Image cannot be made larger, only smaller.'))
return
tempfile = os.path.join(self.get_activity_root(), 'instance',
'tmp%i' % time.time())
try:
scaled_pixbuf = GdkPixbuf.Pixbuf.new_from_file_at_size( \
filename,resize_to_width, ARBITRARY_LARGE_HEIGHT)
scaled_pixbuf.save(tempfile, "jpeg", \
{"quality":"%d" % JPEG_QUALITY})
except:
print 'File could not be converted'
return
jobject.file_path = tempfile
jobject.metadata['mime_type'] = 'image/jpeg'
im = pygame.image.load(tempfile)
image_width, image_height = im.get_size()
self.dimension_label.set_text(str(image_width) + "x" +
str(image_height))
self.dimension_label.show()
datastore.write(jobject, update_mtime=False,
reply_handler=self.datastore_write_cb,
error_handler=self.datastore_write_error_cb)
title = jobject.metadata.get('title', None)
self.update_log_entries += '\n' + _('Entry %s resized.') % title
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)
size = self.get_size(new_jobject) / 1024
self.ls_journal.set(iter, COLUMN_SIZE, size)
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 = jobject.metadata['title']
self.ls_journal.set(iter, COLUMN_TITLE, title)
mime = jobject.metadata['mime_type']
self.ls_journal.set(iter, COLUMN_MIME, mime)
size = self.get_size(jobject) / 1024
self.ls_journal.set(iter, COLUMN_SIZE, size)
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:
title = jobject.metadata.get('title', None)
self.update_log_entries += '\n' + \
_('Entry %s deleted.') % title
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'
self.update_log_entries += '\n' + \
_('Entry title changed to %s') % self.title_entry.props.text
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
self.update_log_entries += '\n' + \
_('Entry %s tags updated.') % self.title_entry.props.text
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
self.update_log_entries += '\n' + \
_('Entry %s description updated.') % \
self.title_entry.props.text
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):
activity.Activity.close(self, False)
def read_file(self, file_path):
"""Load a file from the datastore on activity start"""
_logger.debug('sugarcommander.read_file: %s', file_path)
def write_file(self, filename):
"Save meta data for the file."
old_description = self.metadata.get('description', \
'Sugar Commander log:')
new_description = old_description + self.update_log_entries
self.metadata['description'] = new_description
self.metadata['mime_type'] = 'text/plain'
f = open(filename, 'w')
try:
f.write(new_description)
finally:
f.close()
self.update_log_entries = ''
def can_close(self):
self.close_requested = True
return 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)
if jobject.metadata['mime_type'] .startswith('image/') \
and jobject.metadata['mime_type'] != 'image/vnd.djvu':
self.btn_resize.show()
self.resize_width_entry.show()
filename = jobject.get_file_path()
im = pygame.image.load(filename)
image_width, image_height = im.get_size()
self.dimension_label.set_text(str(image_width) + "x" +
str(image_height))
self.dimension_label.show()
else:
self.btn_resize.hide()
self.resize_width_entry.hide()
self.dimension_label.hide()
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 'description' in jobject.metadata:
description_textbuffer.set_text(jobject.metadata['description'])
else:
description_textbuffer.set_text('')
tags_textbuffer = self.tags_textview.get_buffer()
if 'tags' in jobject.metadata:
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 'preview' in jobject.metadata:
preview = jobject.metadata['preview']
if preview is None or preview == '' or preview == 'None':
if jobject.metadata['mime_type'] .startswith('image/') and \
jobject.metadata['mime_type'] != 'image/vnd.djvu':
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
self.show_image('xoimage.jpg')
return
if 'preview' in jobject.metadata and \
len(jobject.metadata['preview']) > 4:
preview_data = jobject.metadata['preview']
loader = GdkPixbuf.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
query = {}
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])
size = self.get_size(ds_objects[i]) / 1024
self.ls_journal.set(iter, COLUMN_SIZE, size)
v_adjustment = self.list_scroller_journal.get_vadjustment()
v_adjustment.value = 0
def get_size(self, jobject):
"""Return the file size for a Journal object."""
logging.debug('get_file_size %r', jobject.object_id)
path = jobject.get_file_path()
if not path:
return 0
return os.stat(path).st_size
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/') and file_mimetype != \
'image/vnd.djvu':
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.update_log_entries += '\n' + \
_('File %s copied to the Journal.') % filename
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 = GdkPixbuf.Pixbuf.new_from_file_at_size(filename,
style.zoom(300), style.zoom(225))
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 = GdkPixbuf.Pixbuf.new_from_file_at_size(filename, \
style.zoom(320), style.zoom(240))
preview_data = []
succes, preview_data = scaled_pixbuf.save_to_bufferv('png', [], [])
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
Note: the technique described in this section is broken in some versions of Sugar. If you use this technique your Activity will not work on those versions. The technique is documented and should be supported in every version of Sugar, but there is a certain risk in using it.
In addition to the risk, there is a school of thought that Activities should always leave behind a Journal entry. The idea is that the Journal is not just a place for data, but is the equivalent of a personal journal that a child might keep about his school work. If you subscribe to that idea then every thing the child does should have a Journal entry so the child can enter notes about it.
The current version of Sugar starts Activities from the Activity ring using their most recent Journal entry by default. This makes the problem of extra journal entries left behind by Activities that don't really need journal entries less of a problem than it has been in the past.
The code in this book leaves behind a Journal entry with a log of what has been done with the Activity. You can easily fix it to not leave behind a Journal entry using the technique in this section.
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.
Here is code in Sugar Commander that lists Journal entries:
def load_journal_table(self):
self.btn_save.props.sensitive = False
self.btn_delete.props.sensitive = False
query = {}
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])
size = self.get_size(ds_objects[i]) / 1024
self.ls_journal.set(iter, COLUMN_SIZE, size)
v_adjustment = self.list_scroller_journal.get_vadjustment()
v_adjustment.value = 0
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 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)
To get a preview image use code like this:
if 'preview' in jobject.metadata and \
len(jobject.metadata['preview']) > 4:
preview_data = jobject.metadata['preview']
loader = GdkPixbuf.PixbufLoader()
loader.write(preview_data)
scaled_buf = loader.get_pixbuf()
loader.close()
self.image.set_from_pixbuf(scaled_buf)
self.image.show()
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.