/**
@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}
class wxGridTableBase : public wxObject
{
public:
- /**
-
- */
+ /// Default constructor.
wxGridTableBase();
- /**
+ /// Destructor frees the attribute provider if it was created.
+ virtual ~wxGridTableBase();
- */
- ~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;
- */
- bool AppendCols(size_t numCols = 1);
/**
+ Accessing table cells.
+ */
+ //@{
- */
- bool AppendRows(size_t numRows = 1);
+ /// Must be overridden to implement testing for empty cells.
+ 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;
- */
- bool CanGetValueAs(int row, int col, const wxString& typeName);
+ /// Must be overridden to implement setting the table values as text.
+ virtual void SetValue(int row, int col, const wxString& value) = 0;
/**
- Does this table allow attributes? Default implementation creates
- a wxGridCellAttrProvider if necessary.
- */
- bool CanHaveAttributes();
+ Returns the type of the value in the given cell.
+
+ By default all cells are strings and this method returns @c
+ 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.
- */
- bool CanSetValueAs(int row, int col, const wxString& typeName);
+ By default the cells can only be accessed as strings. Note that a cell
+ 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);
/**
+ Returns true if the value of the given cell can be set as if it were of
+ the specified type.
- */
- void Clear();
+ @see CanGetValueAs()
+ */
+ virtual bool CanSetValueAs(int row, int col, const wxString& typeName);
/**
+ Returns the value of the given cell as a long.
- */
- bool DeleteCols(size_t pos = 0, size_t numCols = 1);
+ This should only be called if CanGetValueAs() returns @true when called
+ 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.
- */
- bool DeleteRows(size_t pos = 0, size_t numRows = 1);
+ This should only be called if CanGetValueAs() returns @true when called
+ with @c wxGRID_VALUE_FLOAT argument. Default implementation always
+ return 0.0.
+ */
+ virtual double GetValueAsDouble(int row, int col);
/**
- by default forwarded to wxGridCellAttrProvider if any. May be
- overridden to handle attributes directly in the table.
- */
- wxGridCellAttr* GetAttr(int row, int col);
+ Returns the value of the given cell as a boolean.
- /**
- get the currently used attr provider (may be @NULL)
- */
- wxGridCellAttrProvider* GetAttrProvider() const;
+ This should only be called if CanGetValueAs() returns @true when called
+ 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);
- */
- wxString GetColLabelValue(int col);
/**
+ Sets the value of the given cell as a long.
- */
- int GetNumberCols();
+ This should only be called if CanSetValueAs() returns @true when called
+ with @c wxGRID_VALUE_NUMBER argument. Default implementation doesn't do
+ anything.
+ */
+ virtual void SetValueAsLong(int row, int col, long value);
/**
- You must override these functions in a derived table class.
- */
- int GetNumberRows();
+ Sets the value of the given cell as a double.
+
+ 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.
- */
- wxString GetRowLabelValue(int row);
+ This should only be called if CanSetValueAs() returns @true when called
+ with @c wxGRID_VALUE_BOOL argument. Default implementation doesn't do
+ anything.
+ */
+ virtual void SetValueAsBool( int row, int col, bool value );
/**
- Data type determination and value access.
- */
- wxString GetTypeName(int row, int col);
+ Sets the value of the given cell as a user-defined type.
- /**
+ This should only be called if CanSetValueAs() returns @true when called
+ with @a typeName. Default implementation doesn't do anything.
+ */
+ virtual void SetValueAsCustom(int row, int col, const wxString& typeName,
+ void *value);
- */
- wxString GetValue(int row, int col);
+ //@}
/**
+ Called by the grid when the table is associated with it.
- */
- bool GetValueAsBool(int row, int col);
+ 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);
/**
- For user defined types
- */
- void* GetValueAsCustom(int row, int col,
- const wxString& typeName);
+ Returns the last grid passed to SetView().
+ */
+ virtual wxGrid *GetView() const;
+
/**
+ Modifying the table structure.
- */
- double GetValueAsDouble(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.
- */
- long GetValueAsLong(int row, int col);
+ This method is used by wxGrid::ClearGrid().
+ */
+ virtual void Clear();
/**
+ Insert additional rows into the table.
- */
- wxGrid* GetView() const;
+ @param pos
+ 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);
/**
+ Append additional rows at the end of the table.
- */
- bool InsertCols(size_t pos = 0, size_t numCols = 1);
+ This method is provided in addition to InsertRows() as some data models
+ 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.
- */
- bool InsertRows(size_t pos = 0, size_t numRows = 1);
+ @param pos
+ 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);
- */
- bool IsEmptyCell(int row, int col);
+ /// Exactly the same as AppendRows() but for columns.
+ virtual bool AppendCols(size_t numCols = 1);
- /**
- these functions take ownership of the pointer
- */
- void SetAttr(wxGridCellAttr* attr, int row, int col);
+ /// Exactly the same as DeleteRows() but for columns.
+ virtual bool DeleteCols(size_t pos = 0, size_t numCols = 1);
- /**
- Attribute handling
- give us the attr provider to use - we take ownership of the pointer
- */
- void SetAttrProvider(wxGridCellAttrProvider* attrProvider);
+ //@}
/**
+ Table rows and columns labels.
- */
- void SetColAttr(wxGridCellAttr* attr, int col);
+ By default the numbers are used for labeling rows and Latin letters for
+ 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, ...
+ */
+ //@{
- /**
- , @e wxString)
- */
- void SetColLabelValue() const;
+ /// 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.
- */
- void SetRowAttr(wxGridCellAttr* attr, int 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);
+
+ //@}
- /**
- , @e wxString)
- */
- void SetRowLabelValue() const;
/**
+ Attributes management.
- */
- void SetValue(int row, int col, const wxString& value);
+ By default the attributes management is delegated to
+ 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.
- */
- void SetValueAsBool(int row, int col, bool value);
+ The table takes ownership of @a attrProvider pointer and will delete it
+ 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.
- */
- void SetValueAsCustom(int row, int col, const wxString& typeName,
- void* value);
+ This function may return @NULL if the attribute provider hasn't been
+ neither associated with this table by SetAttrProvider() nor created on
+ demand by any other methods.
+ */
+ wxGridCellAttrProvider *GetAttrProvider() const { return m_attrProvider; }
/**
+ Returns true if this table supports attributes or false otherwise.
- */
- void SetValueAsDouble(int row, int col, double value);
+ 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();
/**
+ Return the attribute for the given cell.
- */
- void SetValueAsLong(int row, int col, long value);
+ By default this function is simply forwarded to
+ wxGridCellAttrProvider::GetAttr() but it may be overridden to handle
+ attributes directly in the table.
+ */
+ virtual wxGridCellAttr *GetAttr(int row, int col,
+ wxGridCellAttr::wxAttrKind kind);
/**
- Overriding these is optional
- */
- void SetView(wxGrid* grid);
+ Set attribute of the specified cell.
+
+ By default this function is simply forwarded to
+ 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);
/**
+ Set attribute of the specified row.
- */
- void UpdateAttrCols(size_t pos, int numCols);
+ 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);
/**
- change row/col number in attribute if needed
- */
- void UpdateAttrRows(size_t pos, int numRows);
+ Set attribute of the specified column.
+
+ By default this function is simply forwarded to
+ wxGridCellAttrProvider::SetColAttr().
+
+ The table takes ownership of @a attr, i.e. will call DecRef() on it.
+ */
+ virtual void SetColAttr(wxGridCellAttr *attr, int col);
+
+ //@}
};
projects / wxWidgets.git / commitdiff
