X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/bb778cae9972d3a3b04fa1d1c05450fd1dd5ee13..60ee01727442e8b364825cd965a3e06c21f07833:/interface/wx/grid.h diff --git a/interface/wx/grid.h b/interface/wx/grid.h index 47a223594c..bd4284dc55 100644 --- a/interface/wx/grid.h +++ b/interface/wx/grid.h @@ -12,7 +12,7 @@ This class may be used to format floating point data in a cell. @library{wxadv} - @category{FIXME} + @category{grid} @see wxGridCellRenderer, wxGridCellNumberRenderer, wxGridCellStringRenderer, wxGridCellBoolRenderer @@ -29,27 +29,27 @@ public: wxGridCellFloatRenderer(int width = -1, int precision = -1); /** - Returns the precision ( see @ref constr() wxGridCellFloatRenderer ). + Returns the precision. */ int GetPrecision() const; /** - Returns the width ( see @ref constr() wxGridCellFloatRenderer ). + Returns the width. */ int GetWidth() const; /** Parameters string format is "width[,precision]". */ - void SetParameters(const wxString& params); + virtual void SetParameters(const wxString& params); /** - Sets the precision ( see @ref constr() wxGridCellFloatRenderer ). + Sets the precision. */ void SetPrecision(int precision); /** - Sets the width ( see @ref constr() wxGridCellFloatRenderer ) + Sets the width. */ void SetWidth(int width); }; @@ -59,218 +59,387 @@ 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{FIXME} + @category{grid} */ 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); + + //@} }; @@ -285,7 +454,7 @@ public: even for the entire grid. @library{wxadv} - @category{FIXME} + @category{grid} @see wxGridCellTextEditor, wxGridCellFloatEditor, wxGridCellBoolEditor, wxGridCellNumberEditor, wxGridCellChoiceEditor @@ -301,7 +470,7 @@ public: /** The dtor is private because only DecRef() can delete us. */ - ~wxGridCellEditor(); + virtual ~wxGridCellEditor(); /** Fetch the value from the table and prepare the edit control @@ -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); }; @@ -387,7 +556,7 @@ public: The editor for string/text data. @library{wxadv} - @category{FIXME} + @category{grid} @see wxGridCellEditor, wxGridCellFloatEditor, wxGridCellBoolEditor, wxGridCellNumberEditor, wxGridCellChoiceEditor @@ -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); }; @@ -416,7 +585,7 @@ public: for string cells. @library{wxadv} - @category{FIXME} + @category{grid} @see wxGridCellRenderer, wxGridCellNumberRenderer, wxGridCellFloatRenderer, wxGridCellBoolRenderer @@ -438,7 +607,7 @@ public: The editor for string data allowing to choose from a list of strings. @library{wxadv} - @category{FIXME} + @category{grid} @see wxGridCellEditor, wxGridCellFloatEditor, wxGridCellBoolEditor, wxGridCellTextEditor, wxGridCellNumberEditor @@ -465,7 +634,7 @@ public: /** Parameters string format is "item1[,item2[...,itemN]]" */ - void SetParameters(const wxString& params); + virtual void SetParameters(const wxString& params); }; @@ -475,7 +644,7 @@ public: @library{wxadv} - @category{FIXME} + @category{grid} */ class wxGridEditorCreatedEvent : public wxCommandEvent { @@ -530,7 +699,7 @@ public: @library{wxadv} - @category{FIXME} + @category{grid} */ class wxGridRangeSelectEvent : public wxNotifyEvent { @@ -554,12 +723,12 @@ public: /** Returns @true if the Alt key was down at the time of the event. */ - bool AltDown(); + bool AltDown() const; /** Returns @true if the Control key was down at the time of the event. */ - bool ControlDown(); + bool ControlDown() const; /** Top left corner of the rectangular area that was (de)selected. @@ -594,7 +763,7 @@ public: /** Returns @true if the Meta key was down at the time of the event. */ - bool MetaDown(); + bool MetaDown() const; /** Returns @true if the area was selected, @false otherwise. @@ -604,7 +773,7 @@ public: /** Returns @true if the Shift key was down at the time of the event. */ - bool ShiftDown(); + bool ShiftDown() const; }; @@ -620,7 +789,7 @@ public: predefined derived classes or derive your own class from it. @library{wxadv} - @category{FIXME} + @category{grid} @see wxGridCellStringRenderer, wxGridCellNumberRenderer, wxGridCellFloatRenderer, wxGridCellBoolRenderer @@ -660,7 +829,7 @@ public: The editor for numeric integer data. @library{wxadv} - @category{FIXME} + @category{grid} @see wxGridCellEditor, wxGridCellFloatEditor, wxGridCellBoolEditor, wxGridCellTextEditor, wxGridCellChoiceEditor @@ -688,7 +857,7 @@ public: /** Parameters string format is "min,max". */ - void SetParameters(const wxString& params); + virtual void SetParameters(const wxString& params); }; @@ -699,7 +868,7 @@ public: This event class contains information about a row/column resize event. @library{wxadv} - @category{FIXME} + @category{grid} */ class wxGridSizeEvent : public wxNotifyEvent { @@ -722,12 +891,12 @@ public: /** Returns @true if the Alt key was down at the time of the event. */ - bool AltDown(); + bool AltDown() const; /** Returns @true if the Control key was down at the time of the event. */ - bool ControlDown(); + bool ControlDown() const; /** Position in pixels at which the event occurred. @@ -742,12 +911,12 @@ public: /** Returns @true if the Meta key was down at the time of the event. */ - bool MetaDown(); + bool MetaDown() const; /** Returns @true if the Shift key was down at the time of the event. */ - bool ShiftDown(); + bool ShiftDown() const; }; @@ -758,7 +927,7 @@ public: This class may be used to format integer data in a cell. @library{wxadv} - @category{FIXME} + @category{grid} @see wxGridCellRenderer, wxGridCellStringRenderer, wxGridCellFloatRenderer, wxGridCellBoolRenderer @@ -782,7 +951,7 @@ public: class may be returned by wxGridTableBase::GetAttr. @library{wxadv} - @category{FIXME} + @category{grid} */ class wxGridCellAttr { @@ -932,7 +1101,7 @@ public: for string cells. @library{wxadv} - @category{FIXME} + @category{grid} @see wxGridCellRenderer, wxGridCellStringRenderer, wxGridCellFloatRenderer, wxGridCellNumberRenderer @@ -954,7 +1123,7 @@ public: This event class contains information about various grid events. @library{wxadv} - @category{FIXME} + @category{grid} */ class wxGridEvent : public wxNotifyEvent { @@ -977,17 +1146,17 @@ public: /** Returns @true if the Alt key was down at the time of the event. */ - bool AltDown(); + bool AltDown() const; /** Returns @true if the Control key was down at the time of the event. */ - bool ControlDown(); + bool ControlDown() const; /** Column at which the event occurred. */ - int GetCol(); + virtual int GetCol(); /** Position in pixels at which the event occurred. @@ -997,12 +1166,12 @@ 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. */ - bool MetaDown(); + bool MetaDown() const; /** Returns @true if the user is selecting grid cells, @false -- if @@ -1013,7 +1182,7 @@ public: /** Returns @true if the Shift key was down at the time of the event. */ - bool ShiftDown(); + bool ShiftDown() const; }; @@ -1024,7 +1193,7 @@ public: The editor for floating point numbers data. @library{wxadv} - @category{FIXME} + @category{grid} @see wxGridCellEditor, wxGridCellNumberEditor, wxGridCellBoolEditor, wxGridCellTextEditor, wxGridCellChoiceEditor @@ -1043,7 +1212,7 @@ public: /** Parameters string format is "width,precision" */ - void SetParameters(const wxString& params); + virtual void SetParameters(const wxString& params); }; @@ -1052,96 +1221,163 @@ public: @class wxGrid wxGrid and its related classes are used for displaying and editing tabular - data. They provide a rich set of features for display, editing, and - interacting with a variety of data sources. For simple applications, and to - help you get started, wxGrid is the only class you need to refer to - directly. It will set up default instances of the other classes and manage - them for you. For more complex applications you can derive your own - classes for custom grid views, grid data tables, cell editors and - renderers. The @ref overview_gridoverview has - examples of simple and more complex applications, explains the - relationship between the various grid classes and has a summary of the - keyboard shortcuts and mouse functions provided by wxGrid. - - wxGrid has been greatly expanded and redesigned for wxWidgets 2.2 - onwards. The new grid classes are reasonably backward-compatible - but there are some exceptions. There are also easier ways of doing many things - compared to - the previous implementation. - - A wxGridTableBase class holds the actual - data to be displayed by a wxGrid class. One or more wxGrid classes - may act as a view for one table class. - The default table class is called wxGridStringTable and - holds an array of strings. An instance of such a class is created - by wxGrid::CreateGrid. - - wxGridCellRenderer is the abstract base - class for rendereing contents in a cell. The following renderers are - predefined: - wxGridCellStringRenderer, - wxGridCellBoolRenderer, - wxGridCellFloatRenderer, - wxGridCellNumberRenderer. The - look of a cell can be further defined using wxGridCellAttr. - An object of this type may be returned by wxGridTableBase::GetAttr. - - wxGridCellEditor is the abstract base - class for editing the value of a cell. The following editors are - predefined: - wxGridCellTextEditor - wxGridCellBoolEditor - wxGridCellChoiceEditor - wxGridCellNumberEditor. + data. + They provide a rich set of features for display, editing, and interacting + with a variety of data sources. For simple applications, and to help you + get started, wxGrid is the only class you need to refer to directly. It + will set up default instances of the other classes and manage them for you. + For more complex applications you can derive your own classes for custom + grid views, grid data tables, cell editors and renderers. The @ref + overview_grid "wxGrid overview" has examples of simple and more complex applications, + explains the relationship between the various grid classes and has a + summary of the keyboard shortcuts and mouse functions provided by wxGrid. + + wxGrid has been greatly expanded and redesigned for wxWidgets 2.2 onwards. + The new grid classes are reasonably backward-compatible but there are some + exceptions. There are also easier ways of doing many things compared to the + previous implementation. + + A wxGridTableBase class holds the actual data to be displayed by a wxGrid + class. One or more wxGrid classes may act as a view for one table class. + The default table class is called wxGridStringTable and holds an array of + strings. An instance of such a class is created by wxGrid::CreateGrid. + + wxGridCellRenderer is the abstract base class for rendereing contents in a + cell. The following renderers are predefined: + - wxGridCellStringRenderer, + - wxGridCellBoolRenderer, + - wxGridCellFloatRenderer, + - wxGridCellNumberRenderer. + The look of a cell can be further defined using wxGridCellAttr. An object + of this type may be returned by wxGridTableBase::GetAttr. + + wxGridCellEditor is the abstract base class for editing the value of a + cell. The following editors are predefined: + - wxGridCellTextEditor + - wxGridCellBoolEditor + - wxGridCellChoiceEditor + - wxGridCellNumberEditor. @library{wxadv} - @category{miscwnd} + @category{grid} - @see @ref overview_gridoverview "wxGrid overview" + @see @ref overview_grid "wxGrid overview" */ class wxGrid : public wxScrolledWindow { public: - //@{ /** - Constructor to create a grid object. Call either CreateGrid() or - SetTable() directly after this to initialize the grid before using - it. - */ + Different selection modes supported by the grid. + */ + enum wxGridSelectionModes + { + /** + The default selection mode allowing selection of the individual + cells as well as of the entire rows and columns. + */ + wxGridSelectCells, + + /** + The selection mode allowing the selection of the entire rows only. + + The user won't be able to select any cells or columns in this mode. + */ + wxGridSelectRows, + + /** + The selection mode allowing the selection of the entire columns only. + + The user won't be able to select any cells or rows in this mode. + */ + wxGridSelectColumns + }; + + /** + Default constructor. + + You must call Create() to really create the grid window and also call + CreateGrid() or SetTable() to initialize the grid contents. + */ wxGrid(); - wxGrid(wxWindow* parent, wxWindowID id, + + /** + Constructor creating the grid window. + + You must call either CreateGrid() or SetTable() to initialize the grid + contents before using it. + */ + wxGrid(wxWindow* parent, + wxWindowID id, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxWANTS_CHARS, - const wxString& name = wxPanelNameStr); - //@} + const wxString& name = wxGridNameStr); + + /** + Creates the grid window for an object initialized using the default + constructor. + + You must call either CreateGrid() or SetTable() to initialize the grid + contents before using it. + */ + bool Create(wxWindow* parent, + wxWindowID id, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxWANTS_CHARS, + const wxString& name = wxGridNameStr); /** - Destructor. This will also destroy the associated grid table unless you passed - a table - object to the grid and specified that the grid should not take ownership of the - table (see wxGrid::SetTable). + Destructor. + + This will also destroy the associated grid table unless you passed a + table object to the grid and specified that the grid should not take + ownership of the table (see wxGrid::SetTable). */ - ~wxGrid(); + virtual ~wxGrid(); /** - Appends one or more new columns to the right of the grid and returns @true if - successful. The updateLabels argument is not used at present. - If you are using a derived grid table class you will need to override - wxGridTableBase::AppendCols. See - InsertCols() for further information. + Appends one or more new columns to the right of the grid. + + The @a updateLabels argument is not used at present. If you are using a + derived grid table class you will need to override + wxGridTableBase::AppendCols. See InsertCols() for further information. + + @return @true on success or @false if appending columns failed. */ bool AppendCols(int numCols = 1, bool updateLabels = true); /** - Appends one or more new rows to the bottom of the grid and returns @true if - successful. The updateLabels argument is not used at present. - If you are using a derived grid table class you will need to override - wxGridTableBase::AppendRows. See - InsertRows() for further information. + Appends one or more new rows to the bottom of the grid. + + The @a updateLabels argument is not used at present. If you are using a + derived grid table class you will need to override + wxGridTableBase::AppendRows. See InsertRows() for further information. + + @return @true on success or @false if appending rows failed. */ bool AppendRows(int numRows = 1, bool updateLabels = true); + /** + Return @true if the horizontal grid lines stop at the last column + boundary or @false if they continue to the end of the window. + + The default is to clip grid lines. + + @see ClipHorzGridLines(), AreVertGridLinesClipped() + */ + bool AreHorzGridLinesClipped() const; + + /** + Return @true if the vertical grid lines stop at the last row + boundary or @false if they continue to the end of the window. + + The default is to clip grid lines. + + @see ClipVertGridLines(), AreHorzGridLinesClipped() + */ + bool AreVertGridLinesClipped() const; + /** Automatically sets the height and width of all rows and columns to fit their contents. @@ -1187,140 +1423,99 @@ public: void AutoSizeRows(bool setAsMin = true); /** - AutoSizeColumn() - - AutoSizeRow() - - AutoSizeColumns() - - AutoSizeRows() - - AutoSize() + Increments the grid's batch count. - SetColMinimalWidth() + When the count is greater than zero repainting of the grid is + suppressed. Each call to BeginBatch must be matched by a later call to + EndBatch(). Code that does a lot of grid modification can be enclosed + between BeginBatch and EndBatch calls to avoid screen flicker. The + final EndBatch will cause the grid to be repainted. - SetRowMinimalHeight() - - SetColMinimalAcceptableWidth() - - SetRowMinimalAcceptableHeight() - - GetColMinimalAcceptableWidth() - - GetRowMinimalAcceptableHeight() - */ - - - /** - Increments the grid's batch count. When the count is greater than zero - repainting of - the grid is suppressed. Each call to BeginBatch must be matched by a later call - to - EndBatch(). Code that does a lot of grid - modification can be enclosed between BeginBatch and EndBatch calls to avoid - screen flicker. The final EndBatch will cause the grid to be repainted. - - @see wxGridUpdateLocker + Notice that you should use wxGridUpdateLocker which ensures that there + is always a matching EndBatch() call for this BeginBatch() if possible + instead of calling this method directly. */ void BeginBatch(); /** + Convert grid cell coordinates to grid window pixel coordinates. + This function returns the rectangle that encloses the block of cells - limited by TopLeft and BottomRight cell in device coords and clipped - to the client size of the grid window. + limited by @a topLeft and @a bottomRight cell in device coords and + clipped to the client size of the grid window. + + @see CellToRect() */ wxRect BlockToDeviceRect(const wxGridCellCoords& topLeft, const wxGridCellCoords& bottomRight) const; /** - Returns @true if columns can be moved by dragging with the mouse. Columns can be - moved - by dragging on their labels. + Returns @true if columns can be moved by dragging with the mouse. + + Columns can be moved by dragging on their labels. */ bool CanDragColMove() const; /** - Returns @true if columns can be resized by dragging with the mouse. Columns can - be resized - by dragging the edges of their labels. If grid line dragging is enabled they - can also be - resized by dragging the right edge of the column in the grid cell area - (see wxGrid::EnableDragGridSize). + Returns @true if columns can be resized by dragging with the mouse. + + Columns can be resized by dragging the edges of their labels. If grid + line dragging is enabled they can also be resized by dragging the right + edge of the column in the grid cell area (see + wxGrid::EnableDragGridSize). */ bool CanDragColSize() const; /** - Return @true if the dragging of grid lines to resize rows and columns is enabled - or @false otherwise. + Return @true if the dragging of grid lines to resize rows and columns + is enabled or @false otherwise. */ bool CanDragGridSize() const; /** - Returns @true if rows can be resized by dragging with the mouse. Rows can be - resized - by dragging the edges of their labels. If grid line dragging is enabled they - can also be - resized by dragging the lower edge of the row in the grid cell area - (see wxGrid::EnableDragGridSize). + Returns @true if rows can be resized by dragging with the mouse. + + Rows can be resized by dragging the edges of their labels. If grid line + dragging is enabled they can also be resized by dragging the lower edge + of the row in the grid cell area (see wxGrid::EnableDragGridSize). */ bool CanDragRowSize() const; /** - Returns @true if the in-place edit control for the current grid cell can be used - and - @false otherwise (e.g. if the current cell is read-only). - */ - bool CanEnableCellControl() const; + Returns @true if the in-place edit control for the current grid cell + can be used and @false otherwise. - /** - Do we have some place to store attributes in? + This function always returns @false for the read-only cells. */ - bool CanHaveAttributes() const; + bool CanEnableCellControl() const; /** - EnableDragRowSize() - - EnableDragColSize() - - CanDragRowSize() - - CanDragColSize() - - EnableDragColMove() - - CanDragColMove() - - EnableDragGridSize() - - CanDragGridSize() - - GetColAt() - - SetColPos() - - GetColPos() + Returns @true if this grid has support for cell attributes. - EnableDragCell() - - CanDragCell() + The grid supports attributes if it has the associated table which, in + turn, has attributes support, i.e. wxGridTableBase::CanHaveAttributes() + returns @true. */ - + bool CanHaveAttributes() const; //@{ /** - Return the rectangle corresponding to the grid cell's size and position in - logical - coordinates. + Return the rectangle corresponding to the grid cell's size and position + in logical coordinates. + + @see BlockToDeviceRect() */ wxRect CellToRect(int row, int col) const; - const wxRect CellToRect(const wxGridCellCoords& coords) const; + const wxRect CellToRect(const wxGridCellCoords& coords) const; + //@} /** - Clears all data in the underlying grid table and repaints the grid. The table - is not deleted by - this function. If you are using a derived table class then you need to override - wxGridTableBase::Clear for this function to have any effect. + Clears all data in the underlying grid table and repaints the grid. + + The table is not deleted by this function. If you are using a derived + table class then you need to override wxGridTableBase::Clear() for this + function to have any effect. */ void ClearGrid(); @@ -1330,18 +1525,32 @@ public: void ClearSelection(); /** - @ref ctor() wxGrid + Change whether the horizontal grid lines are clipped by the end of the + last column. - @ref dtor() ~wxGrid + By default the grid lines are not drawn beyond the end of the last + column but after calling this function with @a clip set to @false they + will be drawn across the entire grid window. - CreateGrid() + @see AreHorzGridLinesClipped(), ClipVertGridLines() + */ + void ClipHorzGridLines(bool clip); - SetTable() - */ + /** + Change whether the vertical grid lines are clipped by the end of the + last row. + + By default the grid lines are not drawn beyond the end of the last + row but after calling this function with @a clip set to @false they + will be drawn across the entire grid window. + @see AreVertzGridLinesClipped(), ClipHorzGridLines() + */ + void ClipVertzGridLines(bool clip); /** Creates a grid with the specified initial number of rows and columns. + Call this directly after the grid constructor. When you use this function wxGrid will create and manage a simple table of string values for you. All of the grid data will be stored in memory. @@ -1350,90 +1559,71 @@ public: class and pass a table object to the grid with SetTable(). */ bool CreateGrid(int numRows, int numCols, - wxGrid::wxGridSelectionModes selmode = wxGrid::wxGridSelectCells); + wxGridSelectionModes selmode = wxGridSelectCells); /** - MoveCursorUp() - - MoveCursorDown() - - MoveCursorLeft() - - MoveCursorRight() - - MoveCursorPageUp() - - MoveCursorPageDown() - - MoveCursorUpBlock() - - MoveCursorDownBlock() + Deletes one or more columns from a grid starting at the specified + position. - MoveCursorLeftBlock() + The @a updateLabels argument is not used at present. If you are using a + derived grid table class you will need to override + wxGridTableBase::DeleteCols. See InsertCols() for further information. - MoveCursorRightBlock() + @return @true on success or @false if deleting columns failed. */ - + bool DeleteCols(int pos = 0, int numCols = 1, bool updateLabels = true); /** - Deletes one or more columns from a grid starting at the specified position and - returns - @true if successful. The updateLabels argument is not used at present. - If you are using a derived grid table class you will need to override - wxGridTableBase::DeleteCols. See - InsertCols() for further information. - */ - bool DeleteCols(int pos = 0, int numCols = 1, - bool updateLabels = true); + Deletes one or more rows from a grid starting at the specified position. - /** - Deletes one or more rows from a grid starting at the specified position and - returns - @true if successful. The updateLabels argument is not used at present. - If you are using a derived grid table class you will need to override - wxGridTableBase::DeleteRows. See - InsertRows() for further information. + The @a updateLabels argument is not used at present. If you are using a + derived grid table class you will need to override + wxGridTableBase::DeleteRows. See InsertRows() for further information. + + @return @true on success or @false if appending rows failed. */ - bool DeleteRows(int pos = 0, int numRows = 1, - bool updateLabels = true); + bool DeleteRows(int pos = 0, int numRows = 1, bool updateLabels = true); /** Disables in-place editing of grid cells. + Equivalent to calling EnableCellEditControl(@false). */ void DisableCellEditControl(); /** - Disables column moving by dragging with the mouse. Equivalent to passing @false - to - EnableDragColMove(). + Disables column moving by dragging with the mouse. + + Equivalent to passing @false to EnableDragColMove(). */ void DisableDragColMove(); /** - Disables column sizing by dragging with the mouse. Equivalent to passing @false - to - EnableDragColSize(). + Disables column sizing by dragging with the mouse. + + Equivalent to passing @false to EnableDragColSize(). */ void DisableDragColSize(); /** - Disable mouse dragging of grid lines to resize rows and columns. Equivalent to - passing - @false to EnableDragGridSize() + Disable mouse dragging of grid lines to resize rows and columns. + + Equivalent to passing @false to EnableDragGridSize() */ void DisableDragGridSize(); /** - Disables row sizing by dragging with the mouse. Equivalent to passing @false to - EnableDragRowSize(). + Disables row sizing by dragging with the mouse. + + Equivalent to passing @false to EnableDragRowSize(). */ void DisableDragRowSize(); /** - Enables or disables in-place editing of grid cell data. The grid will issue - either a - wxEVT_GRID_EDITOR_SHOWN or wxEVT_GRID_EDITOR_HIDDEN event. + Enables or disables in-place editing of grid cell data. + + The grid will issue either a wxEVT_GRID_EDITOR_SHOWN or + wxEVT_GRID_EDITOR_HIDDEN event. */ void EnableCellEditControl(bool enable = true); @@ -1459,19 +1649,18 @@ public: void EnableDragRowSize(bool enable = true); /** - If the edit argument is @false this function sets the whole grid as read-only. - If the - argument is @true the grid is set to the default state where cells may be - editable. In the - default state you can set single grid cells and whole rows and columns to be - editable or - read-only via - wxGridCellAttribute::SetReadOnly. For single - cells you can also use the shortcut function - SetReadOnly(). + Makes the grid globally editable or read-only. + + If the edit argument is @false this function sets the whole grid as + read-only. If the argument is @true the grid is set to the default + state where cells may be editable. In the default state you can set + single grid cells and whole rows and columns to be editable or + read-only via wxGridCellAttribute::SetReadOnly. For single cells you + can also use the shortcut function SetReadOnly(). + For more information about controlling grid cell attributes see the wxGridCellAttr cell attribute class and the - @ref overview_gridoverview. + @ref overview_grid "wxGrid overview". */ void EnableEditing(bool edit); @@ -1481,13 +1670,13 @@ public: void EnableGridLines(bool enable = true); /** - Decrements the grid's batch count. When the count is greater than zero - repainting of - the grid is suppressed. Each previous call to - BeginBatch() must be matched by a later call to - EndBatch. Code that does a lot of grid modification can be enclosed between - BeginBatch and EndBatch calls to avoid screen flicker. The final EndBatch will - cause the grid to be repainted. + Decrements the grid's batch count. + + When the count is greater than zero repainting of the grid is + suppressed. Each previous call to BeginBatch() must be matched by a + later call to EndBatch. Code that does a lot of grid modification can + be enclosed between BeginBatch and EndBatch calls to avoid screen + flicker. The final EndBatch will cause the grid to be repainted. @see wxGridUpdateLocker */ @@ -1499,8 +1688,9 @@ public: void Fit(); /** - Causes immediate repainting of the grid. Use this instead of the usual - wxWindow::Refresh. + Causes immediate repainting of the grid. + + Use this instead of the usual wxWindow::Refresh. */ void ForceRefresh(); @@ -1509,15 +1699,17 @@ 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 for the - grid cell at the specified location. - Horizontal alignment will be one of wxALIGN_LEFT, wxALIGN_CENTRE or - wxALIGN_RIGHT. + Sets the arguments to the horizontal and vertical text alignment values + for the grid cell at the specified location. + + Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE + or @c wxALIGN_RIGHT. - Vertical alignment will be one of wxALIGN_TOP, wxALIGN_CENTRE or wxALIGN_BOTTOM. + Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or + @c wxALIGN_BOTTOM. */ void GetCellAlignment(int row, int col, int* horiz, int* vert) const; @@ -1528,9 +1720,11 @@ public: /** Returns a pointer to the editor for the cell at the specified location. - See wxGridCellEditor and - the @ref overview_gridoverview "wxGrid overview" for more information about - cell editors and renderers. + + See wxGridCellEditor and the @ref overview_grid "wxGrid overview" + for more information about cell editors and renderers. + + The caller must call DecRef() on the returned pointer. */ wxGridCellEditor* GetCellEditor(int row, int col) const; @@ -1540,10 +1734,13 @@ public: wxFont GetCellFont(int row, int col) const; /** - Returns a pointer to the renderer for the grid cell at the specified location. - See wxGridCellRenderer and - the @ref overview_gridoverview "wxGrid overview" for more information about - cell editors and renderers. + Returns a pointer to the renderer for the grid cell at the specified + location. + + See wxGridCellRenderer and the @ref overview_grid "wxGrid overview" + for more information about cell editors and renderers. + + The caller must call DecRef() on the returned pointer. */ wxGridCellRenderer* GetCellRenderer(int row, int col) const; @@ -1554,18 +1751,17 @@ public: //@{ /** - Returns the string contained in the cell at the specified location. For simple - applications where a - grid object automatically uses a default grid table of string values you use - this function together - with SetCellValue() to access cell values. - For more complex applications where you have derived your own grid table class - that contains - various data types (e.g. numeric, boolean or user-defined custom types) then - you only use this - function for those cells that contain string values. - See wxGridTableBase::CanGetValueAs - and the @ref overview_gridoverview "wxGrid overview" for more information. + Returns the string contained in the cell at the specified location. + + For simple applications where a grid object automatically uses a + default grid table of string values you use this function together with + SetCellValue() to access cell values. For more complex applications + where you have derived your own grid table class that contains various + data types (e.g. numeric, boolean or user-defined custom types) then + you only use this function for those cells that contain string values. + + See wxGridTableBase::CanGetValueAs and the @ref overview_grid "wxGrid overview" + for more information. */ wxString GetCellValue(int row, int col) const; const wxString GetCellValue(const wxGridCellCoords& coords) const; @@ -1577,19 +1773,24 @@ public: int GetColAt(int colPos) const; /** - Returns the pen used for vertical grid lines. This virtual function may be - overridden in derived classes in order to change the appearance of individual - grid lines for the given column @e col. + Returns the pen used for vertical grid lines. + + This virtual function may be overridden in derived classes in order to + change the appearance of individual grid lines for the given column @e + col. + See GetRowGridLinePen() for an example. */ - wxPen GetColGridLinePen(int col); + virtual wxPen GetColGridLinePen(int col); /** Sets the arguments to the current column label alignment values. - Horizontal alignment will be one of wxALIGN_LEFT, wxALIGN_CENTRE or - wxALIGN_RIGHT. - Vertical alignment will be one of wxALIGN_TOP, wxALIGN_CENTRE or wxALIGN_BOTTOM. + 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. */ void GetColLabelAlignment(int* horiz, int* vert) const; @@ -1599,29 +1800,33 @@ public: int GetColLabelSize() const; /** - Returns the specified column label. The default grid table class provides - column labels of - the form A,B...Z,AA,AB...ZZ,AAA... If you are using a custom grid table you can - override - wxGridTableBase::GetColLabelValue to provide - your own labels. + Returns the specified column label. + + The default grid table class provides column labels of the form + A,B...Z,AA,AB...ZZ,AAA... If you are using a custom grid table you can + override wxGridTableBase::GetColLabelValue to provide your own labels. */ wxString GetColLabelValue(int col) const; /** - + Returns the coordinate of the left border specified column. */ int GetColLeft(int col) const; /** - This returns the value of the lowest column width that can be handled - correctly. See - member SetColMinimalAcceptableWidth() for details. + Returns the minimal width to which a column may be resized. + + Use SetColMinimalAcceptableWidth() to change this value globally or + SetColMinimalWidth() to do it for individual columns. */ int GetColMinimalAcceptableWidth() const; /** Get the minimal width of the given column/row. + + The value returned by this function may be different than that returned + by GetColMinimalAcceptableWidth() if SetColMinimalWidth() had been + called for this column. */ int GetColMinimalWidth(int col) const; @@ -1631,7 +1836,7 @@ public: int GetColPos(int colID) const; /** - + Returns the coordinate of the right border specified column. */ int GetColRight(int col) const; @@ -1641,12 +1846,15 @@ public: int GetColSize(int col) const; /** - Sets the arguments to the current default horizontal and vertical text alignment - values. - Horizontal alignment will be one of wxALIGN_LEFT, wxALIGN_CENTRE or - wxALIGN_RIGHT. + Returns the default cell alignment. + + Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE + or @c wxALIGN_RIGHT. - Vertical alignment will be one of wxALIGN_TOP, wxALIGN_CENTRE or wxALIGN_BOTTOM. + Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or + @c wxALIGN_BOTTOM. + + @see SetDefaultCellAlignment() */ void GetDefaultCellAlignment(int* horiz, int* vert) const; @@ -1677,51 +1885,83 @@ public: /** Returns a pointer to the current default grid cell editor. - See wxGridCellEditor and - the @ref overview_gridoverview "wxGrid overview" for more information about - cell editors and renderers. + + See wxGridCellEditor and the @ref overview_grid "wxGrid overview" + for more information about cell editors and renderers. */ wxGridCellEditor* GetDefaultEditor() const; //@{ /** + Returns the default editor for the specified cell. + + The base class version returns the editor appropriate for the current + cell type but this method may be overridden in the derived classes to + use custom editors for some cells by default. + + Notice that the same may be usually achieved in simpler way by + associating a custom editor with the given cell or cells. + The caller must call DecRef() on the returned pointer. */ - wxGridCellEditor* GetDefaultEditorForCell(int row, int col) const; - const wxGridCellEditor* GetDefaultEditorForCell(const wxGridCellCoords& c) const; + virtual wxGridCellEditor* GetDefaultEditorForCell(int row, int col) const; + wxGridCellEditor* GetDefaultEditorForCell(const wxGridCellCoords& c) const; //@} /** + Returns the default editor for the cells containing values of the given + type. + The base class version returns the editor which was associated with the + specified @a typeName when it was registered RegisterDataType() but + this function may be overridden to return something different. This + allows to override an editor used for one of the standard types. + + The caller must call DecRef() on the returned pointer. */ - wxGridCellEditor* GetDefaultEditorForType(const wxString& typeName) const; + virtual wxGridCellEditor * + GetDefaultEditorForType(const wxString& typeName) const; /** - Returns the pen used for grid lines. This virtual function may be overridden in - derived classes in order to change the appearance of grid lines. Note that - currently the pen width must be 1. + Returns the pen used for grid lines. + + This virtual function may be overridden in derived classes in order to + change the appearance of grid lines. Note that currently the pen width + must be 1. @see GetColGridLinePen(), GetRowGridLinePen() */ - wxPen GetDefaultGridLinePen(); + virtual wxPen GetDefaultGridLinePen(); /** Returns a pointer to the current default grid cell renderer. - See wxGridCellRenderer and - the @ref overview_gridoverview "wxGrid overview" for more information about - cell editors and renderers. + + See wxGridCellRenderer and the @ref overview_grid "wxGrid overview" + for more information about cell editors and renderers. + + The caller must call DecRef() on the returned pointer. */ wxGridCellRenderer* GetDefaultRenderer() const; /** + Returns the default renderer for the given cell. + + The base class version returns the renderer appropriate for the current + cell type but this method may be overridden in the derived classes to + use custom renderers for some cells by default. + The caller must call DecRef() on the returned pointer. */ - wxGridCellRenderer* GetDefaultRendererForCell(int row, int col) const; + virtual wxGridCellRenderer *GetDefaultRendererForCell(int row, int col) const; /** + Returns the default renderer for the cell containing values of the + given type. + @see GetDefaultEditorForType() */ - wxGridCellRenderer* GetDefaultRendererForType(const wxString& typeName) const; + virtual wxGridCellRenderer * + GetDefaultRendererForType(const wxString& typeName) const; /** Returns the default width for the row labels. @@ -1766,36 +2006,60 @@ public: wxColour GetLabelTextColour() const; /** - Returns the total number of grid columns (actually the number of columns in the - underlying grid - table). + Returns the total number of grid columns. + + This is the same as the number of columns in the underlying grid + table. */ int GetNumberCols() const; /** - Returns the total number of grid rows (actually the number of rows in the - underlying grid table). + Returns the total number of grid rows. + + This is the same as the number of rows in the underlying grid table. */ int GetNumberRows() const; /** + Returns the attribute for the given cell creating one if necessary. + + If the cell already has an attribute, it is returned. Otherwise a new + attribute is created, associated with the cell and returned. In any + case the caller must call DecRef() on the returned pointer. + This function may only be called if CanHaveAttributes() returns @true. */ - wxGridCellAttr* GetOrCreateCellAttr(int row, int col) const; + wxGridCellAttr *GetOrCreateCellAttr(int row, int col) const; /** - Returns the pen used for horizontal grid lines. This virtual function may be - overridden in derived classes in order to change the appearance of individual - grid line for the given row @e row. + Returns the pen used for horizontal grid lines. + + This virtual function may be overridden in derived classes in order to + change the appearance of individual grid line for the given row @e row. + Example: + @code + // in a grid displaying music notation, use a solid black pen between + // octaves (C0=row 127, C1=row 115 etc.) + wxPen MidiGrid::GetRowGridLinePen(int row) + { + if ( row % 12 == 7 ) + return wxPen(*wxBLACK, 1, wxSOLID); + else + return GetDefaultGridLinePen(); + } + @endcode */ - wxPen GetRowGridLinePen(int row); + virtual wxPen GetRowGridLinePen(int row); /** - Sets the arguments to the current row label alignment values. - Horizontal alignment will be one of wxLEFT, wxCENTRE or wxRIGHT. + Returns the alignment used for row labels. + + Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE + or @c wxALIGN_RIGHT. - Vertical alignment will be one of wxTOP, wxCENTRE or wxBOTTOM. + Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or + @c wxALIGN_BOTTOM. */ void GetRowLabelAlignment(int* horiz, int* vert) const; @@ -1805,23 +2069,30 @@ public: int GetRowLabelSize() const; /** - Returns the specified row label. The default grid table class provides numeric - row labels. - If you are using a custom grid table you can override - wxGridTableBase::GetRowLabelValue to provide - your own labels. + Returns the specified row label. + + The default grid table class provides numeric row labels. If you are + using a custom grid table you can override + wxGridTableBase::GetRowLabelValue to provide your own labels. */ wxString GetRowLabelValue(int row) const; /** - This returns the value of the lowest row width that can be handled correctly. - See - member SetRowMinimalAcceptableHeight() for details. + Returns the minimal size to which rows can be resized. + + Use SetRowMinimalAcceptableHeight() to change this value globally or + SetRowMinimalHeight() to do it for individual cells. + + @see GetColMinimalAcceptableWidth() */ int GetRowMinimalAcceptableHeight() const; /** + Returns the minimal size for the given column. + The value returned by this function may be different than that returned + by GetRowMinimalAcceptableHeight() if SetRowMinimalHeight() had been + called for this row. */ int GetRowMinimalHeight(int col) const; @@ -1831,44 +2102,60 @@ public: int GetRowSize(int row) const; /** - Returns the number of pixels per horizontal scroll increment. The default is 15. + Returns the number of pixels per horizontal scroll increment. + + The default is 15. @see GetScrollLineY(), SetScrollLineX(), SetScrollLineY() */ int GetScrollLineX() const; /** - Returns the number of pixels per vertical scroll increment. The default is 15. + Returns the number of pixels per vertical scroll increment. + + The default is 15. @see GetScrollLineX(), SetScrollLineX(), SetScrollLineY() */ int GetScrollLineY() const; /** - Returns an array of singly selected cells. + Returns an array of individually selected cells. + + Notice that this array does @em not contain all the selected cells in + general as it doesn't include the cells selected as part of column, row + or block selection. You must use this method, GetSelectedCols(), + GetSelectedRows() and GetSelectionBlockTopLeft() and + GetSelectionBlockBottomRight() methods to obtain the entire selection + in general. + + Please notice this behaviour is by design and is needed in order to + support grids of arbitrary size (when an entire column is selected in + a grid with a million of columns, we don't want to create an array with + a million of entries in this function, instead it returns an empty + array and GetSelectedCols() returns an array containing one element). */ wxGridCellCoordsArray GetSelectedCells() const; /** - Returns an array of selected cols. + Returns an array of selected columns. Please notice that this method alone is not sufficient to find all the - selected columns, see the explanation in GetSelectedRows() - documentation for more details. + selected columns as it contains only the columns which were + individually selected but not those being part of the block selection + or being selected in virtue of all of their cells being selected + individually, please see GetSelectedCells() for more details. */ wxArrayInt GetSelectedCols() const; /** Returns an array of selected rows. - Note that this array contains only the rows which were individually - selected (using the mouse with the row header or combinations involving - @c Ctrl key for selecting individual rows). In particular if the user - selects many rows at once (e.g. by pressing @c Shift key) this array is - @b not updated because this could mean storing a very large number of - elements in it. So in general to find the current selection you need to - use both this method and GetSelectionBlockTopLeft() and - GetSelectionBlockBottomRight() ones. + Please notice that this method alone is not sufficient to find all the + selected rows as it contains only the rows which were individually + selected but not those being part of the block selection or being + selected in virtue of all of their cells being selected individually, + please see GetSelectedCells() for more details. */ wxArrayInt GetSelectedRows() const; @@ -1878,53 +2165,57 @@ public: wxColour GetSelectionBackground() const; /** - Returns an array of the bottom right corners of blocks of selected cells, - see GetSelectionBlockTopLeft(). + Returns an array of the bottom right corners of blocks of selected + cells. + + Please see GetSelectedCells() for more information about the selection + representation in wxGrid. + + @see GetSelectionBlockTopLeft() */ wxGridCellCoordsArray GetSelectionBlockBottomRight() const; /** - Returns an array of the top left corners of blocks of selected cells, - see GetSelectionBlockBottomRight(). + Returns an array of the top left corners of blocks of selected cells. + + Please see GetSelectedCells() for more information about the selection + representation in wxGrid. + + @see GetSelectionBlockBottomRight() */ wxGridCellCoordsArray GetSelectionBlockTopLeft() const; /** - + Returns the colour used for drawing the selection foreground. */ wxColour GetSelectionForeground() const; /** - Returns the current selection mode, see SetSelectionMode(). + Returns the current selection mode. + + @see SetSelectionMode(). */ - wxGrid::wxGridSelectionModes GetSelectionMode() const; + wxGridSelectionModes GetSelectionMode() const; /** Returns a base pointer to the current table object. - */ - wxGridTableBase* GetTable() const; - /** - Returned number of whole cols visible. + The returned pointer is still owned by the grid. */ - int GetViewWidth() const; + wxGridTableBase *GetTable() const; + //@{ /** - EnableGridLines() - - GridLinesEnabled() - - SetGridLineColour() - - GetGridLineColour() - - GetDefaultGridLinePen() - - GetRowGridLinePen() - - GetColGridLinePen() - */ + 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. @@ -1944,61 +2235,57 @@ public: void HideColLabels(); /** - Hides the row labels by calling SetRowLabelSize() - with a size of 0. Show labels again by calling that method with - a width greater than 0. + Hides the row labels by calling SetRowLabelSize() with a size of 0. + + The labels can be shown again by calling SetRowLabelSize() with a width + greater than 0. */ void HideRowLabels(); /** - Init the m_colWidths/Rights arrays - */ - void InitColWidths(); + Inserts one or more new columns into a grid with the first new column + at the specified position. - /** - @note @e never access m_row/col arrays directly because they are created - on demand, @e always use accessor functions instead! - Init the m_rowHeights/Bottoms arrays with default values. - */ - void InitRowHeights(); + Notice that inserting the columns in the grid requires grid table + cooperation: when this method is called, grid object begins by + requesting the underlying grid table to insert new columns. If this is + successful the table notifies the grid and the grid updates the + display. For a default grid (one where you have called + wxGrid::CreateGrid) this process is automatic. If you are using a + custom grid table (specified with wxGrid::SetTable) then you must + override wxGridTableBase::InsertCols() in your derived table class. - /** - Inserts one or more new columns into a grid with the first new column at the - specified position and returns @true if successful. The updateLabels argument is - not - used at present. - The sequence of actions begins with the grid object requesting the underlying - grid - table to insert new columns. If this is successful the table notifies the grid - and the - grid updates the display. For a default grid (one where you have called - wxGrid::CreateGrid) this process is automatic. If you are - using a custom grid table (specified with wxGrid::SetTable) - then you must override - wxGridTableBase::InsertCols in your derived - table class. + @param pos + The position which the first newly inserted column will have. + @param numCols + The number of columns to insert. + @param updateLabels + Currently not used. + @return + @true if the columns were successfully inserted, @false if an error + occurred (most likely the table couldn't be updated). */ - bool InsertCols(int pos = 0, int numCols = 1, - bool updateLabels = true); + bool InsertCols(int pos = 0, int numCols = 1, bool updateLabels = true); /** - Inserts one or more new rows into a grid with the first new row at the specified - position and returns @true if successful. The updateLabels argument is not used - at - present. - The sequence of actions begins with the grid object requesting the underlying - grid - table to insert new rows. If this is successful the table notifies the grid and - the - grid updates the display. For a default grid (one where you have called - wxGrid::CreateGrid) this process is automatic. If you are - using a custom grid table (specified with wxGrid::SetTable) - then you must override - wxGridTableBase::InsertRows in your derived - table class. + Inserts one or more new rows into a grid with the first new row at the + specified position. + + Notice that you must implement wxGridTableBase::InsertRows() if you use + a grid with a custom table, please see InsertCols() for more + information. + + @param pos + The position which the first newly inserted row will have. + @param numRows + The number of rows to insert. + @param updateLabels + Currently not used. + @return + @true if the rows were successfully inserted, @false if an error + occurred (most likely the table couldn't be updated). */ - bool InsertRows(int pos = 0, int numRows = 1, - bool updateLabels = true); + bool InsertRows(int pos = 0, int numRows = 1, bool updateLabels = true); /** Returns @true if the in-place edit control is currently enabled. @@ -2006,42 +2293,50 @@ public: bool IsCellEditControlEnabled() const; /** - Returns @true if the current cell has been set to read-only - (see wxGrid::SetReadOnly). + Returns @true if the current cell is read-only. + + @see SetReadOnly(), IsReadOnly() */ bool IsCurrentCellReadOnly() const; /** - Returns @false if the whole grid has been set as read-only or @true otherwise. - See EnableEditing() for more information about - controlling the editing status of grid cells. + Returns @false if the whole grid has been set as read-only or @true + otherwise. + + See EnableEditing() for more information about controlling the editing + status of grid cells. */ bool IsEditable() const; //@{ /** - Is this cell currently selected. + Is this cell currently selected? */ bool IsInSelection(int row, int col) const; - const bool IsInSelection(const wxGridCellCoords& coords) const; + bool IsInSelection(const wxGridCellCoords& coords) const; //@} /** Returns @true if the cell at the specified location can't be edited. - See also IsReadOnly(). + + @see SetReadOnly(), IsCurrentCellReadOnly() */ bool IsReadOnly(int row, int col) const; /** - Returns @true if there are currently rows, columns or blocks of cells selected. + Returns @true if there are currently any selected cells, rows, columns + or blocks. */ bool IsSelection() const; //@{ /** - Returns @true if a cell is either wholly visible (the default) or at least - partially - visible in the grid window. + Returns @true if a cell is either wholly or at least partially visible + in the grid window. + + By default, the cell must be entirely visible for this function to + return true but if @a wholeCellVisible is @false, the function returns + @true even if the cell is only partially visible. */ bool IsVisible(int row, int col, bool wholeCellVisible = true) const; const bool IsVisible(const wxGridCellCoords& coords, @@ -2051,162 +2346,142 @@ public: //@{ /** Brings the specified cell into the visible grid cell area with minimal - scrolling. Does - nothing if the cell is already visible. + scrolling. + + Does nothing if the cell is already visible. */ void MakeCellVisible(int row, int col); void MakeCellVisible(const wxGridCellCoords& coords); //@} /** - Moves the grid cursor down by one row. If a block of cells was previously - selected it - will expand if the argument is @true or be cleared if the argument is @false. + Moves the grid cursor down by one row. + + If a block of cells was previously selected it will expand if the + argument is @true or be cleared if the argument is @false. */ bool MoveCursorDown(bool expandSelection); /** - Moves the grid cursor down in the current column such that it skips to the - beginning or - end of a block of non-empty cells. If a block of cells was previously selected - it - will expand if the argument is @true or be cleared if the argument is @false. + Moves the grid cursor down in the current column such that it skips to + the beginning or end of a block of non-empty cells. + + If a block of cells was previously selected it will expand if the + argument is @true or be cleared if the argument is @false. */ bool MoveCursorDownBlock(bool expandSelection); /** - Moves the grid cursor left by one column. If a block of cells was previously - selected it - will expand if the argument is @true or be cleared if the argument is @false. + Moves the grid cursor left by one column. + + If a block of cells was previously selected it will expand if the + argument is @true or be cleared if the argument is @false. */ bool MoveCursorLeft(bool expandSelection); /** Moves the grid cursor left in the current row such that it skips to the - beginning or - end of a block of non-empty cells. If a block of cells was previously selected - it - will expand if the argument is @true or be cleared if the argument is @false. + beginning or end of a block of non-empty cells. + + If a block of cells was previously selected it will expand if the + argument is @true or be cleared if the argument is @false. */ bool MoveCursorLeftBlock(bool expandSelection); /** - Moves the grid cursor right by one column. If a block of cells was previously - selected it - will expand if the argument is @true or be cleared if the argument is @false. + Moves the grid cursor right by one column. + + If a block of cells was previously selected it will expand if the + argument is @true or be cleared if the argument is @false. */ bool MoveCursorRight(bool expandSelection); /** - Moves the grid cursor right in the current row such that it skips to the - beginning or - end of a block of non-empty cells. If a block of cells was previously selected - it - will expand if the argument is @true or be cleared if the argument is @false. + Moves the grid cursor right in the current row such that it skips to + the beginning or end of a block of non-empty cells. + + If a block of cells was previously selected it will expand if the + argument is @true or be cleared if the argument is @false. */ bool MoveCursorRightBlock(bool expandSelection); /** - Moves the grid cursor up by one row. If a block of cells was previously - selected it - will expand if the argument is @true or be cleared if the argument is @false. + Moves the grid cursor up by one row. + + If a block of cells was previously selected it will expand if the + argument is @true or be cleared if the argument is @false. */ bool MoveCursorUp(bool expandSelection); /** - Moves the grid cursor up in the current column such that it skips to the - beginning or - end of a block of non-empty cells. If a block of cells was previously selected - it - will expand if the argument is @true or be cleared if the argument is @false. + Moves the grid cursor up in the current column such that it skips to + the beginning or end of a block of non-empty cells. + + If a block of cells was previously selected it will expand if the + argument is @true or be cleared if the argument is @false. */ bool MoveCursorUpBlock(bool expandSelection); /** - Moves the grid cursor down by some number of rows so that the previous bottom - visible row - becomes the top visible row. + Moves the grid cursor down by some number of rows so that the previous + bottom visible row becomes the top visible row. */ bool MovePageDown(); /** - Moves the grid cursor up by some number of rows so that the previous top - visible row - becomes the bottom visible row. + Moves the grid cursor up by some number of rows so that the previous + top visible row becomes the bottom visible row. */ bool MovePageUp(); /** - Methods for a registry for mapping data types to Renderers/Editors + Register a new data type. + + The data types allow to naturally associate specific renderers and + editors to the cells containing values of the given type. For example, + the grid automatically registers a data type with the name @c + wxGRID_VALUE_STRING which uses wxGridCellStringRenderer and + wxGridCellTextEditor as its renderer and editor respectively -- this is + the data type used by all the cells of the default wxGridStringTable, + so this renderer and editor are used by default for all grid cells. + + However if a custom table returns @c wxGRID_VALUE_BOOL from its + wxGridTableBase::GetTypeName() method, then wxGridCellBoolRenderer and + wxGridCellBoolEditor are used for it because the grid also registers a + boolean data type with this name. + + And as this mechanism is completely generic, you may register your own + data types using your own custom renderers and editors. Just remember + that the table must identify a cell as being of the given type for them + to be used for this cell. + + @param typeName + Name of the new type. May be any string, but if the type name is + the same as the name of an already registered type, including one + of the standard ones (which are @c wxGRID_VALUE_STRING, @c + wxGRID_VALUE_BOOL, @c wxGRID_VALUE_NUMBER, @c wxGRID_VALUE_FLOAT + and @c wxGRID_VALUE_CHOICE), then the new registration information + replaces the previously used renderer and editor. + @param renderer + The renderer to use for the cells of this type. Its ownership is + taken by the grid, i.e. it will call DecRef() on this pointer when + it doesn't need it any longer. + @param editor + The editor to use for the cells of this type. Its ownership is also + taken by the grid. */ void RegisterDataType(const wxString& typeName, wxGridCellRenderer* renderer, wxGridCellEditor* editor); /** - SetRowLabelValue() - - SetColLabelValue() - - GetRowLabelValue() - - GetColLabelValue() - - SetUseNativeColLabels() - - HideColLabels() - - HideRowLabels() - - SetRowLabelSize() - - SetColLabelSize() - - GetRowLabelSize() - - GetColLabelSize() - - AutoSizeRowLabelSize() - - AutoSizeColLabelSize() + Sets the value of the current grid cell to the current in-place edit + control value. - GetDefaultRowLabelSize() - - GetDefaultColLabelSize() - - SetRowLabelAlignment() - - SetColLabelAlignment() - - GetRowLabelAlignment() - - GetColLabelAlignment() - - SetLabelFont() - - SetLabelTextColour() - - SetLabelBackgroundColour() - - GetLabelFont() - - GetLabelBackgroundColour() - - GetLabelTextColour() - - SetColLabelTextOrientation() - - GetColLabelTextOrientation() - */ - - - /** - Sets the value of the current grid cell to the current in-place edit control - value. - This is called automatically when the grid cursor moves from the current cell - to a - new cell. It is also a good idea to call this function when closing a grid since - any edits to the final cell location will not be saved otherwise. + This is called automatically when the grid cursor moves from the + current cell to a new cell. It is also a good idea to call this + function when closing a grid since any edits to the final cell location + will not be saved otherwise. */ void SaveEditControlValue(); @@ -2217,12 +2492,13 @@ public: //@{ /** - Selects a rectangular block of cells. If addToSelected is @false then any - existing selection will be - deselected; if @true the column will be added to the existing selection. + Selects a rectangular block of cells. + + If @a addToSelected is @false then any existing selection will be + deselected; if @true the column will be added to the existing + selection. */ - void SelectBlock(int topRow, int leftCol, int bottomRow, - int rightCol, + void SelectBlock(int topRow, int leftCol, int bottomRow, int rightCol, bool addToSelected = false); void SelectBlock(const wxGridCellCoords& topLeft, const wxGridCellCoords& bottomRight, @@ -2230,66 +2506,57 @@ public: //@} /** - Selects the specified column. If addToSelected is @false then any existing - selection will be - deselected; if @true the column will be added to the existing selection. - */ - void SelectCol(int col, bool addToSelected = false); + Selects the specified column. - /** - Selects the specified row. If addToSelected is @false then any existing - selection will be - deselected; if @true the row will be added to the existing selection. + If @a addToSelected is @false then any existing selection will be + deselected; if @true the column will be added to the existing + selection. + + This method won't select anything if the current selection mode is + wxGridSelectRows. */ - void SelectRow(int row, bool addToSelected = false); + void SelectCol(int col, bool addToSelected = false); /** - ClearSelection() - - IsSelection() - - SelectAll() - - SelectBlock() - - SelectCol() - - SelectRow() - */ + Selects the specified row. + If @a addToSelected is @false then any existing selection will be + deselected; if @true the row will be added to the existing selection. - /** - This function returns the rectangle that encloses the selected cells - in device coords and clipped to the client size of the grid window. + This method won't select anything if the current selection mode is + wxGridSelectColumns. */ - wxRect SelectionToDeviceRect() const; + void SelectRow(int row, bool addToSelected = false); //@{ /** - Sets the horizontal and vertical alignment for grid cell text at the specified - location. - Horizontal alignment should be one of wxALIGN_LEFT, wxALIGN_CENTRE or - wxALIGN_RIGHT. + Sets the horizontal and vertical alignment for grid cell text at the + specified location. + + Horizontal alignment should be one of @c wxALIGN_LEFT, @c + wxALIGN_CENTRE or @c wxALIGN_RIGHT. - Vertical alignment should be one of wxALIGN_TOP, wxALIGN_CENTRE or - wxALIGN_BOTTOM. + Vertical alignment should be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE + or @c wxALIGN_BOTTOM. */ void SetCellAlignment(int row, int col, int horiz, int vert); void SetCellAlignment(int align, int row, int col); //@} + //@{ /** - + Set the background colour for the given cell or all cells by default. */ - void SetCellBackgroundColour(int row, int col, - const wxColour& colour); + void SetCellBackgroundColour(int row, int col, const wxColour& colour); + //@} /** Sets the editor for the grid cell at the specified location. + The grid will take ownership of the pointer. - See wxGridCellEditor and - the @ref overview_gridoverview "wxGrid overview" for more information about - cell editors and renderers. + + See wxGridCellEditor and the @ref overview_grid "wxGrid overview" + for more information about cell editors and renderers. */ void SetCellEditor(int row, int col, wxGridCellEditor* editor); @@ -2300,17 +2567,17 @@ public: /** Sets the renderer for the grid cell at the specified location. + The grid will take ownership of the pointer. - See wxGridCellRenderer and - the @ref overview_gridoverview "wxGrid overview" for more information about - cell editors and renderers. + + See wxGridCellRenderer and the @ref overview_grid "wxGrid overview" + for more information about cell editors and renderers. */ - void SetCellRenderer(int row, int col, - wxGridCellRenderer* renderer); + void SetCellRenderer(int row, int col, wxGridCellRenderer* renderer); //@{ /** - Sets the text colour for the grid cell at the specified location. + Sets the text colour for the given cell or all cells by default. */ void SetCellTextColour(int row, int col, const wxColour& colour); void SetCellTextColour(const wxColour& val, int row, int col); @@ -2319,107 +2586,111 @@ public: //@{ /** - Sets the string value for the cell at the specified location. For simple - applications where a - grid object automatically uses a default grid table of string values you use - this function together - with GetCellValue() to access cell values. - For more complex applications where you have derived your own grid table class - that contains - various data types (e.g. numeric, boolean or user-defined custom types) then - you only use this - function for those cells that contain string values. + Sets the string value for the cell at the specified location. + + For simple applications where a grid object automatically uses a + default grid table of string values you use this function together with + GetCellValue() to access cell values. For more complex applications + where you have derived your own grid table class that contains various + data types (e.g. numeric, boolean or user-defined custom types) then + you only use this function for those cells that contain string values. The last form is for backward compatibility only. - See wxGridTableBase::CanSetValueAs - and the @ref overview_gridoverview "wxGrid overview" for more information. + + See wxGridTableBase::CanSetValueAs and the @ref overview_grid + "wxGrid overview" for more information. */ void SetCellValue(int row, int col, const wxString& s); - void SetCellValue(const wxGridCellCoords& coords, - const wxString& s); + void SetCellValue(const wxGridCellCoords& coords, const wxString& s); void SetCellValue(const wxString& val, int row, int col); //@} /** Sets the cell attributes for all cells in the specified column. + For more information about controlling grid cell attributes see the - wxGridCellAttr cell attribute class and the - @ref overview_gridoverview. + wxGridCellAttr cell attribute class and the @ref overview_grid "wxGrid overview". */ void SetColAttr(int col, wxGridCellAttr* attr); /** - Sets the specified column to display boolean values. wxGrid displays boolean - values with a checkbox. + Sets the specified column to display boolean values. + + @see SetColFormatCustom() */ void SetColFormatBool(int col); /** Sets the specified column to display data in a custom format. - See the @ref overview_gridoverview "wxGrid overview" for more information on - working - with custom data types. + + This method provides an alternative to defining a custom grid table + which would return @a typeName from its GetTypeName() method for the + cells in this column: while it doesn't really change the type of the + cells in this column, it does associate the renderer and editor used + for the cells of the specified type with them. + + See the @ref overview_grid "wxGrid overview" for more + information on working with custom data types. */ void SetColFormatCustom(int col, const wxString& typeName); /** - Sets the specified column to display floating point values with the given width - and precision. + Sets the specified column to display floating point values with the + given width and precision. + + @see SetColFormatCustom() */ - void SetColFormatFloat(int col, int width = -1, - int precision = -1); + void SetColFormatFloat(int col, int width = -1, int precision = -1); /** Sets the specified column to display integer values. + + @see SetColFormatCustom() */ void SetColFormatNumber(int col); /** Sets the horizontal and vertical alignment of column label text. - Horizontal alignment should be one of wxALIGN_LEFT, wxALIGN_CENTRE or - wxALIGN_RIGHT. - Vertical alignment should be one of wxALIGN_TOP, wxALIGN_CENTRE or - wxALIGN_BOTTOM. + + 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. */ void SetColLabelAlignment(int horiz, int vert); /** Sets the height of the column labels. + If @a height equals to @c wxGRID_AUTOSIZE then height is calculated - automatically - so that no label is truncated. Note that this could be slow for a large table. + automatically so that no label is truncated. Note that this could be + slow for a large table. */ void SetColLabelSize(int height); /** - Set the value for the given column label. If you are using a derived grid table - you must - override wxGridTableBase::SetColLabelValue - for this to have any effect. + Set the value for the given column label. + + If you are using a custom grid table you must override + wxGridTableBase::SetColLabelValue for this to have any effect. */ void SetColLabelValue(int col, const wxString& value); /** - This modifies the minimum column width that can be handled correctly. - Specifying a low value here - allows smaller grid cells to be dealt with correctly. Specifying a value here - which is much smaller - than the actual minimum size will incur a performance penalty in the functions - which perform - grid cell index lookup on the basis of screen coordinates. - This should normally be called when creating the grid because it will not - resize existing columns - with sizes smaller than the value specified here. + Sets the minimal width to which the user can resize columns. + + @see GetColMinimalAcceptableWidth() */ void SetColMinimalAcceptableWidth(int width); /** - Sets the minimal width for the specified column. This should normally be called - when creating the grid - because it will not resize a column that is already narrower than the minimal - width. - The width argument must be higher than the minimimal acceptable column width, - see - GetColMinimalAcceptableWidth(). + Sets the minimal width for the specified column. + + It is usually best to call this method during grid creation as calling + it later will not resize the column to the given minimal width even if + it is currently narrower than it. + + @a width must be greater than the minimal acceptable column width as + returned by GetColMinimalAcceptableWidth(). */ void SetColMinimalWidth(int col, int width); @@ -2430,21 +2701,25 @@ public: /** Sets the width of the specified column. - This function does not refresh the grid. If you are calling it outside of a - BeginBatch / EndBatch - block you can use ForceRefresh() to see the changes. - Automatically sizes the column to fit its contents. If setAsMin is @true the - calculated width will - also be set as the minimal width for the column. + + Notice that this function does not refresh the grid, you need to call + ForceRefresh() to make the changes take effect immediately. + + @param col + The column index. + @param width + The new column width in pixels or a negative value to fit the + column width to its label width. */ void SetColSize(int col, int width); /** Sets the default horizontal and vertical alignment for grid cell text. - Horizontal alignment should be one of wxALIGN_LEFT, wxALIGN_CENTRE or - wxALIGN_RIGHT. - Vertical alignment should be one of wxALIGN_TOP, wxALIGN_CENTRE or - wxALIGN_BOTTOM. + + 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. */ void SetDefaultCellAlignment(int horiz, int vert); @@ -2464,44 +2739,63 @@ public: void SetDefaultCellTextColour(const wxColour& colour); /** - Sets the default width for columns in the grid. This will only affect columns - subsequently added to - the grid unless resizeExistingCols is @true. + Sets the default width for columns in the grid. + + This will only affect columns subsequently added to the grid unless + @a resizeExistingCols is @true. + + If @a width is less than GetColMinimalAcceptableWidth(), then the + minimal acceptable width is used instead of it. */ - void SetDefaultColSize(int width, - bool resizeExistingCols = false); + void SetDefaultColSize(int width, bool resizeExistingCols = false); /** - Sets the default editor for grid cells. The grid will take ownership of the - pointer. - See wxGridCellEditor and - the @ref overview_gridoverview "wxGrid overview" for more information about - cell editors and renderers. + Sets the default editor for grid cells. + + The grid will take ownership of the pointer. + + See wxGridCellEditor and the @ref overview_grid "wxGrid overview" + for more information about cell editors and renderers. */ void SetDefaultEditor(wxGridCellEditor* editor); /** - Sets the default renderer for grid cells. The grid will take ownership of the - pointer. - See wxGridCellRenderer and - the @ref overview_gridoverview "wxGrid overview" for more information about - cell editors and renderers. + Sets the default renderer for grid cells. + + The grid will take ownership of the pointer. + + See wxGridCellRenderer and the @ref overview_grid "wxGrid overview" + for more information about cell editors and renderers. */ void SetDefaultRenderer(wxGridCellRenderer* renderer); /** - Sets the default height for rows in the grid. This will only affect rows - subsequently added - to the grid unless resizeExistingRows is @true. + Sets the default height for rows in the grid. + + This will only affect rows subsequently added to the grid unless + @a resizeExistingRows is @true. + + If @a height is less than GetRowMinimalAcceptableHeight(), then the + minimal acceptable heihgt is used instead of it. */ - void SetDefaultRowSize(int height, - bool resizeExistingRows = false); + 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. @@ -2524,153 +2818,138 @@ public: void SetLabelTextColour(const wxColour& colour); /** - A grid may occupy more space than needed for its rows/columns. This - function allows to set how big this extra space is - */ - void SetMargins(int extraWidth, int extraHeight); + Sets the extra margins used around the grid area. - /** - Common part of AutoSizeColumn/Row() and GetBestSize() + A grid may occupy more space than needed for its data display and + this function allows to set how big this extra space is */ - int SetOrCalcColumnSizes(bool calcOnly, bool setAsMin = true); - - /** - - */ - int SetOrCalcRowSizes(bool calcOnly, bool setAsMin = true); + void SetMargins(int extraWidth, int extraHeight); /** Makes the cell at the specified location read-only or editable. - See also IsReadOnly(). + + @see IsReadOnly() */ void SetReadOnly(int row, int col, bool isReadOnly = true); /** Sets the cell attributes for all cells in the specified row. - See the wxGridCellAttr class for more information - about controlling cell attributes. + + The grid takes ownership of the attribute pointer. + + See the wxGridCellAttr class for more information about controlling + cell attributes. */ void SetRowAttr(int row, wxGridCellAttr* attr); /** Sets the horizontal and vertical alignment of row label text. - Horizontal alignment should be one of wxALIGN_LEFT, wxALIGN_CENTRE or - wxALIGN_RIGHT. - Vertical alignment should be one of wxALIGN_TOP, wxALIGN_CENTRE or - wxALIGN_BOTTOM. + + 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. */ void SetRowLabelAlignment(int horiz, int vert); /** Sets the width of the row labels. - If @a width equals @c wxGRID_AUTOSIZE then width is calculated automatically - so that no label is truncated. Note that this could be slow for a large table. + + If @a width equals @c wxGRID_AUTOSIZE then width is calculated + automatically so that no label is truncated. Note that this could be + slow for a large table. */ void SetRowLabelSize(int width); /** - Set the value for the given row label. If you are using a derived grid table - you must - override wxGridTableBase::SetRowLabelValue - for this to have any effect. + Sets the value for the given row label. + + If you are using a derived grid table you must override + wxGridTableBase::SetRowLabelValue for this to have any effect. */ void SetRowLabelValue(int row, const wxString& value); /** - This modifies the minimum row width that can be handled correctly. Specifying a - low value here - allows smaller grid cells to be dealt with correctly. Specifying a value here - which is much smaller - than the actual minimum size will incur a performance penalty in the functions - which perform - grid cell index lookup on the basis of screen coordinates. - This should normally be called when creating the grid because it will not - resize existing rows - with sizes smaller than the value specified here. + Sets the minimal row height used by default. + + See SetColMinimalAcceptableWidth() for more information. */ void SetRowMinimalAcceptableHeight(int height); /** - Sets the minimal height for the specified row. This should normally be called - when creating the grid - because it will not resize a row that is already shorter than the minimal - height. - The height argument must be higher than the minimimal acceptable row height, see - GetRowMinimalAcceptableHeight(). + Sets the minimal height for the specified row. + + See SetColMinimalWidth() for more information. */ void SetRowMinimalHeight(int row, int height); /** Sets the height of the specified row. - This function does not refresh the grid. If you are calling it outside of a - BeginBatch / EndBatch - block you can use ForceRefresh() to see the changes. - Automatically sizes the column to fit its contents. If setAsMin is @true the - calculated width will - also be set as the minimal width for the column. + + See SetColSize() for more information. */ void SetRowSize(int row, int height); /** - Sets the number of pixels per horizontal scroll increment. The default is 15. - Sometimes wxGrid has trouble setting the scrollbars correctly due to rounding - errors: setting this to 1 can help. + Sets the number of pixels per horizontal scroll increment. + + The default is 15. @see GetScrollLineX(), GetScrollLineY(), SetScrollLineY() */ void SetScrollLineX(int x); /** - Sets the number of pixels per vertical scroll increment. The default is 15. - Sometimes wxGrid has trouble setting the scrollbars correctly due to rounding - errors: setting this to 1 can help. + Sets the number of pixels per vertical scroll increment. + + The default is 15. @see GetScrollLineX(), GetScrollLineY(), SetScrollLineX() */ void SetScrollLineY(int y); /** - + Set the colour to be used for drawing the selection background. */ void SetSelectionBackground(const wxColour& c); /** - + Set the colour to be used for drawing the selection foreground. */ void SetSelectionForeground(const wxColour& c); /** Set the selection behaviour of the grid. - @param wxGridSelectCells() - The default mode where individual cells are selected. - @param wxGridSelectRows() - Selections will consist of whole rows. - @param wxGridSelectColumns() - Selections will consist of whole columns. + The existing selection is converted to conform to the new mode if + possible and discarded otherwise (e.g. any individual selected cells + are deselected if the new mode allows only the selection of the entire + rows or columns). */ - void SetSelectionMode(wxGrid::wxGridSelectionModes selmode); + void SetSelectionMode(wxGridSelectionModes selmode); /** - Passes a pointer to a custom grid table to be used by the grid. This should be - called - after the grid constructor and before using the grid object. If takeOwnership - is set to - @true then the table will be deleted by the wxGrid destructor. - Use this function instead of CreateGrid() when your - application involves complex or non-string data or data sets that are too large - to fit - wholly in memory. + Passes a pointer to a custom grid table to be used by the grid. + + This should be called after the grid constructor and before using the + grid object. If @a takeOwnership is set to @true then the table will be + deleted by the wxGrid destructor. + + Use this function instead of CreateGrid() when your application + involves complex or non-string data or data sets that are too large to + fit wholly in memory. */ - bool SetTable(wxGridTableBase* table, bool takeOwnership = false, - wxGrid::wxGridSelectionModes selmode = wxGrid::wxGridSelectCells); + bool SetTable(wxGridTableBase* table, + bool takeOwnership = false, + wxGridSelectionModes selmode = wxGridSelectCells); /** Call this in order to make the column labels use a native look by using - wxRenderer::DrawHeaderButton - internally. There is no equivalent method for drawing row columns as - there is not native look for that. This option is useful when using - wxGrid for displaying tables and not as a spread-sheet. + wxRenderer::DrawHeaderButton internally. + + There is no equivalent method for drawing row columns as there is not + native look for that. This option is useful when using wxGrid for + displaying tables and not as a spread-sheet. */ void SetUseNativeColLabels(bool native = true); @@ -2680,30 +2959,60 @@ public: void ShowCellEditControl(); /** + Returns the column at the given pixel position. + @param x The x position to evaluate. @param clipToMinMax - If @true, rather than returning wxNOT_FOUND, it returns either the first or - last column depending on whether x is too far to the left or right respectively. + If @true, rather than returning wxNOT_FOUND, it returns either the + first or last column depending on whether x is too far to the left + or right respectively. + @return + The column index or wxNOT_FOUND. */ int XToCol(int x, bool clipToMinMax = false) const; /** - Returns the column whose right hand edge is close to the given logical x - position. + Returns the column whose right hand edge is close to the given logical + x position. + If no column edge is near to this position @c wxNOT_FOUND is returned. */ 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. + Returns the row whose bottom edge is close to the given logical y + position. + If no row edge is near to this position @c wxNOT_FOUND is returned. */ int YToEdgeOfRow(int y) const; /** - Returns the grid row that corresponds to the logical y coordinate. Returns - @c wxNOT_FOUND if there is no row at the y position. + Returns the grid row that corresponds to the logical y coordinate. + + Returns @c wxNOT_FOUND if there is no row at the y position. */ int YToRow(int y) const; }; @@ -2716,7 +3025,7 @@ public: The editor for boolean data. @library{wxadv} - @category{FIXME} + @category{grid} @see wxGridCellEditor, wxGridCellFloatEditor, wxGridCellNumberEditor, wxGridCellTextEditor, wxGridCellChoiceEditor @@ -2776,7 +3085,7 @@ public: because you don't risk not to call the latter (due to an exception for example). @library{wxadv} - @category{FIXME} + @category{grid} */ class wxGridUpdateLocker {