interface/wx/headercol.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/headercol.h
   3 // Purpose:     interface of wxHeaderColumn
   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 license
   9 /////////////////////////////////////////////////////////////////////////////
  10
  11 /**
  12     Special value used for column width meaning unspecified or default.
  13  */
  14 enum { wxCOL_WIDTH_DEFAULT = -1 };
  15
  16 /**
  17     Bit flags used as wxHeaderColumn flags.
  18  */
  19 enum
  20 {
  21     /// Column can be resized (included in default flags).
  22     wxCOL_RESIZABLE   = 1,
  23
  24     /// Column can be clicked to toggle the sort order by its contents.
  25     wxCOL_SORTABLE    = 2,
  26
  27     /// Column can be dragged to change its order (included in default).
  28     wxCOL_REORDERABLE = 4,
  29
  30     /// Column is not shown at all.
  31     wxCOL_HIDDEN      = 8,
  32
  33     /// Default flags for wxHeaderColumn ctor.
  34     wxCOL_DEFAULT_FLAGS = wxCOL_RESIZABLE | wxCOL_REORDERABLE
  35 };
  36
  37 /**
  38     @class wxHeaderColumn
  39
  40     Represents a column header in controls displaying tabular data such as
  41     wxDataViewCtrl or wxGrid.
  42
  43     Notice that this is an abstract base class which is implemented (usually
  44     using the information stored in the associated control) by the different
  45     controls using wxHeaderCtrl. You may use wxHeaderCtrlSimple which uses
  46     concrete wxHeaderColumnSimple if you don't already store the column
  47     information somewhere.
  48
  49     @library{wxcore}
  50     @category{ctrl}
  51  */
  52 class wxHeaderColumn
  53 {
  54 public:
  55     /**
  56         Set the text to display in the column header.
  57      */
  58     virtual void SetTitle(const wxString& title) = 0;
  59
  60     /**
  61         Get the text shown in the column header.
  62      */
  63     virtual wxString GetTitle() const = 0;
  64
  65     /**
  66         Set the bitmap to be displayed in the column header.
  67
  68         Notice that the bitmaps displayed in different columns of the same
  69         control must all be of the same size.
  70      */
  71     virtual void SetBitmap(const wxBitmap& bitmap) = 0;
  72
  73     /**
  74         Returns the bitmap in the header of the column, if any.
  75
  76         If the column has no associated bitmap, wxNullBitmap is returned.
  77     */
  78     virtual wxBitmap GetBitmap() const = 0;
  79
  80     /**
  81         Set the column width.
  82
  83         @param width
  84             The column width in pixels or the special wxCOL_WIDTH_DEFAULT value
  85             meaning to use default width.
  86      */
  87     virtual void SetWidth(int width) = 0;
  88
  89     /**
  90         Returns the current width of the column.
  91
  92         @return
  93             Width of the column in pixels, never wxCOL_WIDTH_DEFAULT.
  94     */
  95     virtual int GetWidth() const = 0;
  96
  97     /**
  98         Set the minimal column width.
  99
 100         This method can be used with resizeable columns (i.e. those for which
 101         wxCOL_RESIZABLE flag is set in GetFlags() or, alternatively,
 102         IsResizeable() returns @true) to prevent the user from making them
 103         narrower than the given width.
 104
 105         @param minWidth
 106             The minimal column width in pixels, may be 0 to remove any
 107             previously set restrictions.
 108      */
 109     virtual void SetMinWidth(int minWidth) = 0;
 110
 111     /**
 112         Return the minimal column width.
 113
 114         @return
 115             The value previously set by SetMinWidth() or 0 by default.
 116      */
 117     virtual int GetMinWidth() const = 0;
 118
 119     /**
 120         Set the alignment of the column header.
 121
 122         @param align
 123             The text alignment in horizontal direction only or wxALIGN_NOT to
 124             use the default alignment, The possible values here are
 125             wxALIGN_CENTRE, wxALIGN_LEFT or wxALIGN_RIGHT with
 126             wxALIGN_CENTRE_HORIZONTAL being also supported as synonym for
 127             wxALIGN_CENTRE for consistency (but notice that GetAlignment()
 128             never returns it).
 129     */
 130     virtual void SetAlignment(wxAlignment align) = 0;
 131
 132     /**
 133         Returns the current column alignment.
 134
 135         @return
 136             One of wxALIGN_CENTRE, wxALIGN_LEFT or wxALIGN_RIGHT.
 137      */
 138     virtual wxAlignment GetAlignment() const = 0;
 139
 140
 141     /**
 142         Set the column flags.
 143
 144         This method allows to set all flags at once, see also generic
 145         ChangeFlag(), SetFlag(), ClearFlag() and ToggleFlag() methods below as
 146         well as specific SetResizeable(), SetSortable(), SetReorderable() and
 147         SetHidden() ones.
 148
 149         @param flags
 150             Combination of wxCOL_RESIZABLE, wxCOL_SORTABLE, wxCOL_REORDERABLE
 151             and wxCOL_HIDDEN bit flags.
 152      */
 153     virtual void SetFlags(int flags) = 0;
 154
 155     /**
 156         Set or clear the given flag.
 157
 158         @param flag
 159             The flag to set or clear.
 160         @param set
 161             If @true, set the flag, i.e. equivalent to calling SetFlag(),
 162             otherwise clear it, as ClearFlag().
 163
 164         @see SetFlags()
 165      */
 166     void ChangeFlag(int flag, bool set);
 167
 168     /**
 169         Set the specified flag for the column.
 170
 171         @see SetFlags()
 172      */
 173     void SetFlag(int flag);
 174
 175     /**
 176         Clear the specified flag for the column.
 177
 178         @see SetFlags()
 179      */
 180     void ClearFlag(int flag);
 181
 182     /**
 183         Toggle the specified flag for the column.
 184
 185         If the flag is currently set, equivalent to ClearFlag(), otherwise --
 186         to SetFlag().
 187
 188         @see SetFlags()
 189      */
 190     void ToggleFlag(int flag);
 191
 192     /**
 193         Get the column flags.
 194
 195         This method retrieves all the flags at once, you can also use HasFlag()
 196         to test for any individual flag or IsResizeable(), IsSortable(),
 197         IsReorderable() and IsHidden() to test for particular flags.
 198
 199         @see SetFlags()
 200      */
 201     virtual int GetFlags() const = 0;
 202
 203     /**
 204         Return @true if the specified flag is currently set for this column.
 205      */
 206     bool HasFlag(int flag) const;
 207
 208
 209     /**
 210         Call this to enable or disable interactive resizing of the column by
 211         the user.
 212
 213         By default, the columns are resizeable.
 214
 215         Equivalent to ChangeFlag(wxCOL_RESIZABLE, resizeable).
 216      */
 217     virtual void SetResizeable(bool resizeable);
 218
 219     /**
 220         Return true if the column can be resized by the user.
 221
 222         Equivalent to HasFlag(wxCOL_RESIZABLE).
 223      */
 224     virtual bool IsResizeable() const;
 225
 226     /**
 227         Allow clicking the column to sort the control contents by the field in
 228         this column.
 229
 230         By default, the columns are not sortable so you need to explicitly call
 231         this function to allow sorting by the field corresponding to this
 232         column.
 233
 234         Equivalent to ChangeFlag(wxCOL_SORTABLE, sortable).
 235      */
 236     virtual void SetSortable(bool sortable);
 237
 238     /**
 239         Returns @true if the column can be clicked by user to sort the control
 240         contents by the field in this column.
 241
 242         This corresponds to wxCOL_SORTABLE flag which is off by default.
 243
 244         @see SetSortable()
 245     */
 246     virtual bool IsSortable() const;
 247
 248     /**
 249         Allow changing the column order by dragging it.
 250
 251         Equivalent to ChangeFlag(wxCOL_REORDERABLE, reorderable).
 252      */
 253     virtual void SetReorderable(bool reorderable);
 254
 255     /**
 256         Returns @true if the column can be dragged by user to change its order.
 257
 258         This corresponds to wxCOL_REORDERABLE flag which is on by default.
 259
 260         @see SetReorderable()
 261     */
 262     virtual bool IsReorderable() const;
 263
 264     /**
 265         Hide or show the column.
 266
 267         By default all columns are shown but some of them can be completely
 268         hidden from view by calling this function.
 269
 270         Equivalent to ChangeFlag(wxCOL_HIDDEN, hidden).
 271      */
 272     virtual void SetHidden(bool hidden);
 273
 274     /**
 275         Returns @true if the column is currently hidden.
 276
 277         This corresponds to wxCOL_HIDDEN flag which is off by default.
 278      */
 279     virtual bool IsHidden() const;
 280
 281     /**
 282         Returns @true if the column is currently shown.
 283
 284         This corresponds to the absence of wxCOL_HIDDEN flag.
 285      */
 286     bool IsShown() const;
 287
 288
 289
 290     /**
 291         Sets this column as the sort key for the associated control.
 292
 293         Calling this function with @true argument means that this column is
 294         currently used for sorting the control contents and so should typically
 295         display an arrow indicating it (the direction of the arrow depends on
 296         IsSortOrderAscending() return value).
 297
 298         Don't confuse this function with SetSortable() which should be used to
 299         indicate that the column @em may be used for sorting while this one is
 300         used to indicate that it currently @em is used for sorting. Of course,
 301         SetAsSortKey() can be only called for sortable columns.
 302
 303         @param sort
 304             Sort (default) or don't sort the control contents by this column.
 305      */
 306     virtual void SetAsSortKey(bool sort = true) = 0;
 307
 308     /**
 309         Don't use this column for sorting.
 310
 311         This is equivalent to calling SetAsSortKey() with @false argument.
 312      */
 313     void UnsetAsSortKey();
 314
 315     /**
 316         Returns @true if the column is currently used for sorting.
 317
 318         Notice that this function simply returns the value last passed to
 319         SetAsSortKey() (or @false if SetAsSortKey() had never been called), it
 320         is up to the associated control to use this information to actually
 321         sort its contents.
 322      */
 323     virtual bool IsSortKey() const = 0;
 324
 325     /**
 326         Sets the sort order for this column.
 327
 328         This only makes sense for sortable columns which are currently used as
 329         sort key, i.e. for which IsSortKey() returns @true and is only taken
 330         into account by the control in which this column is inserted, this
 331         function just stores the sort order in the wxHeaderColumn object.
 332
 333         @param ascending
 334             If @true, sort in ascending order, otherwise in descending order.
 335      */
 336     virtual void SetSortOrder(bool ascending) = 0;
 337
 338     /**
 339         Inverses the sort order.
 340
 341         This function is typically called when the user clicks on a column used
 342         for sorting to change sort order from ascending to descending or vice
 343         versa.
 344
 345         @see SetSortOrder(), IsSortOrderAscending()
 346      */
 347     void ToggleSortOrder();
 348
 349     /**
 350         Returns @true, if the sort order is ascending.
 351
 352         Notice that it only makes sense to call this function if the column is
 353         used for sorting at all, i.e. if IsSortKey() returns @true.
 354
 355         @see SetSortOrder()
 356     */
 357     virtual bool IsSortOrderAscending() const = 0;
 358 };
 359
 360 /**
 361     @class wxHeaderColumnSimple
 362
 363     Simple container for the information about the column.
 364
 365     This is a concrete class implementing all base wxHeaderColumn class methods
 366     in a trivial way, i.e. by just storing the information in the object
 367     itself. It is used by and with wxHeaderCtrlSimple, e.g.
 368     @code
 369         wxHeaderCtrlSimple * header = new wxHeaderCtrlSimple(...);
 370         wxHeaderColumnSimple col("Title");
 371         col.SetWidth(100);
 372         col.SetSortable(100);
 373         header->AppendColumn(col);
 374     @endcode
 375
 376     @library{wxcore}
 377     @category{ctrl}
 378  */
 379 class wxHeaderColumnSimple : public wxHeaderColumn
 380 {
 381 public:
 382     //@{
 383     /**
 384         Constructor for a column header.
 385
 386         The first constructor creates a header showing the given text @a title
 387         while the second one creates one showing the specified @a bitmap image.
 388      */
 389     wxHeaderColumnSimple(const wxString& title,
 390                          int width = wxCOL_WIDTH_DEFAULT,
 391                          wxAlignment align = wxALIGN_NOT,
 392                          int flags = wxCOL_DEFAULT_FLAGS);
 393
 394     wxHeaderColumnSimple(const wxBitmap &bitmap,
 395                          int width = wxDVC_DEFAULT_WIDTH,
 396                          wxAlignment align = wxALIGN_CENTER,
 397                          int flags = wxCOL_DEFAULT_FLAGS);
 398     //@}
 399
 400     //@{
 401
 402     /// Trivial implementations of the base class pure virtual functions.
 403
 404     virtual void SetTitle(const wxString& title);
 405     virtual wxString GetTitle() const;
 406     virtual void SetBitmap(const wxBitmap& bitmap);
 407     virtual wxBitmap GetBitmap() const;
 408     virtual void SetWidth(int width);
 409     virtual int GetWidth() const;
 410     virtual void SetMinWidth(int minWidth);
 411     virtual int GetMinWidth() const;
 412     virtual void SetAlignment(wxAlignment align);
 413     virtual wxAlignment GetAlignment() const;
 414     virtual void SetFlags(int flags);
 415     virtual int GetFlags() const;
 416     virtual void SetAsSortKey(bool sort = true);
 417     virtual bool IsSortKey() const;
 418     virtual void SetSortOrder(bool ascending);
 419     virtual bool IsSortOrderAscending() const;
 420
 421     //@}
 422 };