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/vector.h"
  17
  18 #include "wx/headercol.h"
  19
  20 // notice that the classes in this header are defined in the core library even
  21 // although currently they're only used by wxGrid which is in wxAdv because we
  22 // plan to use it in wxListCtrl which is in core too in the future
  23 class WXDLLIMPEXP_FWD_CORE wxHeaderCtrlEvent;
  24
  25 // ----------------------------------------------------------------------------
  26 // constants
  27 // ----------------------------------------------------------------------------
  28
  29 enum
  30 {
  31     // allow column drag and drop
  32     wxHD_DRAGDROP = 0x0001,
  33
  34     // style used by default when creating the control
  35     wxHD_DEFAULT_STYLE = wxHD_DRAGDROP
  36 };
  37
  38 extern WXDLLIMPEXP_DATA_CORE(const char) wxHeaderCtrlNameStr[];
  39
  40 // ----------------------------------------------------------------------------
  41 // wxHeaderCtrlBase defines the interface of a header control
  42 // ----------------------------------------------------------------------------
  43
  44 class WXDLLIMPEXP_CORE wxHeaderCtrlBase : public wxControl
  45 {
  46 public:
  47     /*
  48         Derived classes must provide default ctor as well as a ctor and
  49         Create() function with the following signatures:
  50
  51     wxHeaderCtrl(wxWindow *parent,
  52                  wxWindowID winid = wxID_ANY,
  53                  const wxPoint& pos = wxDefaultPosition,
  54                  const wxSize& size = wxDefaultSize,
  55                  long style = wxHD_DEFAULT_STYLE,
  56                  const wxString& name = wxHeaderCtrlNameStr);
  57
  58     bool Create(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
  66     // column-related methods
  67     // ----------------------
  68
  69     // set the number of columns in the control
  70     //
  71     // this also calls UpdateColumn() for all columns
  72     void SetColumnCount(unsigned int count) { DoSetCount(count); }
  73
  74     // return the number of columns in the control as set by SetColumnCount()
  75     unsigned int GetColumnCount() const { return DoGetCount(); }
  76
  77     // return whether the control has any columns
  78     bool IsEmpty() const { return DoGetCount() == 0; }
  79
  80     // update the column with the given index
  81     void UpdateColumn(unsigned int idx)
  82     {
  83         wxCHECK_RET( idx < GetColumnCount(), "invalid column index" );
  84
  85         DoUpdate(idx);
  86     }
  87
  88
  89     // implementation only from now on
  90     // -------------------------------
  91
  92     // the user doesn't need to TAB to this control
  93     virtual bool AcceptsFocusFromKeyboard() const { return false; }
  94
  95     // this method is only overridden in order to synchronize the control with
  96     // the main window when it is scrolled, the derived class must implement
  97     // DoScrollHorz()
  98     virtual void ScrollWindow(int dx, int dy, const wxRect *rect = NULL);
  99
 100 protected:
 101     // this method must be implemented by the derived classes to return the
 102     // information for the given column
 103     virtual wxHeaderColumnBase& GetColumn(unsigned int idx) = 0;
 104
 105     // this method is called from the default EVT_HEADER_SEPARATOR_DCLICK
 106     // handler to update the fitting column width of the given column, it
 107     // should return true if the width was really updated
 108     virtual bool UpdateColumnWidthToFit(unsigned int WXUNUSED(idx),
 109                                         int WXUNUSED(widthTitle))
 110     {
 111         return false;
 112     }
 113
 114 private:
 115     // methods implementing our public API and defined in platform-specific
 116     // implementations
 117     virtual void DoSetCount(unsigned int count) = 0;
 118     virtual unsigned int DoGetCount() const = 0;
 119     virtual void DoUpdate(unsigned int idx) = 0;
 120
 121     virtual void DoScrollHorz(int dx) = 0;
 122
 123     // this window doesn't look nice with the border so don't use it by default
 124     virtual wxBorder GetDefaultBorder() const { return wxBORDER_NONE; }
 125
 126     // event handlers
 127     void OnSeparatorDClick(wxHeaderCtrlEvent& event);
 128
 129     DECLARE_EVENT_TABLE()
 130 };
 131
 132 // ----------------------------------------------------------------------------
 133 // wxHeaderCtrl: port-specific header control implementation, notice that this
 134 //               is still an ABC which is meant to be used as part of another
 135 //               control, see wxHeaderCtrlSimple for a standalone version
 136 // ----------------------------------------------------------------------------
 137
 138 #if defined(__WXMSW__) && !defined(__WXUNIVERSAL__)
 139     #include "wx/msw/headerctrl.h"
 140 #else
 141     #define wxHAS_GENERIC_HEADERCTRL
 142     #include "wx/generic/headerctrlg.h"
 143 #endif // platform
 144
 145 // ----------------------------------------------------------------------------
 146 // wxHeaderCtrlSimple: concrete header control which can be used standalone
 147 // ----------------------------------------------------------------------------
 148
 149 class WXDLLIMPEXP_CORE wxHeaderCtrlSimple : public wxHeaderCtrl
 150 {
 151 public:
 152     // control creation
 153     // ----------------
 154
 155     wxHeaderCtrlSimple() { Init(); }
 156     wxHeaderCtrlSimple(wxWindow *parent,
 157                        wxWindowID winid = wxID_ANY,
 158                        const wxPoint& pos = wxDefaultPosition,
 159                        const wxSize& size = wxDefaultSize,
 160                        long style = wxHD_DEFAULT_STYLE,
 161                        const wxString& name = wxHeaderCtrlNameStr)
 162     {
 163         Init();
 164
 165         Create(parent, winid, pos, size, style, name);
 166     }
 167
 168     // managing the columns
 169     // --------------------
 170
 171     // insert the column at the given position, using GetColumnCount() as
 172     // position appends it at the end
 173     void InsertColumn(const wxHeaderColumnSimple& col, unsigned int idx)
 174     {
 175         wxCHECK_RET( idx <= GetColumnCount(), "invalid column index" );
 176
 177         DoInsert(col, idx);
 178     }
 179
 180     // append the column to the end of the control
 181     void AppendColumn(const wxHeaderColumnSimple& col)
 182     {
 183         DoInsert(col, GetColumnCount());
 184     }
 185
 186     // delete the column at the given index
 187     void DeleteColumn(unsigned int idx)
 188     {
 189         wxCHECK_RET( idx < GetColumnCount(), "invalid column index" );
 190
 191         DoDelete(idx);
 192     }
 193
 194     // delete all the existing columns
 195     void DeleteAllColumns();
 196
 197
 198     // modifying columns
 199     // -----------------
 200
 201     // show or hide the column, notice that even when a column is hidden we
 202     // still account for it when using indices
 203     void ShowColumn(unsigned int idx, bool show = true)
 204     {
 205         wxCHECK_RET( idx < GetColumnCount(), "invalid column index" );
 206
 207         DoShowColumn(idx, show);
 208     }
 209
 210     void HideColumn(unsigned int idx)
 211     {
 212         ShowColumn(idx, false);
 213     }
 214
 215     // indicate that the column is used for sorting
 216     void ShowSortIndicator(unsigned int idx, bool ascending = true)
 217     {
 218         wxCHECK_RET( idx < GetColumnCount(), "invalid column index" );
 219
 220         DoShowSortIndicator(idx, ascending);
 221     }
 222
 223     // remove the sort indicator completely
 224     void RemoveSortIndicator();
 225
 226 protected:
 227     // implement/override base class methods
 228     virtual wxHeaderColumnBase& GetColumn(unsigned int idx);
 229     virtual bool UpdateColumnWidthToFit(unsigned int idx, int widthTitle);
 230
 231     // and define another one to be overridden in the derived classes: it
 232     // should return the best width for the given column contents or -1 if not
 233     // implemented, we use it to implement UpdateColumnWidthToFit()
 234     virtual int GetBestFittingWidth(unsigned int WXUNUSED(idx)) const
 235     {
 236         return -1;
 237     }
 238
 239 private:
 240     // functions implementing our public API
 241     void DoInsert(const wxHeaderColumnSimple& col, unsigned int idx);
 242     void DoDelete(unsigned int idx);
 243     void DoShowColumn(unsigned int idx, bool show);
 244     void DoShowSortIndicator(unsigned int idx, bool ascending);
 245
 246     // common part of all ctors
 247     void Init();
 248
 249     // bring the column count in sync with the number of columns we store
 250     void UpdateColumnCount() { SetColumnCount(m_cols.size()); }
 251
 252
 253     // all our current columns
 254     typedef wxVector<wxHeaderColumnSimple> Columns;
 255     Columns m_cols;
 256
 257     // the column currently used for sorting or -1 if none
 258     unsigned int m_sortKey;
 259
 260
 261     DECLARE_NO_COPY_CLASS(wxHeaderCtrlSimple)
 262 };
 263
 264 // ----------------------------------------------------------------------------
 265 // wxHeaderCtrl events
 266 // ----------------------------------------------------------------------------
 267
 268 class WXDLLIMPEXP_CORE wxHeaderCtrlEvent : public wxNotifyEvent
 269 {
 270 public:
 271     wxHeaderCtrlEvent(wxEventType commandType = wxEVT_NULL, int winid = 0)
 272         : wxNotifyEvent(commandType, winid),
 273           m_col(-1),
 274           m_width(0),
 275           m_cancelled(false)
 276     {
 277     }
 278
 279     wxHeaderCtrlEvent(const wxHeaderCtrlEvent& event)
 280         : wxNotifyEvent(event),
 281           m_col(event.m_col),
 282           m_width(event.m_width),
 283           m_cancelled(event.m_cancelled)
 284     {
 285     }
 286
 287     // the column which this event pertains to: valid for all header events
 288     int GetColumn() const { return m_col; }
 289     void SetColumn(int col) { m_col = col; }
 290
 291     // the width of the column: valid for column resizing/dragging events only
 292     int GetWidth() const { return m_width; }
 293     void SetWidth(int width) { m_width = width; }
 294
 295     // was the drag operation cancelled or did it complete successfully?
 296     bool IsCancelled() const { return m_cancelled; }
 297     void SetCancelled() { m_cancelled = true; }
 298
 299     virtual wxEvent *Clone() const { return new wxHeaderCtrlEvent(*this); }
 300
 301 protected:
 302     // the column affected by the event
 303     int m_col;
 304
 305     // the current width for the dragging events
 306     int m_width;
 307
 308     // was the drag operation cancelled?
 309     bool m_cancelled;
 310
 311 private:
 312     DECLARE_DYNAMIC_CLASS_NO_ASSIGN(wxHeaderCtrlEvent)
 313 };
 314
 315
 316 extern WXDLLIMPEXP_CORE const wxEventType wxEVT_COMMAND_HEADER_CLICK;
 317 extern WXDLLIMPEXP_CORE const wxEventType wxEVT_COMMAND_HEADER_RIGHT_CLICK;
 318 extern WXDLLIMPEXP_CORE const wxEventType wxEVT_COMMAND_HEADER_MIDDLE_CLICK;
 319
 320 extern WXDLLIMPEXP_CORE const wxEventType wxEVT_COMMAND_HEADER_DCLICK;
 321 extern WXDLLIMPEXP_CORE const wxEventType wxEVT_COMMAND_HEADER_RIGHT_DCLICK;
 322 extern WXDLLIMPEXP_CORE const wxEventType wxEVT_COMMAND_HEADER_MIDDLE_DCLICK;
 323
 324 extern WXDLLIMPEXP_CORE const wxEventType wxEVT_COMMAND_HEADER_SEPARATOR_DCLICK;
 325
 326 extern WXDLLIMPEXP_CORE const wxEventType wxEVT_COMMAND_HEADER_BEGIN_DRAG;
 327 extern WXDLLIMPEXP_CORE const wxEventType wxEVT_COMMAND_HEADER_DRAGGING;
 328 extern WXDLLIMPEXP_CORE const wxEventType wxEVT_COMMAND_HEADER_END_DRAG;
 329
 330 typedef void (wxEvtHandler::*wxHeaderCtrlEventFunction)(wxHeaderCtrlEvent&);
 331
 332 #define wxHeaderCtrlEventHandler(func) \
 333     (wxObjectEventFunction)(wxEventFunction)wxStaticCastEvent( \
 334             wxHeaderCtrlEventFunction, &func)
 335
 336 #define wx__DECLARE_HEADER_EVT(evt, id, fn) \
 337     wx__DECLARE_EVT1(wxEVT_COMMAND_HEADER_ ## evt, id, wxHeaderCtrlEventHandler(fn))
 338
 339 #define EVT_HEADER_CLICK(id, fn) wx__DECLARE_HEADER_EVT(CLICK, id, fn)
 340 #define EVT_HEADER_RIGHT_CLICK(id, fn) wx__DECLARE_HEADER_EVT(RIGHT_CLICK, id, fn)
 341 #define EVT_HEADER_MIDDLE_CLICK(id, fn) wx__DECLARE_HEADER_EVT(MIDDLE_CLICK, id, fn)
 342
 343 #define EVT_HEADER_DCLICK(id, fn) wx__DECLARE_HEADER_EVT(DCLICK, id, fn)
 344 #define EVT_HEADER_RIGHT_DCLICK(id, fn) wx__DECLARE_HEADER_EVT(RIGHT_DCLICK, id, fn)
 345 #define EVT_HEADER_MIDDLE_DCLICK(id, fn) wx__DECLARE_HEADER_EVT(MIDDLE_DCLICK, id, fn)
 346
 347 #define EVT_HEADER_SEPARATOR_DCLICK(id, fn) wx__DECLARE_HEADER_EVT(SEPARATOR_DCLICK, id, fn)
 348
 349 #define EVT_HEADER_BEGIN_DRAG(id, fn) wx__DECLARE_HEADER_EVT(BEGIN_DRAG, id, fn)
 350 #define EVT_HEADER_DRAGGING(id, fn) wx__DECLARE_HEADER_EVT(DRAGGING, id, fn)
 351 #define EVT_HEADER_END_DRAG(id, fn) wx__DECLARE_HEADER_EVT(END_DRAG, id, fn)
 352
 353 #endif // _WX_HEADERCTRL_H_