include/wx/headercol.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/headercol.h
   3 // Purpose:     declaration of wxHeaderColumn class
   4 // Author:      Vadim Zeitlin
   5 // Created:     2008-12-02
   6 // RCS-ID:      $Id$
   7 // Copyright:   (c) 2008 Vadim Zeitlin <vadim@wxwidgets.org>
   8 // Licence:     wxWindows licence
   9 ///////////////////////////////////////////////////////////////////////////////
  10
  11 #ifndef _WX_HEADERCOL_H_
  12 #define _WX_HEADERCOL_H_
  13
  14 #include "wx/bitmap.h"
  15
  16 #if wxUSE_HEADERCTRL
  17
  18 // ----------------------------------------------------------------------------
  19 // constants
  20 // ----------------------------------------------------------------------------
  21
  22 enum
  23 {
  24     // special value for column width meaning unspecified/default
  25     wxCOL_WIDTH_DEFAULT = -1,
  26
  27     // size the column automatically to fit all values
  28     wxCOL_WIDTH_AUTOSIZE = -2
  29 };
  30
  31 // bit masks for the various column attributes
  32 enum
  33 {
  34     // column can be resized (included in default flags)
  35     wxCOL_RESIZABLE   = 1,
  36
  37     // column can be clicked to toggle the sort order by its contents
  38     wxCOL_SORTABLE    = 2,
  39
  40     // column can be dragged to change its order (included in default)
  41     wxCOL_REORDERABLE = 4,
  42
  43     // column is not shown at all
  44     wxCOL_HIDDEN      = 8,
  45
  46     // default flags for wxHeaderColumn ctor
  47     wxCOL_DEFAULT_FLAGS = wxCOL_RESIZABLE | wxCOL_REORDERABLE
  48 };
  49
  50 // ----------------------------------------------------------------------------
  51 // wxHeaderColumn: interface for a column in a header of controls such as
  52 //                 wxListCtrl, wxDataViewCtrl or wxGrid
  53 // ----------------------------------------------------------------------------
  54
  55 class WXDLLIMPEXP_CORE wxHeaderColumn
  56 {
  57 public:
  58     // ctors and dtor
  59     // --------------
  60
  61     /*
  62        Derived classes must provide ctors with the following signatures
  63        (notice that they shouldn't be explicit to allow passing strings/bitmaps
  64        directly to methods such wxHeaderCtrl::AppendColumn()):
  65     wxHeaderColumn(const wxString& title,
  66                    int width = wxCOL_WIDTH_DEFAULT,
  67                    wxAlignment align = wxALIGN_NOT,
  68                    int flags = wxCOL_DEFAULT_FLAGS);
  69     wxHeaderColumn(const wxBitmap &bitmap,
  70                    int width = wxDVC_DEFAULT_WIDTH,
  71                    wxAlignment align = wxALIGN_CENTER,
  72                    int flags = wxCOL_DEFAULT_FLAGS);
  73     */
  74
  75     // virtual dtor for the base class to avoid gcc warnings even though we
  76     // don't normally delete the objects of this class via a pointer to
  77     // wxHeaderColumn so it's not necessary, strictly speaking
  78     virtual ~wxHeaderColumn() { }
  79
  80     // getters for various attributes
  81     // ------------------------------
  82
  83     // notice that wxHeaderColumn only provides getters as this is all the
  84     // wxHeaderCtrl needs, various derived class must also provide some way to
  85     // change these attributes but this can be done either at the column level
  86     // (in which case they should inherit from wxSettableHeaderColumn) or via
  87     // the methods of the main control in which case you don't need setters in
  88     // the column class at all
  89
  90     // title is the string shown for this column
  91     virtual wxString GetTitle() const = 0;
  92
  93     // bitmap shown (instead of text) in the column header
  94     virtual wxBitmap GetBitmap() const = 0;                                   \
  95
  96     // width of the column in pixels, can be set to wxCOL_WIDTH_DEFAULT meaning
  97     // unspecified/default
  98     virtual int GetWidth() const = 0;
  99
 100     // minimal width can be set for resizable columns to forbid resizing them
 101     // below the specified size (set to 0 to remove)
 102     virtual int GetMinWidth() const = 0;
 103
 104     // alignment of the text: wxALIGN_CENTRE, wxALIGN_LEFT or wxALIGN_RIGHT
 105     virtual wxAlignment GetAlignment() const = 0;
 106
 107
 108     // flags manipulations:
 109     // --------------------
 110
 111     // notice that while we make GetFlags() pure virtual here and implement the
 112     // individual flags access in terms of it, for some derived classes it is
 113     // more natural to implement access to each flag individually, in which
 114     // case they can use our GetFromIndividualFlags() helper below to implement
 115     // GetFlags()
 116
 117     // retrieve all column flags at once: combination of wxCOL_XXX values above
 118     virtual int GetFlags() const = 0;
 119
 120     bool HasFlag(int flag) const { return (GetFlags() & flag) != 0; }
 121
 122
 123     // wxCOL_RESIZABLE
 124     virtual bool IsResizeable() const
 125         { return HasFlag(wxCOL_RESIZABLE); }
 126
 127     // wxCOL_SORTABLE
 128     virtual bool IsSortable() const
 129         { return HasFlag(wxCOL_SORTABLE); }
 130
 131     // wxCOL_REORDERABLE
 132     virtual bool IsReorderable() const
 133         { return HasFlag(wxCOL_REORDERABLE); }
 134
 135     // wxCOL_HIDDEN
 136     virtual bool IsHidden() const
 137         { return HasFlag(wxCOL_HIDDEN); }
 138     bool IsShown() const
 139         { return !IsHidden(); }
 140
 141
 142     // sorting
 143     // -------
 144
 145     // return true if the column is the one currently used for sorting
 146     virtual bool IsSortKey() const = 0;
 147
 148     // for sortable columns indicate whether we should sort in ascending or
 149     // descending order (this should only be taken into account if IsSortKey())
 150     virtual bool IsSortOrderAscending() const = 0;
 151
 152 protected:
 153     // helper for the class overriding IsXXX()
 154     int GetFromIndividualFlags() const;
 155 };
 156
 157 // ----------------------------------------------------------------------------
 158 // wxSettableHeaderColumn: column which allows to change its fields too
 159 // ----------------------------------------------------------------------------
 160
 161 class WXDLLIMPEXP_CORE wxSettableHeaderColumn : public wxHeaderColumn
 162 {
 163 public:
 164     virtual void SetTitle(const wxString& title) = 0;
 165     virtual void SetBitmap(const wxBitmap& bitmap) = 0;
 166     virtual void SetWidth(int width) = 0;
 167     virtual void SetMinWidth(int minWidth) = 0;
 168     virtual void SetAlignment(wxAlignment align) = 0;
 169
 170     // see comment for wxHeaderColumn::GetFlags() about the relationship
 171     // between SetFlags() and Set{Sortable,Reorderable,...}
 172
 173     // change, set, clear, toggle or test for any individual flag
 174     virtual void SetFlags(int flags) = 0;
 175     void ChangeFlag(int flag, bool set);
 176     void SetFlag(int flag);
 177     void ClearFlag(int flag);
 178     void ToggleFlag(int flag);
 179
 180     virtual void SetResizeable(bool resizable)
 181         { ChangeFlag(wxCOL_RESIZABLE, resizable); }
 182     virtual void SetSortable(bool sortable)
 183         { ChangeFlag(wxCOL_SORTABLE, sortable); }
 184     virtual void SetReorderable(bool reorderable)
 185         { ChangeFlag(wxCOL_REORDERABLE, reorderable); }
 186     virtual void SetHidden(bool hidden)
 187         { ChangeFlag(wxCOL_HIDDEN, hidden); }
 188
 189     // This function can be called to indicate that this column is not used for
 190     // sorting any more. Under some platforms it's not necessary to do anything
 191     // in this case as just setting another column as a sort key takes care of
 192     // everything but under MSW we currently need to call this explicitly to
 193     // reset the sort indicator displayed on the column.
 194     virtual void UnsetAsSortKey() { }
 195
 196     virtual void SetSortOrder(bool ascending) = 0;
 197     void ToggleSortOrder() { SetSortOrder(!IsSortOrderAscending()); }
 198
 199 protected:
 200     // helper for the class overriding individual SetXXX() methods instead of
 201     // overriding SetFlags()
 202     void SetIndividualFlags(int flags);
 203 };
 204
 205 // ----------------------------------------------------------------------------
 206 // wxHeaderColumnSimple: trivial generic implementation of wxHeaderColumn
 207 // ----------------------------------------------------------------------------
 208
 209 class wxHeaderColumnSimple : public wxSettableHeaderColumn
 210 {
 211 public:
 212     // ctors and dtor
 213     wxHeaderColumnSimple(const wxString& title,
 214                          int width = wxCOL_WIDTH_DEFAULT,
 215                          wxAlignment align = wxALIGN_NOT,
 216                          int flags = wxCOL_DEFAULT_FLAGS)
 217         : m_title(title),
 218           m_width(width),
 219           m_align(align),
 220           m_flags(flags)
 221     {
 222         Init();
 223     }
 224
 225     wxHeaderColumnSimple(const wxBitmap& bitmap,
 226                          int width = wxCOL_WIDTH_DEFAULT,
 227                          wxAlignment align = wxALIGN_CENTER,
 228                          int flags = wxCOL_DEFAULT_FLAGS)
 229         : m_bitmap(bitmap),
 230           m_width(width),
 231           m_align(align),
 232           m_flags(flags)
 233     {
 234         Init();
 235     }
 236
 237     // implement base class pure virtuals
 238     virtual void SetTitle(const wxString& title) { m_title = title; }
 239     virtual wxString GetTitle() const { return m_title; }
 240
 241     virtual void SetBitmap(const wxBitmap& bitmap) { m_bitmap = bitmap; }
 242     wxBitmap GetBitmap() const { return m_bitmap; }
 243
 244     virtual void SetWidth(int width) { m_width = width; }
 245     virtual int GetWidth() const { return m_width; }
 246
 247     virtual void SetMinWidth(int minWidth) { m_minWidth = minWidth; }
 248     virtual int GetMinWidth() const { return m_minWidth; }
 249
 250     virtual void SetAlignment(wxAlignment align) { m_align = align; }
 251     virtual wxAlignment GetAlignment() const { return m_align; }
 252
 253     virtual void SetFlags(int flags) { m_flags = flags; }
 254     virtual int GetFlags() const { return m_flags; }
 255
 256     virtual bool IsSortKey() const { return m_sort; }
 257     virtual void UnsetAsSortKey() { m_sort = false; }
 258
 259     virtual void SetSortOrder(bool ascending)
 260     {
 261         m_sort = true;
 262         m_sortAscending = ascending;
 263     }
 264
 265     virtual bool IsSortOrderAscending() const { return m_sortAscending; }
 266
 267 private:
 268     // common part of all ctors
 269     void Init()
 270     {
 271         m_minWidth = 0;
 272         m_sort = false;
 273         m_sortAscending = true;
 274     }
 275
 276     wxString m_title;
 277     wxBitmap m_bitmap;
 278     int m_width,
 279         m_minWidth;
 280     wxAlignment m_align;
 281     int m_flags;
 282     bool m_sort,
 283          m_sortAscending;
 284 };
 285
 286 #endif // wxUSE_HEADERCTRL
 287
 288 #endif // _WX_HEADERCOL_H_
 289