document wxGridTableBase

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

interface/wx/grid.h

@@ -59,7 +59,20 @@ public:
 /**
     @class wxGridTableBase
 
-    Grid table classes.
+    The almost abstract base class for grid tables.
+
+    A grid table is responsible for storing the grid data and, indirectly, grid
+    cell attributes. The data can be stored in the way most convenient for the
+    application but has to be provided in string form to wxGrid. It is also
+    possible to provide cells values in other formats if appropriate, e.g. as
+    numbers.
+
+    This base class is not quite abstract as it implements a trivial strategy
+    for storing the attributes by forwarding it to wxGridCellAttrProvider and
+    also provides stubs for some other functions. However it does have a number
+    of pure virtual methods which must be implemented in the derived classes.
+
+    @see wxGridStringTable
 
     @library{wxadv}
     @category{grid}
@@ -67,210 +80,328 @@ public:
 class wxGridTableBase : public wxObject
 {
 public:
-    /**
+    /// Default constructor.
-
-    */
     wxGridTableBase();
 
-    /**
+    /// Destructor frees the attribute provider if it was created.
+    virtual ~wxGridTableBase();
+
+    /// Must be overridden to return the number of rows in the table.
+    virtual int GetNumberRows() = 0;
+
+    /// Must be overridden to return the number of columns in the table.
+    virtual int GetNumberCols() = 0;
 
-    */
-    ~wxGridTableBase();
 
     /**
+        Accessing table cells.
+     */
+    //@{
 
-    */
+    /// Must be overridden to implement testing for empty cells.
-    bool AppendCols(size_t numCols = 1);
+    virtual bool IsEmptyCell(int row, int col) = 0;
+
+    /// Must be overridden to implement accessing the table values as text.
+    virtual wxString GetValue(int row, int col) = 0;
+
+    /// Must be overridden to implement setting the table values as text.
+    virtual void SetValue(int row, int col, const wxString& value) = 0;
 
     /**
+        Returns the type of the value in the given cell.
 
-    */
+        By default all cells are strings and this method returns @c
-    bool AppendRows(size_t numRows = 1);
+        wxGRID_VALUE_STRING.
+     */
+    virtual wxString GetTypeName(int row, int col);
 
     /**
+        Returns true if the value of the given cell can be accessed as if it
+        were of the specified type.
 
-    */
+        By default the cells can only be accessed as strings. Note that a cell
-    bool CanGetValueAs(int row, int col, const wxString& typeName);
+        could be accessible in different ways, e.g. a numeric cell may return
+        @true for @c wxGRID_VALUE_NUMBER but also for @c wxGRID_VALUE_STRING
+        indicating that the value can be coerced to a string form.
+     */
+    virtual bool CanGetValueAs(int row, int col, const wxString& typeName);
 
     /**
-        Does this table allow attributes?  Default implementation creates
+        Returns true if the value of the given cell can be set as if it were of
-        a wxGridCellAttrProvider if necessary.
+        the specified type.
-    */
+
-    bool CanHaveAttributes();
+        @see CanGetValueAs()
+     */
+    virtual bool CanSetValueAs(int row, int col, const wxString& typeName);
 
     /**
+        Returns the value of the given cell as a long.
 
-    */
+        This should only be called if CanGetValueAs() returns @true when called
-    bool CanSetValueAs(int row, int col, const wxString& typeName);
+        with @c wxGRID_VALUE_NUMBER argument. Default implementation always
+        return 0.
+     */
+    virtual long GetValueAsLong(int row, int col);
 
     /**
+        Returns the value of the given cell as a double.
 
-    */
+        This should only be called if CanGetValueAs() returns @true when called
-    void Clear();
+        with @c wxGRID_VALUE_FLOAT argument. Default implementation always
+        return 0.0.
+     */
+    virtual double GetValueAsDouble(int row, int col);
 
     /**
+        Returns the value of the given cell as a boolean.
 
-    */
+        This should only be called if CanGetValueAs() returns @true when called
-    bool DeleteCols(size_t pos = 0, size_t numCols = 1);
+        with @c wxGRID_VALUE_BOOL argument. Default implementation always
+        return false.
+     */
+    virtual bool GetValueAsBool(int row, int col);
 
     /**
+        Returns the value of the given cell as a user-defined type.
+
+        This should only be called if CanGetValueAs() returns @true when called
+        with @a typeName. Default implementation always return @NULL.
+     */
+    virtual void *GetValueAsCustom(int row, int col, const wxString& typeName);
 
-    */
-    bool DeleteRows(size_t pos = 0, size_t numRows = 1);
 
     /**
-        by default forwarded to wxGridCellAttrProvider if any. May be
+        Sets the value of the given cell as a long.
-        overridden to handle attributes directly in the table.
+
-    */
+        This should only be called if CanSetValueAs() returns @true when called
-    wxGridCellAttr* GetAttr(int row, int col);
+        with @c wxGRID_VALUE_NUMBER argument. Default implementation doesn't do
+        anything.
+     */
+    virtual void SetValueAsLong(int row, int col, long value);
 
     /**
-        get the currently used attr provider (may be @NULL)
+        Sets the value of the given cell as a double.
-    */
+
-    wxGridCellAttrProvider* GetAttrProvider() const;
+        This should only be called if CanSetValueAs() returns @true when called
+        with @c wxGRID_VALUE_FLOAT argument. Default implementation doesn't do
+        anything.
+     */
+    virtual void SetValueAsDouble(int row, int col, double value);
 
     /**
+        Sets the value of the given cell as a boolean.
 
-    */
+        This should only be called if CanSetValueAs() returns @true when called
-    wxString GetColLabelValue(int col);
+        with @c wxGRID_VALUE_BOOL argument. Default implementation doesn't do
+        anything.
+     */
+    virtual void SetValueAsBool( int row, int col, bool value );
 
     /**
+        Sets the value of the given cell as a user-defined type.
 
-    */
+        This should only be called if CanSetValueAs() returns @true when called
-    int GetNumberCols();
+        with @a typeName. Default implementation doesn't do anything.
+     */
+    virtual void SetValueAsCustom(int row, int col, const wxString& typeName,
+                                  void *value);
+
+    //@}
 
     /**
-        You must override these functions in a derived table class.
+        Called by the grid when the table is associated with it.
-    */
+
-    int GetNumberRows();
+        The default implementation stores the pointer and returns it from its
+        GetView() and so only makes sense if the table cannot be associated
+        with more than one grid at a time.
+     */
+    virtual void SetView(wxGrid *grid);
 
     /**
+        Returns the last grid passed to SetView().
+     */
+    virtual wxGrid *GetView() const;
 
-    */
-    wxString GetRowLabelValue(int row);
 
     /**
-        Data type determination and value access.
+        Modifying the table structure.
-    */
+
-    wxString GetTypeName(int row, int col);
+        Notice that none of these functions are pure virtual as they don't have
+        to be implemented if the table structure is never modified after
+        creation, i.e. neither rows nor columns are never added or deleted but
+        that you do need to implement them if they are called, i.e. if your
+        code either calls them directly or uses the matching wxGrid methods, as
+        by default they simply do nothing which is definitely inappropriate.
+     */
+    //@{
 
     /**
+        Clear the table contents.
 
-    */
+        This method is used by wxGrid::ClearGrid().
-    wxString GetValue(int row, int col);
+     */
+    virtual void Clear();
 
     /**
+        Insert additional rows into the table.
 
-    */
+        @param pos
-    bool GetValueAsBool(int row, int col);
+            The position of the first new row.
+        @param numRows
+            The number of rows to insert.
+     */
+    virtual bool InsertRows(size_t pos = 0, size_t numRows = 1);
 
     /**
-        For user defined types
+        Append additional rows at the end of the table.
-    */
+
-    void* GetValueAsCustom(int row, int col,
+        This method is provided in addition to InsertRows() as some data models
-                           const wxString& typeName);
+        may only support appending rows to them but not inserting them at
+        arbitrary locations. In such case you may implement this method only
+        and leave InsertRows() unimplemented.
+
+        @param pos
+            The position of the first new row.
+        @param numRows
+            The number of rows to add.
+     */
+    virtual bool AppendRows(size_t numRows = 1);
 
     /**
+        Delete rows from the table.
 
-    */
+        @param pos
-    double GetValueAsDouble(int row, int col);
+            The first row to delete.
+        @param numRows
+            The number of rows to delete.
+     */
+    virtual bool DeleteRows(size_t pos = 0, size_t numRows = 1);
+
+    /// Exactly the same as InsertRows() but for columns.
+    virtual bool InsertCols(size_t pos = 0, size_t numCols = 1);
+
+    /// Exactly the same as AppendRows() but for columns.
+    virtual bool AppendCols(size_t numCols = 1);
+
+    /// Exactly the same as DeleteRows() but for columns.
+    virtual bool DeleteCols(size_t pos = 0, size_t numCols = 1);
+
+    //@}
 
     /**
+        Table rows and columns labels.
 
-    */
+        By default the numbers are used for labeling rows and Latin letters for
-    long GetValueAsLong(int row, int col);
+        labeling 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, ...
+     */
+    //@{
+
+    /// Return the label of the specified row.
+    virtual wxString GetRowLabelValue(int row);
+
+    /// Return the label of the specified column.
+    virtual wxString GetColLabelValue(int col);
 
     /**
+        Set the given label for the specified row.
+
+        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::SetRowLabelValue() to work.
+     */
+    virtual void SetRowLabelValue(int row, const wxString& label);
+
+    /// Exactly the same as SetRowLabelValue() but for columns.
+    virtual void SetColLabelValue(int col, const wxString& label);
+
+    //@}
 
-    */
-    wxGrid* GetView() const;
 
     /**
+        Attributes management.
 
-    */
+        By default the attributes management is delegated to
-    bool InsertCols(size_t pos = 0, size_t numCols = 1);
+        wxGridCellAttrProvider class. You may override the methods in this
+        section to handle the attributes directly if, for example, they can be
+        computed from the cell values.
+     */
+    //@{
 
     /**
+        Associate this attributes provider with the table.
 
-    */
+        The table takes ownership of @a attrProvider pointer and will delete it
-    bool InsertRows(size_t pos = 0, size_t numRows = 1);
+        when it doesn't need it any more. The pointer can be @NULL, however
+        this won't disable attributes management in the table but will just
+        result in a default attributes being recreated the next time any of the
+        other functions in this section is called. To completely disable the
+        attributes support, should this be needed, you need to override
+        CanHaveAttributes() to return @false.
+     */
+    void SetAttrProvider(wxGridCellAttrProvider *attrProvider);
 
     /**
+        Returns the attribute provider currently being used.
 
-    */
+        This function may return @NULL if the attribute provider hasn't been
-    bool IsEmptyCell(int row, int col);
+        neither associated with this table by SetAttrProvider() nor created on
+        demand by any other methods.
+     */
+    wxGridCellAttrProvider *GetAttrProvider() const { return m_attrProvider; }
 
     /**
-        these functions take ownership of the pointer
+        Returns true if this table supports attributes or false otherwise.
-    */
+
-    void SetAttr(wxGridCellAttr* attr, int row, int col);
+        By default, the table automatically creates a wxGridCellAttrProvider
+        when this function is called if it had no attribute provider before and
+        returns @true.
+     */
+    virtual bool CanHaveAttributes();
 
     /**
-        Attribute handling
+        Return the attribute for the given cell.
-        give us the attr provider to use - we take ownership of the pointer
+
-    */
+        By default this function is simply forwarded to
-    void SetAttrProvider(wxGridCellAttrProvider* attrProvider);
+        wxGridCellAttrProvider::GetAttr() but it may be overridden to handle
+        attributes directly in the table.
+     */
+    virtual wxGridCellAttr *GetAttr(int row, int col,
+                                    wxGridCellAttr::wxAttrKind kind);
 
     /**
+        Set attribute of the specified cell.
 
-    */
+        By default this function is simply forwarded to
-    void SetColAttr(wxGridCellAttr* attr, int col);
+        wxGridCellAttrProvider::SetAttr().
+
+        The table takes ownership of @a attr, i.e. will call DecRef() on it.
+     */
+    virtual void SetAttr(wxGridCellAttr* attr, int row, int col);
 
     /**
-        , @e wxString)
+        Set attribute of the specified row.
-    */
+
-    void SetColLabelValue() const;
+        By default this function is simply forwarded to
+        wxGridCellAttrProvider::SetRowAttr().
+
+        The table takes ownership of @a attr, i.e. will call DecRef() on it.
+     */
+    virtual void SetRowAttr(wxGridCellAttr *attr, int row);
 
     /**
+        Set attribute of the specified column.
 
-    */
+        By default this function is simply forwarded to
-    void SetRowAttr(wxGridCellAttr* attr, int row);
+        wxGridCellAttrProvider::SetColAttr().
 
-    /**
+        The table takes ownership of @a attr, i.e. will call DecRef() on it.
-        , @e wxString)
+     */
-    */
+    virtual void SetColAttr(wxGridCellAttr *attr, int col);
-    void SetRowLabelValue() const;
 
-    /**
+    //@}
-
-    */
-    void SetValue(int row, int col, const wxString& value);
-
-    /**
-
-    */
-    void SetValueAsBool(int row, int col, bool value);
-
-    /**
-
-    */
-    void SetValueAsCustom(int row, int col, const wxString& typeName,
-                          void* value);
-
-    /**
-
-    */
-    void SetValueAsDouble(int row, int col, double value);
-
-    /**
-
-    */
-    void SetValueAsLong(int row, int col, long value);
-
-    /**
-        Overriding these is optional
-    */
-    void SetView(wxGrid* grid);
-
-    /**
-
-    */
-    void UpdateAttrCols(size_t pos, int numCols);
-
-    /**
-        change row/col number in attribute if needed
-    */
-    void UpdateAttrRows(size_t pos, int numRows);
 };