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