]>
git.saurik.com Git - wxWidgets.git/blob - interface/wx/headercol.h
b8509e8423abe32a1de3a7d14f071d6c396619c0
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/headercol.h
3 // Purpose: interface of wxHeaderColumn
4 // Author: Vadim Zeitlin
7 // Copyright: (c) 2008 Vadim Zeitlin <vadim@wxwidgets.org>
8 // Licence: wxWindows licence
9 /////////////////////////////////////////////////////////////////////////////
12 Column width special values.
16 /// Special value used for column width meaning unspecified or default.
17 wxCOL_WIDTH_DEFAULT
= -1,
20 Size the column automatically to fit all values.
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.
25 wxCOL_WIDTH_AUTOSIZE
= -2
29 Bit flags used as wxHeaderColumn flags.
33 /// Column can be resized (included in default flags).
36 /// Column can be clicked to toggle the sort order by its contents.
39 /// Column can be dragged to change its order (included in default).
40 wxCOL_REORDERABLE
= 4,
42 /// Column is not shown at all.
45 /// Default flags for wxHeaderColumn ctor.
46 wxCOL_DEFAULT_FLAGS
= wxCOL_RESIZABLE
| wxCOL_REORDERABLE
52 Represents a column header in controls displaying tabular data such as
53 wxDataViewCtrl or wxGrid.
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.
66 Finally, if you don't already store the column information at all anywhere,
67 you should use the concrete wxHeaderColumnSimple class and
77 Get the text shown in the column header.
79 virtual wxString
GetTitle() const = 0;
82 Returns the bitmap in the header of the column, if any.
84 If the column has no associated bitmap, wxNullBitmap should be returned.
86 virtual wxBitmap
GetBitmap() const = 0;
89 Returns the current width of the column.
92 Width of the column in pixels, never wxCOL_WIDTH_DEFAULT or
95 virtual int GetWidth() const = 0;
98 Return the minimal column width.
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.
106 virtual int GetMinWidth() const = 0;
109 Returns the current column alignment.
112 One of wxALIGN_CENTRE, wxALIGN_LEFT or wxALIGN_RIGHT.
114 virtual wxAlignment
GetAlignment() const = 0;
118 Get the column flags.
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.
124 virtual int GetFlags() const = 0;
127 Return @true if the specified flag is currently set for this column.
129 bool HasFlag(int flag
) const;
133 Return true if the column can be resized by the user.
135 Equivalent to HasFlag(wxCOL_RESIZABLE).
137 virtual bool IsResizeable() const;
140 Returns @true if the column can be clicked by user to sort the control
141 contents by the field in this column.
143 This corresponds to wxCOL_SORTABLE flag which is off by default.
145 virtual bool IsSortable() const;
148 Returns @true if the column can be dragged by user to change its order.
150 This corresponds to wxCOL_REORDERABLE flag which is on by default.
152 virtual bool IsReorderable() const;
155 Returns @true if the column is currently hidden.
157 This corresponds to wxCOL_HIDDEN flag which is off by default.
159 virtual bool IsHidden() const;
162 Returns @true if the column is currently shown.
164 This corresponds to the absence of wxCOL_HIDDEN flag.
166 bool IsShown() const;
170 Returns @true if the column is currently used for sorting.
172 virtual bool IsSortKey() const = 0;
175 Returns @true, if the sort order is ascending.
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.
180 virtual bool IsSortOrderAscending() const = 0;
184 @class wxSettableHeaderColumn
186 Adds methods to set the column attributes to wxHeaderColumn.
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.
195 class wxSettableHeaderColumn
: public wxHeaderColumn
199 Set the text to display in the column header.
201 virtual void SetTitle(const wxString
& title
) = 0;
204 Set the bitmap to be displayed in the column header.
206 Notice that the bitmaps displayed in different columns of the same
207 control must all be of the same size.
209 virtual void SetBitmap(const wxBitmap
& bitmap
) = 0;
212 Set the column 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.
219 virtual void SetWidth(int width
) = 0;
222 Set the minimal column width.
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.
230 The minimal column width in pixels, may be 0 to remove any
231 previously set restrictions.
233 virtual void SetMinWidth(int minWidth
) = 0;
236 Set the alignment of the column header.
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()
246 virtual void SetAlignment(wxAlignment align
) = 0;
250 Set the column flags.
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
258 Combination of wxCOL_RESIZABLE, wxCOL_SORTABLE, wxCOL_REORDERABLE
259 and wxCOL_HIDDEN bit flags.
261 virtual void SetFlags(int flags
) = 0;
264 Set or clear the given flag.
267 The flag to set or clear.
269 If @true, set the flag, i.e. equivalent to calling SetFlag(),
270 otherwise clear it, as ClearFlag().
274 void ChangeFlag(int flag
, bool set
);
277 Set the specified flag for the column.
281 void SetFlag(int flag
);
284 Clear the specified flag for the column.
288 void ClearFlag(int flag
);
291 Toggle the specified flag for the column.
293 If the flag is currently set, equivalent to ClearFlag(), otherwise --
298 void ToggleFlag(int flag
);
302 Call this to enable or disable interactive resizing of the column by
305 By default, the columns are resizeable.
307 Equivalent to ChangeFlag(wxCOL_RESIZABLE, resizeable).
309 virtual void SetResizeable(bool resizeable
);
312 Allow clicking the column to sort the control contents by the field in
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
319 Equivalent to ChangeFlag(wxCOL_SORTABLE, sortable).
321 virtual void SetSortable(bool sortable
);
324 Allow changing the column order by dragging it.
326 Equivalent to ChangeFlag(wxCOL_REORDERABLE, reorderable).
328 virtual void SetReorderable(bool reorderable
);
331 Hide or show the column.
333 By default all columns are shown but some of them can be completely
334 hidden from view by calling this function.
336 Equivalent to ChangeFlag(wxCOL_HIDDEN, hidden).
338 virtual void SetHidden(bool hidden
);
342 Sets this column as the sort key for the associated control.
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).
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.
355 Sort (default) or don't sort the control contents by this column.
357 virtual void SetAsSortKey(bool sort
= true) = 0;
360 Don't use this column for sorting.
362 This is equivalent to calling SetAsSortKey() with @false argument.
364 void UnsetAsSortKey();
367 Sets the sort order for this column.
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.
375 If @true, sort in ascending order, otherwise in descending order.
377 virtual void SetSortOrder(bool ascending
) = 0;
380 Inverses the sort order.
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
386 @see SetSortOrder(), IsSortOrderAscending()
388 void ToggleSortOrder();
392 @class wxHeaderColumnSimple
394 Simple container for the information about the column.
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.
400 wxHeaderCtrlSimple * header = new wxHeaderCtrlSimple(...);
401 wxHeaderColumnSimple col("Title");
403 col.SetSortable(100);
404 header->AppendColumn(col);
410 class wxHeaderColumnSimple
: public wxHeaderColumn
415 Constructor for a column header.
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.
420 wxHeaderColumnSimple(const wxString
& title
,
421 int width
= wxCOL_WIDTH_DEFAULT
,
422 wxAlignment align
= wxALIGN_NOT
,
423 int flags
= wxCOL_DEFAULT_FLAGS
);
425 wxHeaderColumnSimple(const wxBitmap
&bitmap
,
426 int width
= wxDVC_DEFAULT_WIDTH
,
427 wxAlignment align
= wxALIGN_CENTER
,
428 int flags
= wxCOL_DEFAULT_FLAGS
);
433 /// Trivial implementations of the base class pure virtual functions.
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;