synchronize GTK2 minimum version in docs

[wxWidgets.git] / interface / wx / grid.h

diff --git a/interface/wx/grid.h b/interface/wx/grid.h
index 7e8c2584beb92a3c3a834c2d1017bfb7c6de7ac7..b69576f0b8955d86773c341d554bf9358ffe0ff2 100644 (file)
--- a/interface/wx/grid.h
+++ b/interface/wx/grid.h
@@ -178,6 +178,31 @@ public:
     virtual void SetParameters(const wxString& params);
 };
 
     virtual void SetParameters(const wxString& params);
 };
 

+/**
+    Specifier used to format the data to string for the numbers handled by
+    wxGridCellFloatRenderer and wxGridCellFloatEditor.
+
+    @since 2.9.3
+*/
+enum wxGridCellFloatFormat
+{
+    /// Decimal floating point (%f).
+    wxGRID_FLOAT_FORMAT_FIXED       = 0x0010,
+
+    /// Scientific notation (mantise/exponent) using e character (%e).
+    wxGRID_FLOAT_FORMAT_SCIENTIFIC  = 0x0020,
+
+    /// Use the shorter of %e or %f (%g).
+    wxGRID_FLOAT_FORMAT_COMPACT     = 0x0040,
+
+    /// To use in combination with one of the above formats for the upper
+    /// case version (%F/%E/%G)
+    wxGRID_FLOAT_FORMAT_UPPER       = 0x0080,
+
+    /// The format used by default (wxGRID_FLOAT_FORMAT_FIXED).
+    wxGRID_FLOAT_FORMAT_DEFAULT     = wxGRID_FLOAT_FORMAT_FIXED
+};
+

 /**
     @class wxGridCellFloatRenderer
 
 /**
     @class wxGridCellFloatRenderer
 


@@ -201,8 +226,22 @@ public:
             Minimum number of characters to be shown.
         @param precision
             Number of digits after the decimal dot.
             Minimum number of characters to be shown.
         @param precision
             Number of digits after the decimal dot.

+        @param format
+            The format used to display the string, must be a combination of
+            ::wxGridCellFloatFormat enum elements. This parameter is only
+            available since wxWidgets 2.9.3.
+    */
+    wxGridCellFloatRenderer(int width = -1, int precision = -1,
+                            int format = wxGRID_FLOAT_FORMAT_DEFAULT);
+
+    /**
+        Returns the specifier used to format the data to string.
+
+        The returned value is a combination of ::wxGridCellFloatFormat elements.
+
+        @since 2.9.3

     */
     */

-    wxGridCellFloatRenderer(int width = -1, int precision = -1);
+    int GetFormat() const;

 
     /**
         Returns the precision.
 
     /**
         Returns the precision.


@@ -215,7 +254,18 @@ public:
     int GetWidth() const;
 
     /**
     int GetWidth() const;
 
     /**

-        Parameters string format is "width[,precision]".
+        Set the format to use for display the number.
+
+        @param format
+            Must be a combination of ::wxGridCellFloatFormat enum elements.
+
+        @since 2.9.3
+    */
+    void SetFormat(int format);
+
+    /**
+        The parameters string format is "width[,precision[,format]]" where
+        @c format should be chosen between f|e|g|E|G (f is used by default)

     */
     virtual void SetParameters(const wxString& params);
 
     */
     virtual void SetParameters(const wxString& params);
 


@@ -596,11 +646,17 @@ public:
             Minimum number of characters to be shown.
         @param precision
             Number of digits after the decimal dot.
             Minimum number of characters to be shown.
         @param precision
             Number of digits after the decimal dot.

+        @param format
+            The format to use for displaying the number, a combination of
+            ::wxGridCellFloatFormat enum elements. This parameter is only
+            available since wxWidgets 2.9.3.

     */
     */

-    wxGridCellFloatEditor(int width = -1, int precision = -1);
+    wxGridCellFloatEditor(int width = -1, int precision = -1,
+                          int format = wxGRID_FLOAT_FORMAT_DEFAULT);

 
     /**
 
     /**

-        Parameters string format is "width,precision"
+        The parameters string format is "width[,precision[,format]]" where
+        @c format should be chosen between f|e|g|E|G (f is used by default)

     */
     virtual void SetParameters(const wxString& params);
 };
     */
     virtual void SetParameters(const wxString& params);
 };


@@ -1135,6 +1191,78 @@ public:
     //@}
 };
 
     //@}
 };
 

+/**
+    Represents coordinates of a grid cell.
+
+    An object of this class is simply a (row, column) pair.
+ */
+class wxGridCellCoords
+{
+public:
+    /**
+        Default constructor initializes the object to invalid state.
+
+        Initially the row and column are both invalid (-1) and so operator!()
+        for an uninitialized wxGridCellCoords returns false.
+     */
+    wxGridCellCoords();
+
+    /**
+        Constructor taking a row and a column.
+     */
+    wxGridCellCoords(int row, int col);
+
+    /**
+        Return the row of the coordinate.
+     */
+    int GetRow() const;
+
+    /**
+        Set the row of the coordinate.
+     */
+    void SetRow(int n);
+
+    /**
+        Return the column of the coordinate.
+     */
+    int GetCol() const;
+
+    /**
+        Set the column of the coordinate.
+     */
+    void SetCol(int n);
+
+    /**
+        Set the row and column of the coordinate.
+     */
+    void Set(int row, int col);
+
+    /**
+        Assignment operator for coordinate types.
+     */
+    wxGridCellCoords& operator=(const wxGridCellCoords& other);
+
+    /**
+        Equality operator.
+     */
+    bool operator==(const wxGridCellCoords& other) const;
+
+    /**
+        Inequality operator.
+     */
+     bool operator!=(const wxGridCellCoords& other) const;
+
+    /**
+        Checks whether the coordinates are invalid.
+
+        Returns false only if both row and column are -1. Notice that if either
+        row or column (but not both) are -1, this method returns true even if
+        the object is invalid. This is done because objects in such state
+        should actually never exist, i.e. either both coordinates should be -1
+        or none of them should be -1.
+     */
+    bool operator!() const;
+};

 
 /**
     @class wxGridTableBase
 
 /**
     @class wxGridTableBase


@@ -1401,6 +1529,9 @@ public:
     /**
         Delete rows from the table.
 
     /**
         Delete rows from the table.
 

+        Notice that currently deleting a row intersecting a multi-cell (see
+        SetCellSize()) is not supported and will result in a crash.
+

         @param pos
             The first row to delete.
         @param numRows
         @param pos
             The first row to delete.
         @param numRows


@@ -1630,7 +1761,7 @@ struct wxGridSizesInfo
     The default table class is called wxGridStringTable and holds an array of
     strings. An instance of such a class is created by CreateGrid().
 
     The default table class is called wxGridStringTable and holds an array of
     strings. An instance of such a class is created by CreateGrid().
 

-    wxGridCellRenderer is the abstract base class for rendereing contents in a
+    wxGridCellRenderer is the abstract base class for rendering contents in a

     cell. The following renderers are predefined:
 
     - wxGridCellBoolRenderer
     cell. The following renderers are predefined:
 
     - wxGridCellBoolRenderer


@@ -1719,6 +1850,50 @@ public:
         CellSpan_Main
     };
 
         CellSpan_Main
     };
 

+    /**
+        Rendering styles supported by wxGrid::Render() method.
+
+        @since 2.9.4
+     */
+    enum wxGridRenderStyle
+    {
+        /// Draw grid row header labels.
+        wxGRID_DRAW_ROWS_HEADER = 0x001,
+
+        /// Draw grid column header labels.
+        wxGRID_DRAW_COLS_HEADER = 0x002,
+
+        /// Draw grid cell border lines.
+        wxGRID_DRAW_CELL_LINES = 0x004,
+
+        /**
+            Draw a bounding rectangle around the rendered cell area.
+
+            Useful where row or column headers are not drawn or where there is
+            multi row or column cell clipping and therefore no cell border at
+            the rendered outer boundary.
+        */
+        wxGRID_DRAW_BOX_RECT = 0x008,
+
+        /**
+            Draw the grid cell selection highlight if a selection is present.
+
+            At present the highlight colour drawn depends on whether the grid
+            window loses focus before drawing begins.
+        */
+        wxGRID_DRAW_SELECTION = 0x010,
+
+        /**
+            The default render style.
+
+            Includes all except wxGRID_DRAW_SELECTION.
+         */
+        wxGRID_DRAW_DEFAULT = wxGRID_DRAW_ROWS_HEADER |
+                              wxGRID_DRAW_COLS_HEADER |
+                              wxGRID_DRAW_CELL_LINES |
+                              wxGRID_DRAW_BOX_RECT
+    };
+

     /**
         @name Constructors and Initialization
      */
     /**
         @name Constructors and Initialization
      */


@@ -2781,7 +2956,7 @@ public:
         @a resizeExistingRows is @true.
 
         If @a height is less than GetRowMinimalAcceptableHeight(), then the
         @a resizeExistingRows is @true.
 
         If @a height is less than GetRowMinimalAcceptableHeight(), then the

-        minimal acceptable heihgt is used instead of it.
+        minimal acceptable height is used instead of it.

     */
     void SetDefaultRowSize(int height, bool resizeExistingRows = false);
 
     */
     void SetDefaultRowSize(int height, bool resizeExistingRows = false);
 


@@ -3009,7 +3184,7 @@ public:
         Notice that currently there is no way to make some columns resizable in
         a grid where columns can't be resized by default as there doesn't seem
         to be any need for this in practice. There is also no way to make the
         Notice that currently there is no way to make some columns resizable in
         a grid where columns can't be resized by default as there doesn't seem
         to be any need for this in practice. There is also no way to make the

-        column marked as fixed using this method resizeable again because it is
+        column marked as fixed using this method resizable again because it is

         supposed that fixed columns are used for static parts of the grid and
         so should remain fixed during the entire grid lifetime.
 
         supposed that fixed columns are used for static parts of the grid and
         so should remain fixed during the entire grid lifetime.
 


@@ -3846,6 +4021,64 @@ public:
     */
     bool InsertRows(int pos = 0, int numRows = 1, bool updateLabels = true);
 
     */
     bool InsertRows(int pos = 0, int numRows = 1, bool updateLabels = true);
 

+    /**
+        Invalidates the cached attribute for the given cell.
+
+        For efficiency reasons, wxGrid may cache the recently used attributes
+        (currently it caches only the single most recently used one, in fact)
+        which can result in the cell appearance not being refreshed even when
+        the attribute returned by your custom wxGridCellAttrProvider-derived
+        class has changed. To force the grid to refresh the cell attribute,
+        this function may be used. Notice that calling it will not result in
+        actually redrawing the cell, you still need to call
+        wxWindow::RefreshRect() to invalidate the area occupied by the cell in
+        the window to do this. Also note that you don't need to call this
+        function if you store the attributes in wxGrid itself, i.e. use its
+        SetAttr() and similar methods, it is only useful when using a separate
+        custom attributes provider.
+
+        @param row
+            The row of the cell whose attribute needs to be queried again.
+        @param col
+            The column of the cell whose attribute needs to be queried again.
+
+        @since 2.9.2
+     */
+    void RefreshAttr(int row, int col);
+
+    /**
+        Draws part or all of a wxGrid on a wxDC for printing or display.
+
+        Pagination can be accomplished by using sequential Render() calls
+        with appropriate values in wxGridCellCoords topLeft and bottomRight.
+
+        @param dc
+            The wxDC to be drawn on.
+        @param pos
+            The position on the wxDC where rendering should begin. If not
+            specified drawing will begin at the wxDC MaxX() and MaxY().
+        @param size
+            The size of the area on the wxDC that the rendered wxGrid should
+            occupy. If not specified the drawing will be scaled to fit the
+            available dc width or height. The wxGrid's aspect ratio is
+            maintained whether or not size is specified.
+        @param topLeft
+            The top left cell of the block to be drawn. Defaults to ( 0, 0 ).
+        @param bottomRight
+            The bottom right cell of the block to be drawn. Defaults to row and
+            column counts.
+        @param style
+            A combination of values from wxGridRenderStyle.
+
+        @since 2.9.4
+     */
+    void Render( wxDC& dc,
+                 const wxPoint& pos = wxDefaultPosition,
+                 const wxSize& size = wxDefaultSize,
+                 const wxGridCellCoords& topLeft = wxGridCellCoords( -1, -1 ),
+                 const wxGridCellCoords& bottomRight = wxGridCellCoords( -1, -1 ),
+                 int style = wxGRID_DRAW_DEFAULT );
+

     /**
         Sets the cell attributes for all cells in the specified column.
 
     /**
         Sets the cell attributes for all cells in the specified column.
 


@@ -4226,6 +4459,10 @@ public:
 
     /**
         Column at which the event occurred.
 
     /**
         Column at which the event occurred.

+
+        Notice that for a @c wxEVT_GRID_SELECT_CELL event this column is the
+        column of the newly selected cell while the previously selected cell
+        can be retrieved using wxGrid::GetGridCursorCol().

     */
     virtual int GetCol();
 
     */
     virtual int GetCol();
 


@@ -4236,6 +4473,10 @@ public:
 
     /**
         Row at which the event occurred.
 
     /**
         Row at which the event occurred.

+
+        Notice that for a @c wxEVT_GRID_SELECT_CELL event this row is the row
+        of the newly selected cell while the previously selected cell can be
+        retrieved using wxGrid::GetGridCursorRow().

     */
     virtual int GetRow();
 
     */
     virtual int GetRow();