]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/headerctrl.h
Move code removing "-psn_xxx" command line arguments to common code.
[wxWidgets.git] / interface / wx / headerctrl.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/headerctrl.h
3 // Purpose: interface of wxHeaderCtrl
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 enum
12 {
13 // allow column drag and drop
14 wxHD_ALLOW_REORDER = 0x0001,
15
16 // allow hiding (and showing back) the columns using the menu shown by
17 // right clicking the header
18 wxHD_ALLOW_HIDE = 0x0002,
19
20 // style used by default when creating the control
21 wxHD_DEFAULT_STYLE = wxHD_ALLOW_REORDER
22 };
23
24
25
26 /**
27 @class wxHeaderCtrl
28
29 wxHeaderCtrl is the control containing the column headings which is usually
30 used for display of tabular data.
31
32 It is used as part of wxGrid, in generic version wxDataViewCtrl and report
33 view of wxListCtrl but can be also used independently. In general this
34 class is meant to be used as part of another control which already stores
35 the column information somewhere as it can't be used directly: instead you
36 need to inherit from it and implement the GetColumn() method to provide
37 column information. See wxHeaderCtrlSimple for a concrete control class
38 which can be used directly.
39
40 In addition to labeling the columns, the control has the following
41 features:
42 - Column reordering support, either by explicitly configuring the
43 columns order and calling SetColumnsOrder() or by dragging the
44 columns interactively (if enabled).
45 - Display of the icons in the header: this is often used to display a
46 sort or reverse sort indicator when the column header is clicked.
47
48 Notice that this control itself doesn't do anything other than displaying
49 the column headers. In particular column reordering and sorting must still
50 be supported by the associated control displaying the real data under the
51 header. Also remember to call ScrollWindow() method of the control if the
52 associated data display window has a horizontal scrollbar, otherwise the
53 headers wouldn't align with the data when the window is scrolled.
54
55 This control is implemented using the native header control under MSW
56 systems and a generic implementation elsewhere.
57
58
59 @section headerctrl_improvements Future Improvements
60
61 Some features are supported by the native MSW control and so could be
62 easily implemented in this version of wxHeaderCtrl but need to be
63 implemented in the generic version as well to be really useful. Please let
64 us know if you need or, better, plan to work on implementing, any of them:
65 - Displaying bitmaps instead of or together with the text
66 - Custom drawn headers
67 - Filters associated with a column.
68
69
70 @beginStyleTable
71 @style{wxHD_ALLOW_REORDER}
72 If this style is specified (it is by default), the user can reorder
73 the control columns by dragging them.
74 @style{wxHD_ALLOW_HIDE}
75 If this style is specified, the control shows a popup menu allowing the
76 user to change the columns visibility on right mouse click. Notice that
77 the program can always hide or show the columns, this style only
78 affects the users capability to do it.
79 @style{wxHD_DEFAULT_STYLE}
80 Symbolic name for the default control style, currently equal to
81 @c wxHD_ALLOW_REORDER.
82 @endStyleTable
83
84 @beginEventEmissionTable{wxHeaderCtrlEvent}
85 @event{EVT_HEADER_CLICK(id, func)}
86 A column heading was clicked.
87 @event{EVT_HEADER_RIGHT_CLICK(id, func)}
88 A column heading was right clicked.
89 @event{EVT_HEADER_MIDDLE_CLICK(id, func)}
90 A column heading was clicked with the middle mouse button.
91 @event{EVT_HEADER_DCLICK(id, func)}
92 A column heading was double clicked.
93 @event{EVT_HEADER_RIGHT_DCLICK(id, func)}
94 A column heading was right double clicked.
95 @event{EVT_HEADER_MIDDLE_DCLICK(id, func)}
96 A column heading was double clicked with the middle mouse button.
97 @event{EVT_HEADER_SEPARATOR_DCLICK(id, func)}
98 Separator to the right of the specified column was double clicked
99 (this action is commonly used to resize the column to fit its
100 contents width and the control provides UpdateColumnWidthToFit() method
101 to make implementing this easier).
102 @event{EVT_HEADER_BEGIN_RESIZE(id, func)}
103 The user started to drag the separator to the right of the column
104 with the specified index (this can only happen for the columns for
105 which wxHeaderColumn::IsResizeable() returns true). The event can
106 be vetoed to prevent the column from being resized. If it isn't,
107 the resizing and end resize (or dragging cancelled) events will be
108 generated later.
109 @event{EVT_HEADER_RESIZING(id, func)}
110 The user is dragging the column with the specified index resizing
111 it and its current width is wxHeaderCtrlEvent::GetWidth().
112 The event can be vetoed to stop the dragging operation completely at
113 any time.
114 @event{EVT_HEADER_END_RESIZE(id, func)}
115 The user stopped dragging the column by releasing the mouse.
116 The column should normally be resized to the value of
117 wxHeaderCtrlEvent::GetWidth().
118 @event{EVT_HEADER_BEGIN_REORDER(id, func)}
119 The user started to drag the column with the specified index (this
120 can only happen for the controls with wxHD_ALLOW_REORDER style).
121 This event can be vetoed to prevent the column from being reordered,
122 otherwise the end reorder message will be generated later.
123 @event{EVT_HEADER_END_REORDER(id, func)}
124 The user dropped the column in its new location. The event can be
125 vetoed to prevent the column from being placed at the new position
126 or handled to update the display of the data in the associated
127 control to match the new column location (available from
128 wxHeaderCtrlEvent::GetNewOrder()).
129 @event{EVT_HEADER_DRAGGING_CANCELLED(id, func)}
130 The resizing or reordering operation currently in progress was
131 cancelled. This can happen if the user pressed Esc key while
132 dragging the mouse or the mouse capture was lost for some other
133 reason. You only need to handle this event if your application
134 entered into some modal mode when resizing or reordering began, in
135 which case it should handle this event in addition to the matching
136 end resizing or reordering ones.
137 @endEventTable
138
139 @library{wxcore}
140 @category{ctrl}
141
142 @see wxGrid, wxListCtrl, wxDataViewCtrl
143 */
144 class wxHeaderCtrl : public wxControl
145 {
146 public:
147 /**
148 Default constructor not creating the underlying window.
149
150 You must use Create() after creating the object using this constructor.
151 */
152 wxHeaderCtrl();
153
154 /**
155 Constructor creating the window.
156
157 Please see Create() for the parameters documentation.
158 */
159 wxHeaderCtrl(wxWindow *parent,
160 wxWindowID winid = wxID_ANY,
161 const wxPoint& pos = wxDefaultPosition,
162 const wxSize& size = wxDefaultSize,
163 long style = wxHD_DEFAULT_STYLE,
164 const wxString& name = wxHeaderCtrlNameStr);
165
166 /**
167 Create the header control window.
168
169 @param parent
170 The parent window. The header control should be typically
171 positioned along the top edge of this window.
172 @param winid
173 Id of the control or @c wxID_ANY if you don't care.
174 @param pos
175 The initial position of the control.
176 @param size
177 The initial size of the control (usually not very useful as this
178 control will typically be resized to have the same width as the
179 associated data display control).
180 @param style
181 The control style, @c wxHD_DEFAULT_STYLE by default. Notice that
182 the default style allows the user to reorder the columns by
183 dragging them and you need to explicitly turn this feature off by
184 using @code wxHD_DEFAULT_STYLE & ~wxHD_ALLOW_REORDER @endcode if
185 this is undesirable.
186 @param name
187 The name of the control.
188 */
189 bool Create(wxWindow *parent,
190 wxWindowID winid = wxID_ANY,
191 const wxPoint& pos = wxDefaultPosition,
192 const wxSize& size = wxDefaultSize,
193 long style = wxHD_DEFAULT_STYLE,
194 const wxString& name = wxHeaderCtrlNameStr);
195
196 /**
197 Set the number of columns in the control.
198
199 The control will use GetColumn() to get information about all the
200 new columns and refresh itself, i.e. this method also has the same
201 effect as calling UpdateColumn() for all columns but it should only be
202 used if the number of columns really changed.
203 */
204 void SetColumnCount(unsigned int count);
205
206 /**
207 Return the number of columns in the control.
208
209 @return
210 Number of columns as previously set by SetColumnCount().
211
212 @see IsEmpty()
213 */
214 unsigned int GetColumnCount() const;
215
216 /**
217 Return whether the control has any columns.
218
219 @see GetColumnCount()
220 */
221 bool IsEmpty() const;
222
223 /**
224 Update the column with the given index.
225
226 When the value returned by GetColumn() changes, this method must be
227 called to notify the control about the change and update the visual
228 display to match the new column data.
229
230 @param idx
231 The column index, must be less than GetColumnCount().
232 */
233 void UpdateColumn(unsigned int idx);
234
235 /**
236 Change the columns display order.
237
238 The display order defines the order in which the columns appear on the
239 screen and does @em not affect the interpretation of indices by all the
240 other class methods.
241
242 The @a order array specifies the column indices corresponding to the
243 display positions.
244
245 @param order
246 A permutation of all column indices, i.e. an array of size
247 GetColumnsOrder() containing all column indices exactly once. The
248 n-th element of this array defines the index of the column shown at
249 the n-th position from left (for the default left-to-right writing
250 direction).
251
252 @see wxListCtrl::SetColumnsOrder()
253 */
254 void SetColumnsOrder(const wxArrayInt& order);
255
256 /**
257 Return the array describing the columns display order.
258
259 For the controls without wxHD_ALLOW_REORDER style the returned array
260 will be the same as was passed to SetColumnsOrder() previously or
261 define the default order (with n-th element being n) if it hadn't been
262 called. But for the controls with wxHD_ALLOW_REORDER style, the columns
263 can be also reordered by user.
264 */
265 wxArrayInt GetColumnsOrder() const;
266
267 /**
268 Return the index of the column displayed at the given position.
269
270 @param pos
271 The display position, e.g. 0 for the left-most column, 1 for the
272 next one and so on until GetColumnCount() - 1.
273
274 @see GetColumnPos()
275 */
276 unsigned int GetColumnAt(unsigned int pos) const;
277
278 /**
279 Get the position at which this column is currently displayed.
280
281 Notice that a valid position is returned even for the hidden columns
282 currently.
283
284 @param idx
285 The column index, must be less than GetColumnCount().
286
287 @see GetColumnAt()
288 */
289 unsigned int GetColumnPos(unsigned int idx) const;
290
291 /**
292 Reset the columns order to the natural one.
293
294 After calling this function, the column with index @c idx appears at
295 position @c idx in the control.
296 */
297 void ResetColumnsOrder();
298
299 /**
300 Helper function to manipulate the array of column indices.
301
302 This function reshuffles the array of column indices indexed by
303 positions (i.e. using the same convention as for SetColumnsOrder()) so
304 that the column with the given index is found at the specified
305 position.
306
307 @param order
308 Array containing the indices of columns in order of their
309 positions.
310 @param idx
311 The index of the column to move.
312 @param pos
313 The new position for the column @a idx.
314 */
315 static void MoveColumnInOrderArray(wxArrayInt& order,
316 unsigned int idx,
317 unsigned int pos);
318
319 /**
320 Show the popup menu allowing the user to show or hide the columns.
321
322 This functions shows the popup menu containing all columns with check
323 marks for the ones which are currently shown and allows the user to
324 check or uncheck them to toggle their visibility. It is called from the
325 default EVT_HEADER_RIGHT_CLICK handler for the controls which have
326 wxHD_ALLOW_HIDE style. And if the column has wxHD_ALLOW_REORDER style
327 as well, the menu also contains an item to customize the columns shown
328 using which results in ShowCustomizeDialog() being called, please see
329 its description for more details.
330
331 If a column was toggled, UpdateColumnVisibility() virtual function is
332 called so it must be implemented for the controls with wxHD_ALLOW_HIDE
333 style or if you call this function explicitly.
334
335 @param pt
336 The position of the menu, in the header window coordinates.
337 @param title
338 The title for the menu if not empty.
339 @return
340 @true if a column was shown or hidden or @false if nothing was
341 done, e.g. because the menu was cancelled.
342 */
343 bool ShowColumnsMenu(const wxPoint& pt, const wxString& title = wxString());
344
345 /**
346 Helper function appending the checkable items corresponding to all the
347 columns to the given menu.
348
349 This function is used by ShowColumnsMenu() but can also be used if you
350 show your own custom columns menu and still want all the columns shown
351 in it. It appends menu items with column labels as their text and
352 consecutive ids starting from @a idColumnsBase to the menu and checks
353 the items corresponding to the currently visible columns.
354
355 Example of use:
356 @code
357 wxMenu menu;
358 menu.Append(100, "Some custom command");
359 menu.AppendSeparator();
360 AddColumnsItems(menu, 200);
361 const int rc = GetPopupMenuSelectionFromUser(menu, pt);
362 if ( rc >= 200 )
363 ... toggle visibility of the column rc-200 ...
364 @endcode
365
366 @param menu
367 The menu to append the items to. It may be currently empty or not.
368 @param idColumnsBase
369 The id for the menu item corresponding to the first column, the
370 other ones are consecutive starting from it. It should be positive.
371 */
372 void AddColumnsItems(wxMenu& menu, int idColumnsBase = 0);
373
374 /**
375 Show the column customization dialog.
376
377 This function displays a modal dialog containing the list of all
378 columns which the user can use to reorder them as well as show or hide
379 individual columns.
380
381 If the user accepts the changes done in the dialog, the virtual
382 methods UpdateColumnVisibility() and UpdateColumnsOrder() will be
383 called so they must be overridden in the derived class if this method
384 is ever called. Please notice that the user will be able to invoke it
385 interactively from the header popup menu if the control has both
386 wxHD_ALLOW_HIDE and wxHD_ALLOW_REORDER styles.
387
388 @see wxRearrangeDialog
389 */
390 bool ShowCustomizeDialog();
391
392 /**
393 Returns width needed for given column's title.
394
395 @since 2.9.4
396 */
397 int GetColumnTitleWidth(const wxHeaderColumn& col);
398
399 protected:
400 /**
401 Method to be implemented by the derived classes to return the
402 information for the given column.
403
404 @param idx
405 The column index, between 0 and the value last passed to
406 SetColumnCount().
407 */
408 virtual const wxHeaderColumn& GetColumn(unsigned int idx) const = 0;
409
410 /**
411 Method called when the column visibility is changed by the user.
412
413 This method is called from ShowColumnsMenu() or ShowCustomizeDialog()
414 when the user interactively hides or shows a column. A typical
415 implementation will simply update the internally stored column state.
416 Notice that there is no need to call UpdateColumn() from this method as
417 it is already done by wxHeaderCtrl itself.
418
419 The base class version doesn't do anything and must be overridden if
420 this method is called.
421
422 @param idx
423 The index of the column whose visibility was toggled.
424 @param show
425 The new visibility value, @true if the column is now shown or
426 @false if it is not hidden.
427 */
428 virtual void UpdateColumnVisibility(unsigned int idx, bool show);
429
430 /**
431 Method called when the columns order is changed in the customization
432 dialog.
433
434 This method is only called from ShowCustomizeDialog() when the user
435 changes the order of columns. In particular it is @em not called if a
436 single column changes place because the user dragged it to the new
437 location, the EVT_HEADER_END_REORDER event handler should be used to
438 react to this.
439
440 A typical implementation in a derived class will update the display
441 order of the columns in the associated control, if any. Notice that
442 there is no need to call SetColumnsOrder() from it as wxHeaderCtrl does
443 it itself.
444
445 The base class version doesn't do anything and must be overridden if
446 this method is called.
447
448 @param order
449 The new column order. This array uses the same convention as
450 SetColumnsOrder().
451 */
452 virtual void UpdateColumnsOrder(const wxArrayInt& order);
453
454 /**
455 Method which may be implemented by the derived classes to allow double
456 clicking the column separator to resize the column to fit its contents.
457
458 When a separator is double clicked, the default handler of
459 EVT_HEADER_SEPARATOR_DCLICK event calls this function and refreshes the
460 column if it returns @true so to implement the resizing of the column
461 to fit its width on header double click you need to implement this
462 method using logic similar to this example:
463 @code
464 class MyHeaderColumn : public wxHeaderColumn
465 {
466 public:
467 ...
468
469 void SetWidth(int width) { m_width = width; }
470 virtual int GetWidth() const { return m_width; }
471
472 private:
473 int m_width;
474 };
475
476 class MyHeaderCtrl : public wxHeaderCtrl
477 {
478 public:
479 protected:
480 virtual wxHeaderColumn& GetColumn(unsigned int idx) const
481 {
482 return m_cols[idx];
483 }
484
485 virtual bool UpdateColumnWidthToFit(unsigned int idx, int widthTitle)
486 {
487 int widthContents = ... compute minimal width for column idx ...
488 m_cols[idx].SetWidth(wxMax(widthContents, widthTitle));
489 return true;
490 }
491
492 wxVector<MyHeaderColumn> m_cols;
493 };
494 @endcode
495
496 Base class version simply returns @false.
497
498 @param idx
499 The zero-based index of the column to update.
500 @param widthTitle
501 Contains minimal width needed to display the column header itself
502 and will usually be used as a starting point for the fitting width
503 calculation.
504
505 @return
506 @true to indicate that the column was resized, i.e. GetColumn() now
507 returns the new width value, and so must be refreshed or @false
508 meaning that the control didn't reach to the separator double click.
509 */
510 virtual bool UpdateColumnWidthToFit(unsigned int idx, int widthTitle);
511
512 /**
513 Can be overridden in the derived class to update internal data
514 structures when the number of the columns in the control changes.
515
516 This method is called by SetColumnCount() before effectively changing
517 the number of columns.
518
519 The base class version does nothing but it is good practice to still
520 call it from the overridden version in the derived class.
521 */
522 virtual void OnColumnCountChanging(unsigned int count);
523 };
524
525
526 /**
527 @class wxHeaderCtrlSimple
528
529 wxHeaderCtrlSimple is a concrete header control which can be used directly,
530 without inheriting from it as you need to do when using wxHeaderCtrl
531 itself.
532
533 When using it, you need to use simple AppendColumn(), InsertColumn() and
534 DeleteColumn() methods instead of setting the number of columns with
535 SetColumnCount() and returning the information about them from the
536 overridden GetColumn().
537
538 @library{wxcore}
539 @category{ctrl}
540
541 @see wxHeaderCtrl
542 */
543 class wxHeaderCtrlSimple : public wxHeaderCtrl
544 {
545 public:
546 /**
547 Default constructor not creating the underlying window.
548
549 You must use Create() after creating the object using this constructor.
550 */
551 wxHeaderCtrlSimple();
552
553 /**
554 Constructor creating the window.
555
556 Please see the base class wxHeaderCtrl::Create() method for the
557 parameters description.
558 */
559 wxHeaderCtrlSimple(wxWindow *parent,
560 wxWindowID winid = wxID_ANY,
561 const wxPoint& pos = wxDefaultPosition,
562 const wxSize& size = wxDefaultSize,
563 long style = wxHD_DEFAULT_STYLE,
564 const wxString& name = wxHeaderCtrlNameStr);
565
566 /**
567 Insert the column at the given position.
568
569 @param col
570 The column to insert. Notice that because of the existence of
571 implicit conversion from wxString to wxHeaderColumn a string
572 can be passed directly here.
573 @param idx
574 The position of the new column, from 0 to GetColumnCount(). Using
575 GetColumnCount() means to append the column to the end.
576
577 @see AppendColumn()
578 */
579 void InsertColumn(const wxHeaderColumnSimple& col, unsigned int idx);
580
581 /**
582 Append the column to the end of the control.
583
584 @see InsertColumn()
585 */
586 void AppendColumn(const wxHeaderColumnSimple& col);
587
588 /**
589 Delete the column at the given position.
590
591 @see InsertColumn(), AppendColumn()
592 */
593 void DeleteColumn(unsigned int idx);
594
595 /**
596 Show or hide the column.
597
598 Initially the column is shown by default or hidden if it was added with
599 wxCOL_HIDDEN flag set.
600
601 When a column is hidden, it doesn't appear at all on the screen but its
602 index is still taken into account when working with other columns. E.g.
603 if there are three columns 0, 1 and 2 and the column 1 is hidden you
604 still need to use index 2 to refer to the last visible column.
605
606 @param idx
607 The index of the column to show or hide, from 0 to GetColumnCount().
608 @param show
609 Indicates whether the column should be shown (default) or hidden.
610 */
611 void ShowColumn(unsigned int idx, bool show = true);
612
613 /**
614 Hide the column with the given index.
615
616 This is the same as calling @code ShowColumn(idx, false) @endcode.
617
618 @param idx
619 The index of the column to show or hide, from 0 to GetColumnCount().
620 */
621 void HideColumn(unsigned int idx);
622
623 /**
624 Update the column sort indicator.
625
626 The sort indicator, if shown, is typically an arrow pointing upwards or
627 downwards depending on whether the control contents is sorted in
628 ascending or descending order.
629
630 @param idx
631 The column to set the sort indicator for.
632 If @c -1 is given, then the currently shown sort indicator
633 will be removed.
634 @param sortOrder
635 If @true or @false show the sort indicator corresponding to
636 ascending or descending sort order respectively.
637 */
638 void ShowSortIndicator(unsigned int idx, bool sortOrder = true);
639
640 /**
641 Remove the sort indicator from the column being used as sort key.
642
643 @see ShowSortIndicator
644 */
645 void RemoveSortIndicator();
646
647 protected:
648 /**
649 This function can be overridden in the classes deriving from this
650 control instead of overriding UpdateColumnWidthToFit().
651
652 To implement automatic column resizing to fit its contents width when
653 the column divider is double clicked, you need to simply return the
654 fitting width for the given column @a idx from this method, the control
655 will automatically use the biggest value between the one returned from
656 here and the one needed for the display of the column title itself.
657
658 The base class version returns -1 indicating that this function is not
659 implemented.
660 */
661 virtual int GetBestFittingWidth(unsigned int idx) const;
662 };
663
664 /**
665 @class wxHeaderCtrlEvent
666
667 Event class representing the events generated by wxHeaderCtrl.
668
669 @library{wxcore}
670 @category{events}
671
672 @see wxHeaderCtrl
673 */
674 class wxHeaderCtrlEvent : public wxNotifyEvent
675 {
676 public:
677 wxHeaderCtrlEvent(wxEventType commandType = wxEVT_NULL, int winid = 0);
678 wxHeaderCtrlEvent(const wxHeaderCtrlEvent& event);
679
680 /**
681 Return the index of the column affected by this event.
682
683 This method can be called for all header control events.
684 */
685 int GetColumn() const;
686 void SetColumn(int col);
687
688 /**
689 Return the current width of the column.
690
691 This method can only be called for the dragging events.
692 */
693 int GetWidth() const;
694 void SetWidth(int width);
695
696 /**
697 Return the new order of the column.
698
699 This method can only be called for a reorder event for which it
700 indicates the tentative new position for the column GetColumn()
701 selected by the user. If the event is not vetoed, this will become the
702 new column position in wxHeaderCtrl::GetColumnsOrder().
703 */
704 unsigned int GetNewOrder() const;
705 void SetNewOrder(unsigned int order);
706 };
707
708
709
710 wxEventType wxEVT_HEADER_CLICK;
711 wxEventType wxEVT_HEADER_RIGHT_CLICK;
712 wxEventType wxEVT_HEADER_MIDDLE_CLICK;
713 wxEventType wxEVT_HEADER_DCLICK;
714 wxEventType wxEVT_HEADER_RIGHT_DCLICK;
715 wxEventType wxEVT_HEADER_MIDDLE_DCLICK;
716 wxEventType wxEVT_HEADER_SEPARATOR_DCLICK;
717 wxEventType wxEVT_HEADER_BEGIN_RESIZE;
718 wxEventType wxEVT_HEADER_RESIZING;
719 wxEventType wxEVT_HEADER_END_RESIZE;
720 wxEventType wxEVT_HEADER_BEGIN_REORDER;
721 wxEventType wxEVT_HEADER_END_REORDER;
722 wxEventType wxEVT_HEADER_DRAGGING_CANCELLED;