Sugar-api-doc: Difference between revisions
Jump to navigation
Jump to search
No edit summary |
|||
| (5 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
[http://wiki.laptop.org/go/Sugar_Almanac This page has been moved to a new location] |
|||
{{Sugar Almanac TOC}} |
|||
= How do I get additional help beyond this almanac? = |
|||
* Looking to get started with the basics of sugar development? Check out Christoph Derndorfer's [http://www.olpcaustria.org/mediawiki/index.php/Activity_handbook Activity Handbook]. |
|||
Now, on to the actual almanac ... |
|||
= Package: sugar.activity = |
|||
* [[sugar.activity.activity]] |
|||
= Package: sugar.graphics = |
|||
* [[sugar.graphics.toolbutton]] |
|||
* [[sugar.graphics.toolbox]] |
|||
= Package: sugar.datastore = |
|||
* [[sugar.datastore.datastore]] |
|||
= MISCELLANEOUS = |
|||
The tasks below are random useful techniques that have come up as I write code and documentation for this reference. They have yet to be categorized, but will be as a sufficient set of related entries are written. |
|||
=== How do I write to a log in my activity code? === |
|||
Sugar uses [http://www.onlamp.com/pub/a/python/2005/06/02/logging.html python's standard logging]. The following code shows how to output something at the debug log level. |
|||
import logging |
|||
_logger = logging.getLogger('annotate-activity') |
|||
... |
|||
_logger.debug('starting activity') |
|||
=== How do I ensure that a text string is correctly translated to another language when appropriate (for internationalization)? === |
|||
To ensure that string output from your activity is correctly translated, you would use the gettext utility. The code below imports gettext, renaming it as '_' for code brevity. Then, whenever there is a string that you want to make sure is translated based on language settings, you simply pass it to the _() function. According to the [http://docs.python.org/lib/node731.html Python Reference Library], gettext will "return the localized translation of message, based on the current global domain, language, and locale directory." |
|||
from gettext import gettext as _ |
|||
... |
|||
#Make sure 'hello world' translates |
|||
print _('hello world') |
|||
=== How do I ensure that using gettext does not crash my activity, especially when I try to translate more complex string substitution? === |
|||
Since some strings require variables to be substituted into them, they need to be translated carefully. If they're not translated correctly, trying to do a string substitution can crash your activity. |
|||
The code below redefines the _() to use the gettext method only if gettext actually works. If there is an exception, the code will simply return the untranslated string. This ensures that instead of crashing, your activity will simply not translate your string. |
|||
<pre> |
|||
#Do the import of the gettext, but do not give it the underscore alias |
|||
from gettext import gettext |
|||
... |
|||
#defensive method against variables not translated correctly |
|||
def _(s): |
|||
#todo: permanent variable |
|||
istrsTest = {} |
|||
for i in range (0,4): |
|||
istrsTest[str(i)] = str(i) |
|||
#try to use gettext. If it fails, then just return the string untranslated. |
|||
try: |
|||
#test translating the string with many replacements |
|||
i = gettext(s) |
|||
test = i % istrsTest |
|||
print test |
|||
except: |
|||
#if it doesn't work, revert |
|||
i = s |
|||
return i |
|||
... |
|||
#Now we can use the _() function and it should not crash if gettext fails. |
|||
substitutionMap = {} |
|||
substitutionMap[str(1)] = 'one' |
|||
substitutionMap[str(2)] = 'two' |
|||
substitutionMap[str(3)] = 'three' |
|||
print _("Lets count to three: %(1)s, %(2)s, %(3)s") % substitutionMap |
|||
<pre> |
|||
=== How do I know when my activity is "active" or not? === |
|||
You can set an event using the VISIBILITY_NOTIFY_MASK constant in order to know when your activity changes visibility. Then in the callback for this event, you simply compare the event's state to gtk-defined variables for activity visibility. See the [http://www.pygtk.org/docs/pygtk/gdk-constants.html#gdk-visibility-state-constants GDK Visibility State Constants] section of gtk.gdk.Constants for more information. |
|||
<pre> |
|||
#Notify when the visibility state changes by calling self._visibleNotifyCb |
|||
#(PUT THIS IN YOUR ACTIVITY CODE - EG. THE __init__() METHOD) |
|||
self.add_events(gtk.gdk.VISIBILITY_NOTIFY_MASK) |
|||
self.connect("visibility-notify-event", self._visibleNotifyCb) |
|||
... |
|||
#Callback method for when the activity's visibility changes |
|||
def _visibleNotifyCb(self, widget, event): |
|||
if (event.state == gtk.gdk.VISIBILITY_FULLY_OBSCURED): |
|||
print "I am not visible" |
|||
elif (event.state == gtk.gdk.VISIBILITY_UNOBSCURED): |
|||
print "I am visible" |
|||
</pre> |
|||
= Notes = |
|||
* See also [[Sugar Code Snippets]] |
|||
<references /> |
|||