dyngrid_layout: added docstrings

Author: PierreRaybaut

qwt/dyngrid_layout.py

@@ -5,6 +5,16 @@
 # Copyright (c) 2015 Pierre Raybaut, for the Python translation/optimization
 # (see LICENSE file for more details)
 
+"""
+qwt.dyngrid_layout
+------------------
+
+The `dyngrid_layout` module provides the `QwtDynGridLayout` class.
+
+.. autoclass:: QwtDynGridLayout
+   :members:
+"""
+
 from qwt.qt.QtGui import QLayout
 from qwt.qt.QtCore import Qt, QRect, QSize
 
@@ -24,6 +34,32 @@ def updateLayoutCache(self):
         self.isDirty = False
 
 class QwtDynGridLayout(QLayout):
+    """
+    The `QwtDynGridLayout` class lays out widgets in a grid,
+    adjusting the number of columns and rows to the current size.
+
+	`QwtDynGridLayout` takes the space it gets, divides it up into rows and
+	columns, and puts each of the widgets it manages into the correct cell(s).
+	It lays out as many number of columns as possible (limited by 
+    :py:meth:`maxColumns()`).
+
+    .. py:class:: QwtDynGridLayout(parent, margin, [spacing=-1])
+    
+        :param QWidget parent: parent widget
+		:param int margin: margin
+		:param int spacing: spacing
+
+    .. py:class:: QwtDynGridLayout(spacing)
+    
+		:param int spacing: spacing
+
+    .. py:class:: QwtDynGridLayout()
+    
+		Initialize the layout with default values.
+	
+		:param int spacing: spacing
+    """
+
     def __init__(self, *args):
         self.__data = None
         parent = None
@@ -47,46 +83,71 @@ def __init__(self, *args):
         self.setContentsMargins(margin, margin, margin, margin)
 
     def invalidate(self):
+        """Invalidate all internal caches"""
         self.__data.isDirty = True
         QLayout.invalidate(self)
 
     def setMaxColumns(self, maxColumns):
+        """Limit the number of columns"""
         self.__data.maxColumns = maxColumns
 
     def maxColumns(self):
+        """Return the upper limit for the number of columns"""
         return self.__data.maxColumns
 
     def addItem(self, item):
+        """Add an item to the next free position"""
         self.__data.itemList.append(item)
         self.invalidate()
 
     def isEmpty(self):
+        """Return true if this layout is empty"""
         return self.count() == 0
 
     def itemCount(self):
+        """Return number of layout items"""
         return self.count()
 
     def itemAt(self, index):
+        """Find the item at a specific index"""
         if index < 0 or index >= len(self.__data.itemList):
             return
         return self.__data.itemList[index]
 
     def takeAt(self, index):
+        """Find the item at a specific index and remove it from the layout"""
         if index < 0 or index >= len(self.__data.itemList):
             return
         self.__data.isDirty = True
         return self.__data.itemList.pop(index)
 
     def count(self):
+        """Return Number of items in the layout"""
         return len(self.__data.itemList)
 
     def setExpandingDirections(self, expanding):
+        """
+        Set whether this layout can make use of more space than sizeHint().
+        A value of Qt.Vertical or Qt.Horizontal means that it wants to grow in 
+        only one dimension, while Qt.Vertical | Qt.Horizontal means that it 
+        wants to grow in both dimensions. The default value is 0.
+        """
         self.__data.expanding = expanding
 
     def expandingDirections(self):
+        """
+        Returns whether this layout can make use of more space than sizeHint().
+        A value of Qt.Vertical or Qt.Horizontal means that it wants to grow in 
+        only one dimension, while Qt.Vertical | Qt.Horizontal means that it 
+        wants to grow in both dimensions.
+        """
         return self.__data.expanding
 
     def setGeometry(self, rect):
+        """
+        Reorganizes columns and rows and resizes managed items within a 
+        rectangle.
+        """
         QLayout.setGeometry(self, rect)
         if self.isEmpty():
             return
@@ -99,6 +160,12 @@ def setGeometry(self, rect):
             it.setGeometry(geo)
 
     def columnsForWidth(self, width):
+        """
+        Calculate the number of columns for a given width. 
+
+        The calculation tries to use as many columns as possible 
+        ( limited by maxColumns() )
+        """
         if self.isEmpty():
             return 0
         maxColumns = self.itemCount()
@@ -113,6 +180,7 @@ def columnsForWidth(self, width):
         return 1
 
     def maxRowWidth(self, numColumns):
+        """Calculate the width of a layout for a given number of columns."""
         colWidth = [0] * numColumns
         if self.__data.isDirty:
             self.__data.updateLayoutCache()
@@ -124,13 +192,18 @@ def maxRowWidth(self, numColumns):
         return margin_w+(numColumns-1)*self.spacing()+sum(colWidth)
 
     def maxItemWidth(self):
+        """Return the maximum width of all layout items"""
         if self.isEmpty():
             return 0
         if self.__data.isDirty:
             self.__data.updateLayoutCache()
         return max([hint.width() for hint in self.__data.itemSizeHints])
 
     def layoutItems(self, rect, numColumns):
+        """
+        Calculate the geometries of the layout items for a layout
+        with numColumns columns and a given rectangle.
+        """
         itemGeometries = []
         if numColumns == 0 or self.isEmpty():
             return itemGeometries
@@ -172,6 +245,10 @@ def layoutItems(self, rect, numColumns):
         return itemGeometries
 
     def layoutGrid(self, numColumns, rowHeight, colWidth):
+        """
+        Calculate the dimensions for the columns and rows for a grid
+        of numColumns columns.
+        """
         if numColumns <= 0:
             return
         if self.__data.isDirty:
@@ -190,9 +267,11 @@ def layoutGrid(self, numColumns, rowHeight, colWidth):
                 colWidth[col] = max([colWidth[col], size.width()])
 
     def hasHeightForWidth(self):
+        """Return true: QwtDynGridLayout implements heightForWidth()."""
         return True
 
     def heightForWidth(self, width):
+        """Return The preferred height for this layout, given a width."""
         if self.isEmpty():
             return 0
         numColumns = self.columnsForWidth(width)
@@ -207,6 +286,11 @@ def heightForWidth(self, width):
         return margin_h+(numRows-1)*self.spacing()+sum(rowHeight)
 
     def stretchGrid(self, rect, numColumns, rowHeight, colWidth):
+        """
+        Stretch columns in case of expanding() & QSizePolicy::Horizontal and
+        rows in case of expanding() & QSizePolicy::Vertical to fill the entire
+        rect. Rows and columns are stretched with the same factor.
+        """
         if numColumns == 0 or self.isEmpty():
             return
         expandH = self.expandingDirections() & Qt.Horizontal
@@ -234,6 +318,11 @@ def stretchGrid(self, rect, numColumns, rowHeight, colWidth):
                     yDelta -= space
 
     def sizeHint(self):
+        """
+        Return the size hint. If maxColumns() > 0 it is the size for
+        a grid with maxColumns() columns, otherwise it is the size for
+        a grid with only one row.
+        """
         if self.isEmpty():
             return QSize()
         numColumns = self.itemCount()
@@ -253,7 +342,9 @@ def sizeHint(self):
         return QSize(w, h)
 
     def numRows(self):
+        """Return Number of rows of the current layout."""
         return self.__data.numRows
 
     def numColumns(self):
+        """Return Number of columns of the current layout."""
         return self.__data.numColumns