X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/8acad210fa179e699cfbb095d24b23b3fbf38dbc..d58526d55433162cef8ad2ed7f422689862c3019:/interface/wx/grid.h diff --git a/interface/wx/grid.h b/interface/wx/grid.h index 3f04db61a8..5fbea265ac 100644 --- a/interface/wx/grid.h +++ b/interface/wx/grid.h @@ -186,7 +186,13 @@ public: /** 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; @@ -207,12 +213,34 @@ public: 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 @@ -300,7 +328,7 @@ public: an empty string otherwise. */ static void UseStringValues(const wxString& valueTrue = "1", - const wxString& valueFalse = wxEmptyString) const; + const wxString& valueFalse = wxEmptyString); }; /** @@ -459,7 +487,7 @@ public: /** Default constructor. */ - wxGridCellAttr(); + wxGridCellAttr(wxGridCellAttr* attrDefault = NULL); /** Constructor specifying some of the often used attributes. */ @@ -1007,6 +1035,68 @@ public: 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; +}; /** @@ -1047,7 +1137,7 @@ public: - wxGridCellFloatEditor - wxGridCellNumberEditor - wxGridCellTextEditor - + Please see wxGridEvent, wxGridSizeEvent, wxGridRangeSelectEvent, and wxGridEditorCreatedEvent for the documentation of all event types you can use with wxGrid. @@ -1376,14 +1466,41 @@ public: /** Call this in order to make the column labels use a native look by using - wxRenderer::DrawHeaderButton() internally. + wxRendererNative::DrawHeaderButton() internally. There is no equivalent method for drawing row columns as there is not native look for that. This option is useful when using wxGrid for displaying tables and not as a spread-sheet. + + @see UseNativeColHeader() */ void SetUseNativeColLabels(bool native = true); + /** + 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 UseNativeColHeader(bool native = true); + //@} @@ -1617,7 +1734,7 @@ public: See wxGridTableBase::CanGetValueAs() and the @ref overview_grid for more information. */ - const wxString GetCellValue(const wxGridCellCoords& coords) const; + wxString GetCellValue(const wxGridCellCoords& coords) const; /** Returns a pointer to the current default grid cell editor. @@ -1920,6 +2037,8 @@ public: /** @name Column and Row Sizes + + @see @ref overview_grid_resizing */ //@{ @@ -1987,6 +2106,11 @@ public: */ int GetColSize(int col) const; + /** + Returns @true if the specified column is not currently hidden. + */ + bool IsColShown(int col) const; + /** Returns the default height for column labels. */ @@ -2027,6 +2151,11 @@ public: */ int GetRowSize(int row) const; + /** + Returns @true if the specified row is not currently hidden. + */ + bool IsRowShown(int row) const; + /** Sets the height of the column labels. @@ -2058,17 +2187,33 @@ public: /** Sets the width of the specified column. - Notice that this function does not refresh the grid, you need to call - ForceRefresh() to make the changes take effect immediately. - @param col The column index. @param width - The new column width in pixels or a negative value to fit the - column width to its label width. + The new column width in pixels, 0 to hide the column or -1 to fit + the column width to its label width. */ void SetColSize(int col, int width); + /** + Hides the specified column. + + To show the column later you need to call SetColSize() with non-0 + width or ShowCol(). + + @param col + The column index. + */ + void HideCol(int col); + + /** + Shows the previously hidden column by resizing it to non-0 size. + + @see HideCol(), SetColSize() + */ + void ShowCol(int col); + + /** Sets the default width for columns in the grid. @@ -2121,11 +2266,75 @@ public: */ void SetRowSize(int row, int height); + /** + 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); + //@} /** @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(). */ //@{ @@ -2142,13 +2351,15 @@ public: bool CanDragColMove() const; /** - Returns @true if columns can be resized by dragging with the mouse. + Returns @true if the given column can be resized by dragging with the + mouse. - Columns can be resized by dragging the edges of their labels. If grid - line dragging is enabled they can also be resized by dragging the right - edge of the column in the grid cell area (see EnableDragGridSize()). + 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() const; + bool CanDragColSize(int col) const; /** Return @true if the dragging of grid lines to resize rows and columns @@ -2157,13 +2368,42 @@ public: bool CanDragGridSize() const; /** - Returns @true if rows can be resized by dragging with the mouse. + Returns @true if the given row can be resized by dragging with the + mouse. - Rows can be resized by dragging the edges of their labels. If grid line - dragging is enabled they can also be resized by dragging the lower edge - of the row in the grid cell area (see EnableDragGridSize()). + This is the same as CanDragColSize() but for rows. */ - bool CanDragRowSize() const; + 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. @@ -2205,6 +2445,8 @@ public: /** Enables or disables column sizing by dragging with the mouse. + + @see DisableColResize() */ void EnableDragColSize(bool enable = true); @@ -2216,6 +2458,8 @@ public: /** Enables or disables row sizing by dragging with the mouse. + + @see DisableRowResize() */ void EnableDragRowSize(bool enable = true); @@ -2234,12 +2478,26 @@ public: */ 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 - */ + */ //@{ /** @@ -2664,7 +2922,7 @@ public: @see BlockToDeviceRect() */ - const wxRect CellToRect(const wxGridCellCoords& coords) const; + wxRect CellToRect(const wxGridCellCoords& coords) const; /** Returns the column at the given pixel position. @@ -2992,6 +3250,143 @@ public: //@} + + /** + @name Sorting support. + + 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. + + 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. + + 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. + */ + //@{ + + /** + Return the column in which the sorting indicator is currently + displayed. + + Returns @c wxNOT_FOUND if sorting indicator is not currently displayed + at all. + + @see SetSortingColumn() + */ + int GetSortingColumn() const; + + /** + Return @true if this column is currently used for sorting. + + @see GetSortingColumn() + */ + bool IsSortingBy(int col) const; + + /** + Return @true if the current sorting order is ascending or @false if it + is descending. + + It only makes sense to call this function if GetSortingColumn() returns + a valid column index and not @c wxNOT_FOUND. + + @see SetSortingColumn() + */ + bool IsSortOrderAscending() const; + + /** + Set the column to display the sorting indicator in and its direction. + + @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. + + @see GetSortingColumn(), IsSortOrderAscending() + */ + void SetSortingColumn(int col, bool ascending = true); + + /** + Remove any currently shown sorting indicator. + + This is equivalent to calling SetSortingColumn() with @c wxNOT_FOUND + first argument. + */ + void UnsetSortingColumn(); + //@} + + + /** + @name Accessors for component windows. + + Return the various child windows of wxGrid. + + 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. + */ + //@{ + + /** + Return the main grid window containing the grid cells. + + This window is always shown. + */ + wxWindow *GetGridWindow() const; + + /** + Return the row labels window. + + This window is not shown if the row labels were hidden using + HideRowLabels(). + */ + wxWindow *GetGridRowLabelWindow() const; + + /** + Return the column labels window. + + This window is not shown if the columns labels were hidden using + HideColLabels(). + + 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. + */ + wxWindow *GetGridColLabelWindow() const; + + /** + Return the window in the top left grid corner. + + 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; + + /** + Return the header control used for column labels display. + + This function can only be called if UseNativeColHeader() had been + called. + */ + wxHeaderCtrl *GetGridColHeader() const; + + //@} + protected: /** Returns @true if this grid has support for cell attributes. @@ -3097,10 +3492,29 @@ public: 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. @@ -3134,54 +3548,32 @@ public: @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 { @@ -3195,8 +3587,7 @@ public: */ 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. @@ -3248,22 +3639,20 @@ public: 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 { @@ -3277,8 +3666,7 @@ public: */ 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. @@ -3326,7 +3714,7 @@ public: @endEventTable @library{wxadv} - @category{grid} + @category{grid,events} */ class wxGridRangeSelectEvent : public wxNotifyEvent { @@ -3342,9 +3730,7 @@ public: 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. @@ -3417,7 +3803,7 @@ public: @endEventTable @library{wxadv} - @category{grid} + @category{grid,events} */ class wxGridEditorCreatedEvent : public wxCommandEvent {