Merge git://git.sugarlabs.org/turtleart/mainline

18 files changed, 197 insertions, 124 deletions

diff --git a/NEWS b/NEWS
index b9388eb..3a0e890 100644
--- a/NEWS
+++ b/NEWS
@@ -11,6 +11,7 @@ ENHANCEMENTS
 * Shared turtles are updated after mouse drag (#2687)
 * Shared turtles cannot be repositioned remotely (#2687)
 * Turtles are synchronized when joining share (#2687)
+* Comments on usage included in the python sample code (#2709)
 
 BUG FIXES
 
@@ -20,6 +21,18 @@ BUG FIXES
 * Fixed regression with camera_plugin after refactoring (#2689)
 * Fixed problem with saving/loading extra turtles when nick changes (#2441)
 
+PYTHON CODE FLAG DAY
+
+* Userdefined code gets TurtleWindow instance rather than LogoCode
+  instance as first argument. This change was made in order to better
+  accommodate and better parallel the new plugin mechanism. Most
+  likely, you had been referencing tw, the TurtleWindow instance from
+  lc, the LogoCode instance, e.g., lc.tw. Now you can reference tw
+  directly, e.g., tw. To reference lc, use tw.lc. Also note that the
+  push_mouse_event.py sample has changed. The x,y position of the
+  mouse is now always pushed to the stack, whether or not the mouse
+  button is pressed.
+
 106
 
 ENHANCEMENTS
diff --git a/TurtleArt/tabasics.py b/TurtleArt/tabasics.py
index da991dd..b4780d9 100644
--- a/TurtleArt/tabasics.py
+++ b/TurtleArt/tabasics.py
@@ -777,7 +777,6 @@ variable'))
                           style='basic-style-extended-vertical',
                           label=_('action 1'),
                           prim_name='stack1',
-                          default=_('action 1'),
                           help_string=_('invokes Action 1 stack'))
         self.tw.lc.def_prim('stack1', 0, primitive_dictionary['stack1'], True)
 
@@ -786,7 +785,6 @@ variable'))
                           style='basic-style-extended-vertical',
                           label=_('action 2'),
                           prim_name='stack2',
-                          default=_('action 2'),
                           help_string=_('invokes Action 2 stack'))
         self.tw.lc.def_prim('stack2', 0, primitive_dictionary['stack2'], True)
 
diff --git a/TurtleArt/tajail.py b/TurtleArt/tajail.py
index 0ec2563..c8cea7f 100644
--- a/TurtleArt/tajail.py
+++ b/TurtleArt/tajail.py
@@ -43,11 +43,11 @@ def myfunc(f, args):
         return userdefined.values()[0](args[0], args[1], args[2])
 
 
-def myfunc_import(lc, f, x):
+def myfunc_import(parent, f, x):
     userdefined = {}
     try:
         exec f in globals(), userdefined
-        return userdefined['myblock'](lc, x)
+        return userdefined['myblock'](parent.tw, x)
     except:
         traceback.print_exc()
         return None
diff --git a/TurtleArt/tawindow.py b/TurtleArt/tawindow.py
index 246a0cf..b214dbb 100644
--- a/TurtleArt/tawindow.py
+++ b/TurtleArt/tawindow.py
@@ -285,13 +285,11 @@ class TurtleArtWindow():
             f = "def f(self): from plugins.%s import %s; return %s(self)" \
                 % (pluginfile, pluginclass, pluginclass)
             plugins = {}
-            #try:
-            #    exec f in globals(), plugins
-            #    self._plugins.append(plugins.values()[0](self))
-            #except ImportError:
-            #    debug_output('failed to import %s' % (pluginclass))
-            exec f in globals(), plugins # BORRAR
-            self._plugins.append(plugins.values()[0](self)) #BORRAR
+            try:
+                exec f in globals(), plugins
+                self._plugins.append(plugins.values()[0](self))
+            except ImportError:
+                debug_output('failed to import %s' % (pluginclass))
 
     def _setup_plugins(self):
         """ Initial setup -- call just once. """
diff --git a/collaboration/presenceservice.py b/collaboration/presenceservice.py
index 142fc4a..33caadd 100644
--- a/collaboration/presenceservice.py
+++ b/collaboration/presenceservice.py
@@ -95,7 +95,7 @@ class PresenceService(gobject.GObject):
                     name = 'org.freedesktop.Telepathy.Error.NotAvailable'
                     if e.get_dbus_name() == name:
                         logging.debug("There's no shared activity with the id "
-                                      "%s", activity_id)
+                                      "%s" % (activity_id))
                     else:
                         raise
                 else:
@@ -166,8 +166,8 @@ class PresenceService(gobject.GObject):
                         dbus_interface=CONNECTION)
                 return self.get_buddy(account_path, contact_ids[0])
 
-        raise ValueError('Unknown buddy in connection %s with handle %d',
-                         tp_conn_path, handle)
+        raise ValueError('Unknown buddy in connection %s with handle %d' % \
+                         (tp_conn_path, handle))
 
     def get_owner(self):
         """Retrieves the laptop Buddy object."""
@@ -203,8 +203,8 @@ class PresenceService(gobject.GObject):
         properties['private'] = private
 
         if self._activity_cache is not None:
-            raise ValueError('Activity %s is already tracked',
-                             activity.get_id())
+            raise ValueError('Activity %s is already tracked' % \
+                             (activity.get_id()))
 
         connection_manager = get_connection_manager()
         account_path, connection = \
@@ -220,8 +220,8 @@ class PresenceService(gobject.GObject):
         self._activity_cache = shared_activity
 
         if shared_activity.props.joined:
-            raise RuntimeError('Activity %s is already shared.' %
-                               activity.props.id)
+            raise RuntimeError('Activity %s is already shared.' % \
+                               (activity.props.id))
 
         shared_activity.share(self.__share_activity_cb,
                               self.__share_activity_error_cb)
diff --git a/plugins/nxt_plugin.py b/plugins/nxt_plugin.py
index 0842c24..4551f56 100644
--- a/plugins/nxt_plugin.py
+++ b/plugins/nxt_plugin.py
@@ -243,7 +243,13 @@ class Nxt_plugin(Plugin):
 
     def stop(self):
         # This gets called by the stop button
-        pass
+        try:
+            self._prim_nxtbrake(PORT_A)
+            self._prim_nxtbrake(PORT_B)
+            self._prim_nxtbrake(PORT_C)
+        except:
+            pass
+
 
     def goto_background(self):
         # This gets called when your process is sent to the background
diff --git a/pysamples/copy_from_heap.py b/pysamples/copy_from_heap.py
index 1978c26..5eb7bab 100644
--- a/pysamples/copy_from_heap.py
+++ b/pysamples/copy_from_heap.py
@@ -21,8 +21,11 @@
 # This procedure is invoked when the user-definable block on the "extras"
 # palette is selected.
 
+# Usage: Import this code into a Python (user-definable) block; when
+# this code is run, the FILO heap will be copied to the clipboard.
 
-def myblock(lc, x):  # second argument is ignored
+
+def myblock(tw, x):  # second argument is ignored
 
     ###########################################################################
     #
@@ -31,6 +34,6 @@ def myblock(lc, x):  # second argument is ignored
     ###########################################################################
 
     from gtk import Clipboard
-    from tautils import data_to_string
+    from TurtleArt.tautils import data_to_string
 
-    Clipboard().set_text(data_to_string(lc.heap))
+    Clipboard().set_text(data_to_string(tw.lc.heap))
diff --git a/pysamples/dotted_line.py b/pysamples/dotted_line.py
index 86d5c7f..e9c1325 100644
--- a/pysamples/dotted_line.py
+++ b/pysamples/dotted_line.py
@@ -47,66 +47,66 @@
 #
 #
 # Class TurtleArtWindow -- useful properties and methods (from within
-# tamyblock.py, lc.tw is the class instance)
+# tamyblock.py, tw is the class instance)
 #
 # Methods and data attributes	Example
-# set_fullscreen(self)		lc.tw.set_fullscreen()
+# set_fullscreen(self)		tw.set_fullscreen()
 # Note: Hides the Sugar toolbar
-# set_cartesian(self, flag)	lc.tw.set_cartesian(True)
+# set_cartesian(self, flag)	tw.set_cartesian(True)
 # Note: True will make the overlay visible;
 #       False will make it invisible
-# set_polar(self, flag)		lc.tw.set_polar(True)
+# set_polar(self, flag)		tw.set_polar(True)
 # Note: True will make the overlay visible;
 #       False will make it invisible
-# hideshow_button(self, flag)	lc.tw.hideshow_button()
+# hideshow_button(self, flag)	tw.hideshow_button()
 # Note: Toggles visibility of blocks and palettes
-# self.active_turtle		lc.tw.active_turtle
+# self.active_turtle		tw.active_turtle
 # Note: The active turtle instance
 #
 #
 # Class TurtleGraphics -- useful properties and methods (from within
-# tamyblock.py, lc.tw.canvas is the class instance)
+# tamyblock.py, tw.canvas is the class instance)
 #
 # Methods and data attributes	Example
-# clearscreen(self)		lc.tw.canvas.clearscreen()
+# clearscreen(self)		tw.canvas.clearscreen()
 # Note: Clears the screen and resets all turtle and
 #       pen attributes to default values
-# setpen(self, flag)		lc.tw.canvas.setpen(True)
+# setpen(self, flag)		tw.canvas.setpen(True)
 # Note: True will set the pen "down", enabling drawing;
 #       False will set the pen "up"
-# forward(self, n)		lc.tw.canvas.forward(100)
+# forward(self, n)		tw.canvas.forward(100)
 # Note: Move the turtle forward 100 units
-# arc(self, a, r)		lc.tw.canvas.arc(120, 50)
+# arc(self, a, r)		tw.canvas.arc(120, 50)
 # Note: Move the turtle along an arc of 120 degrees
 #       (clockwise) and radius of 50 units
-# setheading(self, a)		lc.tw.canvas.setheading(180)
+# setheading(self, a)		tw.canvas.setheading(180)
 # Note: Set the turtle heading to 180
 #       (towards the bottom of the screen)
-# self.heading			lc.tw.canvas.heading
+# self.heading			tw.canvas.heading
 # Note: The current heading
-# setpensize(self, n)		lc.tw.canvas.setpensize(25)
+# setpensize(self, n)		tw.canvas.setpensize(25)
 # Note: Set the turtle pensize to 25 units
-# self.pensize			lc.tw.canvas.pensize
+# self.pensize			tw.canvas.pensize
 # Note: The current pensize
-# setcolor(self, c)		lc.tw.canvas.color(70)
+# setcolor(self, c)		tw.canvas.color(70)
 # Note:	Set the pen color to 70 (blue)
-# self.color			lc.tw.canvas.color
+# self.color			tw.canvas.color
 # Note: The current pen color
-# setshade(self, s)		lc.tw.canvas.shade(50)
+# setshade(self, s)		tw.canvas.shade(50)
 # Note:	Set the pen shade to 50
-# self.shade			lc.tw.canvas.shade
+# self.shade			tw.canvas.shade
 # Note: The current pen shade
-# fillscreen(self, c, s)	lc.tw.canvas.fillscreen(70, 90)
+# fillscreen(self, c, s)	tw.canvas.fillscreen(70, 90)
 # Note: Fill the screen with color 70, shade 90 (light blue)
-# setxy(self, x, y)		lc.tw.canvas.setxy(100,100)
+# setxy(self, x, y)		tw.canvas.setxy(100,100)
 # Note: Move the turtle to position (100, 100)
-# self.xcor			lc.tw.canvas.xcor
+# self.xcor			tw.canvas.xcor
 # Note: The current x coordinate of the turtle
 #       (scaled to current units)
-# self.ycor			lc.tw.canvas.ycor
+# self.ycor			tw.canvas.ycor
 # Note: The current y coordinate of the turtle
 #       (scaled to current units)
-# self.set_turtle(name)		lc.tw.canvas.set_turtle(1)
+# self.set_turtle(name)		tw.canvas.set_turtle(1)
 # Note: Set the current turtle to turtle '1'
 #
 #
@@ -118,14 +118,18 @@
 # Note: See http://docs.python.org/library/math.html
 # from time import localtime	localtime().tm_hour returns the current hour
 # Note: See http://docs.python.org/library/time.html
-# 				lc.heap.append(data) adds data to the heap
+# 				tw.lc.heap.append(data) adds data to the heap
 # Note: See http://docs.python.org/tutorial/datastructures.html
-# 				data = lc.heap.pop(-1) pops data off the heap
+# 				data = tw.lc.heap.pop(-1) pops data off the heap
 # Note: See http://docs.python.org/tutorial/datastructures.html
 #
 
+# Usage: Import this code into a Python (user-definable) block; when
+# this code is run, the turtle will draw a dotted line of the length
+# of the numeric argument block docked to the Python block.
 
-def myblock(lc, line_length):
+
+def myblock(tw, line_length):
 
     ###########################################################################
     #
@@ -137,17 +141,17 @@ def myblock(lc, line_length):
         line_length = float(line_length)
     except ValueError:
         return
-    if lc.tw.canvas.pendown:
+    if tw.canvas.pendown:
         dist = 0
-        while dist + lc.tw.canvas.pensize < line_length:  # repeat drawing dots
-            lc.tw.canvas.setpen(True)
-            lc.tw.canvas.forward(1)
-            lc.tw.canvas.setpen(False)
-            lc.tw.canvas.forward((lc.tw.canvas.pensize * 2) - 1)
-            dist += (lc.tw.canvas.pensize * 2)
+        while dist + tw.canvas.pensize < line_length:  # repeat drawing dots
+            tw.canvas.setpen(True)
+            tw.canvas.forward(1)
+            tw.canvas.setpen(False)
+            tw.canvas.forward((tw.canvas.pensize * 2) - 1)
+            dist += (tw.canvas.pensize * 2)
         # make sure we have moved exactly line_length
-        lc.tw.canvas.forward(line_length - dist)
-        lc.tw.canvas.setpen(True)
+        tw.canvas.forward(line_length - dist)
+        tw.canvas.setpen(True)
     else:
-        lc.tw.canvas.forward(line_length)
+        tw.canvas.forward(line_length)
     return
diff --git a/pysamples/load_block.py b/pysamples/load_block.py
index 4f46a73..8924605 100644
--- a/pysamples/load_block.py
+++ b/pysamples/load_block.py
@@ -21,8 +21,17 @@
 # This procedure is invoked when the user-definable block on the "extras"
 # palette is selected.
 
+# Usage: Import this code into a Python (user-definable) block; when
+# this code is run, the turtle will create a block at the current
+# location of the turtle.  The first argument to the Python block
+# should be a string containing the name of the desired
+# block. Arguments to the block can be passed by expanding the Python
+# block to include up to two additional arguments.  Note that the
+# height of the block is pushed to the FILO heap and can be used to
+# advance the position of the turtle when creating stacks.
 
-def myblock(lc, blkname):
+
+def myblock(tw, blkname):
 
     ###########################################################################
     #
@@ -30,29 +39,29 @@ def myblock(lc, blkname):
     #
     ###########################################################################
 
-    from taconstants import BLOCK_NAMES, PRIMITIVES, CONTENT_BLOCKS, \
-        SPECIAL_NAMES
-    from tautils import find_group
+    from TurtleArt.tapalette import block_names, block_primitives, \
+        special_names, content_blocks
+    from TurtleArt.tautils import find_group
 
-    def make_block(lc, name, x, y, defaults):
+    def make_block(tw, name, x, y, defaults):
         x_pos = x + 20
         y_pos = y + 20
-        lc.tw._new_block(name, x_pos, y_pos, defaults)
+        tw._new_block(name, x_pos, y_pos, defaults)
 
         # Find the block we just created and attach it to a stack.
-        lc.tw.drag_group = None
-        spr = lc.tw.sprite_list.find_sprite((x_pos, y_pos))
+        tw.drag_group = None
+        spr = tw.sprite_list.find_sprite((x_pos, y_pos))
         if spr is not None:
-            blk = lc.tw.block_list.spr_to_block(spr)
+            blk = tw.block_list.spr_to_block(spr)
             if blk is not None:
-                lc.tw.drag_group = find_group(blk)
-                lc.tw._snap_to_dock()
+                tw.drag_group = find_group(blk)
+                tw._snap_to_dock()
 
         # Disassociate new block from mouse.
-        lc.tw.drag_group = None
+        tw.drag_group = None
         return blk.height
 
-    def find_block(lc, blkname, x, y, defaults=None):
+    def find_block(tw, blkname, x, y, defaults=None):
         """ Create a new block. It is a bit more work than just calling
         _new_block(). We need to:
         (1) translate the label name into the internal block name;
@@ -60,27 +69,28 @@ def myblock(lc, blkname):
         (3) disassociate the new block from the mouse. """
 
         print blkname
-        for name in BLOCK_NAMES:
+        for name in block_names:
             # Translate label name into block/prim name.
-            if blkname in BLOCK_NAMES[name]:
-                if (name in PRIMITIVES and PRIMITIVES[name] == name) or \
-                   name in CONTENT_BLOCKS:
-                    return make_block(lc, name, x, y, defaults)
-        for name in SPECIAL_NAMES:
+            if blkname in block_names[name]:
+                if (name in block_primitives and \
+                        block_primitives[name] == name) or \
+                        name in content_blocks:
+                    return make_block(tw, name, x, y, defaults)
+        for name in special_names:
             # Translate label name into block/prim name.
-            if blkname in SPECIAL_NAMES[name]:
-                return make_block(lc, name, x, y, defaults)
+            if blkname in special_names[name]:
+                return make_block(tw, name, x, y, defaults)
         return -1
 
     # Place the block at the active turtle (x, y) and
     # push height to stack.
-    x, y = lc.tw.active_turtle.get_xy()
+    x, y = tw.active_turtle.get_xy()
     if type(blkname) == type([]):
         name = blkname[0]
         value = blkname[1:]
-        dy = int(find_block(lc, name, x, y, value))
+        dy = int(find_block(tw, name, x, y, value))
     else:
         name = blkname
-        dy = int(find_block(lc, name, x, y))
+        dy = int(find_block(tw, name, x, y))
     if dy != -1:
-        lc.heap.append(dy)
+        tw.lc.heap.append(dy)
diff --git a/pysamples/load_journal_entry_to_heap.py b/pysamples/load_journal_entry_to_heap.py
index cf2ec7e..512de76 100644
--- a/pysamples/load_journal_entry_to_heap.py
+++ b/pysamples/load_journal_entry_to_heap.py
@@ -21,8 +21,13 @@
 # This procedure is invoked when the user-definable block on the "extras"
 # palette is selected.
 
+# Usage: Import this code into a Python (user-definable) block; when
+# this code is run, the chooser will be opened for selecting a file
+# from the Journal. The contents of that file will be loaded onto the
+# FILO heap.
 
-def myblock(lc, x):  # ignore second argument
+
+def myblock(tw, x):  # ignore second argument
 
     ###########################################################################
     #
@@ -30,7 +35,7 @@ def myblock(lc, x):  # ignore second argument
     #
     ###########################################################################
 
-    from tautils import chooser
+    from TurtleArt.tautils import chooser
 
     # Choose a datastore object and push data to heap (Sugar only)
-    chooser(lc.tw.parent, '', lc.push_file_data_to_heap)
+    chooser(tw.parent, '', tw.lc.push_file_data_to_heap)
diff --git a/pysamples/paste_to_heap.py b/pysamples/paste_to_heap.py
index a7f67f9..cd36732 100644
--- a/pysamples/paste_to_heap.py
+++ b/pysamples/paste_to_heap.py
@@ -21,8 +21,12 @@
 # This procedure is invoked when the user-definable block on the "extras"
 # palette is selected.
 
+# Usage: Import this code into a Python (user-definable) block; when
+# this code is run, the contents of the clipboard will be appended to
+# the FILO heap.
 
-def myblock(lc, x):  # ignore second argument
+
+def myblock(tw, x):  # ignore second argument
 
     ###########################################################################
     #
@@ -36,5 +40,5 @@ def myblock(lc, x):  # ignore second argument
     text = Clipboard().wait_for_text()
     if text is not None:
         for val in data_from_string(text):
-            lc.heap.append(val)
-        lc.update_label_value('pop', val)
+            tw.lc.heap.append(val)
+        tw.lc.update_label_value('pop', val)
diff --git a/pysamples/push_mouse_event.py b/pysamples/push_mouse_event.py
index 6966310..9a6c504 100644
--- a/pysamples/push_mouse_event.py
+++ b/pysamples/push_mouse_event.py
@@ -22,8 +22,17 @@
 # This procedure is invoked when the user-definable block on the "extras"
 # palette is selected.
 
+# Usage: Import this code into a Python (user-definable) block; when
+# this code is run, the current mouse status will be pushed to the
+# FILO heap. If a mouse button event occurs, a y, x, and 1 are pushed
+# to the heap. If no button is pressed, 0 is pushed to the heap.
 
-def myblock(lc, x):  # ignore second argument
+# To use these data, pop the heap in a compare block to determine if a
+# button has been pushed. If a 1 was popped from the heap, pop the x
+# and y coordinates.
+
+
+def myblock(tw, x):  # ignore second argument
 
     ###########################################################################
     #
@@ -31,11 +40,11 @@ def myblock(lc, x):  # ignore second argument
     #
     ###########################################################################
 
-    if lc.tw.mouse_flag == 1:
+    if tw.mouse_flag == 1:
         # push y first so x will be popped first
-        lc.heap.append((lc.tw.canvas.height / 2) - lc.tw.mouse_y)
-        lc.heap.append(lc.tw.mouse_x - (lc.tw.canvas.width / 2))
-        lc.heap.append(1) # mouse event
-        lc.tw.mouse_flag = 0
+        tw.lc.heap.append((tw.canvas.height / 2) - tw.mouse_y)
+        tw.lc.heap.append(tw.mouse_x - (tw.canvas.width / 2))
+        tw.lc.heap.append(1) # mouse event
+        tw.mouse_flag = 0
     else:
-        lc.heap.append(0) # no mouse event
+        tw.lc.heap.append(0) # no mouse event
diff --git a/pysamples/push_time.py b/pysamples/push_time.py
index 2abf260..1945ca4 100644
--- a/pysamples/push_time.py
+++ b/pysamples/push_time.py
@@ -21,8 +21,13 @@
 # This procedure is invoked when the user-definable block on the "extras"
 # palette is selected.
 
+# Usage: Import this code into a Python (user-definable) block; when
+# this code is run, the current hour, minute, and second are pushed to
+# the FILO heap. To use these values, pop second, then minute, then
+# hour from the FILO.
 
-def myblock(lc, x):  # ignore second argument
+
+def myblock(tw, x):  # ignore second argument
 
     ###########################################################################
     #
@@ -33,6 +38,6 @@ def myblock(lc, x):  # ignore second argument
     #
     ###########################################################################
 
-    lc.heap.append(localtime().tm_hour)
-    lc.heap.append(localtime().tm_min)
-    lc.heap.append(localtime().tm_sec)
+    tw.lc.heap.append(localtime().tm_hour)
+    tw.lc.heap.append(localtime().tm_min)
+    tw.lc.heap.append(localtime().tm_sec)
diff --git a/pysamples/save_heap_to_journal_entry.py b/pysamples/save_heap_to_journal_entry.py
index 2589164..e9121d4 100644
--- a/pysamples/save_heap_to_journal_entry.py
+++ b/pysamples/save_heap_to_journal_entry.py
@@ -21,8 +21,13 @@
 # This procedure is invoked when the user-definable block on the "extras"
 # palette is selected.
 
+# Usage: Import this code into a Python (user-definable) block; when
+# this code is run, the contents of the FILO heap are saved to a
+# Journal entry named by the value of the argument to the Python
+# block.
 
-def myblock(lc, title):
+
+def myblock(tw, title):
 
     ###########################################################################
     #
@@ -37,12 +42,12 @@ def myblock(lc, title):
     from sugar.datastore import datastore
     from sugar import profile
 
-    from tautils import get_path, data_to_file
+    from TurtleArt.tautils import get_path, data_to_file
 
     # Save JSON-encoded heap to temporary file
     heap_file = os.path.join(get_path(activity, 'instance'),
                              str(title) + '.txt')
-    data_to_file(lc.heap, heap_file)
+    data_to_file(tw.lc.heap, heap_file)
 
     # Create a datastore object
     dsobject = datastore.create()
diff --git a/pysamples/set_rgb.py b/pysamples/set_rgb.py
index 0a556fe..c9c0f0c 100644
--- a/pysamples/set_rgb.py
+++ b/pysamples/set_rgb.py
@@ -22,8 +22,14 @@
 # This procedure is invoked when the user-definable block on the "extras"
 # palette is selected and expanded to 3 arguments.
 
+# Usage: Import this code into a Python (user-definable) block.
+# First, expand the Python block to reveal three numerics arguments.
+# Set these values to the desired red, green, and blue. When the code
+# is run, the red, green, and blue values are used to set the pen
+# color.
 
-def myblock(lc, rgb_array):
+
+def myblock(tw, rgb_array):
 
     ###########################################################################
     #
@@ -31,15 +37,8 @@ def myblock(lc, rgb_array):
     #
     ###########################################################################
 
-    def mod(x):
-        while x < 0:
-            x += 256
-        while b > 255:
-            x -= 256
-        return x
-
-    b = mod(int(rgb_array[2]))
-    g = mod(int(rgb_array[1]))
-    r = mod(int(rgb_array[0]))
-    rgb = "#%02x%02x%02x" % (r, g, b)
-    lc.tw.canvas.fgcolor = lc.tw.canvas.cm.alloc_color(rgb)
+    
+    rgb = "#%02x%02x%02x" % ((int(rgb_array[0]) % 256),
+                             (int(rgb_array[1]) % 256),
+                             (int(rgb_array[2]) % 256))
+    tw.canvas.fgcolor = tw.canvas.cm.alloc_color(rgb)
diff --git a/pysamples/sinewave.py b/pysamples/sinewave.py
index 4ddf3b4..54a0700 100644
--- a/pysamples/sinewave.py
+++ b/pysamples/sinewave.py
@@ -21,8 +21,12 @@
 # This procedure is invoked when the user-definable block on the "extras"
 # palette is selected.
 
+# Usage: Import this code into a Python (user-definable) block and
+# pass a frequency in Hertz to the Python block. A tone will play over
+# the speaker at the specified frequency.
 
-def myblock(lc, frequency):
+
+def myblock(tw, frequency):
 
     ###########################################################################
     #
diff --git a/pysamples/speak.py b/pysamples/speak.py
index e8d3864..03f47bc 100644
--- a/pysamples/speak.py
+++ b/pysamples/speak.py
@@ -22,8 +22,13 @@
 # This procedure is invoked when the user-definable block on the "extras"
 # palette is selected.
 
+# Usage: Import this code into a Python (user-definable) block and
+# pass a string to be read by the voice synthesizer. If a second
+# argument is passed, by expanding the Python block, it is used to specify
+# the pitch level of the speaker. Valid range is 0 to 99.
 
-def myblock(lc, arg):
+
+def myblock(tw, arg):
 
     ###########################################################################
     #
diff --git a/pysamples/uturn.py b/pysamples/uturn.py
index b38542a..3f7f623 100644
--- a/pysamples/uturn.py
+++ b/pysamples/uturn.py
@@ -22,7 +22,12 @@
 # This procedure is invoked when the user-definable block on the "extras"
 # palette is selected.
 
-def myblock(parent, arg):
+# Usage: Import this code into a Python (user-definable) block; when
+# it is run, a u-turn block will be added to the Turtle Palette. You
+# can use the u-turn block as you would any other block.
+
+
+def myblock(tw, arg):
     ''' Add a uturn block to the 'turtle' palette '''
 
     from TurtleArt.tapalette import make_palette, palette_name_to_index
@@ -40,10 +45,10 @@ def myblock(parent, arg):
                       help_string=_('make a uturn'))
 
     # Add its primitive to the LogoCode dictionary.
-    parent.tw.lc.def_prim('uturn', 0,
-                     lambda self: primitive_dictionary['set'](
-            'heading', parent.tw.canvas.seth, parent.tw.canvas.heading + 180))
+    tw.lc.def_prim('uturn', 0,
+                   lambda self: primitive_dictionary['set'](
+            'heading', tw.canvas.seth, tw.canvas.heading + 180))
 
     # Regenerate the palette, which will now include the new block.
-    parent.tw.show_toolbar_palette(palette_name_to_index('turtle'),
+    tw.show_toolbar_palette(palette_name_to_index('turtle'),
                                    regenerate=True)