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 // Copyright:   (c) 2008 Vadim Zeitlin <vadim@wxwidgets.org>
   7 // Licence:     wxWindows licence
   8 ///////////////////////////////////////////////////////////////////////////////
   9
  10 #ifndef _WX_HEADERCTRL_H_
  11 #define _WX_HEADERCTRL_H_
  12
  13 #include "wx/control.h"
  14
  15 #if wxUSE_HEADERCTRL
  16
  17 #include "wx/dynarray.h"
  18 #include "wx/vector.h"
  19
  20 #include "wx/headercol.h"
  21
  22 // notice that the classes in this header are defined in the core library even
  23 // although currently they're only used by wxGrid which is in wxAdv because we
  24 // plan to use it in wxListCtrl which is in core too in the future
  25 class WXDLLIMPEXP_FWD_CORE wxHeaderCtrlEvent;
  26
  27 // ----------------------------------------------------------------------------
  28 // constants
  29 // ----------------------------------------------------------------------------
  30
  31 enum
  32 {
  33     // allow column drag and drop
  34     wxHD_ALLOW_REORDER = 0x0001,
  35
  36     // allow hiding (and showing back) the columns using the menu shown by
  37     // right clicking the header
  38     wxHD_ALLOW_HIDE = 0x0002,
  39
  40     // style used by default when creating the control
  41     wxHD_DEFAULT_STYLE = wxHD_ALLOW_REORDER
  42 };
  43
  44 extern WXDLLIMPEXP_DATA_CORE(const char) wxHeaderCtrlNameStr[];
  45
  46 // ----------------------------------------------------------------------------
  47 // wxHeaderCtrlBase defines the interface of a header control
  48 // ----------------------------------------------------------------------------
  49
  50 class WXDLLIMPEXP_CORE wxHeaderCtrlBase : public wxControl
  51 {
  52 public:
  53     /*
  54         Derived classes must provide default ctor as well as a ctor and
  55         Create() function with the following signatures:
  56
  57     wxHeaderCtrl(wxWindow *parent,
  58                  wxWindowID winid = wxID_ANY,
  59                  const wxPoint& pos = wxDefaultPosition,
  60                  const wxSize& size = wxDefaultSize,
  61                  long style = wxHD_DEFAULT_STYLE,
  62                  const wxString& name = wxHeaderCtrlNameStr);
  63
  64     bool Create(wxWindow *parent,
  65                 wxWindowID winid = wxID_ANY,
  66                 const wxPoint& pos = wxDefaultPosition,
  67                 const wxSize& size = wxDefaultSize,
  68                 long style = wxHD_DEFAULT_STYLE,
  69                 const wxString& name = wxHeaderCtrlNameStr);
  70      */
  71
  72     // column-related methods
  73     // ----------------------
  74
  75     // set the number of columns in the control
  76     //
  77     // this also calls UpdateColumn() for all columns
  78     void SetColumnCount(unsigned int count);
  79
  80     // return the number of columns in the control as set by SetColumnCount()
  81     unsigned int GetColumnCount() const { return DoGetCount(); }
  82
  83     // return whether the control has any columns
  84     bool IsEmpty() const { return DoGetCount() == 0; }
  85
  86     // update the column with the given index
  87     void UpdateColumn(unsigned int idx)
  88     {
  89         wxCHECK_RET( idx < GetColumnCount(), "invalid column index" );
  90
  91         DoUpdate(idx);
  92     }
  93
  94
  95     // columns order
  96     // -------------
  97
  98     // set the columns order: the array defines the column index which appears
  99     // the given position, it must have GetColumnCount() elements and contain
 100     // all indices exactly once
 101     void SetColumnsOrder(const wxArrayInt& order);
 102     wxArrayInt GetColumnsOrder() const;
 103
 104     // get the index of the column at the given display position
 105     unsigned int GetColumnAt(unsigned int pos) const;
 106
 107     // get the position at which this column is currently displayed
 108     unsigned int GetColumnPos(unsigned int idx) const;
 109
 110     // reset the columns order to the natural one
 111     void ResetColumnsOrder();
 112
 113     // helper function used by the generic version of this control and also
 114     // wxGrid: reshuffles the array of column indices indexed by positions
 115     // (i.e. using the same convention as for SetColumnsOrder()) so that the
 116     // column with the given index is found at the specified position
 117     static void MoveColumnInOrderArray(wxArrayInt& order,
 118                                        unsigned int idx,
 119                                        unsigned int pos);
 120
 121
 122     // UI helpers
 123     // ----------
 124
 125 #if wxUSE_MENUS
 126     // show the popup menu containing all columns with check marks for the ones
 127     // which are currently shown and return true if something was done using it
 128     // (in this case UpdateColumnVisibility() will have been called) or false
 129     // if the menu was cancelled
 130     //
 131     // this is called from the default right click handler for the controls
 132     // with wxHD_ALLOW_HIDE style
 133     bool ShowColumnsMenu(const wxPoint& pt, const wxString& title = wxString());
 134
 135     // append the entries for all our columns to the given menu, with the
 136     // currently visible columns being checked
 137     //
 138     // this is used by ShowColumnsMenu() but can also be used if you use your
 139     // own custom columns menu but nevertheless want to show all the columns in
 140     // it
 141     //
 142     // the ids of the items corresponding to the columns are consecutive and
 143     // start from idColumnsBase
 144     void AddColumnsItems(wxMenu& menu, int idColumnsBase = 0);
 145 #endif // wxUSE_MENUS
 146
 147     // show the columns customization dialog and return true if something was
 148     // changed using it (in which case UpdateColumnVisibility() and/or
 149     // UpdateColumnsOrder() will have been called)
 150     //
 151     // this is called by the control itself from ShowColumnsMenu() (which in
 152     // turn is only called by the control if wxHD_ALLOW_HIDE style was
 153     // specified) and if the control has wxHD_ALLOW_REORDER style as well
 154     bool ShowCustomizeDialog();
 155
 156     // compute column title width
 157     int GetColumnTitleWidth(const wxHeaderColumn& col);
 158
 159     // implementation only from now on
 160     // -------------------------------
 161
 162     // the user doesn't need to TAB to this control
 163     virtual bool AcceptsFocusFromKeyboard() const { return false; }
 164
 165     // this method is only overridden in order to synchronize the control with
 166     // the main window when it is scrolled, the derived class must implement
 167     // DoScrollHorz()
 168     virtual void ScrollWindow(int dx, int dy, const wxRect *rect = NULL);
 169
 170 protected:
 171     // this method must be implemented by the derived classes to return the
 172     // information for the given column
 173     virtual const wxHeaderColumn& GetColumn(unsigned int idx) const = 0;
 174
 175     // this method is called from the default EVT_HEADER_SEPARATOR_DCLICK
 176     // handler to update the fitting column width of the given column, it
 177     // should return true if the width was really updated
 178     virtual bool UpdateColumnWidthToFit(unsigned int WXUNUSED(idx),
 179                                         int WXUNUSED(widthTitle))
 180     {
 181         return false;
 182     }
 183
 184     // this method is called from ShowColumnsMenu() and must be overridden to
 185     // update the internal column visibility (there is no need to call
 186     // UpdateColumn() from here, this will be done internally)
 187     virtual void UpdateColumnVisibility(unsigned int WXUNUSED(idx),
 188                                         bool WXUNUSED(show))
 189     {
 190         wxFAIL_MSG( "must be overridden if called" );
 191     }
 192
 193     // this method is called from ShowCustomizeDialog() to reorder all columns
 194     // at once and should be implemented for controls using wxHD_ALLOW_REORDER
 195     // style (there is no need to call SetColumnsOrder() from here, this is
 196     // done by the control itself)
 197     virtual void UpdateColumnsOrder(const wxArrayInt& WXUNUSED(order))
 198     {
 199         wxFAIL_MSG( "must be overridden if called" );
 200     }
 201
 202     // this method can be overridden in the derived classes to do something
 203     // (e.g. update/resize some internal data structures) before the number of
 204     // columns in the control changes
 205     virtual void OnColumnCountChanging(unsigned int WXUNUSED(count)) { }
 206
 207
 208     // helper function for the derived classes: update the array of column
 209     // indices after the number of columns changed
 210     void DoResizeColumnIndices(wxArrayInt& colIndices, unsigned int count);
 211
 212 protected:
 213     // this window doesn't look nice with the border so don't use it by default
 214     virtual wxBorder GetDefaultBorder() const { return wxBORDER_NONE; }
 215
 216 private:
 217     // methods implementing our public API and defined in platform-specific
 218     // implementations
 219     virtual void DoSetCount(unsigned int count) = 0;
 220     virtual unsigned int DoGetCount() const = 0;
 221     virtual void DoUpdate(unsigned int idx) = 0;
 222
 223     virtual void DoScrollHorz(int dx) = 0;
 224
 225     virtual void DoSetColumnsOrder(const wxArrayInt& order) = 0;
 226     virtual wxArrayInt DoGetColumnsOrder() const = 0;
 227
 228
 229     // event handlers
 230     void OnSeparatorDClick(wxHeaderCtrlEvent& event);
 231 #if wxUSE_MENUS
 232     void OnRClick(wxHeaderCtrlEvent& event);
 233 #endif // wxUSE_MENUS
 234
 235     DECLARE_EVENT_TABLE()
 236 };
 237
 238 // ----------------------------------------------------------------------------
 239 // wxHeaderCtrl: port-specific header control implementation, notice that this
 240 //               is still an ABC which is meant to be used as part of another
 241 //               control, see wxHeaderCtrlSimple for a standalone version
 242 // ----------------------------------------------------------------------------
 243
 244 #if defined(__WXMSW__) && !defined(__WXUNIVERSAL__)
 245     #include "wx/msw/headerctrl.h"
 246 #else
 247     #define wxHAS_GENERIC_HEADERCTRL
 248     #include "wx/generic/headerctrlg.h"
 249 #endif // platform
 250
 251 // ----------------------------------------------------------------------------
 252 // wxHeaderCtrlSimple: concrete header control which can be used standalone
 253 // ----------------------------------------------------------------------------
 254
 255 class WXDLLIMPEXP_CORE wxHeaderCtrlSimple : public wxHeaderCtrl
 256 {
 257 public:
 258     // control creation
 259     // ----------------
 260
 261     wxHeaderCtrlSimple() { Init(); }
 262     wxHeaderCtrlSimple(wxWindow *parent,
 263                        wxWindowID winid = wxID_ANY,
 264                        const wxPoint& pos = wxDefaultPosition,
 265                        const wxSize& size = wxDefaultSize,
 266                        long style = wxHD_DEFAULT_STYLE,
 267                        const wxString& name = wxHeaderCtrlNameStr)
 268     {
 269         Init();
 270
 271         Create(parent, winid, pos, size, style, name);
 272     }
 273
 274     // managing the columns
 275     // --------------------
 276
 277     // insert the column at the given position, using GetColumnCount() as
 278     // position appends it at the end
 279     void InsertColumn(const wxHeaderColumnSimple& col, unsigned int idx)
 280     {
 281         wxCHECK_RET( idx <= GetColumnCount(), "invalid column index" );
 282
 283         DoInsert(col, idx);
 284     }
 285
 286     // append the column to the end of the control
 287     void AppendColumn(const wxHeaderColumnSimple& col)
 288     {
 289         DoInsert(col, GetColumnCount());
 290     }
 291
 292     // delete the column at the given index
 293     void DeleteColumn(unsigned int idx)
 294     {
 295         wxCHECK_RET( idx < GetColumnCount(), "invalid column index" );
 296
 297         DoDelete(idx);
 298     }
 299
 300     // delete all the existing columns
 301     void DeleteAllColumns();
 302
 303
 304     // modifying columns
 305     // -----------------
 306
 307     // show or hide the column, notice that even when a column is hidden we
 308     // still account for it when using indices
 309     void ShowColumn(unsigned int idx, bool show = true)
 310     {
 311         wxCHECK_RET( idx < GetColumnCount(), "invalid column index" );
 312
 313         DoShowColumn(idx, show);
 314     }
 315
 316     void HideColumn(unsigned int idx)
 317     {
 318         ShowColumn(idx, false);
 319     }
 320
 321     // indicate that the column is used for sorting
 322     void ShowSortIndicator(unsigned int idx, bool ascending = true)
 323     {
 324         wxCHECK_RET( idx < GetColumnCount(), "invalid column index" );
 325
 326         DoShowSortIndicator(idx, ascending);
 327     }
 328
 329     // remove the sort indicator completely
 330     void RemoveSortIndicator();
 331
 332 protected:
 333     // implement/override base class methods
 334     virtual const wxHeaderColumn& GetColumn(unsigned int idx) const;
 335     virtual bool UpdateColumnWidthToFit(unsigned int idx, int widthTitle);
 336
 337     // and define another one to be overridden in the derived classes: it
 338     // should return the best width for the given column contents or -1 if not
 339     // implemented, we use it to implement UpdateColumnWidthToFit()
 340     virtual int GetBestFittingWidth(unsigned int WXUNUSED(idx)) const
 341     {
 342         return -1;
 343     }
 344
 345 private:
 346     // functions implementing our public API
 347     void DoInsert(const wxHeaderColumnSimple& col, unsigned int idx);
 348     void DoDelete(unsigned int idx);
 349     void DoShowColumn(unsigned int idx, bool show);
 350     void DoShowSortIndicator(unsigned int idx, bool ascending);
 351
 352     // common part of all ctors
 353     void Init();
 354
 355     // bring the column count in sync with the number of columns we store
 356     void UpdateColumnCount()
 357     {
 358         SetColumnCount(static_cast<int>(m_cols.size()));
 359     }
 360
 361
 362     // all our current columns
 363     typedef wxVector<wxHeaderColumnSimple> Columns;
 364     Columns m_cols;
 365
 366     // the column currently used for sorting or -1 if none
 367     unsigned int m_sortKey;
 368
 369
 370     wxDECLARE_NO_COPY_CLASS(wxHeaderCtrlSimple);
 371 };
 372
 373 // ----------------------------------------------------------------------------
 374 // wxHeaderCtrl events
 375 // ----------------------------------------------------------------------------
 376
 377 class WXDLLIMPEXP_CORE wxHeaderCtrlEvent : public wxNotifyEvent
 378 {
 379 public:
 380     wxHeaderCtrlEvent(wxEventType commandType = wxEVT_NULL, int winid = 0)
 381         : wxNotifyEvent(commandType, winid),
 382           m_col(-1),
 383           m_width(0),
 384           m_order(static_cast<unsigned int>(-1))
 385     {
 386     }
 387
 388     wxHeaderCtrlEvent(const wxHeaderCtrlEvent& event)
 389         : wxNotifyEvent(event),
 390           m_col(event.m_col),
 391           m_width(event.m_width),
 392           m_order(event.m_order)
 393     {
 394     }
 395
 396     // the column which this event pertains to: valid for all header events
 397     int GetColumn() const { return m_col; }
 398     void SetColumn(int col) { m_col = col; }
 399
 400     // the width of the column: valid for column resizing/dragging events only
 401     int GetWidth() const { return m_width; }
 402     void SetWidth(int width) { m_width = width; }
 403
 404     // the new position of the column: for end reorder events only
 405     unsigned int GetNewOrder() const { return m_order; }
 406     void SetNewOrder(unsigned int order) { m_order = order; }
 407
 408     virtual wxEvent *Clone() const { return new wxHeaderCtrlEvent(*this); }
 409
 410 protected:
 411     // the column affected by the event
 412     int m_col;
 413
 414     // the current width for the dragging events
 415     int m_width;
 416
 417     // the new column position for end reorder event
 418     unsigned int m_order;
 419
 420 private:
 421     DECLARE_DYNAMIC_CLASS_NO_ASSIGN(wxHeaderCtrlEvent)
 422 };
 423
 424
 425 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_CORE, wxEVT_HEADER_CLICK, wxHeaderCtrlEvent );
 426 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_CORE, wxEVT_HEADER_RIGHT_CLICK, wxHeaderCtrlEvent );
 427 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_CORE, wxEVT_HEADER_MIDDLE_CLICK, wxHeaderCtrlEvent );
 428
 429 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_CORE, wxEVT_HEADER_DCLICK, wxHeaderCtrlEvent );
 430 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_CORE, wxEVT_HEADER_RIGHT_DCLICK, wxHeaderCtrlEvent );
 431 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_CORE, wxEVT_HEADER_MIDDLE_DCLICK, wxHeaderCtrlEvent );
 432
 433 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_CORE, wxEVT_HEADER_SEPARATOR_DCLICK, wxHeaderCtrlEvent );
 434
 435 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_CORE, wxEVT_HEADER_BEGIN_RESIZE, wxHeaderCtrlEvent );
 436 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_CORE, wxEVT_HEADER_RESIZING, wxHeaderCtrlEvent );
 437 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_CORE, wxEVT_HEADER_END_RESIZE, wxHeaderCtrlEvent );
 438
 439 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_CORE, wxEVT_HEADER_BEGIN_REORDER, wxHeaderCtrlEvent );
 440 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_CORE, wxEVT_HEADER_END_REORDER, wxHeaderCtrlEvent );
 441
 442 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_CORE, wxEVT_HEADER_DRAGGING_CANCELLED, wxHeaderCtrlEvent );
 443
 444 typedef void (wxEvtHandler::*wxHeaderCtrlEventFunction)(wxHeaderCtrlEvent&);
 445
 446 #define wxHeaderCtrlEventHandler(func) \
 447     wxEVENT_HANDLER_CAST(wxHeaderCtrlEventFunction, func)
 448
 449 #define wx__DECLARE_HEADER_EVT(evt, id, fn) \
 450     wx__DECLARE_EVT1(wxEVT_HEADER_ ## evt, id, wxHeaderCtrlEventHandler(fn))
 451
 452 #define EVT_HEADER_CLICK(id, fn) wx__DECLARE_HEADER_EVT(CLICK, id, fn)
 453 #define EVT_HEADER_RIGHT_CLICK(id, fn) wx__DECLARE_HEADER_EVT(RIGHT_CLICK, id, fn)
 454 #define EVT_HEADER_MIDDLE_CLICK(id, fn) wx__DECLARE_HEADER_EVT(MIDDLE_CLICK, id, fn)
 455
 456 #define EVT_HEADER_DCLICK(id, fn) wx__DECLARE_HEADER_EVT(DCLICK, id, fn)
 457 #define EVT_HEADER_RIGHT_DCLICK(id, fn) wx__DECLARE_HEADER_EVT(RIGHT_DCLICK, id, fn)
 458 #define EVT_HEADER_MIDDLE_DCLICK(id, fn) wx__DECLARE_HEADER_EVT(MIDDLE_DCLICK, id, fn)
 459
 460 #define EVT_HEADER_SEPARATOR_DCLICK(id, fn) wx__DECLARE_HEADER_EVT(SEPARATOR_DCLICK, id, fn)
 461
 462 #define EVT_HEADER_BEGIN_RESIZE(id, fn) wx__DECLARE_HEADER_EVT(BEGIN_RESIZE, id, fn)
 463 #define EVT_HEADER_RESIZING(id, fn) wx__DECLARE_HEADER_EVT(RESIZING, id, fn)
 464 #define EVT_HEADER_END_RESIZE(id, fn) wx__DECLARE_HEADER_EVT(END_RESIZE, id, fn)
 465
 466 #define EVT_HEADER_BEGIN_REORDER(id, fn) wx__DECLARE_HEADER_EVT(BEGIN_REORDER, id, fn)
 467 #define EVT_HEADER_END_REORDER(id, fn) wx__DECLARE_HEADER_EVT(END_REORDER, id, fn)
 468
 469 #define EVT_HEADER_DRAGGING_CANCELLED(id, fn) wx__DECLARE_HEADER_EVT(DRAGGING_CANCELLED, id, fn)
 470
 471 // old wxEVT_COMMAND_* constants
 472 #define wxEVT_COMMAND_HEADER_CLICK                wxEVT_HEADER_CLICK
 473 #define wxEVT_COMMAND_HEADER_RIGHT_CLICK          wxEVT_HEADER_RIGHT_CLICK
 474 #define wxEVT_COMMAND_HEADER_MIDDLE_CLICK         wxEVT_HEADER_MIDDLE_CLICK
 475 #define wxEVT_COMMAND_HEADER_DCLICK               wxEVT_HEADER_DCLICK
 476 #define wxEVT_COMMAND_HEADER_RIGHT_DCLICK         wxEVT_HEADER_RIGHT_DCLICK
 477 #define wxEVT_COMMAND_HEADER_MIDDLE_DCLICK        wxEVT_HEADER_MIDDLE_DCLICK
 478 #define wxEVT_COMMAND_HEADER_SEPARATOR_DCLICK     wxEVT_HEADER_SEPARATOR_DCLICK
 479 #define wxEVT_COMMAND_HEADER_BEGIN_RESIZE         wxEVT_HEADER_BEGIN_RESIZE
 480 #define wxEVT_COMMAND_HEADER_RESIZING             wxEVT_HEADER_RESIZING
 481 #define wxEVT_COMMAND_HEADER_END_RESIZE           wxEVT_HEADER_END_RESIZE
 482 #define wxEVT_COMMAND_HEADER_BEGIN_REORDER        wxEVT_HEADER_BEGIN_REORDER
 483 #define wxEVT_COMMAND_HEADER_END_REORDER          wxEVT_HEADER_END_REORDER
 484 #define wxEVT_COMMAND_HEADER_DRAGGING_CANCELLED   wxEVT_HEADER_DRAGGING_CANCELLED
 485
 486 #endif // wxUSE_HEADERCTRL
 487
 488 #endif // _WX_HEADERCTRL_H_