diff --git a/src/DataViews/GrampletView.py b/src/DataViews/GrampletView.py index 3056b80b1..a97936729 100644 --- a/src/DataViews/GrampletView.py +++ b/src/DataViews/GrampletView.py @@ -26,7 +26,7 @@ GrampletView interface. #------------------------------------------------------------------------- # -# gtk modules +# Python modules # #------------------------------------------------------------------------- import gtk @@ -40,6 +40,11 @@ import types import os from gettext import gettext as _ +#------------------------------------------------------------------------- +# +# GRAMPS modules +# +#------------------------------------------------------------------------- import Errors import const import PageView @@ -68,6 +73,9 @@ NL = "\n" debug = False def register_gramplet(data_dict): + """ + Function to register a gramplet. Called from plugin directory. + """ global AVAILABLE_GRAMPLETS base_opts = {"name":"Unnamed Gramplet", "tname": _("Unnamed Gramplet"), @@ -78,6 +86,10 @@ def register_gramplet(data_dict): AVAILABLE_GRAMPLETS[base_opts["name"]] = base_opts def register(**data): + """ + Wrapper around register_gramplet to demonstrate a common + interface for all plugins. + """ if "type" in data: if data["type"].lower() == "gramplet": register_gramplet(data) @@ -87,6 +99,9 @@ def register(**data): print ("Plugin did not define type.") def parse_tag_attr(text): + """ + Function used to parse markup. + """ text = text.strip() parts = text.split(" ", 1) attrs = {} @@ -102,6 +117,10 @@ def parse_tag_attr(text): return [parts[0].upper(), attrs] def get_gramplet_opts(name, opts): + """ + Lookup the options for a given gramplet name and update + the options with provided dictionary, opts. + """ if name in AVAILABLE_GRAMPLETS: data = AVAILABLE_GRAMPLETS[name] my_data = data.copy() @@ -112,6 +131,9 @@ def get_gramplet_opts(name, opts): return {} def get_gramplet_options_by_name(name): + """ + Get options by gramplet name. + """ if debug: print "name:", name if name in AVAILABLE_GRAMPLETS: return AVAILABLE_GRAMPLETS[name].copy() @@ -120,6 +142,9 @@ def get_gramplet_options_by_name(name): return None def get_gramplet_options_by_tname(name): + """ + get options by translated name. + """ if debug: print "name:", name for key in AVAILABLE_GRAMPLETS: if AVAILABLE_GRAMPLETS[key]["tname"] == name: @@ -128,6 +153,9 @@ def get_gramplet_options_by_tname(name): return None def make_requested_gramplet(viewpage, name, opts, dbstate, uistate): + """ + Make a GUI gramplet given its name. + """ if name in AVAILABLE_GRAMPLETS: gui = GuiGramplet(viewpage, dbstate, uistate, **opts) if opts.get("content", None): @@ -152,6 +180,9 @@ def logical_true(value): return value in ["True", True, 1, "1"] class LinkTag(gtk.TextTag): + """ + Class for keeping track of link data. + """ lid = 0 def __init__(self, buffer): LinkTag.lid += 1 @@ -162,7 +193,13 @@ class LinkTag(gtk.TextTag): tag_table.add(self) class GrampletWindow(ManagedWindow.ManagedWindow): + """ + Class for showing a detached gramplet. + """ def __init__(self, gramplet): + """ + Constructs the window, and loads the GUI gramplet. + """ self.title = gramplet.title + " " + _("Gramplet") self.gramplet = gramplet ManagedWindow.ManagedWindow.__init__(self, gramplet.uistate, [], self.__class__) @@ -188,6 +225,9 @@ class GrampletWindow(ManagedWindow.ManagedWindow): self.gramplet.gvoptions.hide() def handle_response(self, object, response): + """ + Callback for tacking care of button clicks. + """ if response in [gtk.RESPONSE_CLOSE, gtk.STOCK_CLOSE]: self.close() elif response == gtk.RESPONSE_HELP: @@ -196,9 +236,15 @@ class GrampletWindow(ManagedWindow.ManagedWindow): self.gramplet.tname.replace(" ", "_")) def build_menu_names(self, obj): + """ + Part of the GRAMPS window interface. + """ return (self.title, 'Gramplet') def get_title(self): + """ + Returns the window title. + """ return self.title def close(self, *args): @@ -224,7 +270,13 @@ class GrampletWindow(ManagedWindow.ManagedWindow): #------------------------------------------------------------------------ class Gramplet(object): + """ + Base class for non-graphical gramplet code. + """ def __init__(self, gui): + """ + Internal constructor for non-graphical gramplets. + """ self._idle_id = 0 self._pause = False self._generator = None @@ -250,14 +302,23 @@ class Gramplet(object): self._active_changed(self.dbstate.active.handle) def init(self): # once, constructor + """ + External constructor for developers to put their initialization + code. Designed to be overridden. + """ pass def build_options(self): + """ + External constructor for developers to put code for building + options. + """ pass def main(self): # return false finishes """ - Generator which will be run in the background. + The main place for the gramplet's code. This is a generator. + Generator which will be run in the background, through update(). """ if debug: print "%s dummy" % self.gui.title yield False @@ -278,44 +339,89 @@ class Gramplet(object): return def active_changed(self, handle): + """ + Developers should put their code that occurs when the active + person is changed. + """ pass def _active_changed(self, handle): + """ + Private code that updates the GUI when active_person is changed. + """ self.uistate.push_message(self.gui.dbstate, _("Gramplet %s is running") % self.gui.title) self.active_changed(handle) def db_changed(self): + """ + Method executed when the database is changed. + """ if debug: print "%s is connecting" % self.gui.title pass def link(self, text, link_type, data, size=None, tooltip=None): + """ + Creates a clickable link in the textview area. + """ self.gui.link(text, link_type, data, size, tooltip) # Shortcuts to the gui functionality: def set_tooltip(self, tip): + """ + Sets the tooltip for this gramplet. + """ self.gui.tooltip = tip def get_text(self): + """ + Returns the current text of the textview. + """ return self.gui.get_text() def insert_text(self, text): + """ + Insert the given text in the textview at the cursor. + """ self.gui.insert_text(text) def render_text(self, text): + """ + Render the given text, given that set_use_markup is on. + """ self.gui.render_text(text) def clear_text(self): + """ + Clear all of the text from the textview. + """ self.gui.clear_text() def set_text(self, text, scroll_to='start'): + """ + Clear and set the text to the given text. Additionally, move the + cursor to the position given. Positions are: + 'start': start of textview + 'end': end of textview + 'begin': begin of line, before setting the text. + """ self.gui.set_text(text, scroll_to) def append_text(self, text, scroll_to="end"): + """ + Append the text to the textview. Additionally, move the + cursor to the position given. Positions are: + 'start': start of textview + 'end': end of textview + 'begin': begin of line, before setting the text. + """ self.gui.append_text(text, scroll_to) def set_use_markup(self, value): + """ + Allows the use of render_text to show markup. + """ self.gui.set_use_markup(value) def set_wrap(self, value): @@ -345,12 +451,19 @@ class Gramplet(object): # Other functions of the gramplet: def load_data_to_text(self, pos=0): + """ + Load information from the data portion of the saved + Gramplet to the textview. + """ if len(self.gui.data) >= pos + 1: text = self.gui.data[pos] text = text.replace("\\n", chr(10)) self.set_text(text, 'end') def save_text_to_data(self): + """ + Save the textview to the data portion of a saved gramplet. + """ text = self.get_text() text = text.replace(chr(10), "\\n") self.gui.data.append(text) @@ -430,6 +543,10 @@ class Gramplet(object): self._idle_id = 0 def _db_changed(self, db): + """ + Internal method for handling items that should happen when the + database changes. This will push a message to the GUI status bar. + """ if debug: print "%s is _connecting" % self.gui.title self.uistate.push_message(self.dbstate, _("Gramplet %s is running") % self.gui.title) @@ -439,12 +556,21 @@ class Gramplet(object): self.update() def get_option_widget(self, label): + """ + Retrieve an option's widget by its label text. + """ return self.option_dict[label][0] def get_option(self, label): + """ + Retireve an option by its label text. + """ return self.option_dict[label][1] def add_option(self, option): + """ + Add an option to the GUI gramplet. + """ from PluginUtils import make_gui_option #tooltips, dbstate, uistate, track widget, label = make_gui_option(option, None, self.dbstate, @@ -453,6 +579,9 @@ class Gramplet(object): self.option_order.append(option.get_label()) def save_update_options(self, obj): + """ + Save a gramplet's options to file. + """ self.save_options() self.update() @@ -467,6 +596,9 @@ class GuiGramplet: LOCAL_DRAG_TYPE = 'GRAMPLET' LOCAL_DRAG_TARGET = (LOCAL_DRAG_TYPE, 0, TARGET_TYPE_FRAME) def __init__(self, viewpage, dbstate, uistate, title, **kwargs): + """ + Internal constructor for GUI portion of a gramplet. + """ self.viewpage = viewpage self.dbstate = dbstate self.uistate = uistate @@ -478,6 +610,8 @@ class GuiGramplet: ########## Set defaults self.name = kwargs.get("name", "Unnamed Gramplet") self.tname = kwargs.get("tname", "Unnamed Gramplet") + self.version = kwargs.get("version", "0.0.0") + self.gramps = kwargs.get("gramps", "0.0.0") self.expand = logical_true(kwargs.get("expand", False)) self.height = int(kwargs.get("height", 200)) self.column = int(kwargs.get("column", -1)) @@ -522,6 +656,9 @@ class GuiGramplet: gtk.gdk.ACTION_COPY) def close(self, *obj): + """ + Remove (delete) the gramplet from view. + """ if self.state == "windowed": return self.state = "closed" @@ -529,6 +666,9 @@ class GuiGramplet: self.mainframe.get_parent().remove(self.mainframe) def detach(self): + """ + Detach the gramplet from the GrampletView, and open in own window. + """ # hide buttons: self.set_state("windowed") self.viewpage.detached_gramplets.append(self) @@ -536,6 +676,9 @@ class GuiGramplet: self.detached_window = GrampletWindow(self) def set_state(self, state): + """ + Set the state of a gramplet. + """ self.state = state if state == "minimized": self.scrolledwindow.hide() @@ -560,6 +703,9 @@ class GuiGramplet: self.pui.update() def change_state(self, obj): + """ + Change the state of a gramplet. + """ if self.state == "windowed": pass # don't change if windowed else: @@ -569,6 +715,9 @@ class GuiGramplet: self.set_state("maximized") def set_properties(self, obj): + """ + Set the properties of a gramplet. + """ if self.state == "windowed": pass else: @@ -1109,6 +1258,8 @@ class GrampletView(PageView.PersonNavView): elif key == "title": continue elif key == "column": continue elif key == "row": continue + elif key == "version": continue # code, don't save + elif key == "gramps": continue # code, don't save elif key == "data": if not isinstance(base_opts["data"], (list, tuple)): fp.write(("data[0]=%s" + NL) % base_opts["data"]) diff --git a/src/plugins/gramplet/AgeOnDateGramplet.py b/src/plugins/gramplet/AgeOnDateGramplet.py index 11cedc0a4..b4b45636c 100644 --- a/src/plugins/gramplet/AgeOnDateGramplet.py +++ b/src/plugins/gramplet/AgeOnDateGramplet.py @@ -18,6 +18,11 @@ # $Id$ +""" +AgeOnDateGramplet computes the age for everyone thought to be alive +on a particular date. +""" + #------------------------------------------------------------------------ # # Python modules @@ -40,7 +45,15 @@ from QuickReports import run_quick_report_by_name # #------------------------------------------------------------------------ class AgeOnDateGramplet(Gramplet): + """ + Gramplet that computes ages on a particular date for everyone + thought to be alive. + """ def init(self): + """ + Constructs the GUI, consisting of a message, an entry, and + a Run button. + """ import gtk # GUI setup: self.set_tooltip(_("Enter a date, click Run")) @@ -72,6 +85,11 @@ class AgeOnDateGramplet(Gramplet): vbox.show_all() def run(self, obj): + """ + Method that is run when you click the Run button. + The date is retrieved from the entry box, parsed as a date, + and then handed to the quick report. + """ text = self.entry.get_text() date = DateHandler.parser.parse(text) run_quick_report_by_name(self.gui.dbstate, @@ -87,6 +105,8 @@ class AgeOnDateGramplet(Gramplet): register(type="gramplet", name="Age on Date Gramplet", tname=_("Age on Date Gramplet"), + version="2.0.0", + gramps="3.1.0", height=200, content = AgeOnDateGramplet, title=_("Age on Date"),