don't place NULL pointers in the GDK window array in GTKGetWindow()
[wxWidgets.git] / interface / wx / vscroll.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: vscroll.h
3 // Purpose: interface of wxVarHScrollHelper
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxVarScrollHelperBase
11
12 This class provides all common base functionality for scroll calculations
13 shared among all variable scrolled window implementations as well as
14 automatic scrollbar functionality, saved scroll positions, controlling
15 target windows to be scrolled, as well as defining all required virtual
16 functions that need to be implemented for any orientation specific work.
17
18 Documentation of this class is provided specifically for referencing use
19 of the functions provided by this class for use with the variable scrolled
20 windows that derive from here. You will likely want to derive your window
21 from one of the already implemented variable scrolled windows rather than
22 from wxVarScrollHelperBase directly.
23
24 @library{wxcore}
25 @category{miscwnd}
26
27 @see wxHScrolledWindow, wxHVScrolledWindow, wxVScrolledWindow
28 */
29 class wxVarScrollHelperBase
30 {
31 public:
32 /**
33 Constructor taking the target window to be scrolled by this helper
34 class. This will attach scroll event handlers to the target window to
35 catch and handle scroll events appropriately.
36 */
37 wxVarScrollHelperBase(wxWindow* winToScroll);
38
39 /**
40 Virtual destructor for detaching scroll event handlers attached with
41 this helper class.
42 */
43 virtual ~wxVarScrollHelperBase();
44
45 /**
46 Translates the logical coordinate given to the current device
47 coordinate. For example, if the window is scrolled 10 units and each
48 scroll unit represents 10 device units (which may not be the case since
49 this class allows for variable scroll unit sizes), a call to this
50 function with a coordinate of 15 will return -85.
51
52 @see CalcUnscrolledPosition()
53 */
54 int CalcScrolledPosition(int coord) const;
55
56 /**
57 Translates the device coordinate given to the corresponding logical
58 coordinate. For example, if the window is scrolled 10 units and each
59 scroll unit represents 10 device units (which may not be the case since
60 this class allows for variable scroll unit sizes), a call to this
61 function with a coordinate of 15 will return 115.
62
63 @see CalcScrolledPosition()
64 */
65 int CalcUnscrolledPosition(int coord) const;
66
67 /**
68 With physical scrolling on (when this is @true), the device origin is
69 changed properly when a wxPaintDC is prepared, children are actually
70 moved and laid out properly, and the contents of the window (pixels)
71 are actually moved. When this is @false, you are responsible for
72 repainting any invalidated areas of the window yourself to account for
73 the new scroll position.
74 */
75 void EnablePhysicalScrolling(bool scrolling = true);
76
77 /**
78 This function needs to be overridden in the in the derived class to
79 return the window size with respect to the opposing orientation. If
80 this is a vertical scrolled window, it should return the height.
81
82 @see GetOrientationTargetSize()
83 */
84 virtual int GetNonOrientationTargetSize() const = 0;
85
86 /**
87 This function need to be overridden to return the orientation that this
88 helper is working with, either @c wxHORIZONTAL or @c wxVERTICAL.
89 */
90 virtual wxOrientation GetOrientation() const = 0;
91
92 /**
93 This function needs to be overridden in the in the derived class to
94 return the window size with respect to the orientation this helper is
95 working with. If this is a vertical scrolled window, it should return
96 the width.
97
98 @see GetNonOrientationTargetSize()
99 */
100 virtual int GetOrientationTargetSize() const = 0;
101
102 /**
103 This function will return the target window this helper class is
104 currently scrolling.
105
106 @see SetTargetWindow()
107 */
108 virtual wxWindow* GetTargetWindow() const;
109
110 /**
111 Returns the index of the first visible unit based on the scroll
112 position.
113 */
114 size_t GetVisibleBegin() const;
115
116 /**
117 Returns the index of the last visible unit based on the scroll
118 position. This includes the last unit even if it is only partially
119 visible.
120 */
121 size_t GetVisibleEnd() const;
122
123 /**
124 Returns @true if the given scroll unit is currently visible (even if
125 only partially visible) or @false otherwise.
126 */
127 bool IsVisible(size_t unit) const;
128
129 /**
130 Recalculate all parameters and repaint all units.
131 */
132 virtual void RefreshAll();
133
134 /**
135 Normally the window will scroll itself, but in some rare occasions you
136 might want it to scroll (part of) another window (e.g. a child of it in
137 order to scroll only a portion the area between the scrollbars like a
138 spreadsheet where only the cell area will move).
139
140 @see GetTargetWindow()
141 */
142 virtual void SetTargetWindow(wxWindow* target);
143
144 /**
145 Update the thumb size shown by the scrollbar.
146 */
147 virtual void UpdateScrollbar();
148
149 /**
150 Returns the virtual scroll unit under the device unit given accounting
151 for scroll position or @c wxNOT_FOUND if none (i.e. if it is below the
152 last item).
153 */
154 int VirtualHitTest(wxCoord coord) const;
155
156
157 protected:
158
159 /**
160 This function doesn't have to be overridden but it may be useful to do
161 so if calculating the units' sizes is a relatively expensive operation
162 as it gives your code a chance to calculate several of them at once and
163 cache the result if necessary.
164
165 OnGetUnitsSizeHint() is normally called just before OnGetUnitSize() but
166 you shouldn't rely on the latter being called for all units in the
167 interval specified here. It is also possible that OnGetUnitSize() will
168 be called for units outside of this interval, so this is really just a
169 hint, not a promise.
170
171 Finally, note that @a unitMin is inclusive, while @a unitMax is
172 exclusive.
173 */
174 virtual void OnGetUnitsSizeHint(size_t unitMin, size_t unitMax) const;
175
176 /**
177 When the number of scroll units change, we try to estimate the total
178 size of all units when the full window size is needed (i.e. to
179 calculate the scrollbar thumb size). This is a rather expensive
180 operation in terms of unit access, so if the user code may estimate the
181 average size better or faster than we do, it should override this
182 function to implement its own logic. This function should return the
183 best guess for the total virtual window size.
184
185 @note Although returning a totally wrong value would still work, it
186 risks resulting in very strange scrollbar behaviour so this
187 function should really try to make the best guess possible.
188 */
189 virtual wxCoord EstimateTotalSize() const;
190
191 /**
192 This function must be overridden in the derived class, and should
193 return the size of the given unit in pixels.
194 */
195 virtual wxCoord OnGetUnitSize(size_t unit) const = 0;
196 };
197
198
199
200 /**
201 @class wxVarVScrollHelper
202
203 This class provides functions wrapping the wxVarScrollHelperBase class,
204 targeted for vertical-specific scrolling.
205
206 Like wxVarScrollHelperBase, this class is mostly only useful to those
207 classes built into wxWidgets deriving from here, and this documentation is
208 mostly only provided for referencing the functions provided by this class.
209 You will likely want to derive your window from wxVScrolledWindow rather
210 than from here directly.
211
212 @library{wxcore}
213 @category{miscwnd}
214
215 @see wxHScrolledWindow, wxHVScrolledWindow, wxVScrolledWindow
216 */
217 class wxVarVScrollHelper : public wxVarScrollHelperBase
218 {
219 public:
220 /**
221 Constructor taking the target window to be scrolled by this helper
222 class. This will attach scroll event handlers to the target window to
223 catch and handle scroll events appropriately.
224 */
225 wxVarVScrollHelper(wxWindow* winToScroll);
226
227 /**
228 Returns the number of rows the target window contains.
229
230 @see SetRowCount()
231 */
232 size_t GetRowCount() const;
233
234 /**
235 Returns the index of the first visible row based on the scroll
236 position.
237 */
238 size_t GetVisibleRowsBegin() const;
239
240 /**
241 Returns the index of the last visible row based on the scroll position.
242 This includes the last row even if it is only partially visible.
243 */
244 size_t GetVisibleRowsEnd() const;
245
246 /**
247 Returns @true if the given row is currently visible (even if only
248 partially visible) or @false otherwise.
249 */
250 bool IsRowVisible(size_t row) const;
251
252 /**
253 Triggers a refresh for just the given row's area of the window if it's
254 visible.
255 */
256 virtual void RefreshRow(size_t row);
257
258 /**
259 Triggers a refresh for the area between the specified range of rows
260 given (inclusively).
261 */
262 virtual void RefreshRows(size_t from, size_t to);
263
264 /**
265 Scroll by the specified number of pages which may be positive (to
266 scroll down) or negative (to scroll up).
267 */
268 virtual bool ScrollRowPages(int pages);
269
270 /**
271 Scroll by the specified number of rows which may be positive (to scroll
272 down) or negative (to scroll up).
273
274 @return @true if the window was scrolled, @false otherwise (for
275 example, if we're trying to scroll down but we are already
276 showing the last row).
277 */
278 virtual bool ScrollRows(int rows);
279
280 /**
281 Scroll to the specified row. It will become the first visible row in
282 the window.
283
284 @return @true if we scrolled the window, @false if nothing was done.
285 */
286 bool ScrollToRow(size_t row);
287
288 /**
289 Set the number of rows the window contains. The derived class must
290 provide the heights for all rows with indices up to the one given here
291 in it's OnGetRowHeight() implementation.
292
293 @see GetRowCount()
294 */
295 void SetRowCount(size_t rowCount);
296
297 protected:
298
299 /**
300 This function doesn't have to be overridden but it may be useful to do
301 so if calculating the rows' sizes is a relatively expensive operation
302 as it gives your code a chance to calculate several of them at once and
303 cache the result if necessary.
304
305 OnGetRowsHeightHint() is normally called just before OnGetRowHeight()
306 but you shouldn't rely on the latter being called for all rows in the
307 interval specified here. It is also possible that OnGetRowHeight() will
308 be called for units outside of this interval, so this is really just a
309 hint, not a promise.
310
311 Finally, note that @a rowMin is inclusive, while @a rowMax is
312 exclusive.
313 */
314 virtual void OnGetRowsHeightHint(size_t rowMin, size_t rowMax) const;
315
316 /**
317 This class forwards calls from EstimateTotalSize() to this function so
318 derived classes can override either just the height or the width
319 estimation, or just estimate both differently if desired in any
320 wxHVScrolledWindow derived class.
321
322 @note This function will not be called if EstimateTotalSize() is
323 overridden in your derived class.
324 */
325 virtual wxCoord EstimateTotalHeight() const;
326
327 /**
328 This function must be overridden in the derived class, and should
329 return the height of the given row in pixels.
330 */
331 virtual wxCoord OnGetRowHeight(size_t row) const = 0;
332 };
333
334
335
336 /**
337 @class wxVarHScrollHelper
338
339 This class provides functions wrapping the wxVarScrollHelperBase class,
340 targeted for horizontal-specific scrolling.
341
342 Like wxVarScrollHelperBase, this class is mostly only useful to those
343 classes built into wxWidgets deriving from here, and this documentation is
344 mostly only provided for referencing the functions provided by this class.
345 You will likely want to derive your window from wxHScrolledWindow rather
346 than from here directly.
347
348 @library{wxcore}
349 @category{miscwnd}
350
351 @see wxHScrolledWindow, wxHVScrolledWindow, wxVScrolledWindow
352 */
353 class wxVarHScrollHelper : public wxVarScrollHelperBase
354 {
355 public:
356 /**
357 Constructor taking the target window to be scrolled by this helper
358 class. This will attach scroll event handlers to the target window to
359 catch and handle scroll events appropriately.
360 */
361 wxVarHScrollHelper(wxWindow* winToScroll);
362
363 /**
364 Returns the number of columns the target window contains.
365
366 @see SetColumnCount()
367 */
368 size_t GetColumnCount() const;
369
370 /**
371 Returns the index of the first visible column based on the scroll
372 position.
373 */
374 size_t GetVisibleColumnsBegin() const;
375
376 /**
377 Returns the index of the last visible column based on the scroll
378 position. This includes the last column even if it is only partially
379 visible.
380 */
381 size_t GetVisibleColumnsEnd() const;
382
383 /**
384 Returns @true if the given column is currently visible (even if only
385 partially visible) or @false otherwise.
386 */
387 bool IsColumnVisible(size_t column) const;
388
389 /**
390 Triggers a refresh for just the given column's area of the window if
391 it's visible.
392 */
393 virtual void RefreshColumn(size_t column);
394
395 /**
396 Triggers a refresh for the area between the specified range of columns
397 given (inclusively).
398 */
399 virtual void RefreshColumns(size_t from, size_t to);
400
401 /**
402 Scroll by the specified number of pages which may be positive (to
403 scroll right) or negative (to scroll left).
404 */
405 virtual bool ScrollColumnPages(int pages);
406
407 /**
408 Scroll by the specified number of columns which may be positive (to
409 scroll right) or negative (to scroll left).
410
411 @return @true if the window was scrolled, @false otherwise (for
412 example, if we're trying to scroll right but we are already
413 showing the last column).
414 */
415 virtual bool ScrollColumns(int columns);
416
417 /**
418 Scroll to the specified column. It will become the first visible column
419 in the window.
420
421 @return @true if we scrolled the window, @false if nothing was done.
422 */
423 bool ScrollToColumn(size_t column);
424
425 /**
426 Set the number of columns the window contains. The derived class must
427 provide the widths for all columns with indices up to the one given
428 here in it's OnGetColumnWidth() implementation.
429
430 @see GetColumnCount()
431 */
432 void SetColumnCount(size_t columnCount);
433
434 protected:
435
436 /**
437 This class forwards calls from EstimateTotalSize() to this function so
438 derived classes can override either just the height or the width
439 estimation, or just estimate both differently if desired in any
440 wxHVScrolledWindow derived class.
441
442 @note This function will not be called if EstimateTotalSize() is
443 overridden in your derived class.
444 */
445 virtual wxCoord EstimateTotalWidth() const;
446
447 /**
448 This function doesn't have to be overridden but it may be useful to do
449 so if calculating the columns' sizes is a relatively expensive
450 operation as it gives your code a chance to calculate several of them
451 at once and cache the result if necessary.
452
453 OnGetColumnsWidthHint() is normally called just before
454 OnGetColumnWidth() but you shouldn't rely on the latter being called
455 for all columns in the interval specified here. It is also possible
456 that OnGetColumnWidth() will be called for units outside of this
457 interval, so this is really just a hint, not a promise.
458
459 Finally, note that @a columnMin is inclusive, while @a columnMax is
460 exclusive.
461 */
462 virtual void OnGetColumnsWidthHint(size_t columnMin,
463 size_t columnMax) const;
464
465 /**
466 This function must be overridden in the derived class, and should
467 return the width of the given column in pixels.
468 */
469 virtual wxCoord OnGetColumnWidth(size_t column) const = 0;
470 };
471
472
473
474 /**
475 @class wxVarHVScrollHelper
476
477 This class provides functions wrapping the wxVarHScrollHelper and
478 wxVarVScrollHelper classes, targeted for scrolling a window in both axis.
479 Since this class is also the join class of the horizontal and vertical
480 scrolling functionality, it also addresses some wrappers that help avoid
481 the need to specify class scope in your wxHVScrolledWindow derived class
482 when using wxVarScrollHelperBase functionality.
483
484 Like all three of it's scroll helper base classes, this class is mostly
485 only useful to those classes built into wxWidgets deriving from here, and
486 this documentation is mostly only provided for referencing the functions
487 provided by this class. You will likely want to derive your window from
488 wxHVScrolledWindow rather than from here directly.
489
490 @library{wxcore}
491 @category{miscwnd}
492
493 @see wxHScrolledWindow, wxHVScrolledWindow, wxVScrolledWindow
494 */
495 class wxVarHVScrollHelper : public wxVarVScrollHelper,
496 public wxVarHScrollHelper
497 {
498 public:
499 /**
500 Constructor taking the target window to be scrolled by this helper
501 class. This will attach scroll event handlers to the target window to
502 catch and handle scroll events appropriately.
503 */
504 wxVarHVScrollHelper(wxWindow* winToScroll);
505
506 /**
507 With physical scrolling on (when this is @true), the device origin is
508 changed properly when a wxPaintDC is prepared, children are actually
509 moved and laid out properly, and the contents of the window (pixels)
510 are actually moved. When this is @false, you are responsible for
511 repainting any invalidated areas of the window yourself to account for
512 the new scroll position.
513
514 @param vscrolling
515 Specifies if physical scrolling should be turned on when scrolling
516 vertically.
517 @param hscrolling
518 Specifies if physical scrolling should be turned on when scrolling
519 horizontally.
520 */
521 void EnablePhysicalScrolling(bool vscrolling = true,
522 bool hscrolling = true);
523
524 /**
525 Returns the number of columns and rows the target window contains.
526
527 @see SetRowColumnCount()
528 */
529 wxSize GetRowColumnCount() const;
530
531 /**
532 Returns the index of the first visible column and row based on the
533 current scroll position.
534 */
535 wxPosition GetVisibleBegin() const;
536
537 /**
538 Returns the index of the last visible column and row based on the
539 scroll position. This includes any partially visible columns or rows.
540 */
541 wxPosition GetVisibleEnd() const;
542
543 //@{
544 /**
545 Returns @true if both the given row and column are currently visible
546 (even if only partially visible) or @false otherwise.
547 */
548 bool IsVisible(size_t row, size_t column) const;
549 bool IsVisible(const wxPosition& pos) const;
550 //@}
551
552 //@{
553 /**
554 Triggers a refresh for just the area shared between the given row and
555 column of the window if it is visible.
556 */
557 virtual void RefreshRowColumn(size_t row, size_t column);
558 virtual void RefreshRowColumn(const wxPosition& pos);
559 //@}
560
561 //@{
562 /**
563 Triggers a refresh for the visible area shared between all given rows
564 and columns (inclusive) of the window. If the target window for both
565 orientations is the same, the rectangle of cells is refreshed; if the
566 target windows differ, the entire client size opposite the orientation
567 direction is refreshed between the specified limits.
568 */
569 virtual void RefreshRowsColumns(size_t fromRow, size_t toRow,
570 size_t fromColumn, size_t toColumn);
571 virtual void RefreshRowsColumns(const wxPosition& from,
572 const wxPosition& to);
573 //@}
574
575 //@{
576 /**
577 Scroll to the specified row and column. It will become the first
578 visible row and column in the window. Returns @true if we scrolled the
579 window, @false if nothing was done.
580 */
581 bool ScrollToRowColumn(size_t row, size_t column);
582 bool ScrollToRowColumn(const wxPosition& pos);
583 //@}
584
585 /**
586 Set the number of rows and columns the target window will contain. The
587 derived class must provide the sizes for all rows and columns with
588 indices up to the ones given here in it's OnGetRowHeight() and
589 OnGetColumnWidth() implementations, respectively.
590
591 @see GetRowColumnCount()
592 */
593 void SetRowColumnCount(size_t rowCount, size_t columnCount);
594
595 //@{
596 /**
597 Returns the virtual scroll unit under the device unit given accounting
598 for scroll position or @c wxNOT_FOUND (for the row, column, or possibly
599 both values) if none.
600 */
601 wxPosition VirtualHitTest(wxCoord x, wxCoord y) const;
602 wxPosition VirtualHitTest(const wxPoint& pos) const;
603 //@}
604 };
605
606
607
608 /**
609 @class wxVScrolledWindow
610
611 In the name of this class, "V" may stand for "variable" because it can be
612 used for scrolling rows of variable heights; "virtual", because it is not
613 necessary to know the heights of all rows in advance -- only those which
614 are shown on the screen need to be measured; or even "vertical", because
615 this class only supports scrolling vertically.
616
617 In any case, this is a generalization of wxScrolled which can be only used
618 when all rows have the same heights. It lacks some other wxScrolled
619 features however, notably it can't scroll specific pixel sizes of the
620 window or its exact client area size.
621
622 To use this class, you need to derive from it and implement the
623 OnGetRowHeight() pure virtual method. You also must call SetRowCount() to
624 let the base class know how many rows it should display, but from that
625 moment on the scrolling is handled entirely by wxVScrolledWindow. You only
626 need to draw the visible part of contents in your @c OnPaint() method as
627 usual. You should use GetVisibleRowsBegin() and GetVisibleRowsEnd() to
628 select the lines to display. Note that the device context origin is not
629 shifted so the first visible row always appears at the point (0, 0) in
630 physical as well as logical coordinates.
631
632 @section vscrolledwindow_compat wxWidgets 2.8 Compatibility Functions
633
634 The following functions provide backwards compatibility for applications
635 originally built using wxVScrolledWindow in 2.6 or 2.8. Originally,
636 wxVScrolledWindow referred to scrolling "lines". We now use "units" in
637 wxVarScrollHelperBase to avoid implying any orientation (since the
638 functions are used for both horizontal and vertical scrolling in derived
639 classes). And in the new wxVScrolledWindow and wxHScrolledWindow classes,
640 we refer to them as "rows" and "columns", respectively. This is to help
641 clear some confusion in not only those classes, but also in
642 wxHVScrolledWindow where functions are inherited from both.
643
644 You are encouraged to update any existing code using these function to use
645 the new replacements mentioned below, and avoid using these functions for
646 any new code as they are deprecated.
647
648 @beginTable
649 @row2col{ <tt>size_t %GetFirstVisibleLine() const</tt>,
650 Deprecated for GetVisibleRowsBegin(). }
651 @row2col{ <tt>size_t %GetLastVisibleLine() const</tt>,
652 Deprecated for GetVisibleRowsEnd(). This function originally had a
653 slight design flaw in that it was possible to return
654 <tt>(size_t)-1</tt> (ie: a large positive number) if the scroll
655 position was 0 and the first line wasn't completely visible. }
656 @row2col{ <tt>size_t %GetLineCount() const</tt>,
657 Deprecated for GetRowCount(). }
658 @row2col{ <tt>int %HitTest(wxCoord x\, wxCoord y) const
659 @n int %HitTest(const wxPoint& pt) const</tt>,
660 Deprecated for VirtualHitTest(). }
661 @row2col{ <tt>virtual wxCoord %OnGetLineHeight(size_t line) const</tt>,
662 Deprecated for OnGetRowHeight(). }
663 @row2col{ <tt>virtual void %OnGetLinesHint(size_t lineMin\, size_t lineMax) const</tt>,
664 Deprecated for OnGetRowsHeightHint(). }
665 @row2col{ <tt>virtual void %RefreshLine(size_t line)</tt>,
666 Deprecated for RefreshRow(). }
667 @row2col{ <tt>virtual void %RefreshLines(size_t from\, size_t to)</tt>,
668 Deprecated for RefreshRows(). }
669 @row2col{ <tt>virtual bool %ScrollLines(int lines)</tt>,
670 Deprecated for ScrollRows(). }
671 @row2col{ <tt>virtual bool %ScrollPages(int pages)</tt>,
672 Deprecated for ScrollRowPages(). }
673 @row2col{ <tt>bool %ScrollToLine(size_t line)</tt>,
674 Deprecated for ScrollToRow(). }
675 @row2col{ <tt>void %SetLineCount(size_t count)</tt>,
676 Deprecated for SetRowCount(). }
677 @endTable
678
679 @library{wxcore}
680 @category{miscwnd}
681
682 @see wxHScrolledWindow, wxHVScrolledWindow
683 */
684 class wxVScrolledWindow : public wxPanel, public wxVarVScrollHelper
685 {
686 public:
687 /**
688 Default constructor, you must call Create() later.
689 */
690 wxVScrolledWindow();
691 /**
692 This is the normal constructor, no need to call Create() after using
693 this constructor.
694
695 @note @c wxVSCROLL is always automatically added to the style, there is
696 no need to specify it explicitly.
697
698 @param parent
699 The parent window, must not be @NULL.
700 @param id
701 The identifier of this window, wxID_ANY by default.
702 @param pos
703 The initial window position.
704 @param size
705 The initial window size.
706 @param style
707 The window style. There are no special style bits defined for this
708 class.
709 @param name
710 The name for this window; usually not used.
711 */
712 wxVScrolledWindow(wxWindow* parent, wxWindowID id = wxID_ANY,
713 const wxPoint& pos = wxDefaultPosition,
714 const wxSize& size = wxDefaultSize, long style = 0,
715 const wxString& name = wxPanelNameStr);
716
717 /**
718 Same as the non-default constuctor, but returns a status code: @true if
719 ok, @false if the window couldn't be created.
720
721 Just as with the constructor, the @c wxVSCROLL style is always used,
722 there is no need to specify it explicitly.
723 */
724 bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
725 const wxPoint& pos = wxDefaultPosition,
726 const wxSize& size = wxDefaultSize, long style = 0,
727 const wxString& name = wxPanelNameStr);
728 };
729
730
731
732 /**
733 @class wxHScrolledWindow
734
735 In the name of this class, "H" stands for "horizontal" because it can be
736 used for scrolling columns of variable widths. It is not necessary to know
737 the widths of all columns in advance -- only those which are shown on the
738 screen need to be measured.
739
740 In any case, this is a generalization of wxScrolled which can be only used
741 when all columns have the same widths. It lacks some other wxScrolled
742 features however, notably it can't scroll specific pixel sizes of the
743 window or its exact client area size.
744
745 To use this class, you need to derive from it and implement the
746 OnGetColumnWidth() pure virtual method. You also must call SetColumnCount()
747 to let the base class know how many columns it should display, but from
748 that moment on the scrolling is handled entirely by wxHScrolledWindow. You
749 only need to draw the visible part of contents in your @c OnPaint() method
750 as usual. You should use GetVisibleColumnsBegin() and
751 GetVisibleColumnsEnd() to select the lines to display. Note that the device
752 context origin is not shifted so the first visible column always appears at
753 the point (0, 0) in physical as well as logical coordinates.
754
755 @library{wxcore}
756 @category{miscwnd}
757
758 @see wxHVScrolledWindow, wxVScrolledWindow
759 */
760 class wxHScrolledWindow : public wxPanel, public wxVarHScrollHelper
761 {
762 public:
763 /**
764 Default constructor, you must call Create() later.
765 */
766 wxHScrolledWindow();
767 /**
768 This is the normal constructor, no need to call Create() after using
769 this constructor.
770
771 @note @c wxHSCROLL is always automatically added to the style, there is
772 no need to specify it explicitly.
773
774 @param parent
775 The parent window, must not be @NULL.
776 @param id
777 The identifier of this window, wxID_ANY by default.
778 @param pos
779 The initial window position.
780 @param size
781 The initial window size.
782 @param style
783 The window style. There are no special style bits defined for this
784 class.
785 @param name
786 The name for this window; usually not used.
787 */
788 wxHScrolledWindow(wxWindow* parent, wxWindowID id = wxID_ANY,
789 const wxPoint& pos = wxDefaultPosition,
790 const wxSize& size = wxDefaultSize, long style = 0,
791 const wxString& name = wxPanelNameStr);
792
793 /**
794 Same as the non-default constuctor, but returns a status code: @true if
795 ok, @false if the window couldn't be created.
796
797 Just as with the constructor, the @c wxHSCROLL style is always used,
798 there is no need to specify it explicitly.
799 */
800 bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
801 const wxPoint& pos = wxDefaultPosition,
802 const wxSize& size = wxDefaultSize, long style = 0,
803 const wxString& name = wxPanelNameStr);
804 };
805
806
807
808 /**
809 @class wxHVScrolledWindow
810
811 This window inherits all functionality of both vertical and horizontal,
812 variable scrolled windows. It automatically handles everything needed to
813 scroll both axis simultaneously with both variable row heights and variable
814 column widths.
815
816 In any case, this is a generalization of wxScrolled which can be only used
817 when all rows and columns are the same size. It lacks some other wxScrolled
818 features however, notably it can't scroll specific pixel sizes of the
819 window or its exact client area size.
820
821 To use this class, you must derive from it and implement both the
822 OnGetRowHeight() and OnGetColumnWidth() pure virtual methods to let the
823 base class know how many rows and columns it should display. You also need
824 to set the total rows and columns the window contains, but from that moment
825 on the scrolling is handled entirely by wxHVScrolledWindow. You only need
826 to draw the visible part of contents in your @c OnPaint() method as usual.
827 You should use GetVisibleBegin() and GetVisibleEnd() to select the lines to
828 display. Note that the device context origin is not shifted so the first
829 visible row and column always appear at the point (0, 0) in physical as
830 well as logical coordinates.
831
832 @library{wxcore}
833 @category{miscwnd}
834
835 @see wxHScrolledWindow, wxVScrolledWindow
836 */
837 class wxHVScrolledWindow : public wxPanel, public wxVarHVScrollHelper
838 {
839 public:
840 /**
841 Default constructor, you must call Create() later.
842 */
843 wxHVScrolledWindow();
844 /**
845 This is the normal constructor, no need to call Create() after using
846 this constructor.
847
848 @note @c wxHSCROLL and @c wxVSCROLL are always automatically added to
849 the style, there is no need to specify it explicitly.
850
851 @param parent
852 The parent window, must not be @NULL.
853 @param id
854 The identifier of this window, wxID_ANY by default.
855 @param pos
856 The initial window position.
857 @param size
858 The initial window size.
859 @param style
860 The window style. There are no special style bits defined for this
861 class.
862 @param name
863 The name for this window; usually not used.
864 */
865 wxHVScrolledWindow(wxWindow* parent, wxWindowID id = wxID_ANY,
866 const wxPoint& pos = wxDefaultPosition,
867 const wxSize& size = wxDefaultSize, long style = 0,
868 const wxString& name = wxPanelNameStr);
869
870 /**
871 Same as the non-default constuctor, but returns a status code: @true if
872 ok, @false if the window couldn't be created.
873
874 Just as with the constructor, the @c wxHSCROLL and @c wxVSCROLL styles
875 are always used, there is no need to specify them explicitly.
876 */
877 bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
878 const wxPoint& pos = wxDefaultPosition,
879 const wxSize& size = wxDefaultSize, long style = 0,
880 const wxString& name = wxPanelNameStr);
881 };
882