X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e2c4ccaf8a7f03658a29ec4f4f2b71c95827e4ff..c29c95fe24973b94fd724db767193171ca7c513d:/interface/wx/headerctrl.h diff --git a/interface/wx/headerctrl.h b/interface/wx/headerctrl.h index a5358665c1..718e02749a 100644 --- a/interface/wx/headerctrl.h +++ b/interface/wx/headerctrl.h @@ -5,7 +5,7 @@ // Created: 2008-12-01 // RCS-ID: $Id$ // Copyright: (c) 2008 Vadim Zeitlin -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -14,13 +14,13 @@ wxHeaderCtrl is the control containing the column headings which is usually used for display of tabular data. - It is used as part of wxGrid and (will be used in the near future) in - in wxDataViewCtrl and report view of wxListCtrl but can be also used - independently. In general this class is meant to be used as part of another - control which already stores the column information somewhere as it can't - be used directly: instead you need to inherit from it and implement the - GetColumn() method to provide column information. See wxHeaderCtrlSimple - for a concrete control class which can be used directly. + It is used as part of wxGrid, in generic version wxDataViewCtrl and report + view of wxListCtrl but can be also used independently. In general this + class is meant to be used as part of another control which already stores + the column information somewhere as it can't be used directly: instead you + need to inherit from it and implement the GetColumn() method to provide + column information. See wxHeaderCtrlSimple for a concrete control class + which can be used directly. In addition to labeling the columns, the control has the following features: @@ -53,15 +53,20 @@ @beginStyleTable - @style{wxHD_DRAGDROP} + @style{wxHD_ALLOW_REORDER} If this style is specified (it is by default), the user can reorder the control columns by dragging them. + @style{wxHD_ALLOW_HIDE} + If this style is specified, the control shows a popup menu allowing the + user to change the columns visibility on right mouse click. Notice that + the program can always hide or show the columns, this style only + affects the users capability to do it. @style{wxHD_DEFAULT_STYLE} Symbolic name for the default control style, currently equal to - @c wxHD_DRAGDROP. + @c wxHD_ALLOW_REORDER. @endStyleTable - @beginEventTable{wxHeaderCtrlEvent} + @beginEventEmissionTable{wxHeaderCtrlEvent} @event{EVT_HEADER_CLICK(id, func)} A column heading was clicked. @event{EVT_HEADER_RIGHT_CLICK(id, func)} @@ -97,7 +102,7 @@ wxHeaderCtrlEvent::GetWidth(). @event{EVT_HEADER_BEGIN_REORDER(id, func)} The user started to drag the column with the specified index (this - can only happen for the controls with wxHD_DRAGDROP style). + can only happen for the controls with wxHD_ALLOW_REORDER style). This event can be vetoed to prevent the column from being reordered, otherwise the end reorder message will be generated later. @event{EVT_HEADER_END_REORDER(id, func)} @@ -121,7 +126,7 @@ @see wxGrid, wxListCtrl, wxDataViewCtrl */ -class wxHeaderCtrl +class wxHeaderCtrl : public wxControl { public: /** @@ -161,8 +166,8 @@ public: The control style, @c wxHD_DEFAULT_STYLE by default. Notice that the default style allows the user to reorder the columns by dragging them and you need to explicitly turn this feature off by - using @code wxHD_DEFAULT_STYLE & ~wxHD_DRAGDROP @endcode if this is - undesirable. + using @code wxHD_DEFAULT_STYLE & ~wxHD_ALLOW_REORDER @endcode if + this is undesirable. @param name The name of the control. */ @@ -236,11 +241,11 @@ public: /** Return the array describing the columns display order. - For the controls without wxHD_DRAGDROP style the returned array will be - the same as was passed to SetColumnsOrder() previously or define the - default order (with n-th element being n) if it hadn't been called. But - for the controls with wxHD_DRAGDROP style, the columns can be also - reordered by user. + For the controls without wxHD_ALLOW_REORDER style the returned array + will be the same as was passed to SetColumnsOrder() previously or + define the default order (with n-th element being n) if it hadn't been + called. But for the controls with wxHD_ALLOW_REORDER style, the columns + can be also reordered by user. */ wxArrayInt GetColumnsOrder() const; @@ -268,6 +273,14 @@ public: */ unsigned int GetColumnPos(unsigned int idx) const; + /** + Reset the columns order to the natural one. + + After calling this function, the column with index @c idx appears at + position @c idx in the control. + */ + void ResetColumnsOrder(); + /** Helper function to manipulate the array of column indices. @@ -288,6 +301,79 @@ public: unsigned int idx, unsigned int pos); + /** + Show the popup menu allowing the user to show or hide the columns. + + This functions shows the popup menu containing all columns with check + marks for the ones which are currently shown and allows the user to + check or uncheck them to toggle their visibility. It is called from the + default EVT_HEADER_RIGHT_CLICK handler for the controls which have + wxHD_ALLOW_HIDE style. And if the column has wxHD_ALLOW_REORDER style + as well, the menu also contains an item to customize the columns shown + using which results in ShowCustomizeDialog() being called, please see + its description for more details. + + If a column was toggled, UpdateColumnVisibility() virtual function is + called so it must be implemented for the controls with wxHD_ALLOW_HIDE + style or if you call this function explicitly. + + @param pt + The position of the menu, in the header window coordinates. + @param title + The title for the menu if not empty. + @return + @true if a column was shown or hidden or @false if nothing was + done, e.g. because the menu was cancelled. + */ + bool ShowColumnsMenu(const wxPoint& pt, const wxString& title = wxString()); + + /** + Helper function appending the checkable items corresponding to all the + columns to the given menu. + + This function is used by ShowColumnsMenu() but can also be used if you + show your own custom columns menu and still want all the columns shown + in it. It appends menu items with column labels as their text and + consecutive ids starting from @a idColumnsBase to the menu and checks + the items corresponding to the currently visible columns. + + Example of use: + @code + wxMenu menu; + menu.Append(100, "Some custom command"); + menu.AppendSeparator(); + AddColumnsItems(menu, 200); + const int rc = GetPopupMenuSelectionFromUser(menu, pt); + if ( rc >= 200 ) + ... toggle visibility of the column rc-200 ... + @endcode + + @param menu + The menu to append the items to. It may be currently empty or not. + @param idColumnsBase + The id for the menu item corresponding to the first column, the + other ones are consecutive starting from it. It should be positive. + */ + void AddColumnsItems(wxMenu& menu, int idColumnsBase = 0); + + /** + Show the column customization dialog. + + This function displays a modal dialog containing the list of all + columns which the user can use to reorder them as well as show or hide + individual columns. + + If the user accepts the changes done in the dialog, the virtual + methods UpdateColumnVisibility() and UpdateColumnsOrder() will be + called so they must be overridden in the derived class if this method + is ever called. Please notice that the user will be able to invoke it + interactively from the header popup menu if the control has both + wxHD_ALLOW_HIDE and wxHD_ALLOW_REORDER styles. + + @see wxRearrangeDialog + */ + bool ShowCustomizeDialog(); + protected: /** Method to be implemented by the derived classes to return the @@ -297,7 +383,51 @@ protected: The column index, between 0 and the value last passed to SetColumnCount(). */ - virtual wxHeaderColumnBase& GetColumn(unsigned int idx) = 0; + virtual const wxHeaderColumn& GetColumn(unsigned int idx) const = 0; + + /** + Method called when the column visibility is changed by the user. + + This method is called from ShowColumnsMenu() or ShowCustomizeDialog() + when the user interactively hides or shows a column. A typical + implementation will simply update the internally stored column state. + Notice that there is no need to call UpdateColumn() from this method as + it is already done by wxHeaderCtrl itself. + + The base class version doesn't do anything and must be overridden if + this method is called. + + @param idx + The index of the column whose visibility was toggled. + @param show + The new visibility value, @true if the column is now shown or + @false if it is not hidden. + */ + virtual void UpdateColumnVisibility(unsigned int idx, bool show); + + /** + Method called when the columns order is changed in the customization + dialog. + + This method is only called from ShowCustomizeDialog() when the user + changes the order of columns. In particular it is @em not called if a + single column changes place because the user dragged it to the new + location, the EVT_HEADER_END_REORDER event handler should be used to + react to this. + + A typical implementation in a derived class will update the display + order of the columns in the associated control, if any. Notice that + there is no need to call SetColumnsOrder() from it as wxHeaderCtrl does + it itself. + + The base class version doesn't do anything and must be overridden if + this method is called. + + @param order + The new column order. This array uses the same convention as + SetColumnsOrder(). + */ + virtual void UpdateColumnsOrder(const wxArrayInt& order); /** Method which may be implemented by the derived classes to allow double @@ -309,7 +439,7 @@ protected: to fit its width on header double click you need to implement this method using logic similar to this example: @code - class MyHeaderCtrl : public wxHeaderColumnBase + class MyHeaderColumn : public wxHeaderColumn { public: ... @@ -325,7 +455,7 @@ protected: { public: protected: - virtual wxHeaderColumnBase& GetColumn(unsigned int idx) + virtual wxHeaderColumn& GetColumn(unsigned int idx) const { return m_cols[idx]; } @@ -424,14 +554,14 @@ public: @see AppendColumn() */ - void InsertColumn(const wxHeaderColumn& col, unsigned int idx); + void InsertColumn(const wxHeaderColumnSimple& col, unsigned int idx); /** Append the column to the end of the control. @see InsertColumn() */ - void AppendColumn(const wxHeaderColumn& col); + void AppendColumn(const wxHeaderColumnSimple& col); /** Delete the column at the given position. @@ -477,22 +607,20 @@ public: @param idx The column to set the sort indicator for. + If @c -1 is given, then the currently shown sort indicator + will be removed. @param sortOrder If @true or @false show the sort indicator corresponding to - ascending or descending sort order respectively, if @c -1 remove - the currently shown sort indicator. + ascending or descending sort order respectively. */ - virtual void ShowSortIndicator(unsigned int idx, int sortOrder); + void ShowSortIndicator(unsigned int idx, bool sortOrder = true); /** - Remove the sort indicator from the given column. - - This is the same as calling ShowSortIndicator() with @c -1 argument. + Remove the sort indicator from the column being used as sort key. - @param idx - The column to remove sort indicator for. + @see ShowSortIndicator */ - void RemoveSortIndicator(unsigned int idx); + void RemoveSortIndicator(); protected: /** @@ -517,7 +645,7 @@ protected: Event class representing the events generated by wxHeaderCtrl. @library{wxcore} - @category{ctrl} + @category{events} @see wxHeaderCtrl */