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