From 5039f140c4d1ea413991e95477cdc6f755ab4b73 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Tue, 16 Sep 2008 16:18:39 +0000 Subject: [PATCH] document wxGridTableBase git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@55662 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- interface/wx/grid.h | 349 ++++++++++++++++++++++++++++++-------------- 1 file changed, 240 insertions(+), 109 deletions(-) diff --git a/interface/wx/grid.h b/interface/wx/grid.h index 1dace1eee9..10d96fc530 100644 --- a/interface/wx/grid.h +++ b/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(); - */ - ~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); + + //@} }; -- 2.45.2