]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/headercol.h
Make storing non-trivial data in wxThreadSpecificInfo possible.
[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 // 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 };