wxGUI/giface: documentation, creating interface class for doc reasons, small fix of argument, ws changes

git-svn-id: https://svn.osgeo.org/grass/grass/trunk@54942 15284696-431f-4ddb-bdfa-cd5b030d7da7

gui/wxpython/core/giface.py

@@ -22,28 +22,136 @@ from core.gconsole import GConsole, \
 
 import grass.script as grass
 
+
+# to disable Abstract class not referenced
+#pylint: disable=R0921
+
+
+class Layer(object):
+    """!Layer is generaly usable layer object.
+
+    @note Currently without specifying the interface.
+    Current implementations only provides all attributes of existing layer
+    as used in lmgr.
+    """
+
+
+class LayerList(object):
+    def GetSelectedLayers(self, checkedOnly=True):
+        """!Returns list of selected layers.
+
+        @note Usage of checked and selected is still subject to change.
+        Checked layers should be showed. Selected are for analyses.
+        However, this may be the same for some implementations
+        (e.g. it d.mon has all layers checked and selected).
+        """
+        raise NotImplementedError()
+
+
+class GrassInterface:
+    """!GrassInterface provides the functionality which should be available
+    to every GUI component.
+
+    @note The GrassInterface process is not finished.
+    """
+    def RunCmd(self, *args, **kwargs):
+        """!Executes a command.
+        """
+        raise NotImplementedError()
+
+    def Help(self, entry):
+        """Shows a manual page for a given entry.
+        """
+        raise NotImplementedError()
+
+    def WriteLog(self, text, wrap=None, switchPage=False, priority=1):
+        """!Writes log message.
+
+        @note It is not clear how the switchPage and priority should work.
+        @note Use priority rather than switchPage, switchPage will be removed.
+        """
+        raise NotImplementedError()
+
+    def WriteCmdLog(self, line, pid=None, switchPage=True):
+        """!Writes message related to start or end of the command.
+        """
+        raise NotImplementedError()
+
+    def WriteWarning(self, line):
+        """!Writes warning message for the user.
+
+        Currently used also for important messages for user.
+        Overlaps with log message with high priority.
+        """
+        raise NotImplementedError()
+
+    def WriteError(self, line):
+        """!Writes error message for the user."""
+        raise NotImplementedError()
+
+    def GetLayerTree(self):
+        """!Returns LayerManager's tree GUI object.
+        @note Will be removed from the interface.
+        """
+        raise NotImplementedError()
+
+    def GetLayerList(self):
+        """!Returns a layer management object.
+        """
+        raise NotImplementedError()
+
+    def GetMapDisplay(self):
+        """!Returns current map display.
+
+        @note For layer related tasks use GetLayerList().
+
+        @return MapFrame instance
+        @return None when no mapdisplay open
+        """
+        raise NotImplementedError()
+
+    def GetAllMapDisplays(self):
+        """!Get list of all map displays.
+
+        @note Might be removed from the interface.
+
+        @return list of MapFrame instances
+        """
+        raise NotImplementedError()
+
+    def GetMapWindow(self):
+        """!Returns current map window.
+        @note For layer related tasks use GetLayerList().
+        """
+        raise NotImplementedError()
+
+    def GetProgress(self):
+        """!Returns object which shows the progress.
+
+        @note Some implementations may not implement this method.
+        """
+        raise NotImplementedError()
+
+
 class StandaloneGrassInterface():
+    """!@implements GrassInterface"""
     def __init__(self):
         self._gconsole = GConsole()
         self._gconsole.Bind(EVT_CMD_PROGRESS, self._onCmdProgress)
         self._gconsole.Bind(EVT_CMD_OUTPUT, self._onCmdOutput)
         self._gconsole.Bind(EVT_WRITE_LOG,
-                            lambda event:
-                                self.WriteLog(text = event.text))
+                            lambda event: self.WriteLog(text=event.text))
         self._gconsole.Bind(EVT_WRITE_CMD_LOG,
-                            lambda event:
-                                self.WriteCmdLog(line = event.line))
+                            lambda event: self.WriteCmdLog(line=event.line))
         self._gconsole.Bind(EVT_WRITE_WARNING,
-                            lambda event:
-                                self.WriteWarning(line = event.line))
+                            lambda event: self.WriteWarning(line=event.line))
         self._gconsole.Bind(EVT_WRITE_ERROR,
-                            lambda event:
-                                self.WriteError(line = event.line))
+                            lambda event: self.WriteError(line=event.line))
 
     def _onCmdOutput(self, event):
         """!Print command output"""
         message = event.text
-        style  = event.type
+        style = event.type
 
         if style == 'warning':
             self.WriteWarning(message)
@@ -67,11 +175,11 @@ class StandaloneGrassInterface():
     def Help(self, entry):
         self._gconsole.RunCmd(['g.manual', 'entry=%s' % entry])
 
-    def WriteLog(self, text, wrap = None,
-                 switchPage = False, priority = 1):
+    def WriteLog(self, text, wrap=None,
+                 switchPage=False, priority=1):
         self._write(grass.message, text)
 
-    def WriteCmdLog(self, line, pid = None, switchPage = True):
+    def WriteCmdLog(self, line, pid=None, switchPage=True):
         if pid:
             line = '(' + str(pid) + ') ' + line
         self._write(grass.message, line)
@@ -90,7 +198,7 @@ class StandaloneGrassInterface():
 
     def GetLayerList(self):
         return None
-        
+
     def GetMapDisplay(self):
         """!Get current map display.
         """
@@ -105,4 +213,4 @@ class StandaloneGrassInterface():
         return None
 
     def GetProgress(self):
-        raise NotImplementedError
+        raise NotImplementedError()

gui/wxpython/lmgr/giface.py

@@ -17,6 +17,11 @@ This program is free software under the GNU General Public License
 
 
 class Layer(object):
+    """!@implements core::giface::Layer
+
+    @note Currently implemented without specifying the interface.
+    It only provides all attributes of existing layer as used in lmgr.
+    """
     def __init__(self, pydata):
         self._pydata = pydata
 
@@ -25,15 +30,18 @@ class Layer(object):
 
 
 class LayerList(object):
+    """!@implements core.giface.Layer"""
     def __init__(self, tree):
         self._tree = tree
 
 #    def __iter__(self):
+#    """!Iterates over the contents of the list."""
 #        for in :
-#            yield 
+#            yield
 
-    def GetSelectedLayers(self, checkedOnly = True):
-        items = self._tree.GetSelectedLayer(multi = True, checkedOnly = True)
+    def GetSelectedLayers(self, checkedOnly=True):
+        items = self._tree.GetSelectedLayer(multi=True,
+                                            checkedOnly=checkedOnly)
         layers = []
         for item in items:
             layer = Layer(self._tree.GetPyData(item))
@@ -41,11 +49,19 @@ class LayerList(object):
         return layers
 
     def GetLayerInfo(self, layer):
+        """!For compatibility only, will be removed."""
         return Layer(self._tree.GetPyData(layer))
 
 
-class LayerManagerGrassInterface:
+class LayerManagerGrassInterface(object):
+    """!@implements GrassInterface"""
     def __init__(self, lmgr):
+        """!Costructor is specific to the current implementation.
+
+        Uses Layer Manager object including its private attributes.
+        (It encapsulates existing Layer Manager so access to private members
+        is intention.)
+        """
         self.lmgr = lmgr
 
     def RunCmd(self, *args, **kwargs):
@@ -70,24 +86,15 @@ class LayerManagerGrassInterface:
         self.lmgr._gconsole.WriteError(line = line)
 
     def GetLayerTree(self):
-        return LayerList(self.lmgr.GetLayerTree())
+        return self.lmgr.GetLayerTree()
 
     def GetLayerList(self):
         return LayerList(self.lmgr.GetLayerTree())
 
     def GetMapDisplay(self):
-        """!Get current map display.
-
-        @return MapFrame instance
-        @return None no mapdisplay open
-        """
         return self.lmgr.GetMapDisplay(onlyCurrent=True)
 
     def GetAllMapDisplays(self):
-        """!Get list of all map displays.
-
-        @return list of MapFrame instances
-        """
         return self.lmgr.GetMapDisplay(onlyCurrent=False)
 
     def GetMapWindow(self):