* Use specific registering of event handlers on object

* Use the numerical hierarchy for the widget hierarchy
* Add a new tutorial to TAbiWordActivity to use those
* Get 4 more points according to Pylint!

1 files changed, 168 insertions, 51 deletions

diff --git a/src/sugar/tutorius/tutorial.py b/src/sugar/tutorius/tutorial.py
index fc1d8ae..10af1d1 100644
--- a/src/sugar/tutorius/tutorial.py
+++ b/src/sugar/tutorius/tutorial.py
@@ -14,7 +14,12 @@
 # You should have received a copy of the GNU General Public License
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+"""
+Module Tutorial
 
+This is the main module for Tutorius.
+
+"""
 
 import gtk
 import logging
@@ -25,17 +30,37 @@ from sugar.tutorius.dialog import TutoriusDialog
 logger = logging.getLogger("tutorius")
 
 class Event:
+    """Event descriptor class.
+    This class is used to describe events that are expected to happen.
+    """
+
     def __init__(self, object_name, event_name ):
+        """Constructor for Event
+        @param object_name str name of the object that will send the event
+        @param event_name str name of the event
+        
+        Example:
+        evt=Event("0.0.1.1.2", "clicked")
+        """
         self.object_name = object_name
         self.event_name = event_name
 
     def test(self, sig, name):
+        """Utility method for testing the equality between a signal and object
+        names and their expected values.
+        @param sig str signal name
+        @param name str object name
+        @return True if both match the expected values, False otherwise
+        """
         if self.object_name == name and self.event_name == sig:
             return True
         return False
 
 
 class Tutorial (object):
+    """
+    Tutorial Class, used to run through the FSM.
+    """
     EVENTS = [
         "focus",
         "button-press-event",
@@ -57,69 +82,82 @@ class Tutorial (object):
     ]
 
     def __init__(self, name, fsm):
+        """Create an unattached tutorial
+        """
         object.__init__(self)
         self.name = name
         self.state_machine = fsm
+        self.state = None
 
         self.handlers = []
         self.activity = None
-        #self.setState("INIT")
-        #self.state="INIT"
-        #self.register_signals(self.activity, self.handleEvent, max_depth=10)
+        #Rest of initialisation happens when attached
 
     def attach(self, activity):
+        """Attach to a running activity
+        @param activity the activity to attach to
+        """
         #For now, absolutely detach if a previous one!
         if self.activity:
             self.detach()
         self.activity = activity
-        self.state="INIT"
-        self.register_signals(self.activity,self.handleEvent, max_depth=10)
+        self.set_state("INIT")
 
     def detach(self):
-        self.disconnectHandlers()
+        """Detach from the current activity"""
+        self.disconnect_handlers()
         self.activity = None
         
-    def handleEvent(self, *args):
+    def handle_event(self, *args):
+        """Default event handler for the Tutorial.
+        Tests the received object and signal names onto each defined
+        transition and changes to the next state if successful.
+
+        The last parameter should be a two-tuple containing the
+        (signal_name, object_name)
+        """
         sig, objname = args[-1]
         logger.debug("EVENT %s ON %s" % (sig, objname) )
         for transition, next in self.state_machine[self.state]["Events"]:
-            if transition.test(sig,objname):
-                logger.debug("====NEW STATE: %s====" % next)
-                self.state = next
-                dlg = TutoriusDialog(self.state_machine[self.state]["Message"])
-                dlg.setButtonClickedCallback(dlg.closeSelf)
-                dlg.run()
+            if transition.test(sig, objname):
+                self.set_state(next)
 
 #    @staticmethod
 #    def logEvent(obj, *args):
 #        logger.debug("%s" % str(args[-1]))
 
-    def disconnectHandlers(self):
-        for t, id in self.handlers:
-            t.disconnect_handler(id)
-
-#    def setState(self,name):
-#        self.disconnectHandlers()
-#        self.state = name
-#        newstate = ABIWORD_MEF.get(name,())
-#        for event, n in newstate:
-#            target = self.activity
-#            try:
-#                for obj in event.object_name.split("."):
-#                    target = getattr(target,obj)
-#                id = target.connect(self.handler,(event.object_name, event.event_name))
-#                self.handlers.append(target, id)
-#                id = target.connect(Tutorial.logEvent,"EVENT %s ON %s" % (event.object_name, event.event_name))
-#                self.handlers.append(target, id)
-#            except Exception, e:
-#                logger.debug(str(e))
+    def disconnect_handlers(self):
+        """Disconnect all event handlers attached by self"""
+        #Loop through handlers
+        for obj, hid in self.handlers:
+            obj.handler_disconnect(hid)
+        self.handlers = []
+
+
+    def set_state(self, name):
+        """Switch to a new state"""
+        if not self.state_machine.has_key(name):
+            return
+        logger.debug("====NEW STATE: %s====" % name)
+        self.disconnect_handlers()
+        self.state = name
+        newstate = self.state_machine.get(name)
+        for event, unused in newstate["Events"]:
+            self.register_signal(self.handle_event, \
+                        event.object_name, event.event_name)
             
-    def register_signals(self,object,handler,prefix=None,max_depth=None):
+        if newstate.has_key("Message"):
+            dlg = TutoriusDialog(newstate["Message"])
+            dlg.setButtonClickedCallback(dlg.closeSelf)
+            dlg.run()
+
+
+    def register_signals(self, target, handler, prefix=None, max_depth=None):
         """
-            Recursive function to register event handlers on an object
+            Recursive function to register event handlers on an target
             and it's children. The event handler is called with an extra
             argument which is a two-tuple containing the signal name and
-            the FQDN-style name of the object that triggered the event.
+            the FQDN-style name of the target that triggered the event.
 
             This function registers all of the events listed in 
             Tutorial.EVENTS and omits widgets with a name matching
@@ -128,37 +166,108 @@ class Tutorial (object):
             Example arg tuple added:
                 ("focus", "Activity.Toolbox.Bold")
             Side effects:
-                -Handlers connected on the various objects
+                -Handlers connected on the various targets
                 -Handler ID's stored in self.handlers
 
-            @param object the object to recurse on
+            @param target the target to recurse on
             @param handler the handler function to connect
-            @param prefix name prepended to the object name to form a chain
+            @param prefix name prepended to the target name to form a chain
             @param max_depth maximum recursion depth, None for infinity
         """
         #Gtk Containers have a get_children() function
-        if hasattr(object,"get_children") and \
-            hasattr(object.get_children,"__call__"):
-            for child in object.get_children():
+        if hasattr(target, "get_children") and \
+            hasattr(target.get_children, "__call__"):
+            for child in target.get_children():
                 if max_depth is None or max_depth > 0:
                     #Recurse with a prefix on all children
                     pre = ".".join( \
-                        [p for p in (prefix, object.get_name()) \
+                        [p for p in (prefix, target.get_name()) \
                         if not (p is None or p in Tutorial.IGNORED_WIDGETS)] \
                     )
-                    self.register_signals(child,handler,pre,max_depth-1)
+                    self.register_signals(child, handler, pre, max_depth-1)
         name = ".".join( \
-            [p for p in (prefix, object.get_name()) \
+            [p for p in (prefix, target.get_name()) \
             if not (p is None or p in Tutorial.IGNORED_WIDGETS)] \
         )
-        #register events on the object if a widget XXX necessary to check this?
-        if isinstance(object,gtk.Widget):
+        #register events on the target if a widget XXX necessary to check this?
+        if isinstance(target, gtk.Widget):
             for sig in Tutorial.EVENTS:
                 try:
-                    self.handlers.append( (object,object.connect(sig,handler,(sig, name) )) )
+                    self.handlers.append( \
+                        (target, target.connect(sig, handler, (sig, name) )) \
+                    )
                 except TypeError:
                     continue
         
+    def register_signals_numbered(self, \
+                target, handler, prefix="0", max_depth=None):
+        """
+            Recursive function to register event handlers on an target
+            and it's children. The event handler is called with an extra
+            argument which is a two-tuple containing the signal name and
+            the FQDN-style name of the target that triggered the event.
+
+            This function registers all of the events listed in 
+            Tutorial.EVENTS
+
+            Example arg tuple added:
+                ("focus", "1.1.2")
+            Side effects:
+                -Handlers connected on the various targets
+                -Handler ID's stored in self.handlers
+
+            @param target the target to recurse on
+            @param handler the handler function to connect
+            @param prefix name prepended to the target name to form a chain
+            @param max_depth maximum recursion depth, None for infinity
+        """
+        #Gtk Containers have a get_children() function
+        if hasattr(target, "get_children") and \
+            hasattr(target.get_children, "__call__"):
+            children = target.get_children()
+            for i in range(len(children)):
+                child = children[i]
+                if max_depth is None or max_depth > 0:
+                    #Recurse with a prefix on all children
+                    pre = ".".join( \
+                        [p for p in (prefix, str(i)) if not p is None]
+                    )
+                    if max_depth is None:
+                        dep = None
+                    else:
+                        dep = max_depth - 1
+                    self.register_signals_numbered(child, handler, pre, dep)
+        #register events on the target if a widget XXX necessary to check this?
+        if isinstance(target, gtk.Widget):
+            for sig in Tutorial.EVENTS:
+                try:
+                    self.handlers.append( \
+                        (target, target.connect(sig, handler, (sig, prefix) ))\
+                    )
+                except TypeError:
+                    continue
+
+    def register_signal(self, handler, obj_fqdn, signal_name):
+        """Register a signal handler onto a specific widget
+        @param handler function to attach as a handler
+        @param obj_fqdn fqdn-style object name
+        @param signal_name signal name to connect to
+
+        Side effects:
+        the object found and the handler id obtained by connect() are
+        appended in self.handlers
+        """
+        path = obj_fqdn.split(".")
+        #We select the first object and pop the first zero
+        obj = self.activity
+        path.pop(0)
+
+        while len(path) > 0:
+            obj = obj.get_children()[int(path.pop(0))]
+
+        self.handlers.append( \
+            (obj, obj.connect(signal_name, handler, (signal_name, obj_fqdn) ))\
+        )
 
 class State:
     """This is a step in a tutorial. The state represents a collection of 
@@ -207,20 +316,28 @@ class FiniteStateMachine(State):
         """The constructor for a FSM. Pass in the start state and the setup
         actions that need to be taken when the FSM itself start (which may be
         different from what is done in the first state of the machine)."""
+        State.__init__(self)
+
         self.start_state = start_state
         self.actions = setup_actions
         
-        self.tests = []
-        
         self.current_state = self.start_state
+        #TODO Setup current state now?
     
     def setup(self):
+        """
+        Set up the FSM
+        """
         for act in self.actions:
             act.do()
     
     def teardown(self):
+        """
+        Revert any changes done by setup()
+        """
         for act in self.actions:
-            act.undo
+            act.undo()
     
     def verify(self):
-        return self.current_state.verify()
\ No newline at end of file
+        "Verify if the current state passes it's tests"""
+        return self.current_state.verify()