Add documentation for new [Get/Set]CornerLabelValue functionality

interface/wx/grid.h

@@ -1012,20 +1012,18 @@ protected:
 };
 
 /**
-    Base class for corner window renderer.
+    Base class for header cells renderers.
 
-    This is the simplest of all header renderers and only has a single
+    A cell renderer can be used to draw the text of a cell's label, and/or
-    function.
+    the border around it.
-
-    @see wxGridCellAttrProvider::GetCornerRenderer()
 
     @since 2.9.1
  */
-class wxGridCornerHeaderRenderer
+class wxGridHeaderCellRenderer
 {
 public:
     /**
-        Called by the grid to draw the corner window border.
+        Called by the grid to draw the border around the cell header.
 
         This method is responsible for drawing the border inside the given @a
         rect and adjusting the rectangle size to correspond to the area inside
@@ -1033,7 +1031,7 @@ public:
         border width.
 
         @param grid
-            The grid whose corner window is being drawn.
+            The grid whose header cell window is being drawn.
         @param dc
             The device context to use for drawing.
         @param rect
@@ -1044,23 +1042,11 @@ public:
     virtual void DrawBorder(const wxGrid& grid,
                             wxDC& dc,
                             wxRect& rect) const = 0;
-};
 
-/**
-    Common base class for row and column headers renderers.
-
-    @see wxGridColumnHeaderRenderer, wxGridRowHeaderRenderer
-
-    @since 2.9.1
- */
-class wxGridHeaderLabelsRenderer : public wxGridCornerHeaderRenderer
-{
-public:
     /**
         Called by the grid to draw the specified label.
 
-        Notice that the base class DrawBorder() method is called before this
+        Notice that the DrawBorder() method is called before this one.
-        one.
 
         The default implementation uses wxGrid::GetLabelTextColour() and
         wxGrid::GetLabelFont() to draw the label.
@@ -1077,8 +1063,9 @@ public:
 /**
     Base class for row headers renderer.
 
-    This is the same as wxGridHeaderLabelsRenderer currently but we still use a
+    This is the same as wxGridHeaderCellRenderer currently but we still use a
-    separate class for it to distinguish it from wxGridColumnHeaderRenderer.
+    separate class for it to distinguish it from wxGridColumnHeaderRenderer
+    and wxGridCornerHeaderRenderer.
 
     @see wxGridRowHeaderRendererDefault
 
@@ -1086,15 +1073,16 @@ public:
 
     @since 2.9.1
  */
-class wxGridRowHeaderRenderer : public wxGridHeaderLabelsRenderer
+class wxGridRowHeaderRenderer : public wxGridHeaderCellRenderer
 {
 };
 
 /**
     Base class for column headers renderer.
 
-    This is the same as wxGridHeaderLabelsRenderer currently but we still use a
+    This is the same as wxGridHeaderCellRenderer currently but we still use a
-    separate class for it to distinguish it from wxGridRowHeaderRenderer.
+    separate class for it to distinguish it from wxGridRowHeaderRenderer and
+    wxGridCornerHeaderRenderer.
 
     @see wxGridColumnHeaderRendererDefault
 
@@ -1102,7 +1090,24 @@ class wxGridRowHeaderRenderer : public wxGridHeaderLabelsRenderer
 
     @since 2.9.1
  */
-class wxGridColumnHeaderRenderer : public wxGridHeaderLabelsRenderer
+class wxGridColumnHeaderRenderer : public wxGridHeaderCellRenderer
+{
+};
+
+/**
+    Base class for corner header renderer.
+
+    This is the same as wxGridHeaderCellRenderer currently but we still use a
+    separate class for it to distinguish it from wxGridRowHeaderRenderer and
+    wxGridColumnHeaderRenderer.
+
+    @see wxGridCornerHeaderRendererDefault
+
+    @see wxGridCellAttrProvider::GetCornerRenderer()
+
+    @since 2.9.1
+ */
+class wxGridCornerHeaderRenderer : public wxGridHeaderCellRenderer
 {
 };
 
@@ -1113,7 +1118,7 @@ class wxGridColumnHeaderRenderer : public wxGridHeaderLabelsRenderer
     methods (i.e. either DrawLabel() or DrawBorder()) but continue to use the
     default implementation for the other one.
 
-    @see wxGridColumnHeaderRendererDefault
+    @see wxGridColumnHeaderRendererDefault, wxGridCornerHeaderRendererDefault
 
     @since 2.9.1
  */
@@ -1129,7 +1134,7 @@ public:
 /**
     Default column header renderer.
 
-    @see wxGridRowHeaderRendererDefault
+    @see wxGridRowHeaderRendererDefault, wxGridCornerHeaderRendererDefault
 
     @since 2.9.1
  */
@@ -1393,8 +1398,10 @@ public:
 
     void SetRowLabelValue( int row, const wxString& );
     void SetColLabelValue( int col, const wxString& );
+    void SetCornerLabelValue( const wxString& );
     wxString GetRowLabelValue( int row );
     wxString GetColLabelValue( int col );
+    wxString GetCornerLabelValue() const;
 };
 
 /**
@@ -1764,13 +1771,19 @@ public:
     //@}
 
     /*!
-        @name Table Row and Column Labels
+        @name Table Row, Column and Corner Labels
 
         By default the numbers are used for labelling rows and Latin letters for
         labelling columns. If the table has more than 26 columns, the pairs of
         letters are used starting from the 27-th one and so on, i.e. the
         sequence of labels is A, B, ..., Z, AA, AB, ..., AZ, BA, ..., ..., ZZ,
         AAA, ...
+
+        A cell in the top-left corner of a grid can also have a label. It is
+        empty by default. Use wxGrid::SetCornerLabelValue() to set it and
+        wxGrid::GetCornerLabelValue() to get its' current value.
+
+        @see wxGridTableBase::GetCornerLabelValue, wxGridTableBase::SetCornerLabelValue
      */
     //@{
 
@@ -1784,6 +1797,13 @@ public:
      */
     virtual wxString GetColLabelValue(int col);
 
+    /**
+        Return the label of the grid's corner.
+
+        @since 3.1.2
+     */
+    virtual wxString GetCornerLabelValue() const;
+
     /**
         Set the given label for the specified row.
 
@@ -1798,6 +1818,17 @@ public:
      */
     virtual void SetColLabelValue(int col, const wxString& label);
 
+    /**
+        Set the given label for the grid's corner.
+
+        The default version does nothing, i.e. the label is not stored. You
+        must override this method in your derived class if you wish
+        wxGrid::GetCornerLabelValue() to work.
+
+        @since 3.1.2
+     */
+    virtual void SetCornerLabelValue( const wxString& );
+
     //@}
 
 
@@ -2336,6 +2367,34 @@ public:
     */
     wxString GetColLabelValue(int col) const;
 
+    /**
+        Sets the arguments to the current corner label alignment values.
+
+        Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
+        or @c wxALIGN_RIGHT.
+
+        Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
+        @c wxALIGN_BOTTOM.
+
+        @since 3.1.2
+    */
+    void GetCornerLabelAlignment( int *horiz, int *vert ) const;
+
+    /**
+        Returns the orientation of the corner label (either @c wxHORIZONTAL or
+        @c wxVERTICAL).
+
+        @since 3.1.2
+    */
+    int GetCornerLabelTextOrientation() const;
+
+    /**
+        Returns the (top-left) corner label.
+
+        @since 3.1.2
+    */
+    wxString GetCornerLabelValue() const;
+
     /**
         Returns the colour used for the background of row and column labels.
     */
@@ -2408,6 +2467,35 @@ public:
     */
     void SetColLabelValue(int col, const wxString& value);
 
+    /**
+        Sets the horizontal and vertical alignment of the (top-left) corner label text.
+
+        Horizontal alignment should be one of @c wxALIGN_LEFT,
+        @c wxALIGN_CENTRE or @c wxALIGN_RIGHT. Vertical alignment should be one
+        of @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM.
+
+        @since 3.1.2
+    */
+    void SetCornerLabelAlignment( int horiz, int vert );
+
+    /**
+        Sets the orientation of the (top-left) corner label (either @c wxHORIZONTAL or
+        @c wxVERTICAL).
+
+        @since 3.1.2
+    */
+    void SetCornerLabelTextOrientation( int textOrientation );
+
+    /**
+        Set the value for the (top-left) corner label.
+
+        If you are using a custom grid table you must override
+        wxGridTableBase::SetCornerLabelValue() for this to have any effect.
+
+        @since 3.1.2
+    */
+    void SetCornerLabelValue( const wxString& );
+
     /**
         Sets the background colour for row and column labels.
     */