don't place NULL pointers in the GDK window array in GTKGetWindow()
[wxWidgets.git] / interface / wx / headerctrl.h
index 5908cc0a382a3b99821dcc12d3ccbfd48821aecf..73142a1959d99a40973a188324ff6591e5ce089d 100644 (file)
     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:
     @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_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)}
 
     @see wxGrid, wxListCtrl, wxDataViewCtrl
 */
-class wxHeaderCtrl
+class wxHeaderCtrl : public wxControl
 {
 public:
     /**
@@ -300,19 +305,74 @@ public:
         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 at the current mouse
-        position. It is meant to be called from EVT_HEADER_RIGHT_CLICK handler
-        and should toggle the visibility of the n-th column if the function
-        returns valid column index and not wxID_NONE which is returned if the
-        user cancels the menu.
-
+        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
-            A valid column index or wxID_NONE if the user didn't select any
-            column.
+            @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.
      */
-    int ShowColumnsMenu(const wxString& title = wxString());
+    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:
     /**
@@ -323,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 wxHeaderColumnBase& 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
@@ -351,7 +455,7 @@ protected:
             {
             public:
             protected:
-                virtual wxHeaderColumnBase& GetColumn(unsigned int idx)
+                virtual wxHeaderColumnBase& GetColumn(unsigned int idx) const
                 {
                     return m_cols[idx];
                 }
@@ -450,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.
@@ -503,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:
     /**
@@ -543,7 +645,7 @@ protected:
     Event class representing the events generated by wxHeaderCtrl.
 
     @library{wxcore}
-    @category{ctrl}
+    @category{events}
 
     @see wxHeaderCtrl
 */