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