Add documentation for several grid cell renderer/editor classes.

Document the previously undocumented renderers and editors.

Closes #11965.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@64100 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/include/wx/generic/gridctrl.h b/include/wx/generic/gridctrl.h
index d5462055376d2642655ffdd74354997ae36fccb9..375bbc95deba5bde2eb8dfa0bdf79188f9b5dcaa 100644 (file)
--- a/include/wx/generic/gridctrl.h
+++ b/include/wx/generic/gridctrl.h
@@ -148,7 +148,7 @@ private:
 
 #include "wx/datetime.h"
 
 
 #include "wx/datetime.h"
 

-// the default renderer for the cells containing Time and dates..
+// the default renderer for the cells containing times and dates

 class WXDLLIMPEXP_ADV wxGridCellDateTimeRenderer : public wxGridCellStringRenderer
 {
 public:
 class WXDLLIMPEXP_ADV wxGridCellDateTimeRenderer : public wxGridCellStringRenderer
 {
 public:


@@ -170,7 +170,7 @@ public:
 
     virtual wxGridCellRenderer *Clone() const;
 
 
     virtual wxGridCellRenderer *Clone() const;
 

-    // parameters string format is "width[,precision]"
+    // output strptime()-like format string

     virtual void SetParameters(const wxString& params);
 
 protected:
     virtual void SetParameters(const wxString& params);
 
 protected:


@@ -184,7 +184,7 @@ protected:
 
 #endif // wxUSE_DATETIME
 
 
 #endif // wxUSE_DATETIME
 

-// the default renderer for the cells containing Time and dates..
+// renders a number using the corresponding text string

 class WXDLLIMPEXP_ADV wxGridCellEnumRenderer : public wxGridCellStringRenderer
 {
 public:
 class WXDLLIMPEXP_ADV wxGridCellEnumRenderer : public wxGridCellStringRenderer
 {
 public:


@@ -205,7 +205,8 @@ public:
 
     virtual wxGridCellRenderer *Clone() const;
 
 
     virtual wxGridCellRenderer *Clone() const;
 

-    // parameters string format is "item1[,item2[...,itemN]]"
+    // parameters string format is "item1[,item2[...,itemN]]" where itemN will
+    // be used if the cell value is N-1

     virtual void SetParameters(const wxString& params);
 
 protected:
     virtual void SetParameters(const wxString& params);
 
 protected:

diff --git a/interface/wx/grid.h b/interface/wx/grid.h
index 00f9b254b880eba890ec8510572c66227951db1b..4fe31735bce87aa20a308679973f943be94c2b2c 100644 (file)
--- a/interface/wx/grid.h
+++ b/interface/wx/grid.h
@@ -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


@@ -355,18 +496,13 @@ public:
             If allowOthers is @true, the user can type a string not in choices
             array.
     */
             If allowOthers is @true, the user can type a string not in choices
             array.
     */

+    //@{

     wxGridCellChoiceEditor(size_t count = 0,
                            const wxString choices[] = NULL,
                            bool allowOthers = false);
     wxGridCellChoiceEditor(size_t count = 0,
                            const wxString choices[] = NULL,
                            bool allowOthers = false);

-    /**
-        @param choices
-            An array of strings from which the user can choose.
-        @param allowOthers
-            If allowOthers is @true, the user can type a string not in choices
-            array.
-    */

     wxGridCellChoiceEditor(const wxArrayString& choices,
                            bool allowOthers = false);
     wxGridCellChoiceEditor(const wxArrayString& choices,
                            bool allowOthers = false);

+    //@}

 
     /**
         Parameters string format is "item1[,item2[...,itemN]]"
 
     /**
         Parameters string format is "item1[,item2[...,itemN]]"


@@ -374,6 +510,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 +545,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 +573,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 +605,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
 {

diff --git a/src/generic/gridctrl.cpp b/src/generic/gridctrl.cpp
index fdf63a20ffc758de6e948e07c7737ff4b938ea37..6d27bbfe5313e7292e80aee6e11500289e7ab6ab 100644 (file)
--- a/src/generic/gridctrl.cpp
+++ b/src/generic/gridctrl.cpp
@@ -172,7 +172,7 @@ void wxGridCellDateTimeRenderer::SetParameters(const wxString& params)
 #endif // wxUSE_DATETIME
 
 // ----------------------------------------------------------------------------
 #endif // wxUSE_DATETIME
 
 // ----------------------------------------------------------------------------

-// wxGridCellChoiceNumberRenderer
+// wxGridCellEnumRenderer

 // ----------------------------------------------------------------------------
 // Renders a number as a textual equivalent.
 // eg data in cell is 0,1,2 ... n the cell could be rendered as "John","Fred"..."Bob"
 // ----------------------------------------------------------------------------
 // Renders a number as a textual equivalent.
 // eg data in cell is 0,1,2 ... n the cell could be rendered as "John","Fred"..."Bob"