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