]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/headercol.h
b8509e8423abe32a1de3a7d14f071d6c396619c0
[wxWidgets.git] / 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 };