X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ba9574c310e8930a0e71547507c9811e22633f30..a8bda512079352ba81933e278d9ccdb8ef7a9866:/interface/wx/grid.h diff --git a/interface/wx/grid.h b/interface/wx/grid.h index 27cd239a6e..90c5d9a3a5 100644 --- a/interface/wx/grid.h +++ b/interface/wx/grid.h @@ -3,7 +3,7 @@ // Purpose: interface of wxGrid and related classes // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -18,8 +18,10 @@ @library{wxadv} @category{grid} - @see wxGridCellBoolRenderer, wxGridCellFloatRenderer, - wxGridCellNumberRenderer, wxGridCellStringRenderer + @see wxGridCellAutoWrapStringRenderer, wxGridCellBoolRenderer, + wxGridCellDateTimeRenderer, wxGridCellEnumRenderer, + wxGridCellFloatRenderer, wxGridCellNumberRenderer, + wxGridCellStringRenderer */ class wxGridCellRenderer { @@ -50,6 +52,31 @@ public: int row, int col) = 0; }; +/** + @class wxGridCellAutoWrapStringRenderer + + This class may be used to format string data in a cell. The too + long lines are wrapped to be shown entirely at word boundaries. + + @library{wxadv} + @category{grid} + + @see wxGridCellRenderer, wxGridCellBoolRenderer, + wxGridCellDateTimeRenderer, wxGridCellEnumRenderer, + wxGridCellFloatRenderer, wxGridCellNumberRenderer, + wxGridCellStringRenderer +*/ + +class wxGridCellAutoWrapStringRenderer : public wxGridCellStringRenderer +{ +public: + /** + Default constructor. + */ + wxGridCellAutoWrapStringRenderer(); +}; + + /** @class wxGridCellBoolRenderer @@ -58,7 +85,9 @@ public: @library{wxadv} @category{grid} - @see wxGridCellRenderer, wxGridCellFloatRenderer, wxGridCellNumberRenderer, + @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer, + wxGridCellDateTimeRenderer, wxGridCellEnumRenderer, + wxGridCellFloatRenderer, wxGridCellNumberRenderer, wxGridCellStringRenderer */ class wxGridCellBoolRenderer : public wxGridCellRenderer @@ -70,6 +99,85 @@ public: wxGridCellBoolRenderer(); }; +/** + @class wxGridCellDateTimeRenderer + + This class may be used to format a date/time data in a cell. + The class wxDateTime is used internally to display the local date/time + or to parse the string date entered in the cell thanks to the defined format. + + @library{wxadv} + @category{grid} + + @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer, + wxGridCellBoolRenderer, wxGridCellEnumRenderer, + wxGridCellFloatRenderer, wxGridCellNumberRenderer, + wxGridCellStringRenderer +*/ +class wxGridCellDateTimeRenderer : public wxGridCellStringRenderer +{ +public: + /** + Date/time renderer constructor. + + @param outformat + strptime()-like format string used the parse the output date/time. + @param informat + strptime()-like format string used to parse the string entered in the cell. + */ + wxGridCellDateTimeRenderer(const wxString& outformat = wxDefaultDateTimeFormat, + const wxString& informat = wxDefaultDateTimeFormat); + + + /** + Sets the strptime()-like format string which will be used to parse + the date/time. + + @param params + strptime()-like format string used to parse the date/time. + */ + virtual void SetParameters(const wxString& params); +}; + +/** + @class wxGridCellEnumRenderer + + This class may be used to render in a cell a number as a textual + equivalent. + + The corresponding text strings are specified as comma-separated items in + the string passed to this renderer ctor or SetParameters() method. For + example, if this string is @c "John,Fred,Bob" the cell will be rendered as + "John", "Fred" or "Bob" if its contents is 0, 1 or 2 respectively. + + @library{wxadv} + @category{grid} + + @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer, + wxGridCellBoolRenderer, wxGridCellDateTimeRenderer, + wxGridCellFloatRenderer, wxGridCellNumberRenderer, + wxGridCellStringRenderer +*/ +class wxGridCellEnumRenderer : public wxGridCellStringRenderer +{ +public: + /** + Enum renderer ctor. + + @param choices + Comma separated string parameters "item1[,item2[...,itemN]]". + */ + wxGridCellEnumRenderer( const wxString& choices = wxEmptyString ); + + /** + Sets the comma separated string content of the enum. + + @param params + Comma separated string parameters "item1[,item2[...,itemN]]". + */ + virtual void SetParameters(const wxString& params); +}; + /** @class wxGridCellFloatRenderer @@ -78,13 +186,17 @@ public: @library{wxadv} @category{grid} - @see wxGridCellRenderer, wxGridCellBoolRenderer, wxGridCellNumberRenderer, + @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer, + wxGridCellBoolRenderer, wxGridCellDateTimeRenderer, + wxGridCellEnumRenderer, wxGridCellNumberRenderer, wxGridCellStringRenderer */ class wxGridCellFloatRenderer : public wxGridCellStringRenderer { public: /** + Float cell renderer ctor. + @param width Minimum number of characters to be shown. @param precision @@ -126,7 +238,9 @@ public: @library{wxadv} @category{grid} - @see wxGridCellRenderer, wxGridCellBoolRenderer, wxGridCellFloatRenderer, + @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer, + wxGridCellBoolRenderer, wxGridCellDateTimeRenderer, + wxGridCellEnumRenderer, wxGridCellFloatRenderer, wxGridCellStringRenderer */ class wxGridCellNumberRenderer : public wxGridCellStringRenderer @@ -147,7 +261,9 @@ public: @library{wxadv} @category{grid} - @see wxGridCellRenderer, wxGridCellBoolRenderer, wxGridCellFloatRenderer, + @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer, + wxGridCellBoolRenderer, wxGridCellDateTimeRenderer, + wxGridCellEnumRenderer, wxGridCellFloatRenderer, wxGridCellNumberRenderer */ class wxGridCellStringRenderer : public wxGridCellRenderer @@ -160,7 +276,6 @@ public: }; - /** @class wxGridCellEditor @@ -173,8 +288,10 @@ public: @library{wxadv} @category{grid} - @see wxGridCellBoolEditor, wxGridCellChoiceEditor, wxGridCellFloatEditor, - wxGridCellNumberEditor, wxGridCellTextEditor + @see wxGridCellAutoWrapStringEditor, wxGridCellBoolEditor, + wxGridCellChoiceEditor, wxGridCellEnumEditor, + wxGridCellFloatEditor, wxGridCellNumberEditor, + wxGridCellTextEditor */ class wxGridCellEditor { @@ -295,6 +412,24 @@ protected: virtual ~wxGridCellEditor(); }; +/** + @class wxGridCellAutoWrapStringEditor + + Grid cell editor for wrappable string/text data. + + @library{wxadv} + @category{grid} + + @see wxGridCellEditor, wxGridCellBoolEditor, wxGridCellChoiceEditor, + wxGridCellEnumEditor, wxGridCellFloatEditor, + wxGridCellNumberEditor, wxGridCellTextEditor +*/ +class wxGridCellAutoWrapStringEditor : public wxGridCellTextEditor +{ +public: + wxGridCellAutoWrapStringEditor(); +}; + /** @class wxGridCellBoolEditor @@ -303,8 +438,10 @@ protected: @library{wxadv} @category{grid} - @see wxGridCellEditor, wxGridCellChoiceEditor, wxGridCellFloatEditor, - wxGridCellNumberEditor, wxGridCellTextEditor + @see wxGridCellEditor, wxGridCellAutoWrapStringEditor, + wxGridCellChoiceEditor, wxGridCellEnumEditor, + wxGridCellFloatEditor, wxGridCellNumberEditor, + wxGridCellTextEditor */ class wxGridCellBoolEditor : public wxGridCellEditor { @@ -340,13 +477,17 @@ public: @library{wxadv} @category{grid} - @see wxGridCellEditor, wxGridCellBoolEditor, wxGridCellFloatEditor, - wxGridCellNumberEditor, wxGridCellTextEditor + @see wxGridCellEditor, wxGridCellAutoWrapStringEditor, + wxGridCellBoolEditor, wxGridCellEnumEditor, + wxGridCellFloatEditor, wxGridCellNumberEditor, + wxGridCellTextEditor */ class wxGridCellChoiceEditor : public wxGridCellEditor { public: /** + Choice cell renderer ctor. + @param count Number of strings from which the user can choose. @param choices @@ -358,7 +499,10 @@ public: wxGridCellChoiceEditor(size_t count = 0, const wxString choices[] = NULL, bool allowOthers = false); + /** + Choice cell renderer ctor. + @param choices An array of strings from which the user can choose. @param allowOthers @@ -374,6 +518,33 @@ public: virtual void SetParameters(const wxString& params); }; +/** + @class wxGridCellEnumEditor + + Grid cell editor which displays an enum number as a textual equivalent + (eg. data in cell is 0,1,2 ... n the cell could be displayed as + "John","Fred"..."Bob" in the combo choice box). + + @library{wxadv} + @category{grid} + + @see wxGridCellEditor, wxGridCellAutoWrapStringEditor, + wxGridCellBoolEditor, wxGridCellChoiceEditor, + wxGridCellTextEditor, wxGridCellFloatEditor, + wxGridCellNumberEditor +*/ +class wxGridCellEnumEditor : public wxGridCellChoiceEditor +{ +public: + /** + Enum cell editor ctor. + + @param choices + Comma separated choice parameters "item1[,item2[...,itemN]]". + */ + wxGridCellEnumEditor( const wxString& choices = wxEmptyString ); +}; + /** @class wxGridCellTextEditor @@ -382,8 +553,10 @@ public: @library{wxadv} @category{grid} - @see wxGridCellEditor, wxGridCellBoolEditor, wxGridCellChoiceEditor, - wxGridCellFloatEditor, wxGridCellNumberEditor + @see wxGridCellEditor, wxGridCellAutoWrapStringEditor, + wxGridCellBoolEditor, wxGridCellChoiceEditor, + wxGridCellEnumEditor, wxGridCellFloatEditor, + wxGridCellNumberEditor */ class wxGridCellTextEditor : public wxGridCellEditor { @@ -408,13 +581,17 @@ public: @library{wxadv} @category{grid} - @see wxGridCellEditor, wxGridCellNumberEditor, wxGridCellBoolEditor, - wxGridCellTextEditor, wxGridCellChoiceEditor + @see wxGridCellEditor, wxGridCellAutoWrapStringEditor, + wxGridCellBoolEditor, wxGridCellChoiceEditor, + wxGridCellEnumEditor, wxGridCellNumberEditor, + wxGridCellTextEditor */ class wxGridCellFloatEditor : public wxGridCellTextEditor { public: /** + Float cell editor ctor. + @param width Minimum number of characters to be shown. @param precision @@ -436,8 +613,10 @@ public: @library{wxadv} @category{grid} - @see wxGridCellEditor, wxGridCellBoolEditor, wxGridCellChoiceEditor, - wxGridCellFloatEditor, wxGridCellTextEditor + @see wxGridCellEditor, wxGridCellAutoWrapStringEditor, + wxGridCellBoolEditor, wxGridCellChoiceEditor, + wxGridCellEnumEditor, wxGridCellFloatEditor, + wxGridCellTextEditor */ class wxGridCellNumberEditor : public wxGridCellTextEditor { @@ -527,7 +706,21 @@ public: void DecRef(); /** - See SetAlignment() for the returned values. + Get the alignment to use for the cell with the given attribute. + + If this attribute doesn't specify any alignment, the default attribute + alignment is used (which can be changed using + wxGrid::SetDefaultCellAlignment() but is left and top by default). + + Notice that @a hAlign and @a vAlign values are always overwritten by + this function, use GetNonDefaultAlignment() if this is not desirable. + + @param hAlign + Horizontal alignment is returned here if this argument is non-@NULL. + It is one of wxALIGN_LEFT, wxALIGN_CENTRE or wxALIGN_RIGHT. + @param vAlign + Vertical alignment is returned here if this argument is non-@NULL. + It is one of wxALIGN_TOP, wxALIGN_CENTRE or wxALIGN_BOTTOM. */ void GetAlignment(int* hAlign, int* vAlign) const; @@ -546,6 +739,29 @@ public: */ const wxFont& GetFont() const; + /** + Get the alignment defined by this attribute. + + Unlike GetAlignment() this function only modifies @a hAlign and @a + vAlign if this attribute does define a non-default alignment. This + means that they must be initialized before calling this function and + that their values will be preserved unchanged if they are different + from wxALIGN_INVALID. + + For example, the following fragment can be used to use the cell + alignment if one is defined but right-align its contents by default + (instead of left-aligning it by default) while still using the default + vertical alignment: + @code + int hAlign = wxALIGN_RIGHT, + vAlign = wxALIGN_INVALID; + attr.GetNonDefaultAlignment(&hAlign, &vAlign); + @endcode + + @since 2.9.1 + */ + void GetNonDefaultAlignment(int *hAlign, int *vAlign) const; + /** Returns the cell renderer. */ @@ -747,7 +963,7 @@ class wxGridColumnHeaderRenderer : public wxGridHeaderLabelsRenderer @since 2.9.1 */ -class wxGridRowHeaderRendererDefault : public wxGridRowHeaderRendererDefault +class wxGridRowHeaderRendererDefault : public wxGridRowHeaderRenderer { public: /// Implement border drawing for the row labels. @@ -1470,9 +1686,38 @@ public: The user won't be able to select any cells or rows in this mode. */ - wxGridSelectColumns + wxGridSelectColumns, + + /** + The selection mode allowing the user to select either the entire + columns or the entire rows but not individual cells nor blocks. + + Notice that while this constant is defined as @code + wxGridSelectColumns | wxGridSelectRows @endcode this doesn't mean + that all the other combinations are valid -- at least currently + they are not. + + @since 2.9.1 + */ + wxGridSelectRowsOrColumns }; + /** + Return values for GetCellSize(). + + @since 2.9.1 + */ + enum CellSpan + { + /// This cell is inside a span covered by another cell. + CellSpan_Inside = -1, + + /// This is a normal, non-spanning cell. + CellSpan_None = 0, + + /// This cell spans several physical wxGrid cells. + CellSpan_Main + }; /** @name Constructors and Initialization @@ -1790,10 +2035,18 @@ public: 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). + Another difference between the default behaviour and the native header + behaviour is that the latter provides the user with a context menu + (which appears on right clicking the header) allowing to rearrange the + grid columns if CanDragColMove() returns @true. If you want to prevent + this from happening for some reason, you need to define a handler for + @c wxEVT_GRID_LABEL_RIGHT_CLICK event which simply does nothing (in + particular doesn't skip the event) as this will prevent the default + right click handling from working. + + Also note that currently @c wxEVT_GRID_LABEL_RIGHT_DCLICK event is not + generated for the column labels if the native columns header is used + (but this limitation could possibly be lifted in the future). */ void UseNativeColHeader(bool native = true); @@ -2615,6 +2868,81 @@ public: */ void SetRowSizes(const wxGridSizesInfo& sizeInfo); + /** + Set the size of the cell. + + Specifying a value of more than 1 in @a num_rows or @a num_cols will + make the cell at (@a row, @a col) span the block of the specified size, + covering the other cells which would be normally shown in it. Passing 1 + for both arguments resets the cell to normal appearance. + + @see GetCellSize() + + @param row + The row of the cell. + @param col + The column of the cell. + @param num_rows + Number of rows to be occupied by this cell, must be >= 1. + @param num_cols + Number of columns to be occupied by this cell, must be >= 1. + */ + void SetCellSize(int row, int col, int num_rows, int num_cols); + + /** + Get the size of the cell in number of cells covered by it. + + For normal cells, the function fills both @a num_rows and @a num_cols + with 1 and returns CellSpan_None. For cells which span multiple cells, i.e. + for which SetCellSize() had been called, the returned values are the + same ones as were passed to SetCellSize() call and the function return + value is CellSpan_Main. + + More unexpectedly, perhaps, the returned values may be @em negative for + the cells which are inside a span covered by a cell occupying multiple + rows or columns. They correspond to the offset of the main cell of the + span from the cell passed to this functions and the function returns + CellSpan_Inside value to indicate this. + + As an example, consider a 3*3 grid with the cell (1, 1) (the one in the + middle) having a span of 2 rows and 2 columns, i.e. the grid looks like + @code + +----+----+----+ + | | | | + +----+----+----+ + | | | + +----+ | + | | | + +----+----+----+ + @endcode + Then the function returns 2 and 2 in @a num_rows and @a num_cols for + the cell (1, 1) itself and -1 and -1 for the cell (2, 2) as well as -1 + and 0 for the cell (2, 1). + + @param row + The row of the cell. + @param col + The column of the cell. + @param num_rows + Pointer to variable receiving the number of rows, must not be @NULL. + @param num_cols + Pointer to variable receiving the number of columns, must not be + @NULL. + @return + The kind of this cell span (the return value is new in wxWidgets + 2.9.1, this function was void in previous wxWidgets versions). + */ + CellSpan GetCellSize( int row, int col, int *num_rows, int *num_cols ) const; + + /** + Get the number of rows and columns allocated for this cell. + + This overload doesn't return a CellSpan value but the values returned + may still be negative, see GetCellSize(int, int, int *, int *) for + details. + */ + wxSize GetCellSize(const wxGridCellCoords& coords); + //@} @@ -3518,6 +3846,31 @@ public: */ bool InsertRows(int pos = 0, int numRows = 1, bool updateLabels = true); + /** + Invalidates the cached attribute for the given cell. + + For efficiency reasons, wxGrid may cache the recently used attributes + (currently it caches only the single most recently used one, in fact) + which can result in the cell appearance not being refreshed even when + the attribute returned by your custom wxGridCellAttrProvider-derived + class has changed. To force the grid to refresh the cell attribute, + this function may be used. Notice that calling it will not result in + actually redrawing the cell, you still need to call + wxWindow::RefreshRect() to invalidate the area occupied by the cell in + the window to do this. Also note that you don't need to call this + function if you store the attributes in wxGrid itself, i.e. use its + SetAttr() and similar methods, it is only useful when using a separate + custom attributes provider. + + @param row + The row of the cell whose attribute needs to be queried again. + @param col + The column of the cell whose attribute needs to be queried again. + + @since 2.9.2 + */ + void RefreshAttr(int row, int col); + /** Sets the cell attributes for all cells in the specified column. @@ -3898,6 +4251,10 @@ public: /** Column at which the event occurred. + + Notice that for a @c wxEVT_GRID_SELECT_CELL event this column is the + column of the newly selected cell while the previously selected cell + can be retrieved using wxGrid::GetGridCursorCol(). */ virtual int GetCol(); @@ -3908,6 +4265,10 @@ public: /** Row at which the event occurred. + + Notice that for a @c wxEVT_GRID_SELECT_CELL event this row is the row + of the newly selected cell while the previously selected cell can be + retrieved using wxGrid::GetGridCursorRow(). */ virtual int GetRow();