[gnue] r8030 - trunk/gnue-common/src/definitions

[jcater]

Author: jcater
Date: 2005-09-29 05:56:22 -0500 (Thu, 29 Sep 2005)
New Revision: 8030

Modified:
   trunk/gnue-common/src/definitions/GObjects.py
Log:
Added an iterator method/class for GObjects that allows passing in a test 
method or a list of 
types and return an iterator of the children of that object passing the test. 

Also clarified documentation on  what the setitem and getitem hooks are for.



Modified: trunk/gnue-common/src/definitions/GObjects.py
===================================================================
--- trunk/gnue-common/src/definitions/GObjects.py       2005-09-28 17:20:25 UTC 
(rev 8029)
+++ trunk/gnue-common/src/definitions/GObjects.py       2005-09-29 10:56:22 UTC 
(rev 8030)
@@ -99,7 +99,7 @@
     initialize itself.  This type of logic cannot be places into an __init__
     as the children may not be loaded yet or may not yet have the needed
     information.
-    
+
     @type iterations: integer
     @param iterations: Limits the number of passes to the specified number.
                        This doesn't appear to be used anywhere.
@@ -117,7 +117,7 @@
 
 ## TODO: Below is a call-less recursive version of
 ## TODO: phaseInit.  Needs to be profiled both ways.
-## TODO: Profile tests have shown this to be .001 
+## TODO: Profile tests have shown this to be .001
 ## TODO: cpu seconds faster per call
 ##    stack = [self]
 ##    while stack:
@@ -158,7 +158,7 @@
     #       This is only so content can be set, etc, after
     #       loading from XML.
     #
-    
+
     """
     return len(self._inits)
 
@@ -182,11 +182,11 @@
 
   def getChildrenAsContent(self):
     """
-    Returns the content of any GContent objects that are children 
-    of this object.  
-    
+    Returns the content of any GContent objects that are children
+    of this object.
+
     @rtype: string or binary(?)
-    @return: The contents of the children 
+    @return: The contents of the children
     """
 
     # This is down here to avoid recursive importing
@@ -223,7 +223,7 @@
   def addChild(self, child):
     """
     Adds an object to an instances list of children
-    
+
     @type child: GObj derived class
     @param child: The object to add.
     """
@@ -232,7 +232,7 @@
   def getXmlTag(self, stripPrefixes=None):
     """
     Returns the xml tag to be used to represent the object.
-    
+
     @param stripPrefixes: A list of prefixes that will automatically
                           be removed from the objects type.  This can be
                           used to remove the gf from the start of all
@@ -247,8 +247,8 @@
     for prefix in stripPrefixes:
       if prefix == self._type[:len(prefix)]:
         return string.lower(string.replace(self._type[len(prefix):], '_', '-'))
-    return string.lower(string.replace(self._type, '_', '-'))  
-    
+    return string.lower(string.replace(self._type, '_', '-'))
+
   def dumpXML(self, lookupDict, treeDump=None, gap="  ", xmlnamespaces={},
               textEncoding='<locale>', stripPrefixes=None):
     """
@@ -387,7 +387,7 @@
 
   def walk(self, function, *args, **parms):
     """
-    Function that recursivly walks down through a tree of GObj 
+    Function that recursively walks down through a tree of GObj
     instances and applies a function to them.
     """
     function(self, *args, **parms)
@@ -395,6 +395,46 @@
       if isinstance(child, GObj):
         child.walk(function, *args, **parms)
 
+  def iterator(self, test=None, types=(), includeSelf=True):
+    """
+    Return a python iterator of child objects.
+
+    @param test: A function that should return true or false to
+           indicate whether a GObject should be included in the
+           iterator. This method will be passed a GObj instance.
+           e.g., test=lambda obj: obj._type in ('GFField,'GFEntry')
+    @type test: method
+
+    @param types: A list of valid child types to return.
+           E.g., types=('GFField','GFEntry')
+    @type types: list
+
+    @param includeSelf: Should the current object be included in the tests?
+    @type types: boolean
+
+    @return: An iterator of matching objects
+
+    """
+    if includeSelf:
+      objects = [self]
+    else:
+      objects = self._children
+    set = []
+
+    def _includable(object):
+      include = True
+      if test:
+        include = include and test(object)
+      if types:
+        include = include and object._type in types
+      if include:
+        set.append(object)
+
+    for child in objects:
+      child.walk(_includable)
+
+    return _GObjectIterator(set)
+
   def findParentOfType(self, parentType, includeSelf=1):
     """
     Moves upward though the parents of an object till
@@ -416,12 +456,12 @@
         return parentObject
 
       parentObject = parentObject.getParent ()
-  
+
   def findChildNamed(self, name, childType = None):
     """
     Moves downward though the children of an object till
     it finds the child with the specified name.
-    
+
     @param name: The name to search for
     @param childType: The type of object to search for, if None then any type
                  will match.
@@ -435,14 +475,13 @@
 
     return None
 
-
   def findChildOfType(self, childType, includeSelf=1, allowAllChildren=0):
     """
     Moves downward though the children of an object till
     it finds the child of the specified type
-  
+
     """
-  
+
     if includeSelf and self._type == childType:
       return self
 
@@ -495,8 +534,27 @@
       return self._type[2:] + " (%s)" % self._type[2:]
 
   # ===========================================================================
-  # Hooks - I haven't a clue yet
+  # Dictionary-style access to GObject attributes (namespace-safe)
   # ===========================================================================
+  """
+  This is the method of attribute access used by Designer and Reports.
+  For example. if foo is a GObject, then the following are equivalent:
+      foo.required = 'Y'
+      foo['required'] = 'Y'
+
+  The advantage of this method, however, is when namespaces are used
+  in the GObj XML document (i.e., reports). e.g., :
+     foo['Char:x'] = 1
+     foo['Char:y'] = 2
+  These don't have a clean equivalent using the .attribute method.
+  (Though, technically, a tool could access foo.Char__x, but that
+  should be considered bad style.)
+
+  Eventually,  .attribute style access should probably be deprecated,
+  so we can clean up the python namespaces of GObjects. (i.e., we could
+  keep all XML-storable attributes in one dict instead of in the
+  namespace __dict__.
+  """
   def __getitem__(self, key):
     return self.__dict__[key.replace(':', '__')]
 
@@ -504,6 +562,19 @@
     return self._setItemHook(key.replace(':', '__'), value)
 
   def _setItemHook(self, key, value):
+    """
+    This bit of nastiness is here to let GNUe Designer
+    capture the setting of GObject properties. This is
+    primarily used in the wizard system so Designer
+    can act in real time as a wizard sets a document's
+    properties.
+
+    I.e., if a wizard sets
+      field['width'] = 10
+
+    Designer can immediately changed the visual width
+    of the field as displayed on screen.
+    """
     self.__dict__[key] = value
 
 
@@ -598,3 +669,22 @@
               break
 
     return result
+
+
+
+# =============================================================================
+# Convenience class for the GObject .iterator() method
+# =============================================================================
+class _GObjectIterator:
+  def __init__(self, set):
+    self.stack = set[:]
+
+  def __iter__(self):
+    return self
+
+  def next(self):
+    if self.stack:
+      return self.stack.pop(0)
+    else:
+      raise StopIteration
+