1 ///////////////////////////////////////////////////////////////////////////////
2 // Name: wx/headerctrl.h
3 // Purpose: wxHeaderCtrlBase class: interface of wxHeaderCtrl
4 // Author: Vadim Zeitlin
7 // Copyright: (c) 2008 Vadim Zeitlin <vadim@wxwidgets.org>
8 // Licence: wxWindows licence
9 ///////////////////////////////////////////////////////////////////////////////
11 #ifndef _WX_HEADERCTRL_H_
12 #define _WX_HEADERCTRL_H_
14 #include "wx/control.h"
16 #include "wx/dynarray.h"
17 #include "wx/vector.h"
19 #include "wx/headercol.h"
21 // notice that the classes in this header are defined in the core library even
22 // although currently they're only used by wxGrid which is in wxAdv because we
23 // plan to use it in wxListCtrl which is in core too in the future
24 class WXDLLIMPEXP_FWD_CORE wxHeaderCtrlEvent
;
26 // ----------------------------------------------------------------------------
28 // ----------------------------------------------------------------------------
32 // allow column drag and drop
33 wxHD_DRAGDROP
= 0x0001,
35 // style used by default when creating the control
36 wxHD_DEFAULT_STYLE
= wxHD_DRAGDROP
39 extern WXDLLIMPEXP_DATA_CORE(const char) wxHeaderCtrlNameStr
[];
41 // ----------------------------------------------------------------------------
42 // wxHeaderCtrlBase defines the interface of a header control
43 // ----------------------------------------------------------------------------
45 class WXDLLIMPEXP_CORE wxHeaderCtrlBase
: public wxControl
49 Derived classes must provide default ctor as well as a ctor and
50 Create() function with the following signatures:
52 wxHeaderCtrl(wxWindow *parent,
53 wxWindowID winid = wxID_ANY,
54 const wxPoint& pos = wxDefaultPosition,
55 const wxSize& size = wxDefaultSize,
56 long style = wxHD_DEFAULT_STYLE,
57 const wxString& name = wxHeaderCtrlNameStr);
59 bool Create(wxWindow *parent,
60 wxWindowID winid = wxID_ANY,
61 const wxPoint& pos = wxDefaultPosition,
62 const wxSize& size = wxDefaultSize,
63 long style = wxHD_DEFAULT_STYLE,
64 const wxString& name = wxHeaderCtrlNameStr);
67 // column-related methods
68 // ----------------------
70 // set the number of columns in the control
72 // this also calls UpdateColumn() for all columns
73 void SetColumnCount(unsigned int count
);
75 // return the number of columns in the control as set by SetColumnCount()
76 unsigned int GetColumnCount() const { return DoGetCount(); }
78 // return whether the control has any columns
79 bool IsEmpty() const { return DoGetCount() == 0; }
81 // update the column with the given index
82 void UpdateColumn(unsigned int idx
)
84 wxCHECK_RET( idx
< GetColumnCount(), "invalid column index" );
93 // set the columns order: the array defines the column index which appears
94 // the given position, it must have GetColumnCount() elements and contain
95 // all indices exactly once
96 void SetColumnsOrder(const wxArrayInt
& order
);
97 wxArrayInt
GetColumnsOrder() const;
99 // get the index of the column at the given display position
100 unsigned int GetColumnAt(unsigned int pos
) const;
102 // get the position at which this column is currently displayed
103 unsigned int GetColumnPos(unsigned int idx
) const;
105 // reset the columns order to the natural one
106 void ResetColumnsOrder();
108 // helper function used by the generic version of this control and also
109 // wxGrid: reshuffles the array of column indices indexed by positions
110 // (i.e. using the same convention as for SetColumnsOrder()) so that the
111 // column with the given index is found at the specified position
112 static void MoveColumnInOrderArray(wxArrayInt
& order
,
120 // show the popup menu containing all columns with check marks for the ones
121 // which are currently shown -- this is meant to be called from
122 // EVT_HEADER_RIGHT_CLICK handler and should toggle the visibility of the
123 // n-th column if the function returns valid column index and not wxID_NONE
124 // which is returned if the user cancels the menu
125 int ShowColumnsMenu(const wxString
& title
= wxString());
128 // implementation only from now on
129 // -------------------------------
131 // the user doesn't need to TAB to this control
132 virtual bool AcceptsFocusFromKeyboard() const { return false; }
134 // this method is only overridden in order to synchronize the control with
135 // the main window when it is scrolled, the derived class must implement
137 virtual void ScrollWindow(int dx
, int dy
, const wxRect
*rect
= NULL
);
140 // this method must be implemented by the derived classes to return the
141 // information for the given column
142 virtual wxHeaderColumn
& GetColumn(unsigned int idx
) = 0;
144 // this method is called from the default EVT_HEADER_SEPARATOR_DCLICK
145 // handler to update the fitting column width of the given column, it
146 // should return true if the width was really updated
147 virtual bool UpdateColumnWidthToFit(unsigned int WXUNUSED(idx
),
148 int WXUNUSED(widthTitle
))
153 // this method can be overridden in the derived classes to do something
154 // (e.g. update/resize some internal data structures) before the number of
155 // columns in the control changes
156 virtual void OnColumnCountChanging(unsigned int WXUNUSED(count
)) { }
159 // helper function for the derived classes: update the array of column
160 // indices after the number of columns changed
161 void DoResizeColumnIndices(wxArrayInt
& colIndices
, unsigned int count
);
164 // methods implementing our public API and defined in platform-specific
166 virtual void DoSetCount(unsigned int count
) = 0;
167 virtual unsigned int DoGetCount() const = 0;
168 virtual void DoUpdate(unsigned int idx
) = 0;
170 virtual void DoScrollHorz(int dx
) = 0;
172 virtual void DoSetColumnsOrder(const wxArrayInt
& order
) = 0;
173 virtual wxArrayInt
DoGetColumnsOrder() const = 0;
175 // this window doesn't look nice with the border so don't use it by default
176 virtual wxBorder
GetDefaultBorder() const { return wxBORDER_NONE
; }
179 void OnSeparatorDClick(wxHeaderCtrlEvent
& event
);
181 DECLARE_EVENT_TABLE()
184 // ----------------------------------------------------------------------------
185 // wxHeaderCtrl: port-specific header control implementation, notice that this
186 // is still an ABC which is meant to be used as part of another
187 // control, see wxHeaderCtrlSimple for a standalone version
188 // ----------------------------------------------------------------------------
190 #if defined(__WXMSW__) && !defined(__WXUNIVERSAL__)
191 #include "wx/msw/headerctrl.h"
193 #define wxHAS_GENERIC_HEADERCTRL
194 #include "wx/generic/headerctrlg.h"
197 // ----------------------------------------------------------------------------
198 // wxHeaderCtrlSimple: concrete header control which can be used standalone
199 // ----------------------------------------------------------------------------
201 class WXDLLIMPEXP_CORE wxHeaderCtrlSimple
: public wxHeaderCtrl
207 wxHeaderCtrlSimple() { Init(); }
208 wxHeaderCtrlSimple(wxWindow
*parent
,
209 wxWindowID winid
= wxID_ANY
,
210 const wxPoint
& pos
= wxDefaultPosition
,
211 const wxSize
& size
= wxDefaultSize
,
212 long style
= wxHD_DEFAULT_STYLE
,
213 const wxString
& name
= wxHeaderCtrlNameStr
)
217 Create(parent
, winid
, pos
, size
, style
, name
);
220 // managing the columns
221 // --------------------
223 // insert the column at the given position, using GetColumnCount() as
224 // position appends it at the end
225 void InsertColumn(const wxHeaderColumnSimple
& col
, unsigned int idx
)
227 wxCHECK_RET( idx
<= GetColumnCount(), "invalid column index" );
232 // append the column to the end of the control
233 void AppendColumn(const wxHeaderColumnSimple
& col
)
235 DoInsert(col
, GetColumnCount());
238 // delete the column at the given index
239 void DeleteColumn(unsigned int idx
)
241 wxCHECK_RET( idx
< GetColumnCount(), "invalid column index" );
246 // delete all the existing columns
247 void DeleteAllColumns();
253 // show or hide the column, notice that even when a column is hidden we
254 // still account for it when using indices
255 void ShowColumn(unsigned int idx
, bool show
= true)
257 wxCHECK_RET( idx
< GetColumnCount(), "invalid column index" );
259 DoShowColumn(idx
, show
);
262 void HideColumn(unsigned int idx
)
264 ShowColumn(idx
, false);
267 // indicate that the column is used for sorting
268 void ShowSortIndicator(unsigned int idx
, bool ascending
= true)
270 wxCHECK_RET( idx
< GetColumnCount(), "invalid column index" );
272 DoShowSortIndicator(idx
, ascending
);
275 // remove the sort indicator completely
276 void RemoveSortIndicator();
279 // implement/override base class methods
280 virtual wxHeaderColumn
& GetColumn(unsigned int idx
);
281 virtual bool UpdateColumnWidthToFit(unsigned int idx
, int widthTitle
);
283 // and define another one to be overridden in the derived classes: it
284 // should return the best width for the given column contents or -1 if not
285 // implemented, we use it to implement UpdateColumnWidthToFit()
286 virtual int GetBestFittingWidth(unsigned int WXUNUSED(idx
)) const
292 // functions implementing our public API
293 void DoInsert(const wxHeaderColumnSimple
& col
, unsigned int idx
);
294 void DoDelete(unsigned int idx
);
295 void DoShowColumn(unsigned int idx
, bool show
);
296 void DoShowSortIndicator(unsigned int idx
, bool ascending
);
298 // common part of all ctors
301 // bring the column count in sync with the number of columns we store
302 void UpdateColumnCount() { SetColumnCount(m_cols
.size()); }
305 // all our current columns
306 typedef wxVector
<wxHeaderColumnSimple
> Columns
;
309 // the column currently used for sorting or -1 if none
310 unsigned int m_sortKey
;
313 DECLARE_NO_COPY_CLASS(wxHeaderCtrlSimple
)
316 // ----------------------------------------------------------------------------
317 // wxHeaderCtrl events
318 // ----------------------------------------------------------------------------
320 class WXDLLIMPEXP_CORE wxHeaderCtrlEvent
: public wxNotifyEvent
323 wxHeaderCtrlEvent(wxEventType commandType
= wxEVT_NULL
, int winid
= 0)
324 : wxNotifyEvent(commandType
, winid
),
327 m_order(static_cast<unsigned int>(-1))
331 wxHeaderCtrlEvent(const wxHeaderCtrlEvent
& event
)
332 : wxNotifyEvent(event
),
334 m_width(event
.m_width
),
335 m_order(event
.m_order
)
339 // the column which this event pertains to: valid for all header events
340 int GetColumn() const { return m_col
; }
341 void SetColumn(int col
) { m_col
= col
; }
343 // the width of the column: valid for column resizing/dragging events only
344 int GetWidth() const { return m_width
; }
345 void SetWidth(int width
) { m_width
= width
; }
347 // the new position of the column: for end reorder events only
348 unsigned int GetNewOrder() const { return m_order
; }
349 void SetNewOrder(unsigned int order
) { m_order
= order
; }
351 virtual wxEvent
*Clone() const { return new wxHeaderCtrlEvent(*this); }
354 // the column affected by the event
357 // the current width for the dragging events
360 // the new column position for end reorder event
361 unsigned int m_order
;
364 DECLARE_DYNAMIC_CLASS_NO_ASSIGN(wxHeaderCtrlEvent
)
368 extern WXDLLIMPEXP_CORE
const wxEventType wxEVT_COMMAND_HEADER_CLICK
;
369 extern WXDLLIMPEXP_CORE
const wxEventType wxEVT_COMMAND_HEADER_RIGHT_CLICK
;
370 extern WXDLLIMPEXP_CORE
const wxEventType wxEVT_COMMAND_HEADER_MIDDLE_CLICK
;
372 extern WXDLLIMPEXP_CORE
const wxEventType wxEVT_COMMAND_HEADER_DCLICK
;
373 extern WXDLLIMPEXP_CORE
const wxEventType wxEVT_COMMAND_HEADER_RIGHT_DCLICK
;
374 extern WXDLLIMPEXP_CORE
const wxEventType wxEVT_COMMAND_HEADER_MIDDLE_DCLICK
;
376 extern WXDLLIMPEXP_CORE
const wxEventType wxEVT_COMMAND_HEADER_SEPARATOR_DCLICK
;
378 extern WXDLLIMPEXP_CORE
const wxEventType wxEVT_COMMAND_HEADER_BEGIN_RESIZE
;
379 extern WXDLLIMPEXP_CORE
const wxEventType wxEVT_COMMAND_HEADER_RESIZING
;
380 extern WXDLLIMPEXP_CORE
const wxEventType wxEVT_COMMAND_HEADER_END_RESIZE
;
382 extern WXDLLIMPEXP_CORE
const wxEventType wxEVT_COMMAND_HEADER_BEGIN_REORDER
;
383 extern WXDLLIMPEXP_CORE
const wxEventType wxEVT_COMMAND_HEADER_END_REORDER
;
385 extern WXDLLIMPEXP_CORE
const wxEventType wxEVT_COMMAND_HEADER_DRAGGING_CANCELLED
;
387 typedef void (wxEvtHandler::*wxHeaderCtrlEventFunction
)(wxHeaderCtrlEvent
&);
389 #define wxHeaderCtrlEventHandler(func) \
390 (wxObjectEventFunction)(wxEventFunction)wxStaticCastEvent( \
391 wxHeaderCtrlEventFunction, &func)
393 #define wx__DECLARE_HEADER_EVT(evt, id, fn) \
394 wx__DECLARE_EVT1(wxEVT_COMMAND_HEADER_ ## evt, id, wxHeaderCtrlEventHandler(fn))
396 #define EVT_HEADER_CLICK(id, fn) wx__DECLARE_HEADER_EVT(CLICK, id, fn)
397 #define EVT_HEADER_RIGHT_CLICK(id, fn) wx__DECLARE_HEADER_EVT(RIGHT_CLICK, id, fn)
398 #define EVT_HEADER_MIDDLE_CLICK(id, fn) wx__DECLARE_HEADER_EVT(MIDDLE_CLICK, id, fn)
400 #define EVT_HEADER_DCLICK(id, fn) wx__DECLARE_HEADER_EVT(DCLICK, id, fn)
401 #define EVT_HEADER_RIGHT_DCLICK(id, fn) wx__DECLARE_HEADER_EVT(RIGHT_DCLICK, id, fn)
402 #define EVT_HEADER_MIDDLE_DCLICK(id, fn) wx__DECLARE_HEADER_EVT(MIDDLE_DCLICK, id, fn)
404 #define EVT_HEADER_SEPARATOR_DCLICK(id, fn) wx__DECLARE_HEADER_EVT(SEPARATOR_DCLICK, id, fn)
406 #define EVT_HEADER_BEGIN_RESIZE(id, fn) wx__DECLARE_HEADER_EVT(BEGIN_RESIZE, id, fn)
407 #define EVT_HEADER_RESIZING(id, fn) wx__DECLARE_HEADER_EVT(RESIZING, id, fn)
408 #define EVT_HEADER_END_RESIZE(id, fn) wx__DECLARE_HEADER_EVT(END_RESIZE, id, fn)
410 #define EVT_HEADER_BEGIN_REORDER(id, fn) wx__DECLARE_HEADER_EVT(BEGIN_REORDER, id, fn)
411 #define EVT_HEADER_END_REORDER(id, fn) wx__DECLARE_HEADER_EVT(END_REORDER, id, fn)
413 #define EVT_HEADER_DRAGGING_CANCELLED(id, fn) wx__DECLARE_HEADER_EVT(DRAGGING_CANCELLED, id, fn)
415 #endif // _WX_HEADERCTRL_H_