include/wx/headerctrl.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/headerctrl.h
   3 // Purpose:     wxHeaderCtrlBase class: 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 licence
   9 ///////////////////////////////////////////////////////////////////////////////
  10
  11 #ifndef _WX_HEADERCTRL_H_
  12 #define _WX_HEADERCTRL_H_
  13
  14 #include "wx/control.h"
  15
  16 #include "wx/dynarray.h"
  17 #include "wx/vector.h"
  18
  19 #include "wx/headercol.h"
  20
  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;
  25
  26 // ----------------------------------------------------------------------------
  27 // constants
  28 // ----------------------------------------------------------------------------
  29
  30 enum
  31 {
  32     // allow column drag and drop
  33     wxHD_DRAGDROP = 0x0001,
  34
  35     // style used by default when creating the control
  36     wxHD_DEFAULT_STYLE = wxHD_DRAGDROP
  37 };
  38
  39 extern WXDLLIMPEXP_DATA_CORE(const char) wxHeaderCtrlNameStr[];
  40
  41 // ----------------------------------------------------------------------------
  42 // wxHeaderCtrlBase defines the interface of a header control
  43 // ----------------------------------------------------------------------------
  44
  45 class WXDLLIMPEXP_CORE wxHeaderCtrlBase : public wxControl
  46 {
  47 public:
  48     /*
  49         Derived classes must provide default ctor as well as a ctor and
  50         Create() function with the following signatures:
  51
  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);
  58
  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);
  65      */
  66
  67     // column-related methods
  68     // ----------------------
  69
  70     // set the number of columns in the control
  71     //
  72     // this also calls UpdateColumn() for all columns
  73     void SetColumnCount(unsigned int count);
  74
  75     // return the number of columns in the control as set by SetColumnCount()
  76     unsigned int GetColumnCount() const { return DoGetCount(); }
  77
  78     // return whether the control has any columns
  79     bool IsEmpty() const { return DoGetCount() == 0; }
  80
  81     // update the column with the given index
  82     void UpdateColumn(unsigned int idx)
  83     {
  84         wxCHECK_RET( idx < GetColumnCount(), "invalid column index" );
  85
  86         DoUpdate(idx);
  87     }
  88
  89
  90     // columns order
  91     // -------------
  92
  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;
  98
  99     // get the index of the column at the given display position
 100     unsigned int GetColumnAt(unsigned int pos) const;
 101
 102     // get the position at which this column is currently displayed
 103     unsigned int GetColumnPos(unsigned int idx) const;
 104
 105     // reset the columns order to the natural one
 106     void ResetColumnsOrder();
 107
 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,
 113                                        unsigned int idx,
 114                                        unsigned int pos);
 115
 116
 117     // UI helpers
 118     // ----------
 119
 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());
 126
 127
 128     // implementation only from now on
 129     // -------------------------------
 130
 131     // the user doesn't need to TAB to this control
 132     virtual bool AcceptsFocusFromKeyboard() const { return false; }
 133
 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
 136     // DoScrollHorz()
 137     virtual void ScrollWindow(int dx, int dy, const wxRect *rect = NULL);
 138
 139 protected:
 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;
 143
 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))
 149     {
 150         return false;
 151     }
 152
 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)) { }
 157
 158
 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);
 162
 163 private:
 164     // methods implementing our public API and defined in platform-specific
 165     // implementations
 166     virtual void DoSetCount(unsigned int count) = 0;
 167     virtual unsigned int DoGetCount() const = 0;
 168     virtual void DoUpdate(unsigned int idx) = 0;
 169
 170     virtual void DoScrollHorz(int dx) = 0;
 171
 172     virtual void DoSetColumnsOrder(const wxArrayInt& order) = 0;
 173     virtual wxArrayInt DoGetColumnsOrder() const = 0;
 174
 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; }
 177
 178     // event handlers
 179     void OnSeparatorDClick(wxHeaderCtrlEvent& event);
 180
 181     DECLARE_EVENT_TABLE()
 182 };
 183
 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 // ----------------------------------------------------------------------------
 189
 190 #if defined(__WXMSW__) && !defined(__WXUNIVERSAL__)
 191     #include "wx/msw/headerctrl.h"
 192 #else
 193     #define wxHAS_GENERIC_HEADERCTRL
 194     #include "wx/generic/headerctrlg.h"
 195 #endif // platform
 196
 197 // ----------------------------------------------------------------------------
 198 // wxHeaderCtrlSimple: concrete header control which can be used standalone
 199 // ----------------------------------------------------------------------------
 200
 201 class WXDLLIMPEXP_CORE wxHeaderCtrlSimple : public wxHeaderCtrl
 202 {
 203 public:
 204     // control creation
 205     // ----------------
 206
 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)
 214     {
 215         Init();
 216
 217         Create(parent, winid, pos, size, style, name);
 218     }
 219
 220     // managing the columns
 221     // --------------------
 222
 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)
 226     {
 227         wxCHECK_RET( idx <= GetColumnCount(), "invalid column index" );
 228
 229         DoInsert(col, idx);
 230     }
 231
 232     // append the column to the end of the control
 233     void AppendColumn(const wxHeaderColumnSimple& col)
 234     {
 235         DoInsert(col, GetColumnCount());
 236     }
 237
 238     // delete the column at the given index
 239     void DeleteColumn(unsigned int idx)
 240     {
 241         wxCHECK_RET( idx < GetColumnCount(), "invalid column index" );
 242
 243         DoDelete(idx);
 244     }
 245
 246     // delete all the existing columns
 247     void DeleteAllColumns();
 248
 249
 250     // modifying columns
 251     // -----------------
 252
 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)
 256     {
 257         wxCHECK_RET( idx < GetColumnCount(), "invalid column index" );
 258
 259         DoShowColumn(idx, show);
 260     }
 261
 262     void HideColumn(unsigned int idx)
 263     {
 264         ShowColumn(idx, false);
 265     }
 266
 267     // indicate that the column is used for sorting
 268     void ShowSortIndicator(unsigned int idx, bool ascending = true)
 269     {
 270         wxCHECK_RET( idx < GetColumnCount(), "invalid column index" );
 271
 272         DoShowSortIndicator(idx, ascending);
 273     }
 274
 275     // remove the sort indicator completely
 276     void RemoveSortIndicator();
 277
 278 protected:
 279     // implement/override base class methods
 280     virtual wxHeaderColumn& GetColumn(unsigned int idx);
 281     virtual bool UpdateColumnWidthToFit(unsigned int idx, int widthTitle);
 282
 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
 287     {
 288         return -1;
 289     }
 290
 291 private:
 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);
 297
 298     // common part of all ctors
 299     void Init();
 300
 301     // bring the column count in sync with the number of columns we store
 302     void UpdateColumnCount() { SetColumnCount(m_cols.size()); }
 303
 304
 305     // all our current columns
 306     typedef wxVector<wxHeaderColumnSimple> Columns;
 307     Columns m_cols;
 308
 309     // the column currently used for sorting or -1 if none
 310     unsigned int m_sortKey;
 311
 312
 313     DECLARE_NO_COPY_CLASS(wxHeaderCtrlSimple)
 314 };
 315
 316 // ----------------------------------------------------------------------------
 317 // wxHeaderCtrl events
 318 // ----------------------------------------------------------------------------
 319
 320 class WXDLLIMPEXP_CORE wxHeaderCtrlEvent : public wxNotifyEvent
 321 {
 322 public:
 323     wxHeaderCtrlEvent(wxEventType commandType = wxEVT_NULL, int winid = 0)
 324         : wxNotifyEvent(commandType, winid),
 325           m_col(-1),
 326           m_width(0),
 327           m_order(static_cast<unsigned int>(-1))
 328     {
 329     }
 330
 331     wxHeaderCtrlEvent(const wxHeaderCtrlEvent& event)
 332         : wxNotifyEvent(event),
 333           m_col(event.m_col),
 334           m_width(event.m_width),
 335           m_order(event.m_order)
 336     {
 337     }
 338
 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; }
 342
 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; }
 346
 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; }
 350
 351     virtual wxEvent *Clone() const { return new wxHeaderCtrlEvent(*this); }
 352
 353 protected:
 354     // the column affected by the event
 355     int m_col;
 356
 357     // the current width for the dragging events
 358     int m_width;
 359
 360     // the new column position for end reorder event
 361     unsigned int m_order;
 362
 363 private:
 364     DECLARE_DYNAMIC_CLASS_NO_ASSIGN(wxHeaderCtrlEvent)
 365 };
 366
 367
 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;
 371
 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;
 375
 376 extern WXDLLIMPEXP_CORE const wxEventType wxEVT_COMMAND_HEADER_SEPARATOR_DCLICK;
 377
 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;
 381
 382 extern WXDLLIMPEXP_CORE const wxEventType wxEVT_COMMAND_HEADER_BEGIN_REORDER;
 383 extern WXDLLIMPEXP_CORE const wxEventType wxEVT_COMMAND_HEADER_END_REORDER;
 384
 385 extern WXDLLIMPEXP_CORE const wxEventType wxEVT_COMMAND_HEADER_DRAGGING_CANCELLED;
 386
 387 typedef void (wxEvtHandler::*wxHeaderCtrlEventFunction)(wxHeaderCtrlEvent&);
 388
 389 #define wxHeaderCtrlEventHandler(func) \
 390     (wxObjectEventFunction)(wxEventFunction)wxStaticCastEvent( \
 391             wxHeaderCtrlEventFunction, &func)
 392
 393 #define wx__DECLARE_HEADER_EVT(evt, id, fn) \
 394     wx__DECLARE_EVT1(wxEVT_COMMAND_HEADER_ ## evt, id, wxHeaderCtrlEventHandler(fn))
 395
 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)
 399
 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)
 403
 404 #define EVT_HEADER_SEPARATOR_DCLICK(id, fn) wx__DECLARE_HEADER_EVT(SEPARATOR_DCLICK, id, fn)
 405
 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)
 409
 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)
 412
 413 #define EVT_HEADER_DRAGGING_CANCELLED(id, fn) wx__DECLARE_HEADER_EVT(DRAGGING_CANCELLED, id, fn)
 414
 415 #endif // _WX_HEADERCTRL_H_