X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/08dd9b5aedf9fcd0810eb94ff0e632e27478c3be..b91c4601f2cc8fab375dc49a0a1222d58065cfdb:/interface/wx/grid.h diff --git a/interface/wx/grid.h b/interface/wx/grid.h index 1dace1eee9..18a50d7c21 100644 --- a/interface/wx/grid.h +++ b/interface/wx/grid.h @@ -41,7 +41,7 @@ public: /** Parameters string format is "width[,precision]". */ - void SetParameters(const wxString& params); + virtual void SetParameters(const wxString& params); /** Sets the precision. @@ -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,366 @@ 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. - */ - ~wxGridTableBase(); + For backwards compatibility reasons, this method is not const. + Use GetRowsCount() instead of it in const methods of derived table + classes. + */ + virtual int GetNumberRows() = 0; /** + Must be overridden to return the number of columns in the table. - */ - bool AppendCols(size_t numCols = 1); + For backwards compatibility reasons, this method is not const. + Use GetColsCount() instead of it in const methods of derived table + classes, + */ + virtual int GetNumberCols() = 0; /** + Return the number of rows in the table. - */ - bool AppendRows(size_t numRows = 1); + This method is not virtual and is only provided as a convenience for + the derived classes which can't call GetNumberRows() without a @c + const_cast from their const methods. + */ + int GetRowsCount() const; /** + Return the number of columns in the table. - */ - bool CanGetValueAs(int row, int col, const wxString& typeName); + This method is not virtual and is only provided as a convenience for + the derived classes which can't call GetNumberCols() without a @c + const_cast from their const methods. + */ + int GetColsCount() const; - /** - Does this table allow attributes? Default implementation creates - a wxGridCellAttrProvider if necessary. - */ - bool CanHaveAttributes(); /** + Accessing table cells. + */ + //@{ - */ - bool CanSetValueAs(int row, int col, const wxString& typeName); + /// Must be overridden to implement testing for empty cells. + virtual bool IsEmptyCell(int row, int col) = 0; /** + Same as IsEmptyCell() but taking wxGridCellCoords. - */ - void Clear(); + Notice that this method is not virtual, only IsEmptyCell() should be + overridden. + */ + bool IsEmpty(const wxGridCellCoords& coords); - /** + /// Must be overridden to implement accessing the table values as text. + virtual wxString GetValue(int row, int col) = 0; - */ - bool DeleteCols(size_t pos = 0, size_t numCols = 1); + /// 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. - */ - bool DeleteRows(size_t pos = 0, size_t numRows = 1); + By default all cells are strings and this method returns @c + wxGRID_VALUE_STRING. + */ + virtual wxString GetTypeName(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 true if the value of the given cell can be accessed as if it + were of the specified type. - /** - get the currently used attr provider (may be @NULL) - */ - wxGridCellAttrProvider* GetAttrProvider() const; + 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. - */ - wxString GetColLabelValue(int col); + @see CanGetValueAs() + */ + virtual bool CanSetValueAs(int row, int col, const wxString& typeName); /** + Returns the value of the given cell as a long. - */ - int GetNumberCols(); + 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); /** - You must override these functions in a derived table class. - */ - int GetNumberRows(); + Returns the value of the given cell as a double. + + 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); /** + Returns the value of the given cell as a boolean. - */ - wxString GetRowLabelValue(int row); + 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); /** - Data type determination and value access. - */ - wxString GetTypeName(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 GetValue(int row, int col); /** + Sets the value of the given cell as a long. - */ - bool GetValueAsBool(int row, int col); + 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); /** - For user defined types - */ - void* GetValueAsCustom(int row, int col, - const wxString& typeName); + 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. - */ - double GetValueAsDouble(int row, int col); + 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 ); /** + Sets the value of the given cell as a user-defined type. - */ - long GetValueAsLong(int row, int col); + 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); + + //@} /** + Called by the grid when the table is associated with it. - */ - wxGrid* GetView() const; + 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; - */ - bool InsertCols(size_t pos = 0, size_t numCols = 1); /** + Modifying the table structure. - */ - bool InsertRows(size_t pos = 0, size_t numRows = 1); + 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. - */ - bool IsEmptyCell(int row, int col); + This method is used by wxGrid::ClearGrid(). + */ + virtual void Clear(); /** - these functions take ownership of the pointer - */ - void SetAttr(wxGridCellAttr* attr, int row, int col); + Insert additional rows into the table. - /** - Attribute handling - give us the attr provider to use - we take ownership of the pointer - */ - void SetAttrProvider(wxGridCellAttrProvider* attrProvider); + @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. - */ - void SetColAttr(wxGridCellAttr* attr, int col); + 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); /** - , @e wxString) - */ - void SetColLabelValue() const; + Delete rows from the table. + + @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); + + /// 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. - */ - void SetRowAttr(wxGridCellAttr* attr, int row); + 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, ... + */ + //@{ + + /// Return the label of the specified row. + virtual wxString GetRowLabelValue(int row); + + /// Return the label of the specified column. + virtual wxString GetColLabelValue(int col); /** - , @e wxString) - */ - void SetRowLabelValue() const; + 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); + + //@} + /** + 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); + + //@} }; @@ -323,7 +492,7 @@ public: /** Final cleanup. */ - void Destroy(); + virtual void Destroy(); /** Complete the editing of the current cell. Returns @true if the value has @@ -335,7 +504,7 @@ public: Some types of controls on some platforms may need some help with the Return key. */ - void HandleReturn(wxKeyEvent& event); + virtual void HandleReturn(wxKeyEvent& event); /** @@ -357,26 +526,26 @@ public: /** Size and position the edit control. */ - void SetSize(const wxRect& rect); + virtual void SetSize(const wxRect& rect); /** Show or hide the edit control, use the specified attributes to set colours/fonts for it. */ - void Show(bool show, wxGridCellAttr* attr = NULL); + virtual void Show(bool show, wxGridCellAttr* attr = NULL); /** If the editor is enabled by clicking on the cell, this method will be called. */ - void StartingClick(); + virtual void StartingClick(); /** If the editor is enabled by pressing keys on the grid, this will be called to let the editor do something about that first key if desired. */ - void StartingKey(wxKeyEvent& event); + virtual void StartingKey(wxKeyEvent& event); }; @@ -404,7 +573,7 @@ public: The parameters string format is "n" where n is a number representing the maximum width. */ - void SetParameters(const wxString& params); + virtual void SetParameters(const wxString& params); }; @@ -465,7 +634,7 @@ public: /** Parameters string format is "item1[,item2[...,itemN]]" */ - void SetParameters(const wxString& params); + virtual void SetParameters(const wxString& params); }; @@ -688,7 +857,7 @@ public: /** Parameters string format is "min,max". */ - void SetParameters(const wxString& params); + virtual void SetParameters(const wxString& params); }; @@ -987,7 +1156,7 @@ public: /** Column at which the event occurred. */ - int GetCol(); + virtual int GetCol(); /** Position in pixels at which the event occurred. @@ -997,7 +1166,7 @@ public: /** Row at which the event occurred. */ - int GetRow(); + virtual int GetRow(); /** Returns @true if the Meta key was down at the time of the event. @@ -1043,7 +1212,7 @@ public: /** Parameters string format is "width,precision" */ - void SetParameters(const wxString& params); + virtual void SetParameters(const wxString& params); }; @@ -1486,7 +1655,7 @@ public: without (yet) matching calls to EndBatch(). While the grid's batch count is greater than zero the display will not be updated. */ - int GetBatchCount() const; + int GetBatchCount(); /** Sets the arguments to the horizontal and vertical text alignment values @@ -1568,7 +1737,7 @@ public: See GetRowGridLinePen() for an example. */ - wxPen GetColGridLinePen(int col); + virtual wxPen GetColGridLinePen(int col); /** Sets the arguments to the current column label alignment values. @@ -1718,7 +1887,7 @@ public: @see GetColGridLinePen(), GetRowGridLinePen() */ - wxPen GetDefaultGridLinePen(); + virtual wxPen GetDefaultGridLinePen(); /** Returns a pointer to the current default grid cell renderer. @@ -1837,7 +2006,7 @@ public: } @endcode */ - wxPen GetRowGridLinePen(int row); + virtual wxPen GetRowGridLinePen(int row); /** Returns the alignment used for row labels. @@ -1991,6 +2160,19 @@ public: */ wxGridTableBase *GetTable() const; + //@{ + /** + Make the given cell current and ensure it is visible. + + This method is equivalent to calling MakeCellVisible() and + SetGridCursor() and so, as with the latter, a wxEVT_GRID_SELECT_CELL + event is generated by it and the selected cell doesn't change if the + event is vetoed. + */ + void GoToCell(int row, int col); + void GoToCell(const wxGridCellCoords& coords); + //@} + /** Returns @true if drawing of grid lines is turned on, @false otherwise. */ @@ -2554,12 +2736,22 @@ public: */ void SetDefaultRowSize(int height, bool resizeExistingRows = false); + //@{ /** Set the grid cursor to the specified cell. - This function calls MakeCellVisible(). + The grid cursor indicates the current cell and can be moved by the user + using the arrow keys or the mouse. + + Calling this function generates a wxEVT_GRID_SELECT_CELL event and if + the event handler vetoes this event, the cursor is not moved. + + This function doesn't make the target call visible, use GoToCell() to + do this. */ void SetGridCursor(int row, int col); + void SetGridCursor(const wxGridCellCoords& coords); + //@} /** Sets the colour used to draw grid lines. @@ -2744,6 +2936,27 @@ public: */ int XToEdgeOfCol(int x) const; + //@{ + /** + Translates logical pixel coordinates to the grid cell coordinates. + + Notice that this function expects logical coordinates on input so if + you use this function in a mouse event handler you need to translate + the mouse position, which is expressed in device coordinates, to + logical ones. + + @see XToCol(), YToRow() + */ + + // XYToCell(int, int, wxGridCellCoords&) overload is intentionally + // undocumented, using it is ugly and non-const reference parameters are + // not used in wxWidgets API + + wxGridCellCoords XYToCell(int x, int y) const; + wxGridCellCoords XYToCell(const wxPoint& pos) const; + + //@} + /** Returns the row whose bottom edge is close to the given logical y position.