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     wxHeaderCtrl, wxDataViewCtrl or wxGrid.
  42
  43     @library{wxcore}
  44     @category{ctrl}
  45
  46     @see wxHeaderCtrl
  47  */
  48 class wxHeaderColumn
  49 {
  50 public:
  51     //@{
  52     /**
  53         Constructor for a column header.
  54
  55         The first constructor creates a header showing the given text @a title
  56         while the second one creates one showing the specified @a bitmap image.
  57      */
  58     wxHeaderColumn(const wxString& title,
  59                    int width = wxCOL_WIDTH_DEFAULT,
  60                    wxAlignment align = wxALIGN_NOT,
  61                    int flags = wxCOL_DEFAULT_FLAGS);
  62     wxHeaderColumn(const wxBitmap &bitmap,
  63                    int width = wxDVC_DEFAULT_WIDTH,
  64                    wxAlignment align = wxALIGN_CENTER,
  65                    int flags = wxCOL_DEFAULT_FLAGS);
  66     //@}
  67
  68     /**
  69         Set the text to display in the column header.
  70      */
  71     virtual void SetTitle(const wxString& title);
  72
  73     /**
  74         Get the text shown in the column header.
  75      */
  76     virtual wxString GetTitle() const;
  77
  78     /**
  79         Set the bitmap to be displayed in the column header.
  80
  81         Notice that the bitmaps displayed in different columns of the same
  82         control must all be of the same size.
  83      */
  84     virtual void SetBitmap(const wxBitmap& bitmap);
  85
  86     /**
  87         Returns the bitmap in the header of the column, if any.
  88
  89         If the column has no associated bitmap, wxNullBitmap is returned.
  90     */
  91     virtual wxBitmap GetBitmap() const;                                   \
  92
  93     /**
  94         Set the column width.
  95
  96         @param width
  97             The column width in pixels or the special wxCOL_WIDTH_DEFAULT value
  98             meaning to use default width.
  99      */
 100     virtual void SetWidth(int width);
 101
 102     /**
 103         Returns the current width of the column.
 104
 105         @return
 106             Width of the column in pixels, never wxCOL_WIDTH_DEFAULT.
 107     */
 108     virtual int GetWidth() const;
 109
 110     /**
 111         Set the minimal column width.
 112
 113         This method can be used with resizeable columns (i.e. those for which
 114         wxCOL_RESIZABLE flag is set in GetFlags() or, alternatively,
 115         IsResizeable() returns @true) to prevent the user from making them
 116         narrower than the given width.
 117
 118         @param minWidth
 119             The minimal column width in pixels, may be 0 to remove any
 120             previously set restrictions.
 121      */
 122     virtual void SetMinWidth(int minWidth);
 123
 124     /**
 125         Return the minimal column width.
 126
 127         @return
 128             The value previously set by SetMinWidth() or 0 by default.
 129      */
 130     virtual int GetMinWidth() const;
 131
 132     /**
 133         Set the alignment of the column header.
 134
 135         @param align
 136             The text alignment in horizontal direction only or wxALIGN_NOT to
 137             use the default alignment, The possible values here are
 138             wxALIGN_CENTRE, wxALIGN_LEFT or wxALIGN_RIGHT with
 139             wxALIGN_CENTRE_HORIZONTAL being also supported as synonym for
 140             wxALIGN_CENTRE for consistency (but notice that GetAlignment()
 141             never returns it).
 142     */
 143     virtual void SetAlignment(wxAlignment align);
 144
 145     /**
 146         Returns the current column alignment.
 147
 148         @return
 149             One of wxALIGN_CENTRE, wxALIGN_LEFT or wxALIGN_RIGHT.
 150      */
 151     virtual wxAlignment GetAlignment() const;
 152
 153
 154     // not documented because I'm not sure if it should be in the public API at
 155     // all
 156 #if 0
 157     // arbitrary client data associated with the column (currently only
 158     // implemented in MSW because it is used in MSW wxDataViewCtrl
 159     // implementation)
 160     virtual void SetClientData(wxUIntPtr data);
 161     virtual wxUIntPtr GetClientData() const;
 162 #endif
 163
 164
 165     /**
 166         Set the column flags.
 167
 168         This method allows to set all flags at once, see also generic
 169         ChangeFlag(), SetFlag(), ClearFlag() and ToggleFlag() methods below as
 170         well as specific SetResizeable(), SetSortable(), SetReorderable() and
 171         SetHidden() ones.
 172
 173         @param flags
 174             Combination of wxCOL_RESIZABLE, wxCOL_SORTABLE, wxCOL_REORDERABLE
 175             and wxCOL_HIDDEN bit flags.
 176      */
 177     virtual void SetFlags(int flags);
 178
 179     /**
 180         Set or clear the given flag.
 181
 182         @param flag
 183             The flag to set or clear.
 184         @param set
 185             If @true, set the flag, i.e. equivalent to calling SetFlag(),
 186             otherwise clear it, as ClearFlag().
 187
 188         @see SetFlags()
 189      */
 190     void ChangeFlag(int flag, bool set);
 191
 192     /**
 193         Set the specified flag for the column.
 194
 195         @see SetFlags()
 196      */
 197     void SetFlag(int flag);
 198
 199     /**
 200         Clear the specified flag for the column.
 201
 202         @see SetFlags()
 203      */
 204     void ClearFlag(int flag);
 205
 206     /**
 207         Toggle the specified flag for the column.
 208
 209         If the flag is currently set, equivalent to ClearFlag(), otherwise --
 210         to SetFlag().
 211
 212         @see SetFlags()
 213      */
 214     void ToggleFlag(int flag);
 215
 216     /**
 217         Get the column flags.
 218
 219         This method retrieves all the flags at once, you can also use HasFlag()
 220         to test for any individual flag or IsResizeable(), IsSortable(),
 221         IsReorderable() and IsHidden() to test for particular flags.
 222
 223         @see SetFlags()
 224      */
 225     virtual int GetFlags() const;
 226
 227     /**
 228         Return @true if the specified flag is currently set for this column.
 229      */
 230     bool HasFlag(int flag) const;
 231
 232
 233     /**
 234         Call this to enable or disable interactive resizing of the column by
 235         the user.
 236
 237         By default, the columns are resizeable.
 238
 239         Equivalent to ChangeFlag(wxCOL_RESIZABLE, resizeable).
 240      */
 241     virtual void SetResizeable(bool resizeable);
 242
 243     /**
 244         Return true if the column can be resized by the user.
 245
 246         Equivalent to HasFlag(wxCOL_RESIZABLE).
 247      */
 248     virtual bool IsResizeable() const;
 249
 250     /**
 251         Allow clicking the column to sort the control contents by the field in
 252         this column.
 253
 254         By default, the columns are not sortable so you need to explicitly call
 255         this function to allow sorting by the field corresponding to this
 256         column.
 257
 258         Equivalent to ChangeFlag(wxCOL_SORTABLE, sortable).
 259      */
 260     virtual void SetSortable(bool sortable);
 261
 262     /**
 263         Returns @true if the column can be clicked by user to sort the control
 264         contents by the field in this column.
 265
 266         This corresponds to wxCOL_SORTABLE flag which is off by default.
 267
 268         @see SetSortable()
 269     */
 270     virtual bool IsSortable() const;
 271
 272     /**
 273         Allow changing the column order by dragging it.
 274
 275         Equivalent to ChangeFlag(wxCOL_REORDERABLE, reorderable).
 276      */
 277     virtual void SetReorderable(bool reorderable);
 278
 279     /**
 280         Returns @true if the column can be dragged by user to change its order.
 281
 282         This corresponds to wxCOL_REORDERABLE flag which is on by default.
 283
 284         @see SetReorderable()
 285     */
 286     virtual bool IsReorderable() const;
 287
 288     /**
 289         Hide or show the column.
 290
 291         By default all columns are shown but some of them can be completely
 292         hidden from view by calling this function.
 293
 294         Equivalent to ChangeFlag(wxCOL_HIDDEN, hidden).
 295      */
 296     virtual void SetHidden(bool hidden);
 297
 298     /**
 299         Returns @true if the column is currently hidden.
 300
 301         This corresponds to wxCOL_HIDDEN flag which is off by default.
 302      */
 303     virtual bool IsHidden() const;
 304
 305     /**
 306         Returns @true if the column is currently shown.
 307
 308         This corresponds to the absence of wxCOL_HIDDEN flag.
 309      */
 310     bool IsShown() const;
 311
 312     /**
 313         Sets the sort order for this column.
 314
 315         This only makes sense for sortable columns and is only taken into
 316         account by the control in which this column is inserted, this function
 317         just stores the sort order in the wxHeaderColumn object.
 318
 319         @param ascending
 320             If @true, sort in ascending order, otherwise in descending order.
 321      */
 322     virtual void SetSortOrder(bool ascending);
 323
 324     /**
 325         Inverses the sort order.
 326
 327         This function is typically called when the user clicks on a column used
 328         for sorting to change sort order from ascending to descending or vice
 329         versa.
 330
 331         @see SetSortOrder(), IsSortOrderAscending()
 332      */
 333     void ToggleSortOrder();
 334
 335     /**
 336         Returns @true, if the sort order is ascending.
 337
 338         @see SetSortOrder()
 339     */
 340     virtual bool IsSortOrderAscending() const;
 341 };
 342
 343