interface/vscroll.h

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