No changes, just fix a typo in wxBannerWindow documentation.

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

diff --git a/interface/wx/grid.h b/interface/wx/grid.h
index 00f9b254b880eba890ec8510572c66227951db1b..332011b2a5eaf6204020d37f432fa6a7e3370d85 100644 (file)
--- a/interface/wx/grid.h
+++ b/interface/wx/grid.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxGrid and related classes
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxGrid and related classes
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**


@@ -18,8 +18,10 @@
     @library{wxadv}
     @category{grid}
 
     @library{wxadv}
     @category{grid}
 

-    @see wxGridCellBoolRenderer, wxGridCellFloatRenderer,
-         wxGridCellNumberRenderer, wxGridCellStringRenderer
+    @see wxGridCellAutoWrapStringRenderer, wxGridCellBoolRenderer,
+         wxGridCellDateTimeRenderer, wxGridCellEnumRenderer,
+         wxGridCellFloatRenderer, wxGridCellNumberRenderer,
+         wxGridCellStringRenderer

 */
 class wxGridCellRenderer
 {
 */
 class wxGridCellRenderer
 {


@@ -50,6 +52,31 @@ public:
                                int row, int col) = 0;
 };
 
                                int row, int col) = 0;
 };
 

+/**
+    @class wxGridCellAutoWrapStringRenderer
+
+    This class may be used to format string data in a cell. The too
+    long lines are wrapped to be shown entirely at word boundaries.
+
+    @library{wxadv}
+    @category{grid}
+
+    @see wxGridCellRenderer, wxGridCellBoolRenderer,
+         wxGridCellDateTimeRenderer, wxGridCellEnumRenderer,
+         wxGridCellFloatRenderer, wxGridCellNumberRenderer,
+         wxGridCellStringRenderer
+*/
+
+class wxGridCellAutoWrapStringRenderer : public wxGridCellStringRenderer
+{
+public:
+    /**
+        Default constructor.
+    */
+    wxGridCellAutoWrapStringRenderer();
+};
+
+

 /**
     @class wxGridCellBoolRenderer
 
 /**
     @class wxGridCellBoolRenderer
 


@@ -58,7 +85,9 @@ public:
     @library{wxadv}
     @category{grid}
 
     @library{wxadv}
     @category{grid}
 

-    @see wxGridCellRenderer, wxGridCellFloatRenderer, wxGridCellNumberRenderer,
+    @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer,
+         wxGridCellDateTimeRenderer, wxGridCellEnumRenderer,
+         wxGridCellFloatRenderer, wxGridCellNumberRenderer,

          wxGridCellStringRenderer
 */
 class wxGridCellBoolRenderer : public wxGridCellRenderer
          wxGridCellStringRenderer
 */
 class wxGridCellBoolRenderer : public wxGridCellRenderer


@@ -70,6 +99,85 @@ public:
     wxGridCellBoolRenderer();
 };
 
     wxGridCellBoolRenderer();
 };
 

+/**
+    @class wxGridCellDateTimeRenderer
+
+    This class may be used to format a date/time data in a cell.
+    The class wxDateTime is used internally to display the local date/time
+    or to parse the string date entered in the cell thanks to the defined format.
+
+    @library{wxadv}
+    @category{grid}
+
+    @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer,
+         wxGridCellBoolRenderer, wxGridCellEnumRenderer,
+         wxGridCellFloatRenderer, wxGridCellNumberRenderer,
+         wxGridCellStringRenderer
+*/
+class wxGridCellDateTimeRenderer : public wxGridCellStringRenderer
+{
+public:
+    /**
+        Date/time renderer constructor.
+
+        @param outformat
+            strptime()-like format string used the parse the output date/time.
+        @param informat
+            strptime()-like format string used to parse the string entered in the cell.
+    */
+    wxGridCellDateTimeRenderer(const wxString& outformat = wxDefaultDateTimeFormat,
+                               const wxString& informat = wxDefaultDateTimeFormat);
+
+
+    /**
+        Sets the strptime()-like format string which will be used to parse
+        the date/time.
+
+        @param params
+            strptime()-like format string used to parse the date/time.
+    */
+    virtual void SetParameters(const wxString& params);
+};
+
+/**
+    @class wxGridCellEnumRenderer
+
+    This class may be used to render in a cell a number as a textual
+    equivalent.
+
+    The corresponding text strings are specified as comma-separated items in
+    the string passed to this renderer ctor or SetParameters() method. For
+    example, if this string is @c "John,Fred,Bob" the cell will be rendered as
+    "John", "Fred" or "Bob" if its contents is 0, 1 or 2 respectively.
+
+    @library{wxadv}
+    @category{grid}
+
+    @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer,
+         wxGridCellBoolRenderer, wxGridCellDateTimeRenderer,
+         wxGridCellFloatRenderer, wxGridCellNumberRenderer,
+         wxGridCellStringRenderer
+*/
+class wxGridCellEnumRenderer : public wxGridCellStringRenderer
+{
+public:
+    /**
+        Enum renderer ctor.
+
+        @param choices
+            Comma separated string parameters "item1[,item2[...,itemN]]".
+    */
+    wxGridCellEnumRenderer( const wxString& choices = wxEmptyString );
+
+    /**
+        Sets the comma separated string content of the enum.
+
+        @param params
+            Comma separated string parameters "item1[,item2[...,itemN]]".
+    */
+    virtual void SetParameters(const wxString& params);
+};
+

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


@@ -78,13 +186,17 @@ public:
     @library{wxadv}
     @category{grid}
 
     @library{wxadv}
     @category{grid}
 

-    @see wxGridCellRenderer, wxGridCellBoolRenderer, wxGridCellNumberRenderer,
+    @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer,
+         wxGridCellBoolRenderer, wxGridCellDateTimeRenderer,
+         wxGridCellEnumRenderer, wxGridCellNumberRenderer,

          wxGridCellStringRenderer
 */
 class wxGridCellFloatRenderer : public wxGridCellStringRenderer
 {
 public:
     /**
          wxGridCellStringRenderer
 */
 class wxGridCellFloatRenderer : public wxGridCellStringRenderer
 {
 public:
     /**

+        Float cell renderer ctor.
+

         @param width
             Minimum number of characters to be shown.
         @param precision
         @param width
             Minimum number of characters to be shown.
         @param precision


@@ -126,7 +238,9 @@ public:
     @library{wxadv}
     @category{grid}
 
     @library{wxadv}
     @category{grid}
 

-    @see wxGridCellRenderer, wxGridCellBoolRenderer, wxGridCellFloatRenderer,
+    @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer,
+         wxGridCellBoolRenderer, wxGridCellDateTimeRenderer,
+         wxGridCellEnumRenderer, wxGridCellFloatRenderer,

          wxGridCellStringRenderer
 */
 class wxGridCellNumberRenderer : public wxGridCellStringRenderer
          wxGridCellStringRenderer
 */
 class wxGridCellNumberRenderer : public wxGridCellStringRenderer


@@ -147,7 +261,9 @@ public:
     @library{wxadv}
     @category{grid}
 
     @library{wxadv}
     @category{grid}
 

-    @see wxGridCellRenderer, wxGridCellBoolRenderer, wxGridCellFloatRenderer,
+    @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer,
+         wxGridCellBoolRenderer, wxGridCellDateTimeRenderer,
+         wxGridCellEnumRenderer, wxGridCellFloatRenderer,

          wxGridCellNumberRenderer
 */
 class wxGridCellStringRenderer : public wxGridCellRenderer
          wxGridCellNumberRenderer
 */
 class wxGridCellStringRenderer : public wxGridCellRenderer


@@ -160,7 +276,6 @@ public:
 };
 
 
 };
 
 

-

 /**
     @class wxGridCellEditor
 
 /**
     @class wxGridCellEditor
 


@@ -173,8 +288,10 @@ public:
     @library{wxadv}
     @category{grid}
 
     @library{wxadv}
     @category{grid}
 

-    @see wxGridCellBoolEditor, wxGridCellChoiceEditor, wxGridCellFloatEditor,
-         wxGridCellNumberEditor, wxGridCellTextEditor
+    @see wxGridCellAutoWrapStringEditor, wxGridCellBoolEditor,
+         wxGridCellChoiceEditor, wxGridCellEnumEditor,
+         wxGridCellFloatEditor, wxGridCellNumberEditor,
+         wxGridCellTextEditor

 */
 class wxGridCellEditor
 {
 */
 class wxGridCellEditor
 {


@@ -295,6 +412,24 @@ protected:
     virtual ~wxGridCellEditor();
 };
 
     virtual ~wxGridCellEditor();
 };
 

+/**
+    @class wxGridCellAutoWrapStringEditor
+
+    Grid cell editor for wrappable string/text data.
+
+    @library{wxadv}
+    @category{grid}
+
+    @see wxGridCellEditor, wxGridCellBoolEditor, wxGridCellChoiceEditor,
+         wxGridCellEnumEditor, wxGridCellFloatEditor,
+         wxGridCellNumberEditor, wxGridCellTextEditor
+*/
+class wxGridCellAutoWrapStringEditor : public wxGridCellTextEditor
+{
+public:
+    wxGridCellAutoWrapStringEditor();
+};
+

 /**
     @class wxGridCellBoolEditor
 
 /**
     @class wxGridCellBoolEditor
 


@@ -303,8 +438,10 @@ protected:
     @library{wxadv}
     @category{grid}
 
     @library{wxadv}
     @category{grid}
 

-    @see wxGridCellEditor, wxGridCellChoiceEditor, wxGridCellFloatEditor,
-         wxGridCellNumberEditor, wxGridCellTextEditor
+    @see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
+         wxGridCellChoiceEditor, wxGridCellEnumEditor,
+         wxGridCellFloatEditor, wxGridCellNumberEditor,
+         wxGridCellTextEditor

 */
 class wxGridCellBoolEditor : public wxGridCellEditor
 {
 */
 class wxGridCellBoolEditor : public wxGridCellEditor
 {


@@ -340,13 +477,17 @@ public:
     @library{wxadv}
     @category{grid}
 
     @library{wxadv}
     @category{grid}
 

-    @see wxGridCellEditor, wxGridCellBoolEditor, wxGridCellFloatEditor,
-         wxGridCellNumberEditor, wxGridCellTextEditor
+    @see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
+         wxGridCellBoolEditor, wxGridCellEnumEditor,
+         wxGridCellFloatEditor, wxGridCellNumberEditor,
+         wxGridCellTextEditor

 */
 class wxGridCellChoiceEditor : public wxGridCellEditor
 {
 public:
     /**
 */
 class wxGridCellChoiceEditor : public wxGridCellEditor
 {
 public:
     /**

+        Choice cell renderer ctor.
+

         @param count
             Number of strings from which the user can choose.
         @param choices
         @param count
             Number of strings from which the user can choose.
         @param choices


@@ -358,7 +499,10 @@ public:
     wxGridCellChoiceEditor(size_t count = 0,
                            const wxString choices[] = NULL,
                            bool allowOthers = false);
     wxGridCellChoiceEditor(size_t count = 0,
                            const wxString choices[] = NULL,
                            bool allowOthers = false);

+

     /**
     /**

+        Choice cell renderer ctor.
+

         @param choices
             An array of strings from which the user can choose.
         @param allowOthers
         @param choices
             An array of strings from which the user can choose.
         @param allowOthers


@@ -374,6 +518,33 @@ public:
     virtual void SetParameters(const wxString& params);
 };
 
     virtual void SetParameters(const wxString& params);
 };
 

+/**
+    @class wxGridCellEnumEditor
+
+    Grid cell editor which displays an enum number as a textual equivalent
+    (eg. data in cell is 0,1,2 ... n the cell could be displayed as
+    "John","Fred"..."Bob" in the combo choice box).
+
+    @library{wxadv}
+    @category{grid}
+
+    @see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
+         wxGridCellBoolEditor, wxGridCellChoiceEditor,
+         wxGridCellTextEditor, wxGridCellFloatEditor,
+         wxGridCellNumberEditor
+*/
+class wxGridCellEnumEditor : public wxGridCellChoiceEditor
+{
+public:
+    /**
+        Enum cell editor ctor.
+
+        @param choices
+            Comma separated choice parameters "item1[,item2[...,itemN]]".
+    */
+    wxGridCellEnumEditor( const wxString& choices = wxEmptyString );
+};
+

 /**
     @class wxGridCellTextEditor
 
 /**
     @class wxGridCellTextEditor
 


@@ -382,8 +553,10 @@ public:
     @library{wxadv}
     @category{grid}
 
     @library{wxadv}
     @category{grid}
 

-    @see wxGridCellEditor, wxGridCellBoolEditor, wxGridCellChoiceEditor,
-         wxGridCellFloatEditor, wxGridCellNumberEditor
+    @see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
+         wxGridCellBoolEditor, wxGridCellChoiceEditor,
+         wxGridCellEnumEditor, wxGridCellFloatEditor,
+         wxGridCellNumberEditor

 */
 class wxGridCellTextEditor : public wxGridCellEditor
 {
 */
 class wxGridCellTextEditor : public wxGridCellEditor
 {


@@ -408,13 +581,17 @@ public:
     @library{wxadv}
     @category{grid}
 
     @library{wxadv}
     @category{grid}
 

-    @see wxGridCellEditor, wxGridCellNumberEditor, wxGridCellBoolEditor,
-    wxGridCellTextEditor, wxGridCellChoiceEditor
+    @see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
+         wxGridCellBoolEditor, wxGridCellChoiceEditor,
+         wxGridCellEnumEditor, wxGridCellNumberEditor,
+         wxGridCellTextEditor

 */
 class wxGridCellFloatEditor : public wxGridCellTextEditor
 {
 public:
     /**
 */
 class wxGridCellFloatEditor : public wxGridCellTextEditor
 {
 public:
     /**

+        Float cell editor ctor.
+

         @param width
             Minimum number of characters to be shown.
         @param precision
         @param width
             Minimum number of characters to be shown.
         @param precision


@@ -436,8 +613,10 @@ public:
     @library{wxadv}
     @category{grid}
 
     @library{wxadv}
     @category{grid}
 

-    @see wxGridCellEditor, wxGridCellBoolEditor, wxGridCellChoiceEditor,
-         wxGridCellFloatEditor, wxGridCellTextEditor
+    @see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
+         wxGridCellBoolEditor, wxGridCellChoiceEditor,
+         wxGridCellEnumEditor, wxGridCellFloatEditor,
+         wxGridCellTextEditor

 */
 class wxGridCellNumberEditor : public wxGridCellTextEditor
 {
 */
 class wxGridCellNumberEditor : public wxGridCellTextEditor
 {


@@ -1451,7 +1630,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


@@ -1507,7 +1686,20 @@ public:
 
             The user won't be able to select any cells or rows in this mode.
          */
 
             The user won't be able to select any cells or rows in this mode.
          */

-        wxGridSelectColumns
+        wxGridSelectColumns,
+
+        /**
+            The selection mode allowing the user to select either the entire
+            columns or the entire rows but not individual cells nor blocks.
+
+            Notice that while this constant is defined as @code
+            wxGridSelectColumns | wxGridSelectRows @endcode this doesn't mean
+            that all the other combinations are valid -- at least currently
+            they are not.
+
+            @since 2.9.1
+         */
+        wxGridSelectRowsOrColumns

     };
 
     /**
     };
 
     /**


@@ -1843,10 +2035,18 @@ public:
         are using the grid to display tabular data and don't have thousands of
         columns in it.
 
         are using the grid to display tabular data and don't have thousands of
         columns in it.
 

-        Also note that currently @c wxEVT_GRID_LABEL_LEFT_DCLICK and
-        @c wxEVT_GRID_LABEL_RIGHT_DCLICK events are not generated for the column
-        labels if the native columns header is used (but this limitation could
-        possibly be lifted in the future).
+        Another difference between the default behaviour and the native header
+        behaviour is that the latter provides the user with a context menu
+        (which appears on right clicking the header) allowing to rearrange the
+        grid columns if CanDragColMove() returns @true. If you want to prevent
+        this from happening for some reason, you need to define a handler for
+        @c wxEVT_GRID_LABEL_RIGHT_CLICK event which simply does nothing (in
+        particular doesn't skip the event) as this will prevent the default
+        right click handling from working.
+
+        Also note that currently @c wxEVT_GRID_LABEL_RIGHT_DCLICK event is not
+        generated for the column labels if the native columns header is used
+        (but this limitation could possibly be lifted in the future).

      */
     void UseNativeColHeader(bool native = true);
 
      */
     void UseNativeColHeader(bool native = true);
 


@@ -2581,7 +2781,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);
 


@@ -2809,7 +3009,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.
 


@@ -3646,6 +3846,31 @@ 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);
+

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


@@ -4026,6 +4251,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();
 


@@ -4036,6 +4265,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();