]>
Commit | Line | Data |
---|---|---|
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 | }; |