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 resizable 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 resizable.
 306
 307         Equivalent to ChangeFlag(wxCOL_RESIZABLE, resizable).
 308      */
 309     virtual void SetResizeable(bool resizable);
 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         Don't use this column for sorting.
 343
 344         This is the reverse of SetSortOrder() and is called to indicate that
 345         this column is not used for sorting any longer.
 346      */
 347     void UnsetAsSortKey();
 348
 349     /**
 350         Sets this column as the sort key for the associated control.
 351
 352         This function indicates that this column is currently used for sorting
 353         the control and also sets the sorting direction. Notice that actual
 354         sorting is only done in the control associated with the header, this
 355         function doesn't do any sorting on its own.
 356
 357         Don't confuse this function with SetSortable() which should be used to
 358         indicate that the column @em may be used for sorting while this one is
 359         used to indicate that it currently @em is used for sorting. Of course,
 360         SetSortOrder() can be only called for sortable columns.
 361
 362         @param ascending
 363             If @true, sort in ascending order, otherwise in descending order.
 364      */
 365     virtual void SetSortOrder(bool ascending) = 0;
 366
 367     /**
 368         Inverses the sort order.
 369
 370         This function is typically called when the user clicks on a column used
 371         for sorting to change sort order from ascending to descending or vice
 372         versa.
 373
 374         @see SetSortOrder(), IsSortOrderAscending()
 375      */
 376     void ToggleSortOrder();
 377 };
 378
 379 /**
 380     @class wxHeaderColumnSimple
 381
 382     Simple container for the information about the column.
 383
 384     This is a concrete class implementing all wxSettableHeaderColumn class
 385     methods in a trivial way, i.e. by just storing the information in the
 386     object itself. It is used by and with wxHeaderCtrlSimple, e.g.
 387     @code
 388         wxHeaderCtrlSimple * header = new wxHeaderCtrlSimple(...);
 389         wxHeaderColumnSimple col("Title");
 390         col.SetWidth(100);
 391         col.SetSortable(100);
 392         header->AppendColumn(col);
 393     @endcode
 394
 395     @library{wxcore}
 396     @category{ctrl}
 397  */
 398 class wxHeaderColumnSimple : public wxSettableHeaderColumn
 399 {
 400 public:
 401     //@{
 402     /**
 403         Constructor for a column header.
 404
 405         The first constructor creates a header showing the given text @a title
 406         while the second one creates one showing the specified @a bitmap image.
 407      */
 408     wxHeaderColumnSimple(const wxString& title,
 409                          int width = wxCOL_WIDTH_DEFAULT,
 410                          wxAlignment align = wxALIGN_NOT,
 411                          int flags = wxCOL_DEFAULT_FLAGS);
 412
 413     wxHeaderColumnSimple(const wxBitmap &bitmap,
 414                          int width = wxCOL_WIDTH_DEFAULT,
 415                          wxAlignment align = wxALIGN_CENTER,
 416                          int flags = wxCOL_DEFAULT_FLAGS);
 417     //@}
 418
 419     //@{
 420
 421     /// Trivial implementations of the base class pure virtual functions.
 422
 423     virtual void SetTitle(const wxString& title);
 424     virtual wxString GetTitle() const;
 425     virtual void SetBitmap(const wxBitmap& bitmap);
 426     virtual wxBitmap GetBitmap() const;
 427     virtual void SetWidth(int width);
 428     virtual int GetWidth() const;
 429     virtual void SetMinWidth(int minWidth);
 430     virtual int GetMinWidth() const;
 431     virtual void SetAlignment(wxAlignment align);
 432     virtual wxAlignment GetAlignment() const;
 433     virtual void SetFlags(int flags);
 434     virtual int GetFlags() const;
 435     virtual bool IsSortKey() const;
 436     virtual void SetSortOrder(bool ascending);
 437     virtual bool IsSortOrderAscending() const;
 438
 439     //@}
 440 };