Improved the documenation.

svn: r1048

src/AutoComp.py

@@ -24,7 +24,7 @@ strings as the possible completions. This work was adapted from code
 written by David Hampton.
 """
 
-__author__ = "Donald N. Allingham"
+__author__ = "David R. Hampton, Donald N. Allingham"
 __version__ = "$Revision$"
 
 #-------------------------------------------------------------------------
@@ -41,6 +41,11 @@ import string
 #-------------------------------------------------------------------------
 import gtk
 
+#-------------------------------------------------------------------------
+#
+# AutoCompBase
+#
+#-------------------------------------------------------------------------
 class AutoCompBase:
 
     def __init__(self,widget,plist,source=None):
@@ -57,9 +62,8 @@ class AutoCompBase:
         if source:
             self.nlist = source.nlist
         else:
-            cnv = string.lower
             self.nlist = []
-            self.nlist = map((lambda n: (cnv(n),n)),plist)
+            self.nlist = map((lambda n: (string.lower(n),n)),plist)
             self.nlist.sort()
         self.nl = "xzsdkdjecsc"
         self.l = 0
@@ -105,6 +109,11 @@ class AutoCompBase:
         """
         pass
 
+#-------------------------------------------------------------------------
+#
+# AutoCombo
+#
+#-------------------------------------------------------------------------
 class AutoCombo(AutoCompBase):
     """
     Allows allow completion of the GtkCombo widget with the entries
@@ -197,6 +206,11 @@ class AutoCombo(AutoCompBase):
         else:
             self.vals = [""]
 
+#-------------------------------------------------------------------------
+#
+# AutoEntry
+#
+#-------------------------------------------------------------------------
 class AutoEntry(AutoCompBase):
     """
     Allows allow completion of the GtkEntry widget with the entries

src/Bookmarks.py

@@ -20,6 +20,9 @@
 
 "Handle bookmarks for the gramps interface"
 
+__author__ = "Donald N. Allingham"
+__version__ = "$Revision$"
+
 #-------------------------------------------------------------------------
 #
 # GTK/Gnome modules
@@ -27,7 +30,7 @@
 #-------------------------------------------------------------------------
 import gtk 
 import GTK
-from gnome.ui import *
+import gnome.ui
 
 #-------------------------------------------------------------------------
 #
@@ -86,9 +89,10 @@ class Bookmarks :
         self.myMenu.append(item)
 
     def draw_window(self):
-
+        """Draws the bookmark dialog box"""
         title = "%s - GRAMPS" % _("Edit Bookmarks")
-        self.top = GnomeDialog(title,STOCK_BUTTON_OK,STOCK_BUTTON_CANCEL)
+        self.top = gnome.ui.GnomeDialog(title,gnome.ui.STOCK_BUTTON_OK,
+                                        gnome.ui.STOCK_BUTTON_CANCEL)
         self.top.set_policy(0,1,0)
         self.top.vbox.set_spacing(5)
         self.top.vbox.pack_start(gtk.GtkLabel(_("Edit Bookmarks")),0,0,5)
@@ -103,8 +107,8 @@ class Bookmarks :
         box.pack_start(slist,1,1,5)
         bbox = gtk.GtkVButtonBox()
         bbox.set_layout_default(GTK.BUTTONBOX_START)
-        up = GnomePixmapButton(GnomeStock(STOCK_PIXMAP_UP),_("Up"))
+        up = gnome.ui.GnomePixmapButton(gnome.ui.GnomeStock(gnome.ui.STOCK_PIXMAP_UP),_("Up"))
-        down = GnomePixmapButton(GnomeStock(STOCK_PIXMAP_DOWN),_("Down"))
+        down = gnome.ui.GnomePixmapButton(gnome.ui.GnomeStock(gnome.ui.STOCK_PIXMAP_DOWN),_("Down"))
         delete = gtk.GtkButton(_("Delete"))
         up.connect('clicked', self.up_clicked)
         down.connect('clicked',self.down_clicked)

src/Calendar.py

@@ -25,6 +25,9 @@ C implementation. The original C source can be found at Scott's
 web site at http://www.scottlee.com
 """
 
+__author__ = "Donald N. Allingham"
+__version__ = "$Revision$"
+
 _FR_SDN_OFFSET         = 2375474
 _FR_DAYS_PER_4_YEARS   = 1461
 _FR_DAYS_PER_MONTH     = 30

src/ChooseParents.py

@@ -18,6 +18,14 @@
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 #
 
+"""
+ChooseParents interface allows users to select the paretns of an
+individual.
+"""
+
+__author__ = "Donald N. Allingham"
+__version__ = "$Revision$"
+
 #-------------------------------------------------------------------------
 #
 # internationalization
@@ -56,6 +64,15 @@ class ChooseParents:
     to be edited.
     """
     def __init__(self,db,person,family,family_update,full_update):
+        """
+        Creates a ChoosePerson dialog box.
+
+        db - database associated the person
+        person - person whose parents we are selecting
+        family - current family
+        family_update - task that updates the family display
+        full_update - task that updates the main display 
+        """
         self.db = db
         self.person = person
         self.family = family
@@ -128,7 +145,7 @@ class ChooseParents:
         self.top.show()
 
     def redraw(self):
-
+        """Redraws the potential father and mother lists"""
         self.father_list.freeze()
         self.mother_list.freeze()
         self.father_list.clear()
@@ -199,6 +216,7 @@ class ChooseParents:
             self.flabel.set_label(_("Father"))
 
     def parent_relation_changed(self,obj):
+        """Called everytime the parent relationship information is changegd"""
         self.old_type = self.type
         self.type = const.save_frel(obj.get_text())
         if self.old_type == "Partners" or self.type == "Partners":
@@ -231,6 +249,9 @@ class ChooseParents:
         return family
 
     def mother_list_select_row(self,obj,a,b,c):
+        """Called when a row is selected in the mother list. Sets the
+        active mother based off the id associated with the row."""
+        
         id = obj.get_row_data(a)
         if id:
             self.mother = self.db.getPerson(id)
@@ -238,6 +259,8 @@ class ChooseParents:
             self.mother = None
 
     def father_list_select_row(self,obj,a,b,c):
+        """Called when a row is selected in the father list. Sets the
+        active father based off the id associated with the row."""
         id = obj.get_row_data(a)
         if id:
             self.father = self.db.getPerson(id)
@@ -245,6 +268,10 @@ class ChooseParents:
             self.father = None
 
     def save_parents_clicked(self,obj):
+        """
+        Called with the OK button nis pressed. Saves the selected people as parents
+        of the main perosn.
+        """
         mother_rel = const.childRelations[self.mother_rel.get_text()]
         father_rel = const.childRelations[self.father_rel.get_text()]
 
@@ -280,6 +307,8 @@ class ChooseParents:
         self.family_update(None)
 
     def add_new_parent(self,person):
+        """Adds a new person to either the father list or the mother list,
+        depending on the gender of the person."""
         id = person.getId()
         self.type = const.save_frel(self.prel.get_text())
         dinfo = self.db.getPersonDisplay(id)
@@ -303,6 +332,9 @@ class ChooseParents:
         self.full_update()
         
     def add_parent_clicked(self,obj):
+        """Called with the Add New Person button is pressed. Calls the QuickAdd
+        class to create a new person."""
+        
         import QuickAdd
         QuickAdd.QuickAdd(self.db,"male",self.add_new_parent)
 

src/Date.py

@@ -18,7 +18,10 @@
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 #
 
-"Support for the dates"
+"Support for dates"
+
+__author__ = "Donald N. Allingham"
+__version__ = "$Revision$"
 
 #-------------------------------------------------------------------------
 #

src/DateEdit.py

@@ -19,10 +19,16 @@
 #
 
 """
-Adds autocompletion to a GtkEntry box, using the passed list of
+The DateEdit interface provides visual feedback to the user via a pixamp
-strings as the possible completions.
+to indicate if the assocated GtkEntry box contains a valid date. Green
+means complete and valid date. Yellow means a valid, but incomplete date.
+Red means that the date is not valid, and will be viewed as a text string
+instead of a date.
 """
 
+__author__ = "Donald N. Allingham"
+__version__ = "$Revision$"
+
 #-------------------------------------------------------------------------
 #
 # GNOME modules
@@ -37,140 +43,140 @@ import GdkImlib
 #-------------------------------------------------------------------------
 import Date
 
-#-------------------------------------------------------------------------
-#
-# Date indicator pixmaps
-#
-#-------------------------------------------------------------------------
-_good = [
-    "10 10 24 1",
-    " 	c None",
-    ".	c #0EB40E",
-    "+	c #11A711",
-    "@	c #11A211",
-    "#	c #0DA10D",
-    "$	c #09CB09",
-    "%	c #0BCC0B",
-    "&	c #08CD08",
-    "*	c #098609",
-    "=	c #05E705",
-    "-	c #02F502",
-    ";	c #07E007",
-    ">	c #0A9D0A",
-    ",	c #01F901",
-    "'	c #00FF00",
-    ")	c #01F801",
-    "!	c #05E605",
-    "~	c #0AC40A",
-    "{	c #0AC30A",
-    "]	c #000000",
-    "^	c #099209",
-    "/	c #08CB08",
-    "(	c #033403",
-    "_	c #098509",
-    " .+++@#   ",
-    ".$%%%%&*  ",
-    "+%===-;>  ",
-    "+%=,')!~  ",
-    "+%='')!{] ",
-    "@%-))-;^] ",
-    "#&;!!;/(  ",
-    " _>~{^(]  ",
-    "    ]]    ",
-    "          "]
-
-_bad = [
-    "10 10 21 1",
-    " 	c None",
-    ".	c #A21818",
-    "+	c #A31818",
-    "@	c #9A1717",
-    "#	c #C80E0E",
-    "$	c #C90F0F",
-    "%	c #CA0C0C",
-    "&	c #E60606",
-    "*	c #F40202",
-    "=	c #DE0909",
-    "-	c #8F0D0D",
-    ";	c #F90101",
-    ">	c #FF0000",
-    ",	c #F80101",
-    "'	c #E50707",
-    ")	c #C20E0E",
-    "!	c #C10E0E",
-    "~	c #000000",
-    "{	c #810C0C",
-    "]	c #C80C0C",
-    "^	c #130202",
-    "  .++@    ",
-    " #$$$$%   ",
-    ".$&&&*=-  ",
-    "+$&;>,')  ",
-    "+$&>>,'!~ ",
-    "@$*,,*={~ ",
-    " %=''=]^  ",
-    "  -)!{^~  ",
-    "    ~~    ",
-    "          "]
-
-_caution = [
-    "10 10 21 1",
-    " 	c None",
-    ".	c #B0AF28",
-    "+	c #B2B028",
-    "@	c #A9A726",
-    "#	c #D1D017",
-    "$	c #D2D118",
-    "%	c #D2D114",
-    "&	c #EAEA0B",
-    "*	c #F6F604",
-    "=	c #E3E30F",
-    "-	c #979615",
-    ";	c #F9F902",
-    ">	c #FFFF00",
-    ",	c #F9F903",
-    "'	c #E9E90B",
-    ")	c #CACA18",
-    "!	c #C9C918",
-    "~	c #000000",
-    "{	c #898813",
-    "]	c #CFCF14",
-    "^	c #151504",
-    "  .++@    ",
-    " #$$$$%   ",
-    ".$&&&*=-  ",
-    "+$&;>,')  ",
-    "+$&>>,'!~ ",
-    "@$*,,*={~ ",
-    " %=''=]^  ",
-    "  -)!{^~  ",
-    "    ~~    ",
-    "          "]
-
 #-------------------------------------------------------------------------
 #
 # DateEdit
 #
 #-------------------------------------------------------------------------
 class DateEdit:
-    def __init__(self,input,output):
+    """Class that associates a pixmap with a text widget, providing visual
-        self.input = input
+    feedback that indicates if the text widget contains a valid date"""
-        self.output = output
+    
+    good = GdkImlib.create_image_from_xpm([
+        "10 10 24 1",
+        " 	c None",
+        ".	c #0EB40E",
+        "+	c #11A711",
+        "@	c #11A211",
+        "#	c #0DA10D",
+        "$	c #09CB09",
+        "%	c #0BCC0B",
+        "&	c #08CD08",
+        "*	c #098609",
+        "=	c #05E705",
+        "-	c #02F502",
+        ";	c #07E007",
+        ">	c #0A9D0A",
+        ",	c #01F901",
+        "'	c #00FF00",
+        ")	c #01F801",
+        "!	c #05E605",
+        "~	c #0AC40A",
+        "{	c #0AC30A",
+        "]	c #000000",
+        "^	c #099209",
+        "/	c #08CB08",
+        "(	c #033403",
+        "_	c #098509",
+        " .+++@#   ",
+        ".$%%%%&*  ",
+        "+%===-;>  ",
+        "+%=,')!~  ",
+        "+%='')!{] ",
+        "@%-))-;^] ",
+        "#&;!!;/(  ",
+        " _>~{^(]  ",
+        "    ]]    ",
+        "          "])
+    
+    bad = GdkImlib.create_image_from_xpm([
+        "10 10 21 1",
+        " 	c None",
+        ".	c #A21818",
+        "+	c #A31818",
+        "@	c #9A1717",
+        "#	c #C80E0E",
+        "$	c #C90F0F",
+        "%	c #CA0C0C",
+        "&	c #E60606",
+        "*	c #F40202",
+        "=	c #DE0909",
+        "-	c #8F0D0D",
+        ";	c #F90101",
+        ">	c #FF0000",
+        ",	c #F80101",
+        "'	c #E50707",
+        ")	c #C20E0E",
+        "!	c #C10E0E",
+        "~	c #000000",
+        "{	c #810C0C",
+        "]	c #C80C0C",
+        "^	c #130202",
+        "  .++@    ",
+        " #$$$$%   ",
+        ".$&&&*=-  ",
+        "+$&;>,')  ",
+        "+$&>>,'!~ ",
+        "@$*,,*={~ ",
+        " %=''=]^  ",
+        "  -)!{^~  ",
+        "    ~~    ",
+        "          "])
+    
+    caution = GdkImlib.create_image_from_xpm([
+        "10 10 21 1",
+        " 	c None",
+        ".	c #B0AF28",
+        "+	c #B2B028",
+        "@	c #A9A726",
+        "#	c #D1D017",
+        "$	c #D2D118",
+        "%	c #D2D114",
+        "&	c #EAEA0B",
+        "*	c #F6F604",
+        "=	c #E3E30F",
+        "-	c #979615",
+        ";	c #F9F902",
+        ">	c #FFFF00",
+        ",	c #F9F903",
+        "'	c #E9E90B",
+        ")	c #CACA18",
+        "!	c #C9C918",
+        "~	c #000000",
+        "{	c #898813",
+        "]	c #CFCF14",
+        "^	c #151504",
+        "  .++@    ",
+        " #$$$$%   ",
+        ".$&&&*=-  ",
+        "+$&;>,')  ",
+        "+$&>>,'!~ ",
+        "@$*,,*={~ ",
+        " %=''=]^  ",
+        "  -)!{^~  ",
+        "    ~~    ",
+        "          "])
+    
+    def __init__(self,text_obj,pixmap_obj):
+        """Creates a connection between the text_obj and the pixmap_obj"""
+        
+        self.text_obj = text_obj
+        self.pixmap_obj = pixmap_obj
         self.checkval = Date.Date()
-        self.input.connect('focus-out-event',self.check)
+        self.text_obj.connect('focus-out-event',self.check)
-        self.good = GdkImlib.create_image_from_xpm(_good)
-        self.bad = GdkImlib.create_image_from_xpm(_bad)
-        self.caution = GdkImlib.create_image_from_xpm(_caution)
         self.check(None,None)
 
     def check(self,obj,val):
-        text = self.input.get_text()
+        """Called with the text box loses focus. If the string contains a
+        valid date, sets the appropriate pixmap"""
+
+        text = self.text_obj.get_text()
         self.checkval.set(text)
         if not self.checkval.isValid():
-            self.output.load_imlib(self.bad)
+            self.pixmap_obj.load_imlib(DateEdit.bad)
         elif self.checkval.getIncomplete():
-            self.output.load_imlib(self.caution)
+            self.pixmap_obj.load_imlib(DateEdit.caution)
         else:
-            self.output.load_imlib(self.good)
+            self.pixmap_obj.load_imlib(DateEdit.good)