From 66c41b8781070d883ed1c1ad5b8058856cadd646 Mon Sep 17 00:00:00 2001 From: Don Allingham Date: Tue, 18 Jun 2002 23:17:36 +0000 Subject: [PATCH] Updated documentation svn: r1041 --- src/AutoComp.py | 55 +++++++++++++++++++++++++++++--------------- src/RelLib.py | 37 ++++++++++++++++++++++------- src/SubstKeywords.py | 4 ++-- 3 files changed, 68 insertions(+), 28 deletions(-) diff --git a/src/AutoComp.py b/src/AutoComp.py index e0b837f43..ca761f9e1 100644 --- a/src/AutoComp.py +++ b/src/AutoComp.py @@ -20,9 +20,13 @@ """ Adds autocompletion to a GtkEntry box, using the passed list of -strings as the possible completions. +strings as the possible completions. This work was adapted from code +written by David Hampton. """ +__author__ = "Donald N. Allingham" +__version__ = "$Revision$" + #------------------------------------------------------------------------- # # python modules @@ -37,14 +41,19 @@ import string #------------------------------------------------------------------------- import gtk -#------------------------------------------------------------------------- -# -# AutoCompBase -# -#------------------------------------------------------------------------- class AutoCompBase: def __init__(self,widget,plist,source=None): + """ + Creates a autocompleter for the specified GNOME/GTK widget, using the + list of strings as the completion values. The AutoCompBase class + should never be instantiated on its own. Instead, classes should be + derived from it. + + widget - widget instance the completer is assocated with + plist - List of completion strings + source - If not None, uses the completion values of an already existing AutoCompBase instance + """ if source: self.nlist = source.nlist else: @@ -92,19 +101,28 @@ class AutoCompBase: entry.select_region(0, 0) def timer_callback(self,entry): + """ + Perfroms the actual task of completion. This method should be + overridden in all subclasses + """ pass -#------------------------------------------------------------------------- -# -# AutoCombo -# -#------------------------------------------------------------------------- class AutoCombo(AutoCompBase): """ - Allows allow completion of the GtkEntry widget with the entries - in the passed string list. + Allows allow completion of the GtkCombo widget with the entries + in the passed string list. This class updates the drop down window + with the values that currently match the substring in the text box. """ + def __init__(self,widget,plist,source=None): + """ + Creates a autocompleter for the a GtkCombo widget, using the + list of strings as the completion values. The + + widget - GtkCombo instance the completer is assocated with + plist - List of completion strings + source - If not None, uses the completion values of an already existing AutoCompBase instance + """ AutoCompBase.__init__(self,widget,plist,source) self.entry = widget widget.entry.connect("insert-text",self.insert_text) @@ -114,6 +132,8 @@ class AutoCombo(AutoCompBase): self.inb = 0 def setval(self,widget,event): + """Callback task called on the button release""" + self.inb = 0 text = self.entry.entry.get_text() if self.nl == string.lower(text): @@ -121,6 +141,10 @@ class AutoCombo(AutoCompBase): self.entry.entry.select_region(self.l, -1) def build_list(self,widget,event): + """Internal task that builds the popdown strings. This task is called when the + combo button that activates the dropdown menu is pressed + """ + self.inb = 1 if self.vals[0] == "": self.entry.set_popdown_strings([self.entry.entry.get_text()]) @@ -175,11 +199,6 @@ class AutoCombo(AutoCompBase): else: self.vals = [""] -#------------------------------------------------------------------------- -# -# AutoEntry -# -#------------------------------------------------------------------------- class AutoEntry(AutoCompBase): """ Allows allow completion of the GtkEntry widget with the entries diff --git a/src/RelLib.py b/src/RelLib.py index 7d7a43ff1..9e0e6bd8a 100644 --- a/src/RelLib.py +++ b/src/RelLib.py @@ -18,10 +18,10 @@ # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA # -"""The core library of the gramps database""" - -__author__ = "Don Allingham" +"""The core library of the GRAMPS database""" +__author__ = "Donald N. Allingham" +__version__ = "$Revision$" #------------------------------------------------------------------------- # @@ -48,9 +48,9 @@ import const #------------------------------------------------------------------------- try: from ZODB import Persistent - except ImportError: class Persistent: + """Dummy class used if ZODB is not installed on the system""" pass #------------------------------------------------------------------------- @@ -74,9 +74,11 @@ _id_reg = compile("%\d+d") def extlist(lst): + """Returns a copy of the passed list""" return lst[:] # Make a copy. def extmap(map): + """Returns a map""" return map @@ -134,11 +136,13 @@ class SourceNote(Persistent): return self.note def unique_note(self): + """Creates a unique instance of the current note""" self.note = Note(self.note.get()) class LdsOrd(SourceNote): """LDS Ordinance support""" def __init__(self,source=None): + """Creates a LDS Ordinance instance""" SourceNote.__init__(self,source) if source: self.famc = source.famc @@ -169,15 +173,19 @@ class LdsOrd(SourceNote): return self.place def setFamily(self,family): + """Sets the family associated with the LDS ordinance""" self.famc = family def getFamily(self): + """Gets the family associated with the LDS ordinance""" return self.famc def setStatus(self,val): + """Sets the status of the LDS ordinance""" self.status = val def getStatus(self): + """Gets the status of the LDS ordinance""" return self.status def setDate(self, date) : @@ -203,9 +211,11 @@ class LdsOrd(SourceNote): self.date = date def setTemple(self,temple): + """Sets the temple assocated with the LDS ordinance""" self.temple = temple def getTemple(self): + """Gets the temple assocated with the LDS ordinance""" return self.temple def are_equal(self,other): @@ -258,7 +268,6 @@ class Place(SourceNote): source - Object to copy. If none supplied, create an empty place object""" SourceNote.__init__(self,source) - if source: self.long = source.log self.lat = source.lat @@ -367,6 +376,13 @@ class Place(SourceNote): self.photoList = list def getDisplayInfo(self): + """Gets the display information associated with the object. This includes + the information that is used for display and for sorting. Returns a list + consisting of 13 strings. These are: Place Title, Place ID, Main Location + Parish, Main Location County, Main Location City, Main Location State/Province, + Main Location Country, upper case Place Title, upper case Parish, upper + case city, upper case county, upper case state, upper case country""" + if self.main_loc: return [self.title,self.id,self.main_loc.parish,self.main_loc.city, self.main_loc.county,self.main_loc.state,self.main_loc.country, @@ -374,8 +390,7 @@ class Place(SourceNote): upper(self.main_loc.city), upper(self.main_loc.county), upper(self.main_loc.state), upper(self.main_loc.country)] else: - return [self.title,self.id,'','','','','', - upper(self.title), '','','','',''] + return [self.title,self.id,'','','','','',upper(self.title), '','','','',''] class Researcher(Persistent): """Contains the information about the owner of the database""" @@ -654,6 +669,7 @@ class ObjectRef(Persistent): return self.note def unique_note(self): + """Creates a unique instance of the current note""" self.note = Note(self.note.get()) def addAttribute(self,attr): @@ -1253,6 +1269,7 @@ class Person(Persistent): return self.note def unique_note(self): + """Creates a unique instance of the current note""" self.note = Note(self.note.get()) def setPosition(self,pos): @@ -1505,6 +1522,7 @@ class Family(Persistent): return self.note def unique_note(self): + """Creates a unique instance of the current note""" self.note = Note(self.note.get()) def setNoteObj(self,obj): @@ -1695,6 +1713,7 @@ class Source(Persistent): return self.note def unique_note(self): + """Creates a unique instance of the current note""" self.note = Note(self.note.get()) def setAuthor(self,author): @@ -1816,6 +1835,7 @@ class SourceRef(Persistent): return 0 def unique_note(self): + """Creates a unique instance of the current note""" self.comments = Note(self.comments.get()) #------------------------------------------------------------------------- @@ -1824,7 +1844,8 @@ class SourceRef(Persistent): # #------------------------------------------------------------------------- class GrampsDB(Persistent): - """Gramps database object""" + """GRAMPS database object. This object is a base class for other + objects.""" def __init__(self): """creates a new GrampsDB""" diff --git a/src/SubstKeywords.py b/src/SubstKeywords.py index a3a6aeb03..90f59b977 100644 --- a/src/SubstKeywords.py +++ b/src/SubstKeywords.py @@ -64,7 +64,7 @@ class SubstKeywords: """ def __init__(self,person): - """Associates a person with the class""" + """Creates a new object and associates a person with it.""" self.n = person.getPrimaryName().getRegularName() self.N = person.getPrimaryName().getName() @@ -95,7 +95,7 @@ class SubstKeywords: self.M = "" def replace(self,line): - """Returns a new line of text with the substitutions performed""" + """Returns a new line of text with the substitutions performed.""" line = string.replace(line,"$n",self.n) line = string.replace(line,"$N",self.N)