Anonymous avatar Anonymous committed 33b38d7

- improved doc strings

Comments (0)

Files changed (7)

mlsrc/libui/__init__.py

 # -*- coding: utf-8 -*-#
 #!/usr/bin/env python
-"""widgets etc are in this package"""
+"""A package with some custom widgets, sometimes they are very simple
+customization, e.g. just adding the mixins
+"""
+

mlsrc/libui/buttons.py

 # -*- coding: utf-8 -*-#
 #!/usr/bin/env python
-"""A button based on Aquabutton, at least for the moment???"""
+"""Custom buttons, used in uiutils.doCreateButtons"""
+
 import logging
 
 import wx
 import wx.lib.agw.aquabutton as AB
 
 class AquaButton(AB.AquaButton):
-    """AquaButton"""
+    """AquaButton, with custom color"""
     def __init__(self, **kwargs):
         super(AquaButton, self).__init__(**kwargs)
 
 
 
 class BitmapButton(wx.BitmapButton):
-    """Standard wx.Button"""
+    """Standard wx.BitmapButton"""
     def __init__(self, **kwargs):
         super(BitmapButton, self).__init__(**kwargs)

mlsrc/libui/commonDlgs.py

 # -*- coding: utf-8 -*-#
 #!/usr/bin/env python
-# commonDlgs.py
+"""Common dialogs"""
 
 import wx
 
 #----------------------------------------------------------------------
 def showMessageDlg(message, caption, flag=wx.ICON_ERROR|wx.OK):
-    """"""
+    """Show a message
+    
+    :param string message: the message to show, should be wrapped with _()
+    :param string caption: the caption to show, should be wrapped with _()
+    :param flag: a valid style flag
+    
+    """
     msg = wx.MessageDialog(None, message=message,
                            caption=caption, style=flag)
     msg.ShowModal()

mlsrc/libui/cpopupctrl.py

 # -*- coding: utf-8 -*-#
-# A popup control based on code from the wxPython demo
-#
-# but we use wx.lib.sized_controls, which does nicer sizing handling
-#-----------------------------------------------------------------------------
 #!/usr/bin/env python
+"""A popup control based on code from the wxPython demo
+but we use wx.lib.sized_controls for automatic sizer handling
+"""
 import logging
 
 import wx
 from mixins import LabelMixin
 
 class PopButton(wx.PyControl):
+    """The button used on the control"""
     def __init__(self, *args, **kwds):
+        """The constructor
+        
+        :param args: arguments
+        :param kwds: keywords
+        
+        """
         super(PopButton, self).__init__(*args, **kwds)
 
         self._up = True
         pass
 
     def onLeftDown(self, event):
+        """The left down event handler"""
         if not self.IsEnabled():
             return
         self._didDown = True
         event.Skip()
 
     def onLeftUp(self, event):
+        """The left up event handler"""
         if not self.IsEnabled():
             return
         if self._didDown:
         event.Skip()
 
     def onMotion(self, event):
+        """The on motion event handler"""
         if not self.IsEnabled():
             return
         if event.LeftIsDown():
         event.Skip()
 
     def onPaint(self, event):
+        """The on paint event handler"""
         dc = wx.BufferedPaintDC(self)
         if self._up:
             flag = wx.CONTROL_CURRENT
                                             self.GetClientRect(), flag)
 
     def DoGetBestSize(self):
+        """Overridding DoGetBestSize used by sizers for size calculations"""
         # TODO: probably should calculate this no????
         # best size for the button
         return self.myMinSize
 # lets see if SizedDialog will work
 # needs testing on e.g. nix?
 class PopupDialog(sc.SizedDialog, LabelMixin):
+    """The popup dialog, shown when the popup button is clicked"""
     def __init__(self, *args, **kwds):
+        """Constructor
+        
+        :param content: is poped from the keywords
+        :param style: is augmented if present or defaulted
+        :param args: arguments passed to pop dialog
+        :param kwds: keywords passed to pop dialog
+        """
         if 'content' in kwds:
             content = kwds.pop('content')
         else:
         self.Fit()
 
     def setContent(self, content):
+        """Set the content window, can also be passed by keyword
+        
+        :param content: the content window
+        
+        """
         self.content = content
         self.content.Reparent(self.win)
         self.win.SetClientSize(self.content.GetSize())
         self.content.Show(True)
 
     def display(self):
-        """position popup control depending on where we are on the screen"""
-        logging.debug('do display')
+        """Display the popup window depending on where we are on the screen"""
         pos = self.popCtrl.ClientToScreen( (0,0) )
         dSize = wx.GetDisplaySize()
         selfSize = self.GetSize()
 #---------------------------------------------------------------------------
 
 class PopupControl(wx.PyControl, LabelMixin):
+    """The popup control"""
     def __init__(self, *args, **kwds):
+        """Constructor
+        
+        :param style: is defaulted or augmented
+        :param args: arguments
+        :param kwds: keywords
+        
+        """
         if 'style' in kwds:
             kwds['style'] |= wx.BORDER_NONE
         else:
         self.Fit()
 
     def DoGetBestSize(self):
+        """Overridding DoGetBestSize used by sizers for size calculations"""
         self.cPanel.Layout()
         self.Layout()
         bSize = self.cPanel.GetBestSize()
         return bSize
 
     def onSize(self, evt):
+        """Size event handler, forces layout of control"""
         self.cPanel.Layout()
         self.Layout()
 
     def onFocus(self, evt):
-        # embedded control should get focus on TAB keypress
+        """Focus event handler, forwards tab to textctrl"""
         self.textCtrl.SetFocus()
         evt.Skip()
 
     def onButton(self, evt):
+        """Button handler, just calls :py:meth:`doPop` """ 
         logging.debug('button')
         self.doPop()
 
     def doPop(self):
+        """Do the Pop, instantiate dialog if needed and call :py:meth:`display`""" 
         logging.debug('dopop')
         if not self.pop:
             if self.content:
             self.pop.display()
 
     def Enable(self, flag):
+        """Enable the controls
+        
+        :param boolean flag: enable or disable
+        
+        """
         self.textCtrl.Enable(flag)
         self.bCtrl.Enable(flag)
 
     def getTc(self):
+        """Get the embedded textctrl"""
         return self.textCtrl
 
     def setPopupContent(self, content):
+        """Set the content
+        
+        :param content: content window
+        
+        """
         if not self.pop:
             self.content = content
             self.content.Show(False)
             self.pop.setContent(content)
 
     def formatContent(self):
+        """Needs to be overridden see e.g. 
+        :py:meth:`mlsrc.libui.searchctrl.SearchCtrl` 
+        """
         raise NotImplementedError("FormatContent needs to be overiden")
 
     def popDown(self):
+        """End modal the dialog"""
         if self.pop:
             self.pop.EndModal(True)
 
     def SetValue(self, value):
-        """Just do it on the textCtrl"""
+        """Just pass it to the embedded textCtrl"""
         tc = self.textCtrl
         if value:
             tc.SetValue(value.ljust(tc._masklength).strip())
             tc.ClearValue()
 
     def ChangeValue(self, value):
-        """Just do it on the textCtrl"""
+        """Just pass it to the embedded textCtrl"""
         tc = self.textCtrl
         if value:
             tc.ChangeValue(value.ljust(tc._masklength).strip())
             tc.ClearValue()
 
     def ClearValue(self):
-        """Just do it on the textCtrl"""
+        """Just pass it to the embedded textCtrl"""
         self.textCtrl.ClearValue()
 
     def ClearValueAlt(self):
-        """Just do it on the textCtrl"""
+        """Just pass it to the embedded textCtrl"""
         self.textCtrl.ClearValueAlt()
 
     def GetValue(self):
-        """Just do it on the textCtrl"""
+        """Just pass it to the embedded textCtrl
+        
+        :rtype: controls value
+        
+        """
         return self.textCtrl.GetValue()
 
     def SetFont(self, font):
-        """Just do it on the textCtrl"""
+        """Just pass it to the embedded textCtrl"""
         self.textCtrl.SetFont(font)
 
     def GetFont(self):
-        """Just do it on the textCtrl"""
+        """Just pass it to the embedded textCtrl
+        
+        :rtype: the controls font
+        
+        """
         return self.textCtrl.GetFont()
 
     def Refresh(self):
-        """Just do it on the textCtrl"""
+        """Just pass it to the embedded textCtrl"""
         self.textCtrl.Refresh()
         
 

mlsrc/libui/mixins.py

 class DbMixin:
 
     def __init__(self, **kwds):
-        """Mixin to initialize db related variables"""
+        """Mixin to initialize db related variables, this just ensures that
+        the attributes exist, they need to be set appropriatly
+        """
 
-        # db enabling, but they need to be set correctly when using ctrl
         self.dbParent = self
         self.dbColName = ''
         self.dbRelName = ''

mlsrc/libui/olvbase.py

 # -*- coding: utf-8 -*-#
 #!/usr/bin/env python
+"""ObjectListView base mixin, provides common methods used by
+olvgroup, e.g. printing
 
-"""ObjectListView base mixin, provides common methods used by
-olvgroup and olvvirt, e.g. printing
+Tries to import from mlsrc.ObjectListView, if it fails it gets it from 
+site-packages.
 """
 import logging
 import sys
 
 class OlvBase(object):
     def __init__(self, *args, **kwds):
-
+        """Constructor"""
         self.saQuery = None
         self.filter = None
         self.sqljoin = None
         self.nonGroupCols = []
 
         # override the following if you have e.g. multi keys or a different
-        # column name, e.g for drinks
+        # column name
+        # More then one Pkey needs testing, I think up to 3 are supported
         self.itemPkeysCols = ('id', )
 
         self.ignoreDataDirty = False
         self.pluralItemsText = _("%(title)s [%(count)d items]")
 
     def getRel(self, data, relation):
-        """Resolve dotted relation entry"""
+        """Resolve dotted relation entry
+        
+        :param data: the OLV object, an SA model instance, e.g. db.Book()
+        :param relation: the relation to resolve, e.g. "person"
+        
+        """
         baseAttr = data
         if not relation == None:
             comp = relation.split('.')
         return baseAttr
 
     def getRelInfo(self, data, relation, colname):
-        """return value or blank"""
+        """Get information from relation
+        
+        :param data: the OLV object, an SA model instance
+        :param relation: the relation
+        :param colname: the column name
+        :rtype: the column value or blank
+
+        """
         try:
             baseAttr = self.getRel(data, relation)
 
             logging.exception(msgR)
 
     def getColumnDefFromTable(self, table):
-        """Get the column definition from the Olvlist table"""
+        """Get the column definition from the Olvlist table
+        
+        :param string table: the table name, e.g. "Book"
+        :rtype: a list of column definitions
+        
+        """
         listFilter = "tablename = '%s'" % table
         cols = []
         ds = wx.GetApp().session
         return cols
 
     def setColumnDef(self, coldesc, table):
-        """get the column definitions from olvlist table"""
+        """Setup the OLV.ColumnDefn
+        
+        it calls :py:meth:`getColumnDefFromTable` and :py:meth:`createColDef`
+        to do most of the work.  
+        
+        :param coldesc: a dict of column name and column description
+        :param string table: the table name, e.g. "Book"
+        :rtype: a list of OLV.ColumnDefn
+        
+        """
         self.includedColumns = {}
         coldef = []
         listFilter = "tablename = '%s'" % table
         return coldef
 
     def createColDef(self, col, coldesc):
+        """Create an OLV.ColumnDefn 
+        
+        :param col: a Olvlist model row
+        :param coldesc: a dict with the lables per column name
+        :rtype: an OLV.ColumnDefn
+        
+        """
         coldef = []
         try:
             if col.colname in coldesc:
         return coldef
 
     def onListContextMenu(self, event):
-        """Contect menu for printing a list"""
+        """Context menu handler to show menu for printing"""
         if not hasattr(self, "previewListID"):
             self.previewListMinID = wx.NewId()
             self.previewListNormID = wx.NewId()
         menu.Destroy()
 
     def onSaveColumnConfig(self, event):
+        """The context menu handler to save the current column configuration
+        in the database.
+        
+        Doesn't work yet, waiting for 2.9.3
+        """
         logging.debug("did save")
         colNo = 0
         # TODO: wait for next 2.9.3,
             logging.debug("%s, %s" % (col, self.myOlv.GetColumnWidth(col)))
 
     def onPreviewListMinimal(self, event):
+        """Context menu handler for the minimal list print"""
         printer = olvLib.ListCtrlPrinter(self.myOlv, '')
         # basic format
         printer.ReportFormat = self.fmtMinimal()
         printer.PrintPreview()
 
     def onPreviewListNormal(self, event):
+        """Context menu handler for the normal list print"""
         printer = olvLib.ListCtrlPrinter(self.myOlv, '')
         # basic format
         printer.ReportFormat = self.fmtNormal()
         printer.PrintPreview()
 
     def getList(self):
+        """Get the list instance
+        
+        :rtype: the list instance
+        
+        """
         return self.myOlv
 
     def initObjectListView(self, checkstatecol=None, columnDef=None):
+        """Initialize the OLV
+        
+        The list suppresses blank lines between lines and not use a 
+        separate column for useExpansionColumn.
+        
+        :param checkstatecol: a column for the check state, default None
+        :param columDef: a list of OLV.ColumnDefn, default None
+        
+        """
         # put expansion in 1st data column and not use a separate column
         # this way clicking the header always sorts the correct column
         tList = self.getList()
         self.SetMinSize((lcSize, 100))
 
     def initModel(self):
-        """needs to be implemented in olvgroup or olvvirtual"""
+        """Override this in the implemention using this base,
+        see e.g. :py:meth:`mlsrc.libui.olvgroup`
+        """
         raise NotImplementedError("initModel needs to be overidden")
 
     def onOLVItemSelected(self, event):
+        """Event handler for item selected, it calls event.Skip so one can
+        implement additional functionality
+        """
         if not self.ignoreDataDirty:
             # do we ignore dirty state
             if wx.GetApp().dataCheckDirty():
         event.Skip()
 
     def getKeyValue(self, item, key):
+        """Get primary key column value
+        
+        :param item: an OLV object, i.e. a SA model row instance
+        :param key: the primary key column name
+        :rtype: a tuple with primary key value
+        
+        """
         keyValue = item
         if key.find('.') == -1:
             # no relation in key
             return (None, )
 
     def refreshData(self):
+        """Refresh the list, by querying the database"""
         self.initModel()
         self.getList().SetObjects(self.listObjects)
 
     def selectItem(self, keys):
+        """Select an item on the list, ensure it is visible and de-select
+        any other items.
+        
+        :param tuple keys: A tuple of primary keys
+        
+        """
         filter = '%s = %i' % (self.itemPkeysCols[0], keys[0])
         if len(keys) > 1:
             if keys[1]:
                                         ensureVisible=True)
 
     def updatedItem(self):
+        """Current item was updated, this refreshes the object in the list"""
         curItemKeys = self.getList().currentItemPkeys
         if curItemKeys:
             if curItemKeys[0]:
                 self.getList().RefreshObjects(items)
 
     def deletedItem(self, keys):
+        """Item was deleted, remove the object from the list, call this before
+        you update/delete from the database.
+        
+        :param tuple keys: a tuple of primary keys
+        
+        """
         filter = '%s = %i' % (self.itemPkeysCols[0], keys[0])
         if len(keys) > 1:
             if keys[1]:
         self.getList().RemoveObjects(items)
 
     def addedItem(self, keys):
+        """An item was added, add the item to the list, select it and de-select
+        any others
+        
+        :param tuple keys: a tuple of primary keys
+        
+        """
         filter = '%s = %i' % (self.itemPkeysCols[0], keys[0])
         if len(keys) > 1:
             if keys[1]:
     # a couple of formats for printing
     def fmtMinimal(self, headerFontName="Arial", rowFontName="Times New Roman"):
         """
-        Return a minimal format for a report
+        Return a minimal format base on the current list layout for a report
         """
         fmt = olvLib.ReportFormat()
         fmt.AlwaysCenterColumnHeader = True
 
     def fmtNormal(self, headerFontName="Gill Sans", rowFontName="Times New Roman"):
         """
-        Return a reasonable default format for a report
+        Return a reasonable default format base on the current list layout for
+        a report.
         """
         fmt = olvLib.ReportFormat()
         fmt.AlwaysCenterColumnHeader = False
         return fmt
 
     def addListImages(self):
+        """Add the standard images to the list, currently just flags,
+        you might want to override this in you implemention if you have
+        additional images you want to have available.
+        """
         # add flag images to imagelist
         for flag in flags.catalog:
             # resize to
             fImg = flags.catalog[flag].GetImage().Resize((16, 16), (0, 0))
             self.GetList().AddNamedImages(flag, fImg.ConvertToBitmap())
 
-    def flagImageGetterAlt(self, data):
+    def flagImageGetter(self, data):
+        """An image getter for a flag, your data model has to have an
+        iso2code column containing the official country code.  Check the 
+        index of wx.lib.art.flagart for valid entries.
+        """
         retVal = -1
         if data.is2code:
             if data.is2code in flags.catalog:
         return retVal
 
     def moneyConverter(self, value):
+        """A string converter to ensure that a decimal value is shown
+        as a two decimal value, obviously your database column should be 
+        defined accordingly.
+        """
         if value:
             if type(value) == str:
                 value = decimal.Decimal(value)

mlsrc/libui/olvdefs.py

 
 
 def Book():
-    """Column descriptions, list heading and klass name for the table"""
+    """Internationalized heading, column lables and model name for OLV
+    
+    :returns: heading
+    :returns: dict of 'column name': _("Label to translate")
+    :returns: db model class name
+                   
+    """
     coldesc = {'publisher': _("Publisher"),
                'title': _("Title"),
                'author': _("Author"),
     return heading, coldesc, klass
 
 def Person():
-    """Column descriptions, list heading and klass name for the table"""
+    """Internationalized heading, column lables and model name for OLV
+    
+    :returns: heading
+    :returns: dict of 'column name': _("Label to translate")
+    :returns: db model class name
+                   
+    """
     coldesc = {'first_name': _("First name"),
                'last_name': _("Last name")}
     heading = _("Authors")
     return heading, coldesc, klass
 
 def Publisher():
-    """Column descriptions, list heading and klass name for the table"""
+    """Internationalized heading, column lables and model name for OLV
+    
+    :returns: heading
+    :returns: dict of 'column name': _("Label to translate")
+    :returns: db model class name
+                   
+    """
     coldesc = {'name': _("Name"),}
     heading = _("Publishers")
     klass = 'Publisher'
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.