From cd4a2348517b799da5074c76e4a2712782c7beae Mon Sep 17 00:00:00 2001 From: Andrea Gavana Date: Wed, 13 Feb 2013 15:58:36 +0000 Subject: [PATCH] Phoenix: add snippets and overview for the `wx.grid` module. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxPython/Phoenix/trunk@73513 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- .../overviews/grid_overview.rst | 138 ++++++++++++++++++ .../rest_substitutions/overviews/index.rst | 1 + .../snippets/python/converted/StopWatch.1.py | 10 ++ .../converted/grid.Grid.GetCellSize.1.py | 9 ++ .../converted/grid.Grid.GetCellSize.2.py | 9 ++ .../grid.Grid.GetRowGridLinePen.1.py | 9 ++ ...d.GridCellAttr.GetNonDefaultAlignment.1.py | 5 + .../converted/grid.GridUpdateLocker.1.py | 11 ++ sphinxtools/postprocess.py | 3 + sphinxtools/utilities.py | 3 + 10 files changed, 198 insertions(+) create mode 100644 docs/sphinx/rest_substitutions/overviews/grid_overview.rst create mode 100644 docs/sphinx/rest_substitutions/snippets/python/converted/StopWatch.1.py create mode 100644 docs/sphinx/rest_substitutions/snippets/python/converted/grid.Grid.GetCellSize.1.py create mode 100644 docs/sphinx/rest_substitutions/snippets/python/converted/grid.Grid.GetCellSize.2.py create mode 100644 docs/sphinx/rest_substitutions/snippets/python/converted/grid.Grid.GetRowGridLinePen.1.py create mode 100644 docs/sphinx/rest_substitutions/snippets/python/converted/grid.GridCellAttr.GetNonDefaultAlignment.1.py create mode 100644 docs/sphinx/rest_substitutions/snippets/python/converted/grid.GridUpdateLocker.1.py diff --git a/docs/sphinx/rest_substitutions/overviews/grid_overview.rst b/docs/sphinx/rest_substitutions/overviews/grid_overview.rst new file mode 100644 index 00000000..3a2849dd --- /dev/null +++ b/docs/sphinx/rest_substitutions/overviews/grid_overview.rst @@ -0,0 +1,138 @@ +.. include:: headings.inc + + +.. _grid overview: + +================================================= +|phoenix_title| **Grid Overview** +================================================= + + +:class:`~grid.Grid` and its related classes are used for displaying and editing tabular data. + +:class:`~grid.Grid` supports custom attributes for the table cells, allowing to completely +customize its appearance and uses a separate grid table (:class:`~grid.GridTableBase` -derived) +class for the data management meaning that it can be used to display arbitrary amounts of data. + + +.. _grid getting started: + +Getting Started +--------------- + +For simple applications you need only refer to the :class:`~grid.Grid` class in your code. +This example shows how you might create a grid in a frame or dialog constructor and illustrates +some of the formatting functions:: + + import wx + import wx.grid + + class GridFrame(wx.Frame): + + def __init__(self, parent): + + wx.Frame.__init__(self, parent) + + # Create a wxGrid object + grid = wx.grid.Grid(self, -1) + + # Then we call CreateGrid to set the dimensions of the grid + # (100 rows and 10 columns in this example) + grid.CreateGrid(100, 10) + + # We can set the sizes of individual rows and columns + # in pixels + grid.SetRowSize(0, 60) + grid.SetColSize(0, 120) + + # And set grid cell contents as strings + grid.SetCellValue(0, 0, 'wxGrid is good') + + # We can specify that some cells are read.only + grid.SetCellValue(0, 3, 'This is read.only') + grid.SetReadOnly(0, 3) + + # Colours can be specified for grid cell contents + grid.SetCellValue(3, 3, 'green on grey') + grid.SetCellTextColour(3, 3, wx.GREEN) + grid.SetCellBackgroundColour(3, 3, wx.LIGHT_GREY) + + # We can specify the some cells will store numeric + # values rather than strings. Here we set grid column 5 + # to hold floating point values displayed with width of 6 + # and precision of 2 + grid.SetColFormatFloat(5, 6, 2) + grid.SetCellValue(0, 6, '3.1415') + + self.Show() + + + if __name__ == '__main__': + + app = wx.App(0) + frame = GridFrame(None) + app.MainLoop() + + +Here is a list of classes related to :class:`~grid.Grid`: + +- :class:`~grid.Grid`: The main grid control class itself. +- :class:`~grid.GridTableBase`: The base class for grid data provider. +- :class:`~grid.GridStringTable`: Simple :class:`~grid.GridTableBase` implementation + supporting only string data items and storing them all in memory (hence suitable + for not too large grids only). +- :class:`~grid.GridCellAttr`: A cell attribute, allowing to customize its appearance + as well as the renderer and editor used for displaying and editing it. +- :class:`~grid.GridCellAttrProvider`: The object responsible for storing and retrieving the cell attributes. +- :class:`~grid.GridColLabelWindow`: The window showing the grid columns labels. +- :class:`~grid.GridRowLabelWindow`: The window showing the grid rows labels. +- :class:`~grid.GridCornerLabelWindow`: The window used in the upper left grid corner. +- :class:`~grid.GridWindow`: The window representing the main part of the grid. +- :class:`~grid.GridCellRenderer`: Base class for objects used to display a cell value. +- :class:`~grid.GridCellStringRenderer`: Renderer showing the cell as a text string. +- :class:`~grid.GridCellNumberRenderer`: Renderer showing the cell as an integer number. +- :class:`~grid.GridCellFloatRenderer`: Renderer showing the cell as a floating point number. +- :class:`~grid.GridCellBoolRenderer`: Renderer showing the cell as checked or unchecked box. +- :class:`~grid.GridCellEditor`: Base class for objects used to edit the cell value. +- :class:`~grid.GridCellStringEditor`: Editor for cells containing text strings. +- :class:`~grid.GridCellNumberEditor`: Editor for cells containing integer numbers. +- :class:`~grid.GridCellFloatEditor`: Editor for cells containing floating point numbers. +- :class:`~grid.GridCellBoolEditor`: Editor for boolean-valued cells. +- :class:`~grid.GridCellChoiceEditor`: Editor allowing to choose one of the predefined strings (and possibly enter new one). +- :class:`~grid.GridEvent`: The event sent by most of :class:`~grid.Grid` actions. +- :class:`~grid.GridSizeEvent`: The special event sent when a grid column or row is resized. +- :class:`~grid.GridRangeSelectEvent`: The special event sent when a range of cells is selected in the grid. +- :class:`~grid.GridEditorCreatedEvent`: The special event sent when a cell editor is created. +- :class:`~grid.GridSelection`: The object efficiently representing the grid selection. +- :class:`~grid.GridTypeRegistry`: Contains information about the data types supported by the grid. + + + +.. _grid column and row sizes: + +Column and Row Sizes +-------------------- + +.. note:: + + This section will discuss the resizing of :class:`~grid.Grid` rows only to avoid repetitions + but everything in it also applies to grid columns, just replace Row in the method names with Col. + + +Initially all :class:`~grid.Grid` rows have the same height, which can be modified for all of them +at once using :meth:`~grid.Grid.SetDefaultRowSize`. However, unlike simpler controls such as :class:`ListBox` +or :class:`ListCtrl`, :class:`~grid.Grid` also allows its rows to be individually resized to have their +own height using :meth:`~grid.Grid.SetRowSize` (as a special case, a row may be hidden entirely by +setting its size to 0, which is done by a helper :meth:`~grid.Grid.HideRow` method). It is also +possible to resize a row to fit its contents with :meth:`~grid.Grid.AutoSizeRow` or do it for all +rows at once with :meth:`~grid.Grid.AutoSizeRows`. + +Additionally, by default the user can also drag the row separator lines to resize the rows interactively. +This can be forbidden completely by calling :meth:`~grid.Grid.DisableDragRowSize` or just for the +individual rows using :meth:`~grid.Grid.DisableRowResize`. + +If you do allow the user to resize the grid rows, it may be a good idea to save their heights and +restore it when the grid is recreated the next time (possibly during a next program execution): +the functions :meth:`~grid.Grid.GetRowSizes` and :meth:`~grid.Grid.SetRowSizes` can help with this, +you will just need to serialize :class:`~grid.GridSizesInfo` structure returned by the former in +some way and deserialize it back before calling the latter. \ No newline at end of file diff --git a/docs/sphinx/rest_substitutions/overviews/index.rst b/docs/sphinx/rest_substitutions/overviews/index.rst index 68086b4e..b7a8de32 100644 --- a/docs/sphinx/rest_substitutions/overviews/index.rst +++ b/docs/sphinx/rest_substitutions/overviews/index.rst @@ -178,6 +178,7 @@ The new wxPython API documentation is available `in this page `_. adv.functions dataview.1classindex glcanvas.1classindex + grid.1classindex html.1classindex html.functions html2.1classindex diff --git a/docs/sphinx/rest_substitutions/snippets/python/converted/StopWatch.1.py b/docs/sphinx/rest_substitutions/snippets/python/converted/StopWatch.1.py new file mode 100644 index 00000000..eabe244f --- /dev/null +++ b/docs/sphinx/rest_substitutions/snippets/python/converted/StopWatch.1.py @@ -0,0 +1,10 @@ + + sw = wx.StopWatch() + CallLongRunningFunction() + wx.LogMessage("The long running function took %dms to execute", sw.Time()) + sw.Pause() + + # stopwatch is stopped now ... + sw.Resume() + CallLongRunningFunction() + wx.LogMessage("And calling it twice took %dms in all", sw.Time()) diff --git a/docs/sphinx/rest_substitutions/snippets/python/converted/grid.Grid.GetCellSize.1.py b/docs/sphinx/rest_substitutions/snippets/python/converted/grid.Grid.GetCellSize.1.py new file mode 100644 index 00000000..a93719e7 --- /dev/null +++ b/docs/sphinx/rest_substitutions/snippets/python/converted/grid.Grid.GetCellSize.1.py @@ -0,0 +1,9 @@ + # .. code-block:: text + + +----+----+----+ + | | | | + +----+----+----+ + | | | + +----+ | + | | | + +----+----+----+ diff --git a/docs/sphinx/rest_substitutions/snippets/python/converted/grid.Grid.GetCellSize.2.py b/docs/sphinx/rest_substitutions/snippets/python/converted/grid.Grid.GetCellSize.2.py new file mode 100644 index 00000000..a93719e7 --- /dev/null +++ b/docs/sphinx/rest_substitutions/snippets/python/converted/grid.Grid.GetCellSize.2.py @@ -0,0 +1,9 @@ + # .. code-block:: text + + +----+----+----+ + | | | | + +----+----+----+ + | | | + +----+ | + | | | + +----+----+----+ diff --git a/docs/sphinx/rest_substitutions/snippets/python/converted/grid.Grid.GetRowGridLinePen.1.py b/docs/sphinx/rest_substitutions/snippets/python/converted/grid.Grid.GetRowGridLinePen.1.py new file mode 100644 index 00000000..c76b39ac --- /dev/null +++ b/docs/sphinx/rest_substitutions/snippets/python/converted/grid.Grid.GetRowGridLinePen.1.py @@ -0,0 +1,9 @@ + + # in a grid displaying music notation, use a solid black pen between + # octaves (C0=row 127, C1=row 115 etc.) + def GetRowGridLinePen(self, row): + + if row % 12 == 7: + return wx.Pen(wx.BLACK, 1, wx.SOLID) + else: + return self.GetDefaultGridLinePen() diff --git a/docs/sphinx/rest_substitutions/snippets/python/converted/grid.GridCellAttr.GetNonDefaultAlignment.1.py b/docs/sphinx/rest_substitutions/snippets/python/converted/grid.GridCellAttr.GetNonDefaultAlignment.1.py new file mode 100644 index 00000000..aa16a22c --- /dev/null +++ b/docs/sphinx/rest_substitutions/snippets/python/converted/grid.GridCellAttr.GetNonDefaultAlignment.1.py @@ -0,0 +1,5 @@ + + hAlign = wx.ALIGN_RIGHT + vAlign = wx.ALIGN_INVALID + + hAlign, vAlign = attr.GetNonDefaultAlignment() diff --git a/docs/sphinx/rest_substitutions/snippets/python/converted/grid.GridUpdateLocker.1.py b/docs/sphinx/rest_substitutions/snippets/python/converted/grid.GridUpdateLocker.1.py new file mode 100644 index 00000000..6cfc2e33 --- /dev/null +++ b/docs/sphinx/rest_substitutions/snippets/python/converted/grid.GridUpdateLocker.1.py @@ -0,0 +1,11 @@ + + def GridLocker(self): + + self.grid = wx.grid.Grid(self, -1) + + noUpdates = wx.grid.GridUpdateLocker(self.grid) + self.grid.AppendColumn() + # ... many other operations with self.grid ... + self.grid.AppendRow() + + # destructor called, grid refreshed diff --git a/sphinxtools/postprocess.py b/sphinxtools/postprocess.py index fd11e793..c998ccd6 100644 --- a/sphinxtools/postprocess.py +++ b/sphinxtools/postprocess.py @@ -158,6 +158,9 @@ def BuildEnumsAndMethods(sphinxDir): text = text.replace('', 'Window') text = text.replace('', 'Panel') + # Replacement for wx.grid stuff + text = text.replace(' int *,', ' int,') + if 'DocstringsGuidelines' not in input: # Leave the DocstringsGuidelines.txt file alone on these ones text = text.replace(':note:', '.. note::') diff --git a/sphinxtools/utilities.py b/sphinxtools/utilities.py index e43e26ec..c1a707ea 100644 --- a/sphinxtools/utilities.py +++ b/sphinxtools/utilities.py @@ -546,6 +546,9 @@ def MakeSummary(class_name, item_list, template, kind, add_tilde=True): meth_name = regs[regs.index('`')+1:regs.rindex('`')] newstr = ':meth:`~%s.%s`'%(class_name, meth_name) new_docs = new_docs.replace(regs, newstr, 1) + + if '===' in new_docs: + new_docs = '' summary += format%(substr, new_docs) + '\n'