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