/**
Fetch the value from the table and prepare the edit control to begin
- editing. Sets the focus to the edit control.
+ editing.
+
+ This function should save the original value of the grid cell at the
+ given @a row and @a col and show the control allowing the user to
+ change it.
+
+ @see EndEdit()
*/
virtual void BeginEdit(int row, int col, wxGrid* grid) = 0;
virtual void Destroy();
/**
- Complete the editing of the current cell. If necessary, the control may
- be destroyed.
+ End editing the cell.
+
+ This function must check if the current value of the editing control is
+ valid and different from the original value (available as @a oldval in
+ its string form and possibly saved internally using its real type by
+ BeginEdit()). If it isn't, it just returns @false, otherwise it must do
+ the following:
+ # Save the new value internally so that ApplyEdit() could apply it.
+ # Fill @a newval (which is never @NULL) with the string
+ representation of the new value.
+ # Return @true
+
+ Notice that it must @em not modify the grid as the change could still
+ be vetoed.
- @return @true if the value has changed.
+ If the user-defined wxEVT_GRID_CELL_CHANGING event handler doesn't veto
+ this change, ApplyEdit() will be called next.
*/
- virtual bool EndEdit(int row, int col, wxGrid* grid) = 0;
+ virtual bool EndEdit(int row, int col, const wxGrid* grid,
+ const wxString& oldval, wxString* newval) = 0;
+
+ /**
+ Effectively save the changes in the grid.
+
+ This function should save the value of the control in the grid. It is
+ called only after EndEdit() returns @true.
+ */
+ virtual void ApplyEdit(int row, int col, wxGrid* grid) = 0;
/**
Some types of controls on some platforms may need some help with the
an empty string otherwise.
*/
static void UseStringValues(const wxString& valueTrue = "1",
- const wxString& valueFalse = wxEmptyString) const;
+ const wxString& valueFalse = wxEmptyString);
};
/**
/**
Default constructor.
*/
- wxGridCellAttr();
+ wxGridCellAttr(wxGridCellAttr* attrDefault = NULL);
/**
Constructor specifying some of the often used attributes.
*/
//@{
/**
- Must be overridden to implement testing for empty cells.
+ May be overridden to implement testing for empty cells.
+
+ This method is used by the grid to test if the given cell is not used
+ and so whether a neighbouring cell may overflow into it. By default it
+ only returns true if the value of the given cell, as returned by
+ GetValue(), is empty.
*/
- virtual bool IsEmptyCell(int row, int col) = 0;
+ virtual bool IsEmptyCell(int row, int col);
/**
Same as IsEmptyCell() but taking wxGridCellCoords.
virtual bool CanHaveAttributes();
};
+/**
+ @class wxGridSizesInfo
+
+ wxGridSizesInfo stores information about sizes of all wxGrid rows or
+ columns.
+
+ It assumes that most of the rows or columns (which are both called elements
+ here as the difference between them doesn't matter at this class level)
+ have the default size and so stores it separately. And it uses a wxHashMap
+ to store the sizes of all elements which have the non-default size.
+
+ This structure is particularly useful for serializing the sizes of all
+ wxGrid elements at once.
+
+ @library{wxadv}
+ @category{grid}
+ */
+struct wxGridSizesInfo
+{
+ /**
+ Default constructor.
+
+ m_sizeDefault and m_customSizes must be initialized later.
+ */
+ wxGridSizesInfo();
+
+ /**
+ Constructor.
+
+ This constructor is used by wxGrid::GetRowSizes() and GetColSizes()
+ methods. User code will usually use the default constructor instead.
+
+ @param defSize
+ The default element size.
+ @param allSizes
+ Array containing the sizes of @em all elements, including those
+ which have the default size.
+ */
+ wxGridSizesInfo(int defSize, const wxArrayInt& allSizes);
+
+ /**
+ Get the element size.
+
+ @param pos
+ The index of the element.
+ @return
+ The size for this element, using m_customSizes if @a pos is in it
+ or m_sizeDefault otherwise.
+ */
+ int GetSize(unsigned pos) const;
+
+
+ /// Default size
+ int m_sizeDefault;
+
+ /**
+ Map with element indices as keys and their sizes as values.
+
+ This map only contains the elements with non-default size.
+ */
+ wxUnsignedToIntHashMap m_customSizes;
+};
/**
@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_grid "wxGrid overview" has examples of simple and more complex applications,
+ 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 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.
+ strings. An instance of such a class is created by CreateGrid().
wxGridCellRenderer is the abstract base class for rendereing contents in a
cell. The following renderers are predefined:
- - wxGridCellStringRenderer,
- - wxGridCellBoolRenderer,
- - wxGridCellFloatRenderer,
- - wxGridCellNumberRenderer.
+
+ - wxGridCellBoolRenderer
+ - wxGridCellFloatRenderer
+ - wxGridCellNumberRenderer
+ - wxGridCellStringRenderer
+
The look of a cell can be further defined using wxGridCellAttr. An object
- of this type may be returned by wxGridTableBase::GetAttr.
+ 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.
+
+ - wxGridCellBoolEditor
+ - wxGridCellChoiceEditor
+ - wxGridCellFloatEditor
+ - wxGridCellNumberEditor
+ - wxGridCellTextEditor
+
+ Please see wxGridEvent, wxGridSizeEvent, wxGridRangeSelectEvent, and
+ wxGridEditorCreatedEvent for the documentation of all event types you can
+ use with wxGrid.
@library{wxadv}
@category{grid}
- @see @ref overview_grid "wxGrid overview"
+ @see @ref overview_grid, wxGridUpdateLocker
*/
class wxGrid : public wxScrolledWindow
{
public:
+
/**
Different selection modes supported by the grid.
*/
wxGridSelectColumns
};
+
+ /**
+ @name Constructors and Initialization
+ */
+ //@{
+
/**
Default constructor.
CreateGrid() or SetTable() to initialize the grid contents.
*/
wxGrid();
-
/**
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,
+ wxGrid(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 SetTable()).
+ */
+ virtual ~wxGrid();
+
/**
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,
+ bool Create(wxWindow* parent, wxWindowID id,
const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize,
long style = wxWANTS_CHARS,
const wxString& name = wxGridNameStr);
/**
- Destructor.
+ Creates a grid with the specified initial number of rows and columns.
- 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).
+ 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.
+
+ For applications with more complex data types or relationships, or for
+ dealing with very large datasets, you should derive your own grid table
+ class and pass a table object to the grid with SetTable().
*/
- virtual ~wxGrid();
+ bool CreateGrid(int numRows, int numCols,
+ wxGridSelectionModes selmode = wxGridSelectCells);
/**
- Appends one or more new columns to the right of the grid.
+ Passes a pointer to a custom grid table to be used by 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.
+ 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.
- @return @true on success or @false if appending columns failed.
+ 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 AppendCols(int numCols = 1, bool updateLabels = true);
+ bool SetTable(wxGridTableBase* table, bool takeOwnership = false,
+ wxGridSelectionModes selmode = wxGridSelectCells);
- /**
- 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.
+ /**
+ @name Grid Line Formatting
+ */
+ //@{
+
+ /**
+ Turns the drawing of grid lines on or off.
*/
- bool AppendRows(int numRows = 1, bool updateLabels = true);
+ void EnableGridLines(bool enable = 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.
+ Returns the pen used for vertical grid lines.
- The default is to clip 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
+ @a col.
- @see ClipHorzGridLines(), AreVertGridLinesClipped()
- */
- bool AreHorzGridLinesClipped() const;
+ See GetRowGridLinePen() for an example.
+ */
+ virtual wxPen GetColGridLinePen(int col);
/**
- Return @true if the vertical grid lines stop at the last row
- boundary or @false if they continue to the end of the window.
+ Returns the pen used for grid lines.
- The default is to clip 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 ClipVertGridLines(), AreHorzGridLinesClipped()
- */
- bool AreVertGridLinesClipped() const;
+ @see GetColGridLinePen(), GetRowGridLinePen()
+ */
+ virtual wxPen GetDefaultGridLinePen();
/**
- Automatically sets the height and width of all rows and columns to fit their
- contents.
+ Returns the colour used for grid lines.
+
+ @see GetDefaultGridLinePen()
*/
- void AutoSize();
+ wxColour GetGridLineColour() const;
/**
- Automatically adjusts width of the column to fit its label.
+ 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 @a 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
*/
- void AutoSizeColLabelSize(int col);
+ virtual wxPen GetRowGridLinePen(int row);
/**
- 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.
+ Returns @true if drawing of grid lines is turned on, @false otherwise.
*/
- void AutoSizeColumn(int col, bool setAsMin = true);
+ bool GridLinesEnabled() const;
/**
- Automatically sizes all columns to fit their contents. If setAsMin is @true the
- calculated widths will
- also be set as the minimal widths for the columns.
+ Sets the colour used to draw grid lines.
*/
- void AutoSizeColumns(bool setAsMin = true);
+ void SetGridLineColour(const wxColour& colour);
+
+ //@}
+
/**
- Automatically sizes the row to fit its contents. If setAsMin is @true the
- calculated height will
- also be set as the minimal height for the row.
- */
- void AutoSizeRow(int row, bool setAsMin = true);
+ @name Label Values and Formatting
+ */
+ //@{
/**
- Automatically adjusts height of the row to fit its label.
+ Sets the arguments to the current column label alignment values.
+
+ 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 AutoSizeRowLabelSize(int col);
+ void GetColLabelAlignment(int* horiz, int* vert) const;
/**
- Automatically sizes all rows to fit their contents. If setAsMin is @true the
- calculated heights will
- also be set as the minimal heights for the rows.
+ Returns the orientation of the column labels (either @c wxHORIZONTAL or
+ @c wxVERTICAL).
*/
- void AutoSizeRows(bool setAsMin = true);
+ int GetColLabelTextOrientation() const;
/**
- 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.
+ Returns the specified column label.
- 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.
+ 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.
*/
- void BeginBatch();
+ wxString GetColLabelValue(int col) const;
/**
- Convert grid cell coordinates to grid window pixel coordinates.
+ Returns the colour used for the background of row and column labels.
+ */
+ wxColour GetLabelBackgroundColour() const;
- This function returns the rectangle that encloses the block of cells
- limited by @a topLeft and @a bottomRight cell in device coords and
- clipped to the client size of the grid window.
+ /**
+ Returns the font used for row and column labels.
+ */
+ wxFont GetLabelFont() const;
- @see CellToRect()
+ /**
+ Returns the colour used for row and column label text.
*/
- wxRect BlockToDeviceRect(const wxGridCellCoords& topLeft,
- const wxGridCellCoords& bottomRight) const;
+ wxColour GetLabelTextColour() const;
/**
- Returns @true if columns can be moved by dragging with the mouse.
+ Returns the alignment used for row labels.
- Columns can be moved by dragging on their labels.
+ 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.
*/
- bool CanDragColMove() const;
+ void GetRowLabelAlignment(int* horiz, int* vert) const;
/**
- Returns @true if columns can be resized by dragging with the mouse.
+ Returns the specified row label.
- 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).
+ 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.
*/
- bool CanDragColSize() const;
+ wxString GetRowLabelValue(int row) const;
/**
- Return @true if the dragging of grid lines to resize rows and columns
- is enabled or @false otherwise.
+ Hides the column labels by calling SetColLabelSize() with a size of 0.
+ Show labels again by calling that method with a width greater than 0.
*/
- bool CanDragGridSize() const;
+ void HideColLabels();
/**
- Returns @true if rows can be resized by dragging with the mouse.
+ Hides the row labels by calling SetRowLabelSize() with a size of 0.
- 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).
+ The labels can be shown again by calling SetRowLabelSize() with a width
+ greater than 0.
*/
- bool CanDragRowSize() const;
+ void HideRowLabels();
/**
- Returns @true if the in-place edit control for the current grid cell
- can be used and @false otherwise.
+ Sets the horizontal and vertical alignment of column label text.
- This function always returns @false for the read-only cells.
+ 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.
*/
- bool CanEnableCellControl() const;
+ void SetColLabelAlignment(int horiz, int vert);
- //@{
/**
- Return the rectangle corresponding to the grid cell's size and position
- in logical coordinates.
+ Sets the orientation of the column labels (either @c wxHORIZONTAL or
+ @c wxVERTICAL).
+ */
+ void SetColLabelTextOrientation(int textOrientation);
- @see BlockToDeviceRect()
+ /**
+ 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.
*/
- wxRect CellToRect(int row, int col) const;
- const wxRect CellToRect(const wxGridCellCoords& coords) const;
+ void SetColLabelValue(int col, const wxString& value);
- //@}
+ /**
+ Sets the background colour for row and column labels.
+ */
+ void SetLabelBackgroundColour(const wxColour& colour);
/**
- Clears all data in the underlying grid table and repaints the grid.
+ Sets the font for row and column labels.
+ */
+ void SetLabelFont(const wxFont& font);
- 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.
+ /**
+ Sets the colour for row and column label text.
*/
- void ClearGrid();
+ void SetLabelTextColour(const wxColour& colour);
/**
- Deselects all cells that are currently selected.
+ Sets the horizontal and vertical alignment of row label text.
+
+ 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 ClearSelection();
+ void SetRowLabelAlignment(int horiz, int vert);
/**
- Change whether the horizontal grid lines are clipped by the end of the
- last column.
+ Sets the value for the given row label.
- 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.
-
- @see AreHorzGridLinesClipped(), ClipVertGridLines()
- */
- void ClipHorzGridLines(bool clip);
+ 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);
/**
- Change whether the vertical grid lines are clipped by the end of the
- last row.
+ Call this in order to make the column labels use a native look by using
+ wxRendererNative::DrawHeaderButton() internally.
- 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.
+ 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.
+
+ @see UseNativeColHeader()
+ */
+ void SetUseNativeColLabels(bool native = true);
- @see AreVertzGridLinesClipped(), ClipHorzGridLines()
+ /**
+ Enable the use of native header window for column labels.
+
+ If this function is called with @true argument, a wxHeaderCtrl is used
+ instead to display the column labels instead of drawing them in wxGrid
+ code itself. This has the advantage of making the grid look and feel
+ perfectly the same as native applications (using SetUseNativeColLabels()
+ the grid can be made to look more natively but it still doesn't feel
+ natively, notably the column resizing and dragging still works slightly
+ differently as it is implemented in wxWidgets itself) but results in
+ different behaviour for column and row headers, for which there is no
+ equivalent function, and, most importantly, is unsuitable for grids
+ with huge numbers of columns as wxHeaderCtrl doesn't support virtual
+ mode. Because of this, by default the grid does not use the native
+ header control but you should call this function to enable it if you
+ are using the grid to display tabular data and don't have thousands of
+ columns in it.
+
+ Also note that currently @c wxEVT_GRID_LABEL_LEFT_DCLICK and
+ @c wxEVT_GRID_LABEL_RIGHT_DCLICK events are not generated for the column
+ labels if the native columns header is used (but this limitation could
+ possibly be lifted in the future).
*/
- void ClipVertzGridLines(bool clip);
+ void UseNativeColHeader(bool native = true);
+
+ //@}
+
/**
- Creates a grid with the specified initial number of rows and columns.
+ @name Cell Formatting
- 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.
- For applications with more complex data types or relationships, or for
- dealing with very large datasets, you should derive your own grid table
- class and pass a table object to the grid with SetTable().
- */
- bool CreateGrid(int numRows, int numCols,
- wxGridSelectionModes selmode = wxGridSelectCells);
+ Note that wxGridCellAttr can be used alternatively to most of these
+ methods. See the "Attributes Management" of wxGridTableBase.
+ */
+ //@{
/**
- Deletes one or more columns from a grid starting at the specified
- position.
+ Sets the arguments to the horizontal and vertical text alignment values
+ for the grid cell at the specified location.
- 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.
+ Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
+ or @c wxALIGN_RIGHT.
- @return @true on success or @false if deleting columns failed.
+ Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
+ @c wxALIGN_BOTTOM.
*/
- bool DeleteCols(int pos = 0, int numCols = 1, bool updateLabels = true);
+ void GetCellAlignment(int row, int col, int* horiz, int* vert) const;
/**
- Deletes one or more rows from a grid starting at the specified position.
-
- 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.
+ Returns the background colour of the cell at the specified location.
*/
- bool DeleteRows(int pos = 0, int numRows = 1, bool updateLabels = true);
+ wxColour GetCellBackgroundColour(int row, int col) const;
/**
- Disables in-place editing of grid cells.
+ Returns the font for text in the grid cell at the specified location.
+ */
+ wxFont GetCellFont(int row, int col) const;
- Equivalent to calling EnableCellEditControl(@false).
+ /**
+ Returns the text colour for the grid cell at the specified location.
*/
- void DisableCellEditControl();
+ wxColour GetCellTextColour(int row, int col) const;
/**
- Disables column moving by dragging with the mouse.
+ Returns the default cell alignment.
- Equivalent to passing @false to EnableDragColMove().
+ 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.
+
+ @see SetDefaultCellAlignment()
*/
- void DisableDragColMove();
+ void GetDefaultCellAlignment(int* horiz, int* vert) const;
/**
- Disables column sizing by dragging with the mouse.
-
- Equivalent to passing @false to EnableDragColSize().
+ Returns the current default background colour for grid cells.
*/
- void DisableDragColSize();
+ wxColour GetDefaultCellBackgroundColour() const;
/**
- Disable mouse dragging of grid lines to resize rows and columns.
+ Returns the current default font for grid cell text.
+ */
+ wxFont GetDefaultCellFont() const;
- Equivalent to passing @false to EnableDragGridSize()
+ /**
+ Returns the current default colour for grid cell text.
*/
- void DisableDragGridSize();
+ wxColour GetDefaultCellTextColour() const;
/**
- Disables row sizing by dragging with the mouse.
+ Sets the horizontal and vertical alignment for grid cell text at the
+ specified location.
- Equivalent to passing @false to EnableDragRowSize().
- */
- void DisableDragRowSize();
+ 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 SetCellAlignment(int row, int col, int horiz, int vert);
/**
- Enables or disables in-place editing of grid cell data.
+ Sets the horizontal and vertical alignment for grid cell text at the
+ specified location.
- The grid will issue either a wxEVT_GRID_EDITOR_SHOWN or
- wxEVT_GRID_EDITOR_HIDDEN event.
+ 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 EnableCellEditControl(bool enable = true);
+ void SetCellAlignment(int align, int row, int col);
/**
- Enables or disables column moving by dragging with the mouse.
+ Set the background colour for the given cell or all cells by default.
*/
- void EnableDragColMove(bool enable = true);
+ void SetCellBackgroundColour(int row, int col, const wxColour& colour);
/**
- Enables or disables column sizing by dragging with the mouse.
+ Sets the font for text in the grid cell at the specified location.
*/
- void EnableDragColSize(bool enable = true);
+ void SetCellFont(int row, int col, const wxFont& font);
/**
- Enables or disables row and column resizing by dragging gridlines with the
- mouse.
+ Sets the text colour for the given cell.
*/
- void EnableDragGridSize(bool enable = true);
-
+ void SetCellTextColour(int row, int col, const wxColour& colour);
/**
- Enables or disables row sizing by dragging with the mouse.
+ Sets the text colour for the given cell.
*/
- void EnableDragRowSize(bool enable = true);
+ void SetCellTextColour(const wxColour& val, int row, int col);
+ /**
+ Sets the text colour for all cells by default.
+ */
+ void SetCellTextColour(const wxColour& colour);
/**
- Makes the grid globally editable or read-only.
+ Sets the default horizontal and vertical alignment for grid cell text.
- 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().
+ 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);
- For more information about controlling grid cell attributes see the
- wxGridCellAttr cell attribute class and the
- @ref overview_grid "wxGrid overview".
+ /**
+ Sets the default background colour for grid cells.
*/
- void EnableEditing(bool edit);
+ void SetDefaultCellBackgroundColour(const wxColour& colour);
/**
- Turns the drawing of grid lines on or off.
+ Sets the default font to be used for grid cell text.
*/
- void EnableGridLines(bool enable = true);
+ void SetDefaultCellFont(const wxFont& font);
/**
- Decrements the grid's batch count.
+ Sets the current default colour for grid cell text.
+ */
+ void SetDefaultCellTextColour(const wxColour& colour);
- 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
- */
- void EndBatch();
/**
- Overridden wxWindow method.
- */
- virtual void Fit();
+ @name Cell Values, Editors, and Renderers
+
+ Note that wxGridCellAttr can be used alternatively to most of these
+ methods. See the "Attributes Management" of wxGridTableBase.
+ */
+ //@{
/**
- Causes immediate repainting of the grid.
+ Returns @true if the in-place edit control for the current grid cell
+ can be used and @false otherwise.
- Use this instead of the usual wxWindow::Refresh.
+ This function always returns @false for the read-only cells.
*/
- void ForceRefresh();
+ bool CanEnableCellControl() const;
/**
- Returns the number of times that BeginBatch() has been called
- without (yet) matching calls to EndBatch(). While
- the grid's batch count is greater than zero the display will not be updated.
+ Disables in-place editing of grid cells.
+
+ Equivalent to calling EnableCellEditControl(@false).
*/
- int GetBatchCount();
+ void DisableCellEditControl();
/**
- 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.
+ Enables or disables in-place editing of grid cell data.
- Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
- @c wxALIGN_BOTTOM.
+ The grid will issue either a @c wxEVT_GRID_EDITOR_SHOWN or
+ @c wxEVT_GRID_EDITOR_HIDDEN event.
*/
- void GetCellAlignment(int row, int col, int* horiz, int* vert) const;
+ void EnableCellEditControl(bool enable = true);
/**
- Returns the background colour of the cell at the specified location.
+ 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 wxGridCellAttr::SetReadOnly(). For single cells you
+ can also use the shortcut function SetReadOnly().
+
+ For more information about controlling grid cell attributes see the
+ wxGridCellAttr class and the @ref overview_grid.
*/
- wxColour GetCellBackgroundColour(int row, int col) const;
+ void EnableEditing(bool edit);
/**
Returns a pointer to the editor for the cell at the specified location.
- See wxGridCellEditor and the @ref overview_grid "wxGrid overview"
- for more information about cell editors and renderers.
+ See wxGridCellEditor and the @ref overview_grid for more information
+ about cell editors and renderers.
The caller must call DecRef() on the returned pointer.
*/
wxGridCellEditor* GetCellEditor(int row, int col) const;
- /**
- Returns the font for text in the grid cell at the specified location.
- */
- 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_grid "wxGrid overview"
- for more information about cell editors and renderers.
+ See wxGridCellRenderer and the @ref overview_grid for more information
+ about cell editors and renderers.
The caller must call DecRef() on the returned pointer.
*/
wxGridCellRenderer* GetCellRenderer(int row, int col) const;
/**
- Returns the text colour for the grid cell at the specified location.
- */
- wxColour GetCellTextColour(int row, int col) const;
+ 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 for
+ more information.
+ */
+ wxString GetCellValue(int row, int col) const;
/**
Returns the string contained in the cell at the specified location.
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.
+ See wxGridTableBase::CanGetValueAs() and the @ref overview_grid for
+ more information.
*/
- wxString GetCellValue(int row, int col) const;
- const wxString GetCellValue(const wxGridCellCoords& coords) const;
- //@}
+ wxString GetCellValue(const wxGridCellCoords& coords) const;
/**
- Returns the column ID of the specified column position.
+ Returns a pointer to the current default grid cell editor.
+
+ See wxGridCellEditor and the @ref overview_grid for more information
+ about cell editors and renderers.
*/
- int GetColAt(int colPos) const;
+ wxGridCellEditor* GetDefaultEditor() const;
/**
- Returns the pen used for vertical grid lines.
+ Returns the default editor for the specified cell.
- 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.
+ 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.
- See GetRowGridLinePen() for an example.
- */
- virtual wxPen GetColGridLinePen(int col);
+ Notice that the same may be achieved in a usually simpler way by
+ associating a custom editor with the given cell or cells.
+ The caller must call DecRef() on the returned pointer.
+ */
+ virtual wxGridCellEditor* GetDefaultEditorForCell(int row, int col) const;
/**
- Sets the arguments to the current column label alignment values.
+ Returns the default editor for the specified cell.
- Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
- or @c wxALIGN_RIGHT.
+ 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.
- Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
- @c wxALIGN_BOTTOM.
- */
- void GetColLabelAlignment(int* horiz, int* vert) const;
+ Notice that the same may be achieved in a usually simpler way by
+ associating a custom editor with the given cell or cells.
- /**
- Returns the current height of the column labels.
+ The caller must call DecRef() on the returned pointer.
*/
- int GetColLabelSize() const;
+ wxGridCellEditor* GetDefaultEditorForCell(const wxGridCellCoords& c) const;
/**
- Returns the specified column label.
+ Returns the default editor for the cells containing values of the given
+ type.
- 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 minimal width to which a column may be resized.
+ 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.
- Use SetColMinimalAcceptableWidth() to change this value globally or
- SetColMinimalWidth() to do it for individual columns.
+ The caller must call DecRef() on the returned pointer.
*/
- int GetColMinimalAcceptableWidth() const;
+ virtual wxGridCellEditor* GetDefaultEditorForType(const wxString& typeName) const;
/**
- Returns the position of the specified column.
- */
- int GetColPos(int colID) const;
+ Returns a pointer to the current default grid cell renderer.
- /**
- Returns the width of the specified column.
+ See wxGridCellRenderer and the @ref overview_grid for more information
+ about cell editors and renderers.
+
+ The caller must call DecRef() on the returned pointer.
*/
- int GetColSize(int col) const;
+ wxGridCellRenderer* GetDefaultRenderer() const;
/**
- Returns the default cell alignment.
-
- Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
- or @c wxALIGN_RIGHT.
+ Returns the default renderer for the given cell.
- Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
- @c wxALIGN_BOTTOM.
+ 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.
- @see SetDefaultCellAlignment()
+ The caller must call DecRef() on the returned pointer.
*/
- void GetDefaultCellAlignment(int* horiz, int* vert) const;
+ virtual wxGridCellRenderer* GetDefaultRendererForCell(int row, int col) const;
/**
- Returns the current default background colour for grid cells.
+ Returns the default renderer for the cell containing values of the
+ given type.
+
+ @see GetDefaultEditorForType()
*/
- wxColour GetDefaultCellBackgroundColour() const;
+ virtual wxGridCellRenderer* GetDefaultRendererForType(const wxString& typeName) const;
/**
- Returns the current default font for grid cell text.
+ Hides the in-place cell edit control.
*/
- wxFont GetDefaultCellFont() const;
+ void HideCellEditControl();
/**
- Returns the current default colour for grid cell text.
+ Returns @true if the in-place edit control is currently enabled.
*/
- wxColour GetDefaultCellTextColour() const;
+ bool IsCellEditControlEnabled() const;
/**
- Returns the default height for column labels.
+ Returns @true if the current cell is read-only.
+
+ @see SetReadOnly(), IsReadOnly()
*/
- int GetDefaultColLabelSize() const;
+ bool IsCurrentCellReadOnly() const;
/**
- Returns the current default width for grid columns.
+ 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.
*/
- int GetDefaultColSize() const;
+ bool IsEditable() const;
/**
- Returns a pointer to the current default grid cell editor.
+ Returns @true if the cell at the specified location can't be edited.
- See wxGridCellEditor and the @ref overview_grid "wxGrid overview"
- for more information about cell editors and renderers.
+ @see SetReadOnly(), IsCurrentCellReadOnly()
*/
- wxGridCellEditor* GetDefaultEditor() const;
+ bool IsReadOnly(int row, int col) const;
- //@{
/**
- Returns the default editor for the specified cell.
+ Register a new data type.
- 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.
+ 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.
- Notice that the same may be usually achieved in simpler way by
- associating a custom editor with the given cell or 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.
- The caller must call DecRef() on the returned pointer.
+ 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.
*/
- virtual wxGridCellEditor* GetDefaultEditorForCell(int row, int col) const;
- wxGridCellEditor* GetDefaultEditorForCell(const wxGridCellCoords& c) const;
- //@}
+ void RegisterDataType(const wxString& typeName,
+ wxGridCellRenderer* renderer,
+ wxGridCellEditor* editor);
/**
- 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.
+ Sets the value of the current grid cell to the current in-place edit
+ control value.
- The caller must call DecRef() on the returned pointer.
+ 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.
*/
- virtual wxGridCellEditor *
- GetDefaultEditorForType(const wxString& typeName) const;
+ void SaveEditControlValue();
/**
- Returns the pen used for grid lines.
+ Sets the editor for the grid cell at the specified location.
- 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.
+ The grid will take ownership of the pointer.
- @see GetColGridLinePen(), GetRowGridLinePen()
+ See wxGridCellEditor and the @ref overview_grid for more information
+ about cell editors and renderers.
*/
- virtual wxPen GetDefaultGridLinePen();
+ void SetCellEditor(int row, int col, wxGridCellEditor* editor);
/**
- Returns a pointer to the current default grid cell renderer.
+ Sets 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 grid will take ownership of the pointer.
- The caller must call DecRef() on the returned pointer.
+ See wxGridCellRenderer and the @ref overview_grid for more information
+ about cell editors and renderers.
*/
- wxGridCellRenderer* GetDefaultRenderer() const;
+ void SetCellRenderer(int row, int col, wxGridCellRenderer* renderer);
/**
- Returns the default renderer for the given cell.
+ Sets the string value for the cell at the specified location.
- 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.
+ 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 caller must call DecRef() on the returned pointer.
+ See wxGridTableBase::CanSetValueAs() and the @ref overview_grid for
+ more information.
*/
- virtual wxGridCellRenderer *GetDefaultRendererForCell(int row, int col) const;
-
+ void SetCellValue(int row, int col, const wxString& s);
/**
- Returns the default renderer for the cell containing values of the
- given type.
+ Sets the string value for the cell at the specified location.
- @see GetDefaultEditorForType()
- */
- virtual wxGridCellRenderer *
- GetDefaultRendererForType(const wxString& typeName) const;
+ 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.
- /**
- Returns the default width for the row labels.
+ See wxGridTableBase::CanSetValueAs() and the @ref overview_grid for
+ more information.
*/
- int GetDefaultRowLabelSize() const;
-
+ void SetCellValue(const wxGridCellCoords& coords, const wxString& s);
/**
- Returns the current default height for grid rows.
- */
- int GetDefaultRowSize() const;
+ @deprecated Please use SetCellValue(int,int,const wxString&) or
+ SetCellValue(const wxGridCellCoords&,const wxString&)
+ instead.
- /**
- Returns the current grid cell column position.
- */
- int GetGridCursorCol() const;
+ Sets the string value for the cell at the specified location.
- /**
- Returns the current grid cell row position.
+ 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.
+
+ See wxGridTableBase::CanSetValueAs() and the @ref overview_grid for
+ more information.
*/
- int GetGridCursorRow() const;
+ void SetCellValue(const wxString& val, int row, int col);
/**
- Returns the colour used for grid lines.
+ Sets the specified column to display boolean values.
- @see GetDefaultGridLinePen()
+ @see SetColFormatCustom()
*/
- wxColour GetGridLineColour() const;
+ void SetColFormatBool(int col);
/**
- Returns the colour used for the background of row and column labels.
- */
- wxColour GetLabelBackgroundColour() const;
+ Sets the specified column to display data in a custom format.
- /**
- Returns the font used for row and column labels.
- */
- wxFont GetLabelFont() const;
+ 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.
- /**
- Returns the colour used for row and column label text.
+ See the @ref overview_grid for more information on working with custom
+ data types.
*/
- wxColour GetLabelTextColour() const;
+ void SetColFormatCustom(int col, const wxString& typeName);
/**
- Returns the total number of grid columns.
+ Sets the specified column to display floating point values with the
+ given width and precision.
- This is the same as the number of columns in the underlying grid
- table.
+ @see SetColFormatCustom()
*/
- int GetNumberCols() const;
+ void SetColFormatFloat(int col, int width = -1, int precision = -1);
/**
- Returns the total number of grid rows.
+ Sets the specified column to display integer values.
- This is the same as the number of rows in the underlying grid table.
+ @see SetColFormatCustom()
*/
- int GetNumberRows() const;
+ void SetColFormatNumber(int col);
/**
- Returns the attribute for the given cell creating one if necessary.
+ Sets the default editor for grid cells.
- 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.
+ The grid will take ownership of the pointer.
- This function may only be called if CanHaveAttributes() returns @true.
+ See wxGridCellEditor and the @ref overview_grid for more information
+ about cell editors and renderers.
*/
- wxGridCellAttr *GetOrCreateCellAttr(int row, int col) const;
+ void SetDefaultEditor(wxGridCellEditor* editor);
/**
- Returns the pen used for horizontal grid lines.
+ Sets the default renderer for grid cells.
- 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.
+ The grid will take ownership of the pointer.
- 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
+ See wxGridCellRenderer and the @ref overview_grid for more information
+ about cell editors and renderers.
*/
- virtual wxPen GetRowGridLinePen(int row);
+ void SetDefaultRenderer(wxGridCellRenderer* renderer);
/**
- Returns the alignment used for row labels.
-
- Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
- or @c wxALIGN_RIGHT.
+ Makes the cell at the specified location read-only or editable.
- Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
- @c wxALIGN_BOTTOM.
+ @see IsReadOnly()
*/
- void GetRowLabelAlignment(int* horiz, int* vert) const;
+ void SetReadOnly(int row, int col, bool isReadOnly = true);
/**
- Returns the current width of the row labels.
+ Displays the in-place cell edit control for the current cell.
*/
- int GetRowLabelSize() const;
+ void ShowCellEditControl();
- /**
- 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;
/**
- Returns the minimal size to which rows can be resized.
+ @name Column and Row Sizes
- Use SetRowMinimalAcceptableHeight() to change this value globally or
- SetRowMinimalHeight() to do it for individual cells.
+ @see @ref overview_grid_resizing
+ */
+ //@{
- @see GetColMinimalAcceptableWidth()
+ /**
+ Automatically sets the height and width of all rows and columns to fit
+ their contents.
*/
- int GetRowMinimalAcceptableHeight() const;
+ void AutoSize();
/**
- Returns the height of the specified row.
+ Automatically adjusts width of the column to fit its label.
*/
- int GetRowSize(int row) const;
+ void AutoSizeColLabelSize(int col);
/**
- Returns the number of pixels per horizontal scroll increment.
-
- The default is 15.
-
- @see GetScrollLineY(), SetScrollLineX(), SetScrollLineY()
+ Automatically sizes the column to fit its contents. If @a setAsMin is
+ @true the calculated width will also be set as the minimal width for
+ the column.
*/
- int GetScrollLineX() const;
+ void AutoSizeColumn(int col, bool setAsMin = true);
/**
- Returns the number of pixels per vertical scroll increment.
-
- The default is 15.
-
- @see GetScrollLineX(), SetScrollLineX(), SetScrollLineY()
+ Automatically sizes all columns to fit their contents. If @a setAsMin
+ is @true the calculated widths will also be set as the minimal widths
+ for the columns.
*/
- int GetScrollLineY() const;
+ void AutoSizeColumns(bool setAsMin = true);
/**
- 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).
+ Automatically sizes the row to fit its contents. If @a setAsMin is
+ @true the calculated height will also be set as the minimal height for
+ the row.
*/
- wxGridCellCoordsArray GetSelectedCells() const;
+ void AutoSizeRow(int row, bool setAsMin = true);
/**
- Returns an array of selected columns.
-
- Please notice that this method alone is not sufficient to find all the
- 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.
+ Automatically adjusts height of the row to fit its label.
*/
- wxArrayInt GetSelectedCols() const;
+ void AutoSizeRowLabelSize(int col);
/**
- Returns an array of selected rows.
-
- 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.
+ Automatically sizes all rows to fit their contents. If @a setAsMin is
+ @true the calculated heights will also be set as the minimal heights
+ for the rows.
*/
- wxArrayInt GetSelectedRows() const;
+ void AutoSizeRows(bool setAsMin = true);
/**
- Access or update the selection fore/back colours
+ Returns the current height of the column labels.
*/
- wxColour GetSelectionBackground() const;
+ int GetColLabelSize() const;
/**
- Returns an array of the bottom right corners of blocks of selected
- cells.
+ Returns the minimal width to which a column may be resized.
- Please see GetSelectedCells() for more information about the selection
- representation in wxGrid.
+ Use SetColMinimalAcceptableWidth() to change this value globally or
+ SetColMinimalWidth() to do it for individual columns.
- @see GetSelectionBlockTopLeft()
+ @see GetRowMinimalAcceptableHeight()
*/
- wxGridCellCoordsArray GetSelectionBlockBottomRight() const;
+ int GetColMinimalAcceptableWidth() const;
/**
- Returns an array of the top left corners of blocks of selected cells.
+ Returns the width of the specified column.
+ */
+ int GetColSize(int col) const;
- Please see GetSelectedCells() for more information about the selection
- representation in wxGrid.
+ /**
+ Returns @true if the specified column is not currently hidden.
+ */
+ bool IsColShown(int col) const;
- @see GetSelectionBlockBottomRight()
+ /**
+ Returns the default height for column labels.
*/
- wxGridCellCoordsArray GetSelectionBlockTopLeft() const;
+ int GetDefaultColLabelSize() const;
/**
- Returns the colour used for drawing the selection foreground.
+ Returns the current default width for grid columns.
*/
- wxColour GetSelectionForeground() const;
+ int GetDefaultColSize() const;
/**
- Returns the current selection mode.
+ Returns the default width for the row labels.
+ */
+ int GetDefaultRowLabelSize() const;
- @see SetSelectionMode().
+ /**
+ Returns the current default height for grid rows.
*/
- wxGridSelectionModes GetSelectionMode() const;
+ int GetDefaultRowSize() const;
/**
- Returns a base pointer to the current table object.
+ Returns the minimal size to which rows can be resized.
- The returned pointer is still owned by the grid.
+ Use SetRowMinimalAcceptableHeight() to change this value globally or
+ SetRowMinimalHeight() to do it for individual cells.
+
+ @see GetColMinimalAcceptableWidth()
*/
- wxGridTableBase *GetTable() const;
+ int GetRowMinimalAcceptableHeight() const;
- //@{
/**
- Make the given cell current and ensure it is visible.
+ Returns the current width of the row labels.
+ */
+ int GetRowLabelSize() const;
- 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.
+ /**
+ Returns the height of the specified row.
+ */
+ int GetRowSize(int row) const;
+
+ /**
+ Returns @true if the specified row is not currently hidden.
*/
- void GoToCell(int row, int col);
- void GoToCell(const wxGridCellCoords& coords);
- //@}
+ bool IsRowShown(int row) const;
/**
- Returns @true if drawing of grid lines is turned on, @false otherwise.
+ 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.
*/
- bool GridLinesEnabled() const;
+ void SetColLabelSize(int height);
/**
- Hides the in-place cell edit control.
+ Sets the minimal @a width to which the user can resize columns.
+
+ @see GetColMinimalAcceptableWidth()
*/
- void HideCellEditControl();
+ void SetColMinimalAcceptableWidth(int width);
/**
- Hides the column labels by calling SetColLabelSize()
- with a size of 0. Show labels again by calling that method with
- a width greater than 0.
+ Sets the minimal @a width for the specified column @a col.
+
+ 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 HideColLabels();
+ void SetColMinimalWidth(int col, int width);
/**
- Hides the row labels by calling SetRowLabelSize() with a size of 0.
+ Sets the width of the specified column.
- The labels can be shown again by calling SetRowLabelSize() with a width
- greater than 0.
+ @param col
+ The column index.
+ @param width
+ The new column width in pixels, 0 to hide the column or -1 to fit
+ the column width to its label width.
*/
- void HideRowLabels();
+ void SetColSize(int col, int width);
/**
- Inserts one or more new columns into a grid with the first new column
- at the specified position.
+ Hides the specified column.
- 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.
+ To show the column later you need to call SetColSize() with non-0
+ width or ShowCol().
- @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);
+ @param col
+ The column index.
+ */
+ void HideCol(int col);
/**
- Inserts one or more new rows into a grid with the first new row at the
- specified position.
+ Shows the previously hidden column by resizing it to non-0 size.
- Notice that you must implement wxGridTableBase::InsertRows() if you use
- a grid with a custom table, please see InsertCols() for more
- information.
+ @see HideCol(), SetColSize()
+ */
+ void ShowCol(int col);
- @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);
/**
- Returns @true if the in-place edit control is currently enabled.
+ 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.
*/
- bool IsCellEditControlEnabled() const;
+ void SetDefaultColSize(int width, bool resizeExistingCols = false);
/**
- Returns @true if the current cell is read-only.
+ Sets the default height for rows in the grid.
- @see SetReadOnly(), IsReadOnly()
+ 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.
*/
- bool IsCurrentCellReadOnly() const;
+ void SetDefaultRowSize(int height, bool resizeExistingRows = false);
/**
- Returns @false if the whole grid has been set as read-only or @true
- otherwise.
+ Sets the width of the row labels.
- See EnableEditing() for more information about controlling the editing
- status of grid cells.
+ 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.
*/
- bool IsEditable() const;
+ void SetRowLabelSize(int width);
- //@{
/**
- Is this cell currently selected?
+ Sets the minimal row @a height used by default.
+
+ See SetColMinimalAcceptableWidth() for more information.
*/
- bool IsInSelection(int row, int col) const;
- bool IsInSelection(const wxGridCellCoords& coords) const;
- //@}
+ void SetRowMinimalAcceptableHeight(int height);
/**
- Returns @true if the cell at the specified location can't be edited.
+ Sets the minimal @a height for the specified @a row.
- @see SetReadOnly(), IsCurrentCellReadOnly()
+ See SetColMinimalWidth() for more information.
*/
- bool IsReadOnly(int row, int col) const;
+ void SetRowMinimalHeight(int row, int height);
/**
- Returns @true if there are currently any selected cells, rows, columns
- or blocks.
+ Sets the height of the specified row.
+
+ See SetColSize() for more information.
*/
- bool IsSelection() const;
+ void SetRowSize(int row, int height);
- //@{
/**
- Returns @true if a cell is either wholly or at least partially visible
- in the grid window.
+ Hides the specified row.
+
+ To show the row later you need to call SetRowSize() with non-0
+ width or ShowRow().
+
+ @param col
+ The row index.
+ */
+ void HideRow(int col);
+
+ /**
+ Shows the previously hidden row by resizing it to non-0 size.
+
+ @see HideRow(), SetRowSize()
+ */
+ void ShowRow(int col);
+
+ /**
+ Get size information for all columns at once.
+
+ This method is useful when the information about all column widths
+ needs to be saved. The widths can be later restored using
+ SetColSizes().
+
+ @sa wxGridSizesInfo, GetRowSizes()
+ */
+ wxGridSizesInfo GetColSizes() const;
+
+ /**
+ Get size information for all row at once.
+
+ @sa wxGridSizesInfo, GetColSizes()
+ */
+ wxGridSizesInfo GetRowSizes() const;
+
+ /**
+ Restore all columns sizes.
+
+ This is usually called with wxGridSizesInfo object previously returned
+ by GetColSizes().
+
+ @sa SetRowSizes()
+ */
+ void SetColSizes(const wxGridSizesInfo& sizeInfo);
+
+ /**
+ Restore all rows sizes.
+
+ @sa SetColSizes()
+ */
+ void SetRowSizes(const wxGridSizesInfo& sizeInfo);
- 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;
- bool IsVisible(const wxGridCellCoords& coords,
- bool wholeCellVisible = true) const;
//@}
+
+ /**
+ @name User-Resizing and Dragging
+
+ Functions controlling various interactive mouse operations.
+
+ By default, columns and rows can be resized by dragging the edges of
+ their labels (this can be disabled using DisableDragColSize() and
+ DisableDragRowSize() methods). And if grid line dragging is enabled with
+ EnableDragGridSize() they can also be resized by dragging the right or
+ bottom edge of the grid cells.
+
+ Columns can also be moved to interactively change their order but this
+ needs to be explicitly enabled with EnableDragColMove().
+ */
//@{
+
/**
- Brings the specified cell into the visible grid cell area with minimal
- scrolling.
+ Return @true if the dragging of cells is enabled or @false otherwise.
+ */
+ bool CanDragCell() const;
- Does nothing if the cell is already visible.
+ /**
+ Returns @true if columns can be moved by dragging with the mouse.
+
+ Columns can be moved by dragging on their labels.
*/
- void MakeCellVisible(int row, int col);
- void MakeCellVisible(const wxGridCellCoords& coords);
+ bool CanDragColMove() const;
+
+ /**
+ Returns @true if the given column can be resized by dragging with the
+ mouse.
+
+ This function returns @true if resizing the columns interactively is
+ globally enabled, i.e. if DisableDragColSize() hadn't been called, and
+ if this column wasn't explicitly marked as non-resizable with
+ DisableColResize().
+ */
+ bool CanDragColSize(int col) const;
+
+ /**
+ Return @true if the dragging of grid lines to resize rows and columns
+ is enabled or @false otherwise.
+ */
+ bool CanDragGridSize() const;
+
+ /**
+ Returns @true if the given row can be resized by dragging with the
+ mouse.
+
+ This is the same as CanDragColSize() but for rows.
+ */
+ bool CanDragRowSize(int row) const;
+
+ /**
+ Disable interactive resizing of the specified column.
+
+ This method allows to disable resizing of an individual column in a
+ grid where the columns are otherwise resizable (which is the case by
+ default).
+
+ Notice that currently there is no way to make some columns resizable in
+ a grid where columns can't be resized by default as there doesn't seem
+ to be any need for this in practice. There is also no way to make the
+ column marked as fixed using this method resizeable again because it is
+ supposed that fixed columns are used for static parts of the grid and
+ so should remain fixed during the entire grid lifetime.
+
+ Also notice that disabling interactive column resizing will not prevent
+ the program from changing the column size.
+
+ @see EnableDragColSize()
+ */
+ void DisableColResize(int col);
+
+ /**
+ Disable interactive resizing of the specified row.
+
+ This is the same as DisableColResize() but for rows.
+
+ @see EnableDragRowSize()
+ */
+ void DisableRowResize(int row);
+
+ /**
+ 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().
+ */
+ void DisableDragColSize();
+
+ /**
+ 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().
+ */
+ void DisableDragRowSize();
+
+ /**
+ Enables or disables cell dragging with the mouse.
+ */
+ void EnableDragCell(bool enable = true);
+
+ /**
+ Enables or disables column moving by dragging with the mouse.
+ */
+ void EnableDragColMove(bool enable = true);
+
+ /**
+ Enables or disables column sizing by dragging with the mouse.
+
+ @see DisableColResize()
+ */
+ void EnableDragColSize(bool enable = true);
+
+ /**
+ Enables or disables row and column resizing by dragging gridlines with
+ the mouse.
+ */
+ void EnableDragGridSize(bool enable = true);
+
+ /**
+ Enables or disables row sizing by dragging with the mouse.
+
+ @see DisableRowResize()
+ */
+ void EnableDragRowSize(bool enable = true);
+
+ /**
+ Returns the column ID of the specified column position.
+ */
+ int GetColAt(int colPos) const;
+
+ /**
+ Returns the position of the specified column.
+ */
+ int GetColPos(int colID) const;
+
+ /**
+ Sets the position of the specified column.
+ */
+ void SetColPos(int colID, int newPos);
+
+ /**
+ Sets the positions of all columns at once.
+
+ This method takes an array containing the indices of the columns in
+ their display order, i.e. uses the same convention as
+ wxHeaderCtrl::SetColumnsOrder().
+ */
+ void SetColumnsOrder(const wxArrayInt& order);
+
+ /**
+ Resets the position of the columns to the default.
+ */
+ void ResetColPos();
+
//@}
+
+ /**
+ @name Cursor Movement
+ */
+ //@{
+
+ /**
+ Returns the current grid cell column position.
+ */
+ int GetGridCursorCol() const;
+
+ /**
+ Returns the current grid cell row position.
+ */
+ int GetGridCursorRow() const;
+
+ /**
+ Make the given cell current and ensure it is visible.
+
+ This method is equivalent to calling MakeCellVisible() and
+ SetGridCursor() and so, as with the latter, a @c 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);
+ /**
+ 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 @c wxEVT_GRID_SELECT_CELL
+ event is generated by it and the selected cell doesn't change if the
+ event is vetoed.
+ */
+ void GoToCell(const wxGridCellCoords& coords);
+
/**
Moves the grid cursor down by one row.
bool MovePageUp();
/**
- 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.
+ Set the grid cursor to the specified cell.
- 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.
+ The grid cursor indicates the current cell and can be moved by the user
+ using the arrow keys or the mouse.
- 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.
+ Calling this function generates a @c wxEVT_GRID_SELECT_CELL event and
+ if the event handler vetoes this event, the cursor is not moved.
- @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.
+ This function doesn't make the target call visible, use GoToCell() to
+ do this.
*/
- void RegisterDataType(const wxString& typeName,
- wxGridCellRenderer* renderer,
- wxGridCellEditor* editor);
-
+ void SetGridCursor(int row, int col);
/**
- Sets the value of the current grid cell to the current in-place edit
- control value.
+ Set the grid cursor to the specified cell.
- 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.
+ 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 @c 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 SaveEditControlValue();
+ void SetGridCursor(const wxGridCellCoords& coords);
+
+ //@}
+
/**
- Selects all cells in the grid.
+ @name User Selection
+ */
+ //@{
+
+ /**
+ Deselects all cells that are currently selected.
*/
- void SelectAll();
+ void ClearSelection();
- //@{
/**
- Selects a rectangular block of cells.
+ Returns an array of individually selected 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,
+ 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 columns.
+
+ Please notice that this method alone is not sufficient to find all the
+ 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.
+
+ 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;
+
+ /**
+ Returns the colour used for drawing the selection background.
+ */
+ wxColour GetSelectionBackground() const;
+
+ /**
+ 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.
+
+ 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().
+ */
+ wxGridSelectionModes GetSelectionMode() const;
+
+ /**
+ Returns @true if the given cell is selected.
+ */
+ bool IsInSelection(int row, int col) const;
+ /**
+ Returns @true if the given cell is selected.
+ */
+ bool IsInSelection(const wxGridCellCoords& coords) const;
+
+ /**
+ Returns @true if there are currently any selected cells, rows, columns
+ or blocks.
+ */
+ bool IsSelection() const;
+
+ /**
+ Selects all cells in the grid.
+ */
+ void SelectAll();
+
+ /**
+ 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,
bool addToSelected = false);
+ /**
+ 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(const wxGridCellCoords& topLeft,
const wxGridCellCoords& bottomRight,
bool addToSelected = false);
- //@}
/**
Selects the specified column.
*/
void SelectRow(int row, bool addToSelected = false);
- //@{
/**
- Sets the horizontal and vertical alignment for grid cell text at the
- specified location.
+ 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);
- Horizontal alignment should be one of @c wxALIGN_LEFT, @c
- wxALIGN_CENTRE or @c wxALIGN_RIGHT.
+ /**
+ Set the selection behaviour of the grid.
- Vertical alignment should be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE
- or @c wxALIGN_BOTTOM.
+ 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 SetCellAlignment(int row, int col, int horiz, int vert);
- void SetCellAlignment(int align, int row, int col);
+ void SetSelectionMode(wxGridSelectionModes selmode);
+
//@}
+
+ /**
+ @name Scrolling
+ */
//@{
+
/**
- Set the background colour for the given cell or all cells by default.
+ Returns the number of pixels per horizontal scroll increment.
+
+ The default is 15.
+
+ @see GetScrollLineY(), SetScrollLineX(), SetScrollLineY()
*/
- void SetCellBackgroundColour(int row, int col, const wxColour& colour);
- //@}
+ int GetScrollLineX() const;
/**
- Sets the editor for the grid cell at the specified location.
+ Returns the number of pixels per vertical scroll increment.
- The grid will take ownership of the pointer.
+ The default is 15.
- See wxGridCellEditor and the @ref overview_grid "wxGrid overview"
- for more information about cell editors and renderers.
+ @see GetScrollLineX(), SetScrollLineX(), SetScrollLineY()
*/
- void SetCellEditor(int row, int col, wxGridCellEditor* editor);
+ int GetScrollLineY() const;
/**
- Sets the font for text in the grid cell at the specified location.
+ Returns @true if a cell is either entirely 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.
*/
- void SetCellFont(int row, int col, const wxFont& font);
+ bool IsVisible(int row, int col, bool wholeCellVisible = true) const;
+ /**
+ Returns @true if a cell is either entirely 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(const wxGridCellCoords& coords,
+ bool wholeCellVisible = true) const;
/**
- Sets the renderer for the grid cell at the specified location.
+ Brings the specified cell into the visible grid cell area with minimal
+ scrolling.
- The grid will take ownership of the pointer.
+ Does nothing if the cell is already visible.
+ */
+ void MakeCellVisible(int row, int col);
+ /**
+ Brings the specified cell into the visible grid cell area with minimal
+ scrolling.
- See wxGridCellRenderer and the @ref overview_grid "wxGrid overview"
- for more information about cell editors and renderers.
+ Does nothing if the cell is already visible.
*/
- void SetCellRenderer(int row, int col, wxGridCellRenderer* renderer);
+ void MakeCellVisible(const wxGridCellCoords& coords);
- //@{
/**
- Sets the text colour for the given cell or all cells by default.
+ Sets the number of pixels per horizontal scroll increment.
+
+ The default is 15.
+
+ @see GetScrollLineX(), GetScrollLineY(), SetScrollLineY()
*/
- void SetCellTextColour(int row, int col, const wxColour& colour);
- void SetCellTextColour(const wxColour& val, int row, int col);
- void SetCellTextColour(const wxColour& colour);
- //@}
+ void SetScrollLineX(int x);
- //@{
/**
- Sets the string value for the cell at the specified location.
+ Sets the number of pixels per vertical scroll increment.
- 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.
+ The default is 15.
- See wxGridTableBase::CanSetValueAs and the @ref overview_grid
- "wxGrid overview" for more information.
+ @see GetScrollLineX(), GetScrollLineY(), SetScrollLineX()
*/
- void SetCellValue(int row, int col, const wxString& s);
- void SetCellValue(const wxGridCellCoords& coords, const wxString& s);
- void SetCellValue(const wxString& val, int row, int col);
+ void SetScrollLineY(int y);
+
//@}
- /**
- 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_grid "wxGrid overview".
- */
- void SetColAttr(int col, wxGridCellAttr* attr);
+ /**
+ @name Cell and Device Coordinate Translation
+ */
+ //@{
/**
- Sets the specified column to display boolean values.
+ Convert grid cell coordinates to grid window pixel coordinates.
- @see SetColFormatCustom()
+ This function returns the rectangle that encloses the block of cells
+ limited by @a topLeft and @a bottomRight cell in device coords and
+ clipped to the client size of the grid window.
+
+ @see CellToRect()
*/
- void SetColFormatBool(int col);
+ wxRect BlockToDeviceRect(const wxGridCellCoords& topLeft,
+ const wxGridCellCoords& bottomRight) const;
/**
- Sets the specified column to display data in a custom format.
+ Return the rectangle corresponding to the grid cell's size and position
+ in logical coordinates.
- 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 BlockToDeviceRect()
+ */
+ wxRect CellToRect(int row, int col) const;
+ /**
+ Return the rectangle corresponding to the grid cell's size and position
+ in logical coordinates.
- See the @ref overview_grid "wxGrid overview" for more
- information on working with custom data types.
+ @see BlockToDeviceRect()
*/
- void SetColFormatCustom(int col, const wxString& typeName);
+ wxRect CellToRect(const wxGridCellCoords& coords) const;
/**
- Sets the specified column to display floating point values with the
- given width and precision.
+ Returns the column at the given pixel position.
- @see SetColFormatCustom()
+ @param x
+ The x position to evaluate.
+ @param clipToMinMax
+ If @true, rather than returning @c wxNOT_FOUND, it returns either
+ the first or last column depending on whether @a x is too far to
+ the left or right respectively.
+ @return
+ The column index or @c wxNOT_FOUND.
*/
- void SetColFormatFloat(int col, int width = -1, int precision = -1);
+ int XToCol(int x, bool clipToMinMax = false) const;
/**
- Sets the specified column to display integer values.
+ Returns the column whose right hand edge is close to the given logical
+ @a x position.
- @see SetColFormatCustom()
+ If no column edge is near to this position @c wxNOT_FOUND is returned.
*/
- void SetColFormatNumber(int col);
+ int XToEdgeOfCol(int x) const;
/**
- Sets the horizontal and vertical alignment of column label text.
+ Translates logical pixel coordinates to the grid cell coordinates.
- 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.
+ 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()
+ */
+ wxGridCellCoords XYToCell(int x, int y) 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()
+ */
+ wxGridCellCoords XYToCell(const wxPoint& pos) const;
+ // XYToCell(int, int, wxGridCellCoords&) overload is intentionally
+ // undocumented, using it is ugly and non-const reference parameters are
+ // not used in wxWidgets API
+
+ /**
+ Returns the row whose bottom edge is close to the given logical @a y
+ position.
+
+ If no row edge is near to this position @c wxNOT_FOUND is returned.
*/
- void SetColLabelAlignment(int horiz, int vert);
+ int YToEdgeOfRow(int y) const;
/**
- Sets the height of the column labels.
+ Returns the grid row that corresponds to the logical @a y coordinate.
- 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.
+ Returns @c wxNOT_FOUND if there is no row at the @a y position.
*/
- void SetColLabelSize(int height);
+ int YToRow(int y, bool clipToMinMax = false) const;
+
+ //@}
+
/**
- Set the value for the given column label.
+ @name Miscellaneous Functions
+ */
+ //@{
- If you are using a custom grid table you must override
- wxGridTableBase::SetColLabelValue for this to have any effect.
+ /**
+ 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.
*/
- void SetColLabelValue(int col, const wxString& value);
+ bool AppendCols(int numCols = 1, bool updateLabels = true);
/**
- Sets the minimal width to which the user can resize columns.
+ Appends one or more new rows to the bottom of the grid.
- @see GetColMinimalAcceptableWidth()
+ 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.
*/
- void SetColMinimalAcceptableWidth(int width);
+ bool AppendRows(int numRows = 1, bool updateLabels = true);
/**
- Sets the minimal width for the specified column.
+ Return @true if the horizontal grid lines stop at the last column
+ boundary or @false if they continue to the end of the window.
- 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.
+ The default is to clip grid lines.
- @a width must be greater than the minimal acceptable column width as
- returned by GetColMinimalAcceptableWidth().
+ @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;
+
+ /**
+ 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() call will cause the grid to be repainted.
+
+ 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 SetColMinimalWidth(int col, int width);
+ void BeginBatch();
/**
- Sets the position of the specified column.
+ 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 SetColPos(int colID, int newPos);
+ void ClearGrid();
/**
- Sets the width of the specified column.
+ Change whether the horizontal grid lines are clipped by the end of the
+ last column.
- Notice that this function does not refresh the grid, you need to call
- ForceRefresh() to make the changes take effect immediately.
+ 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.
- @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.
+ @see AreHorzGridLinesClipped(), ClipVertGridLines()
+ */
+ void ClipHorzGridLines(bool clip);
+
+ /**
+ 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 AreVertGridLinesClipped(), ClipHorzGridLines()
+ */
+ void ClipVertGridLines(bool clip);
+
+ /**
+ Deletes one or more columns from a grid starting at the specified
+ position.
+
+ 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.
+
+ @return @true on success or @false if deleting columns failed.
*/
- void SetColSize(int col, int width);
+ bool DeleteCols(int pos = 0, int numCols = 1, bool updateLabels = true);
/**
- Sets the default horizontal and vertical alignment for grid cell text.
+ Deletes one or more rows from a grid starting at the specified
+ position.
- 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.
+ 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.
*/
- void SetDefaultCellAlignment(int horiz, int vert);
+ bool DeleteRows(int pos = 0, int numRows = 1, bool updateLabels = true);
/**
- Sets the default background colour for grid cells.
+ 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
*/
- void SetDefaultCellBackgroundColour(const wxColour& colour);
+ void EndBatch();
/**
- Sets the default font to be used for grid cell text.
+ Overridden wxWindow method.
*/
- void SetDefaultCellFont(const wxFont& font);
+ virtual void Fit();
/**
- Sets the current default colour for grid cell text.
+ Causes immediate repainting of the grid.
+
+ Use this instead of the usual wxWindow::Refresh().
*/
- void SetDefaultCellTextColour(const wxColour& colour);
+ void ForceRefresh();
/**
- Sets the default width for columns in the grid.
+ Returns the number of times that BeginBatch() has been called without
+ (yet) matching calls to EndBatch(). While the grid's batch count is
+ greater than zero the display will not be updated.
+ */
+ int GetBatchCount();
- This will only affect columns subsequently added to the grid unless
- @a resizeExistingCols is @true.
+ /**
+ Returns the total number of grid columns.
- If @a width is less than GetColMinimalAcceptableWidth(), then the
- minimal acceptable width is used instead of it.
+ This is the same as the number of columns in the underlying grid table.
*/
- void SetDefaultColSize(int width, bool resizeExistingCols = false);
+ int GetNumberCols() const;
/**
- Sets the default editor for grid cells.
-
- The grid will take ownership of the pointer.
+ Returns the total number of grid rows.
- See wxGridCellEditor and the @ref overview_grid "wxGrid overview"
- for more information about cell editors and renderers.
+ This is the same as the number of rows in the underlying grid table.
*/
- void SetDefaultEditor(wxGridCellEditor* editor);
+ int GetNumberRows() const;
/**
- Sets the default renderer for grid cells.
+ Returns the attribute for the given cell creating one if necessary.
- The grid will take ownership of the pointer.
+ 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.
- See wxGridCellRenderer and the @ref overview_grid "wxGrid overview"
- for more information about cell editors and renderers.
+ This function may only be called if CanHaveAttributes() returns @true.
*/
- void SetDefaultRenderer(wxGridCellRenderer* renderer);
+ wxGridCellAttr *GetOrCreateCellAttr(int row, int col) const;
/**
- Sets the default height for rows in the grid.
-
- This will only affect rows subsequently added to the grid unless
- @a resizeExistingRows is @true.
+ Returns a base pointer to the current table object.
- If @a height is less than GetRowMinimalAcceptableHeight(), then the
- minimal acceptable heihgt is used instead of it.
+ The returned pointer is still owned by the grid.
*/
- void SetDefaultRowSize(int height, bool resizeExistingRows = false);
+ wxGridTableBase *GetTable() const;
- //@{
/**
- Set the grid cursor to the specified cell.
-
- The grid cursor indicates the current cell and can be moved by the user
- using the arrow keys or the mouse.
+ Inserts one or more new columns into a grid with the first new column
+ at the specified position.
- Calling this function generates a wxEVT_GRID_SELECT_CELL event and if
- the event handler vetoes this event, the cursor is not moved.
+ 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 CreateGrid())
+ this process is automatic. If you are using a custom grid table
+ (specified with SetTable()) then you must override
+ wxGridTableBase::InsertCols() in your derived table class.
- This function doesn't make the target call visible, use GoToCell() to
- do this.
+ @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).
*/
- void SetGridCursor(int row, int col);
- void SetGridCursor(const wxGridCellCoords& coords);
- //@}
+ bool InsertCols(int pos = 0, int numCols = 1, bool updateLabels = true);
/**
- Sets the colour used to draw grid lines.
- */
- void SetGridLineColour(const wxColour& colour);
+ Inserts one or more new rows into a grid with the first new row at the
+ specified position.
- /**
- Sets the background colour for row and column labels.
- */
- void SetLabelBackgroundColour(const wxColour& colour);
+ Notice that you must implement wxGridTableBase::InsertRows() if you use
+ a grid with a custom table, please see InsertCols() for more
+ information.
- /**
- Sets the font for row and column labels.
+ @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).
*/
- void SetLabelFont(const wxFont& font);
+ bool InsertRows(int pos = 0, int numRows = 1, bool updateLabels = true);
/**
- Sets the colour for row and column label text.
+ 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_grid.
*/
- void SetLabelTextColour(const wxColour& colour);
+ void SetColAttr(int col, wxGridCellAttr* attr);
/**
Sets the extra margins used around the grid area.
*/
void SetMargins(int extraWidth, int extraHeight);
- /**
- Makes the cell at the specified location read-only or editable.
-
- @see IsReadOnly()
- */
- void SetReadOnly(int row, int col, bool isReadOnly = true);
-
/**
Sets the cell attributes for all cells in the specified row.
*/
void SetRowAttr(int row, wxGridCellAttr* attr);
- /**
- Sets the horizontal and vertical alignment of row label text.
-
- 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.
- */
- void SetRowLabelSize(int width);
/**
- Sets the value for the given row label.
+ @name Sorting support.
- 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);
+ wxGrid doesn't provide any support for sorting the data but it does
+ generate events allowing the user code to sort it and supports
+ displaying the sort indicator in the column used for sorting.
- /**
- Sets the minimal row height used by default.
+ To use wxGrid sorting support you need to handle wxEVT_GRID_COL_SORT
+ event (and not veto it) and resort the data displayed in the grid. The
+ grid will automatically update the sorting indicator on the column
+ which was clicked.
- See SetColMinimalAcceptableWidth() for more information.
- */
- void SetRowMinimalAcceptableHeight(int height);
+ You can also call the functions in this section directly to update the
+ sorting indicator. Once again, they don't do anything with the grid
+ data, it remains your responsibility to actually sort it appropriately.
+ */
+ //@{
/**
- Sets the minimal height for the specified row.
+ Return the column in which the sorting indicator is currently
+ displayed.
- See SetColMinimalWidth() for more information.
- */
- void SetRowMinimalHeight(int row, int height);
-
- /**
- Sets the height of the specified row.
+ Returns @c wxNOT_FOUND if sorting indicator is not currently displayed
+ at all.
- See SetColSize() for more information.
- */
- void SetRowSize(int row, int height);
+ @see SetSortingColumn()
+ */
+ int GetSortingColumn() const;
/**
- Sets the number of pixels per horizontal scroll increment.
-
- The default is 15.
+ Return @true if this column is currently used for sorting.
- @see GetScrollLineX(), GetScrollLineY(), SetScrollLineY()
- */
- void SetScrollLineX(int x);
+ @see GetSortingColumn()
+ */
+ bool IsSortingBy(int col) const;
/**
- Sets the number of pixels per vertical scroll increment.
-
- The default is 15.
+ Return @true if the current sorting order is ascending or @false if it
+ is descending.
- @see GetScrollLineX(), GetScrollLineY(), SetScrollLineX()
- */
- void SetScrollLineY(int y);
+ It only makes sense to call this function if GetSortingColumn() returns
+ a valid column index and not @c wxNOT_FOUND.
- /**
- Set the colour to be used for drawing the selection background.
- */
- void SetSelectionBackground(const wxColour& c);
+ @see SetSortingColumn()
+ */
+ bool IsSortOrderAscending() const;
/**
- Set the colour to be used for drawing the selection foreground.
- */
- void SetSelectionForeground(const wxColour& c);
+ Set the column to display the sorting indicator in and its direction.
- /**
- Set the selection behaviour of the grid.
+ @param col
+ The column to display the sorting indicator in or @c wxNOT_FOUND to
+ remove any currently displayed sorting indicator.
+ @param ascending
+ If @true, display the ascending sort indicator, otherwise display
+ the descending sort indicator.
- 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(wxGridSelectionModes selmode);
+ @see GetSortingColumn(), IsSortOrderAscending()
+ */
+ void SetSortingColumn(int col, bool ascending = true);
/**
- Passes a pointer to a custom grid table to be used by the grid.
+ Remove any currently shown sorting indicator.
- 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.
+ This is equivalent to calling SetSortingColumn() with @c wxNOT_FOUND
+ first argument.
+ */
+ void UnsetSortingColumn();
+ //@}
- 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,
- wxGridSelectionModes selmode = wxGridSelectCells);
/**
- Call this in order to make the column labels use a native look by using
- wxRenderer::DrawHeaderButton internally.
+ @name Accessors for component windows.
- 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);
+ Return the various child windows of wxGrid.
- /**
- Displays the in-place cell edit control for the current cell.
- */
- void ShowCellEditControl();
+ wxGrid is an empty parent window for 4 children representing the column
+ labels window (top), the row labels window (left), the corner window
+ (top left) and the main grid window. It may be necessary to use these
+ individual windows and not the wxGrid window itself if you need to
+ handle events for them (this can be done using wxEvtHandler::Connect()
+ or wxWindow::PushEventHandler()) or do something else requiring the use
+ of the correct window pointer. Notice that you should not, however,
+ change these windows (e.g. reposition them or draw over them) because
+ they are managed by wxGrid itself.
+ */
+ //@{
/**
- Returns the column at the given pixel position.
+ Return the main grid window containing the grid cells.
- @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.
- @return
- The column index or wxNOT_FOUND.
- */
- int XToCol(int x, bool clipToMinMax = false) const;
+ This window is always shown.
+ */
+ wxWindow *GetGridWindow() const;
/**
- Returns the column whose right hand edge is close to the given logical
- x position.
+ Return the row labels window.
- If no column edge is near to this position @c wxNOT_FOUND is returned.
- */
- int XToEdgeOfCol(int x) const;
+ This window is not shown if the row labels were hidden using
+ HideRowLabels().
+ */
+ wxWindow *GetGridRowLabelWindow() const;
- //@{
/**
- Translates logical pixel coordinates to the grid cell coordinates.
+ Return the column labels window.
- 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.
+ This window is not shown if the columns labels were hidden using
+ HideColLabels().
- @see XToCol(), YToRow()
+ Depending on whether UseNativeColHeader() was called or not this can be
+ either a wxHeaderCtrl or a plain wxWindow. This function returns a valid
+ window pointer in either case but in the former case you can also use
+ GetGridColHeader() to access it if you need wxHeaderCtrl-specific
+ functionality.
*/
-
- // 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;
-
- //@}
+ wxWindow *GetGridColLabelWindow() const;
/**
- Returns the row whose bottom edge is close to the given logical y
- position.
+ Return the window in the top left grid corner.
- If no row edge is near to this position @c wxNOT_FOUND is returned.
- */
- int YToEdgeOfRow(int y) const;
+ This window is shown only of both columns and row labels are shown and
+ normally doesn't contain anything. Clicking on it is handled by wxGrid
+ however and can be used to select the entire grid.
+ */
+ wxWindow *GetGridCornerLabelWindow() const;
/**
- Returns the grid row that corresponds to the logical y coordinate.
+ Return the header control used for column labels display.
- Returns @c wxNOT_FOUND if there is no row at the y position.
- */
- int YToRow(int y, bool clipToMinMax = false) const;
+ This function can only be called if UseNativeColHeader() had been
+ called.
+ */
+ wxHeaderCtrl *GetGridColHeader() const;
+
+ //@}
protected:
/**
This event class contains information about various grid events.
+ Notice that all grid event table macros are available in two versions:
+ @c EVT_GRID_XXX and @c EVT_GRID_CMD_XXX. The only difference between the
+ two is that the former doesn't allow to specify the grid window identifier
+ and so takes a single parameter, the event handler, but is not suitable if
+ there is more than one grid control in the window where the event table is
+ used (as it would catch the events from all the grids). The version with @c
+ CMD takes the id as first argument and the event handler as the second one
+ and so can be used with multiple grids as well. Otherwise there are no
+ difference between the two and only the versions without the id are
+ documented below for brevity.
+
@beginEventTable{wxGridEvent}
- @event{EVT_GRID_CELL_CHANGE(func)}
- The user changed the data in a cell. Processes a
- @c wxEVT_GRID_CELL_CHANGE event type.
+ @event{EVT_GRID_CELL_CHANGING(func)}
+ The user is about to change the data in a cell. The new cell value as
+ string is available from GetString() event object method. This event
+ can be vetoed if the change is not allowed.
+ Processes a @c wxEVT_GRID_CELL_CHANGING event type.
+ @event{EVT_GRID_CELL_CHANGED(func)}
+ The user changed the data in a cell. The old cell value as string is
+ available from GetString() event object method. Notice that vetoing
+ this event still works for backwards compatibility reasons but any new
+ code should only veto EVT_GRID_CELL_CHANGING event and not this one.
+ Processes a @c wxEVT_GRID_CELL_CHANGED event type.
@event{EVT_GRID_CELL_LEFT_CLICK(func)}
The user clicked a cell with the left mouse button. Processes a
@c wxEVT_GRID_CELL_LEFT_CLICK event type.
@event{EVT_GRID_SELECT_CELL(func)}
The user moved to, and selected a cell. Processes a
@c wxEVT_GRID_SELECT_CELL event type.
- @event{EVT_GRID_CMD_CELL_CHANGE(id, func)}
- The user changed the data in a cell; variant taking a window
- identifier. Processes a @c wxEVT_GRID_CELL_CHANGE event type.
- @event{EVT_GRID_CMD_CELL_LEFT_CLICK(id, func)}
- The user clicked a cell with the left mouse button; variant taking a
- window identifier. Processes a @c wxEVT_GRID_CELL_LEFT_CLICK event
- type.
- @event{EVT_GRID_CMD_CELL_LEFT_DCLICK(id, func)}
- The user double-clicked a cell with the left mouse button; variant
- taking a window identifier. Processes a @c wxEVT_GRID_CELL_LEFT_DCLICK
- event type.
- @event{EVT_GRID_CMD_CELL_RIGHT_CLICK(id, func)}
- The user clicked a cell with the right mouse button; variant taking a
- window identifier. Processes a @c wxEVT_GRID_CELL_RIGHT_CLICK event
- type.
- @event{EVT_GRID_CMD_CELL_RIGHT_DCLICK(id, func)}
- The user double-clicked a cell with the right mouse button; variant
- taking a window identifier. Processes a @c wxEVT_GRID_CELL_RIGHT_DCLICK
- event type.
- @event{EVT_GRID_CMD_EDITOR_HIDDEN(id, func)}
- The editor for a cell was hidden; variant taking a window identifier.
- Processes a @c wxEVT_GRID_EDITOR_HIDDEN event type.
- @event{EVT_GRID_CMD_EDITOR_SHOWN(id, func)}
- The editor for a cell was shown; variant taking a window identifier.
- Processes a @c wxEVT_GRID_EDITOR_SHOWN event type.
- @event{EVT_GRID_CMD_LABEL_LEFT_CLICK(id, func)}
- The user clicked a label with the left mouse button; variant taking a
- window identifier. Processes a @c wxEVT_GRID_LABEL_LEFT_CLICK event
- type.
- @event{EVT_GRID_CMD_LABEL_LEFT_DCLICK(id, func)}
- The user double-clicked a label with the left mouse button; variant
- taking a window identifier. Processes a @c wxEVT_GRID_LABEL_LEFT_DCLICK
- event type.
- @event{EVT_GRID_CMD_LABEL_RIGHT_CLICK(id, func)}
- The user clicked a label with the right mouse button; variant taking a
- window identifier. Processes a @c wxEVT_GRID_LABEL_RIGHT_CLICK event
- type.
- @event{EVT_GRID_CMD_LABEL_RIGHT_DCLICK(id, func)}
- The user double-clicked a label with the right mouse button; variant
- taking a window identifier. Processes a
- @c wxEVT_GRID_LABEL_RIGHT_DCLICK event type.
- @event{EVT_GRID_CMD_SELECT_CELL(id, func)}
- The user moved to, and selected a cell; variant taking a window
- identifier. Processes a @c wxEVT_GRID_SELECT_CELL event type.
+ @event{EVT_GRID_COL_MOVE(func)}
+ The user tries to change the order of the columns in the grid by
+ dragging the column specified by GetCol(). This event can be vetoed to
+ either prevent the user from reordering the column change completely
+ (but notice that if you don't want to allow it at all, you simply
+ shouldn't call wxGrid::EnableDragColMove() in the first place), vetoed
+ but handled in some way in the handler, e.g. by really moving the
+ column to the new position at the associated table level, or allowed to
+ proceed in which case wxGrid::SetColPos() is used to reorder the
+ columns display order without affecting the use of the column indices
+ otherwise.
+ This event macro corresponds to @c wxEVT_GRID_COL_MOVE event type.
+ @event{EVT_GRID_COL_SORT(func)}
+ This event is generated when a column is clicked by the user and its
+ name is explained by the fact that the custom reaction to a click on a
+ column is to sort the grid contents by this column. However the grid
+ itself has no special support for sorting and it's up to the handler of
+ this event to update the associated table. But if the event is handled
+ (and not vetoed) the grid supposes that the table was indeed resorted
+ and updates the column to indicate the new sort order and refreshes
+ itself.
+ This event macro corresponds to @c wxEVT_GRID_COL_SORT event type.
@endEventTable
@library{wxadv}
- @category{grid}
+ @category{grid,events}
*/
class wxGridEvent : public wxNotifyEvent
{
*/
wxGridEvent(int id, wxEventType type, wxObject* obj,
int row = -1, int col = -1, int x = -1, int y = -1,
- bool sel = true, bool control = false, bool shift = false,
- bool alt = false, bool meta = false);
+ bool sel = true, const wxKeyboardState& kbd = wxKeyboardState());
/**
Returns @true if the Alt key was down at the time of the event.
This event class contains information about a row/column resize event.
@beginEventTable{wxGridSizeEvent}
- @event{EVT_GRID_COL_SIZE(func)}
- The user resized a column by dragging it. Processes a
- @c wxEVT_GRID_COL_SIZE event type.
- @event{EVT_GRID_ROW_SIZE(func)}
- The user resized a row by dragging it. Processes a
- @c wxEVT_GRID_ROW_SIZE event type.
@event{EVT_GRID_CMD_COL_SIZE(id, func)}
- The user resized a column by dragging it; variant taking a window
- identifier. Processes a @c wxEVT_GRID_COL_SIZE event type.
+ The user resized a column, corresponds to @c wxEVT_GRID_COL_SIZE event
+ type.
@event{EVT_GRID_CMD_ROW_SIZE(id, func)}
- The user resized a row by dragging it; variant taking a window
- identifier. Processes a @c wxEVT_GRID_ROW_SIZE event type.
+ The user resized a row, corresponds to @c wxEVT_GRID_ROW_SIZE event
+ type.
+ @event{EVT_GRID_COL_SIZE(func)}
+ Same as EVT_GRID_CMD_COL_SIZE() but uses `wxID_ANY` id.
+ @event{EVT_GRID_ROW_SIZE(func)}
+ Same as EVT_GRID_CMD_ROW_SIZE() but uses `wxID_ANY` id.
@endEventTable
@library{wxadv}
- @category{grid}
+ @category{grid,events}
*/
class wxGridSizeEvent : public wxNotifyEvent
{
*/
wxGridSizeEvent(int id, wxEventType type, wxObject* obj,
int rowOrCol = -1, int x = -1, int y = -1,
- bool control = false, bool shift = false,
- bool alt = false, bool meta = false);
+ const wxKeyboardState& kbd = wxKeyboardState());
/**
Returns @true if the Alt key was down at the time of the event.
@endEventTable
@library{wxadv}
- @category{grid}
+ @category{grid,events}
*/
class wxGridRangeSelectEvent : public wxNotifyEvent
{
wxObject* obj,
const wxGridCellCoords& topLeft,
const wxGridCellCoords& bottomRight,
- bool sel = true, bool control = false,
- bool shift = false, bool alt = false,
- bool meta = false);
+ bool sel = true, const wxKeyboardState& kbd = wxKeyboardState());
/**
Returns @true if the Alt key was down at the time of the event.
@endEventTable
@library{wxadv}
- @category{grid}
+ @category{grid,events}
*/
class wxGridEditorCreatedEvent : public wxCommandEvent
{
projects / wxWidgets.git / blobdiff