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