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