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