interface/wx/headerctrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/headerctrl.h
   3 // Purpose:     interface of wxHeaderCtrl
   4 // Author:      Vadim Zeitlin
   5 // Created:     2008-12-01
   6 // RCS-ID:      $Id$
   7 // Copyright:   (c) 2008 Vadim Zeitlin <vadim@wxwidgets.org>
   8 // Licence:     wxWindows license
   9 /////////////////////////////////////////////////////////////////////////////
  10
  11 /**
  12     @class wxHeaderCtrl
  13
  14     wxHeaderCtrl is the control containing the column headings which is usually
  15     used for display of tabular data.
  16
  17     It is used as part of wxGrid and (will be used in the near future) in
  18     in wxDataViewCtrl and report view of wxListCtrl but can be also used
  19     independently.
  20
  21     In addition to labeling the columns, the control has the following
  22     features:
  23         - Column reordering support, either by explicitly configuring the
  24           columns order and calling SetColumnsOrder() or by dragging the
  25           columns interactively (if enabled).
  26         - Display of the icons in the header: this is often used to display a
  27           sort or reverse sort indicator when the column header is clicked.
  28
  29     Notice that this control itself doesn't do anything other than displaying
  30     the column headers. In particular column reordering and sorting must still
  31     be supported by the associated control displaying the real data under the
  32     header.
  33
  34     This control is implemented using the native header control under MSW
  35     systems and a generic implementation elsewhere.
  36
  37     @beginStyleTable
  38         @style{wxHD_DRAGDROP}
  39             If this style is specified (it is by default), the user can reorder
  40             the control columns by dragging them.
  41         @style{wxHD_DEFAULT_STYLE}
  42             Symbolic name for the default control style, currently equal to @c
  43             wxHD_DRAGDROP.
  44     @endStyleTable
  45
  46     @beginEventTable{wxHeaderEvent}
  47     @event{EVT_HEADER_CLICK(id, func)}
  48         A column heading was clicked.
  49     @endEventTable
  50
  51     @library{wxcore}
  52     @category{ctrl}
  53
  54     @see wxGrid, wxListCtrl, wxDataViewCtrl
  55
  56
  57     @section headerctrl_improvements Future Improvements
  58
  59     Some features are supported by the native MSW control and so could be
  60     easily implemented in this version of wxHeaderCtrl but need to be
  61     implemented in the generic version as well to be really useful. Please let
  62     us know if you need or, better, plan to work on implementing, any of them:
  63         - Displaying bitmaps instead of or together with the text
  64         - Custom drawn headers
  65         - Filters associated with a column.
  66 */
  67 class wxHeaderCtrl
  68 {
  69 public:
  70     /**
  71         Default constructor not creating the underlying window.
  72
  73         You must use Create() after creating the object using this constructor.
  74      */
  75     wxHeaderCtrl();
  76
  77     /**
  78         Constructor creating the window.
  79
  80         Please see Create() for the parameters documentation.
  81      */
  82     wxHeaderCtrl(wxWindow *parent,
  83                  wxWindowID winid = wxID_ANY,
  84                  const wxPoint& pos = wxDefaultPosition,
  85                  const wxSize& size = wxDefaultSize,
  86                  long style = 0,
  87                  const wxString& name = wxHeaderCtrlNameStr);
  88
  89     /**
  90         Create the header control window.
  91
  92         @param parent
  93             The parent window. The header control should be typically
  94             positioned along the top edge of this window.
  95         @param winid
  96             Id of the control or @c wxID_ANY if you don't care.
  97         @param pos
  98             The initial position of the control.
  99         @param size
 100             The initial size of the control (usually not very useful as this
 101             control will typically be resized to have the same width as the
 102             associated data display control).
 103         @param style
 104             The control style, @c wxHD_DEFAULT_STYLE by default. Notice that
 105             the default style allows the user to reorder the columns by
 106             dragging them and you need to explicitly turn this feature off by
 107             using @code wxHD_DEFAULT_STYLE & ~wxHD_DRAGDROP @endcode if this is
 108             undesirable.
 109         @param name
 110             The name of the control.
 111      */
 112     bool Create(wxWindow *parent,
 113                 wxWindowID winid = wxID_ANY,
 114                 const wxPoint& pos = wxDefaultPosition,
 115                 const wxSize& size = wxDefaultSize,
 116                 long style = 0,
 117                 const wxString& name = wxHeaderCtrlNameStr);
 118
 119     /**
 120         Return the number of columns in the control.
 121
 122         @see IsEmpty()
 123      */
 124     unsigned int GetColumnCount() const;
 125
 126     /**
 127         Return whether the control has any columns.
 128
 129         @see GetColumnCount()
 130      */
 131     bool IsEmpty() const;
 132
 133     /**
 134         Insert the column at the given position.
 135
 136         @param col
 137             The column to insert. Notice that because of the existence of
 138             implicit conversion from wxString to wxHeaderColumn a string
 139             can be passed directly here.
 140         @param idx
 141             The position of the new column, from 0 to GetColumnCount(). Using
 142             GetColumnCount() means to append the column to the end.
 143
 144         @see AppendColumn()
 145      */
 146     void InsertColumn(const wxHeaderColumn& col, unsigned int idx);
 147
 148     /**
 149         Append the column to the end of the control.
 150
 151         @see InsertColumn()
 152      */
 153     void AppendColumn(const wxHeaderColumn& col);
 154
 155     /**
 156         Delete the column at the given position.
 157
 158         @see InsertColumn(), AppendColumn()
 159      */
 160     void DeleteColumn(unsigned int idx);
 161
 162     /**
 163         Show or hide the column.
 164
 165         Initially the column is shown by default or hidden if it was added with
 166         wxCOL_HIDDEN flag set.
 167
 168         When a column is hidden, it doesn't appear at all on the screen but its
 169         index is still taken into account when working with other columns. E.g.
 170         if there are three columns 0, 1 and 2 and the column 1 is hidden you
 171         still need to use index 2 to refer to the last visible column.
 172
 173         @param idx
 174             The index of the column to show or hide, from 0 to GetColumnCount().
 175         @param show
 176             Indicates whether the column should be shown (default) or hidden.
 177      */
 178     void ShowColumn(unsigned int idx, bool show = true);
 179
 180     /**
 181         Hide the column with the given index.
 182
 183         This is the same as calling @code ShowColumn(idx, false) @endcode.
 184
 185         @param idx
 186             The index of the column to show or hide, from 0 to GetColumnCount().
 187      */
 188     void HideColumn(unsigned int idx);
 189
 190     /**
 191         Update the column sort indicator.
 192
 193         The sort indicator, if shown, is typically an arrow pointing upwards or
 194         downwards depending on whether the control contents is sorted in
 195         ascending or descending order.
 196
 197         @param idx
 198             The column to set the sort indicator for.
 199         @param sortOrder
 200             If @true or @false show the sort indicator corresponding to
 201             ascending or descending sort order respectively, if @c -1 remove
 202             the currently shown sort indicator.
 203      */
 204     virtual void ShowSortIndicator(unsigned int idx, int sortOrder);
 205
 206     /**
 207         Remove the sort indicator from the given column.
 208
 209         This is the same as calling ShowSortIndicator() with @c -1 argument.
 210
 211         @param idx
 212             The column to remove sort indicator for.
 213      */
 214     void RemoveSortIndicator(unsigned int idx);
 215 };