1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/headerctrl.h
3 // Purpose: interface of wxHeaderCtrl
4 // Author: Vadim Zeitlin
7 // Copyright: (c) 2008 Vadim Zeitlin <vadim@wxwidgets.org>
8 // Licence: wxWindows license
9 /////////////////////////////////////////////////////////////////////////////
14 wxHeaderCtrl is the control containing the column headings which is usually
15 used for display of tabular data.
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
21 In addition to labeling the columns, the control has the following
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.
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. Also remember to call ScrollWindow() method of the control if the
33 associated data display window has a horizontal scrollbar, otherwise the
34 headers wouldn't align with the data when the window is scrolled.
36 This control is implemented using the native header control under MSW
37 systems and a generic implementation elsewhere.
41 If this style is specified (it is by default), the user can reorder
42 the control columns by dragging them.
43 @style{wxHD_DEFAULT_STYLE}
44 Symbolic name for the default control style, currently equal to @c
48 @beginEventTable{wxHeaderEvent}
49 @event{EVT_HEADER_CLICK(id, func)}
50 A column heading was clicked.
56 @see wxGrid, wxListCtrl, wxDataViewCtrl
59 @section headerctrl_improvements Future Improvements
61 Some features are supported by the native MSW control and so could be
62 easily implemented in this version of wxHeaderCtrl but need to be
63 implemented in the generic version as well to be really useful. Please let
64 us know if you need or, better, plan to work on implementing, any of them:
65 - Displaying bitmaps instead of or together with the text
66 - Custom drawn headers
67 - Filters associated with a column.
73 Default constructor not creating the underlying window.
75 You must use Create() after creating the object using this constructor.
80 Constructor creating the window.
82 Please see Create() for the parameters documentation.
84 wxHeaderCtrl(wxWindow
*parent
,
85 wxWindowID winid
= wxID_ANY
,
86 const wxPoint
& pos
= wxDefaultPosition
,
87 const wxSize
& size
= wxDefaultSize
,
89 const wxString
& name
= wxHeaderCtrlNameStr
);
92 Create the header control window.
95 The parent window. The header control should be typically
96 positioned along the top edge of this window.
98 Id of the control or @c wxID_ANY if you don't care.
100 The initial position of the control.
102 The initial size of the control (usually not very useful as this
103 control will typically be resized to have the same width as the
104 associated data display control).
106 The control style, @c wxHD_DEFAULT_STYLE by default. Notice that
107 the default style allows the user to reorder the columns by
108 dragging them and you need to explicitly turn this feature off by
109 using @code wxHD_DEFAULT_STYLE & ~wxHD_DRAGDROP @endcode if this is
112 The name of the control.
114 bool Create(wxWindow
*parent
,
115 wxWindowID winid
= wxID_ANY
,
116 const wxPoint
& pos
= wxDefaultPosition
,
117 const wxSize
& size
= wxDefaultSize
,
119 const wxString
& name
= wxHeaderCtrlNameStr
);
122 Return the number of columns in the control.
126 unsigned int GetColumnCount() const;
129 Return whether the control has any columns.
131 @see GetColumnCount()
133 bool IsEmpty() const;
136 Insert the column at the given position.
139 The column to insert. Notice that because of the existence of
140 implicit conversion from wxString to wxHeaderColumn a string
141 can be passed directly here.
143 The position of the new column, from 0 to GetColumnCount(). Using
144 GetColumnCount() means to append the column to the end.
148 void InsertColumn(const wxHeaderColumn
& col
, unsigned int idx
);
151 Append the column to the end of the control.
155 void AppendColumn(const wxHeaderColumn
& col
);
158 Delete the column at the given position.
160 @see InsertColumn(), AppendColumn()
162 void DeleteColumn(unsigned int idx
);
165 Show or hide the column.
167 Initially the column is shown by default or hidden if it was added with
168 wxCOL_HIDDEN flag set.
170 When a column is hidden, it doesn't appear at all on the screen but its
171 index is still taken into account when working with other columns. E.g.
172 if there are three columns 0, 1 and 2 and the column 1 is hidden you
173 still need to use index 2 to refer to the last visible column.
176 The index of the column to show or hide, from 0 to GetColumnCount().
178 Indicates whether the column should be shown (default) or hidden.
180 void ShowColumn(unsigned int idx
, bool show
= true);
183 Hide the column with the given index.
185 This is the same as calling @code ShowColumn(idx, false) @endcode.
188 The index of the column to show or hide, from 0 to GetColumnCount().
190 void HideColumn(unsigned int idx
);
193 Update the column sort indicator.
195 The sort indicator, if shown, is typically an arrow pointing upwards or
196 downwards depending on whether the control contents is sorted in
197 ascending or descending order.
200 The column to set the sort indicator for.
202 If @true or @false show the sort indicator corresponding to
203 ascending or descending sort order respectively, if @c -1 remove
204 the currently shown sort indicator.
206 virtual void ShowSortIndicator(unsigned int idx
, int sortOrder
);
209 Remove the sort indicator from the given column.
211 This is the same as calling ShowSortIndicator() with @c -1 argument.
214 The column to remove sort indicator for.
216 void RemoveSortIndicator(unsigned int idx
);