interface/vscroll.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        vscroll.h
   3 // Purpose:     interface of wxVarHScrollHelper
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class 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     @see wxHScrolledWindow, wxHVScrolledWindow, wxVScrolledWindow
  26 */
  27 class wxVarHScrollHelper : public wxVarScrollHelperBase
  28 {
  29 public:
  30     /**
  31         Constructor taking the target window to be scrolled by this helper class.
  32         This will attach scroll event handlers to the target window to catch and
  33         handle scroll events appropriately.
  34     */
  35     wxVarHScrollHelper(wxWindow* winToScroll);
  36
  37     /**
  38         This class forwards calls from
  39         wxVarScrollHelperBase::EstimateTotalSize
  40         to this function so derived classes can override either just the height or
  41         the width estimation, or just estimate both differently if desired in any
  42         wxHVScrolledWindow derived class.
  43         Please note that this function will not be called if @c EstimateTotalSize()
  44         is overridden in your derived class.
  45     */
  46     virtual wxCoord EstimateTotalWidth() const;
  47
  48     /**
  49         Returns the number of columns the target window contains.
  50
  51         @see SetColumnCount()
  52     */
  53     size_t GetColumnCount() const;
  54
  55     /**
  56         Returns the index of the first visible column based on the scroll position.
  57     */
  58     size_t GetVisibleColumnsBegin() const;
  59
  60     /**
  61         Returns the index of the last visible column based on the scroll position. This
  62         includes the last column even if it is only partially visible.
  63     */
  64     size_t GetVisibleColumnsEnd() const;
  65
  66     /**
  67         Returns @true if the given column is currently visible (even if only
  68         partially visible) or @false otherwise.
  69     */
  70     bool IsColumnVisible(size_t column) const;
  71
  72     /**
  73         This function must be overridden in the derived class, and should return the
  74         width of the given column in pixels.
  75     */
  76     virtual wxCoord OnGetColumnWidth(size_t column) const;
  77
  78     /**
  79         This function doesn't have to be overridden but it may be useful to do so if
  80         calculating the columns' sizes is a relatively expensive operation as it gives
  81         your code a chance to calculate several of them at once and cache the result
  82         if necessary.
  83         @c OnGetColumnsWidthHint() is normally called just before
  84         OnGetColumnWidth() but you
  85         shouldn't rely on the latter being called for all columns in the interval
  86         specified here. It is also possible that OnGetColumnWidth() will be called for
  87         units outside of this interval, so this is really just a hint, not a promise.
  88         Finally, note that columnMin is inclusive, while columnMax is exclusive.
  89     */
  90     virtual void OnGetColumnsWidthHint(size_t columnMin,
  91                                        size_t columnMax) const;
  92
  93     /**
  94         Triggers a refresh for just the given column's area of the window if it's
  95         visible.
  96     */
  97     virtual void RefreshColumn(size_t column);
  98
  99     /**
 100         Triggers a refresh for the area between the specified range of columns given
 101         (inclusively).
 102     */
 103     virtual void RefreshColumns(size_t from, size_t to);
 104
 105     /**
 106         Scroll by the specified number of pages which may be positive (to scroll right)
 107         or negative (to scroll left).
 108     */
 109     virtual bool ScrollColumnPages(int pages);
 110
 111     /**
 112         Scroll by the specified number of columns which may be positive (to scroll
 113         right)
 114         or negative (to scroll left).
 115         Returns @true if the window was scrolled, @false otherwise (for
 116         example, if we're trying to scroll right but we are already showing the last
 117         column).
 118     */
 119     virtual bool ScrollColumns(int columns);
 120
 121     /**
 122         Scroll to the specified column. It will become the first visible column in the
 123         window.
 124         Returns @true if we scrolled the window, @false if nothing was done.
 125     */
 126     bool ScrollToColumn(size_t column);
 127
 128     /**
 129         Set the number of columns the window contains. The derived class must provide
 130         the widths for all columns with indices up to the one given here in it's
 131         OnGetColumnWidth() implementation.
 132     */
 133     void SetColumnCount(size_t columnCount);
 134 };
 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     @see wxHScrolledWindow, wxHVScrolledWindow, wxVScrolledWindow
 155 */
 156 class wxVarVScrollHelper : public wxVarScrollHelperBase
 157 {
 158 public:
 159     /**
 160         Constructor taking the target window to be scrolled by this helper class.
 161         This will attach scroll event handlers to the target window to catch and
 162         handle scroll events appropriately.
 163     */
 164     wxVarVScrollHelper(wxWindow* winToScroll);
 165
 166     /**
 167         This class forwards calls from
 168         wxVarScrollHelperBase::EstimateTotalSize
 169         to this function so derived classes can override either just the height or
 170         the width estimation, or just estimate both differently if desired in any
 171         wxHVScrolledWindow derived class.
 172         Please note that this function will not be called if @c EstimateTotalSize()
 173         is overridden in your derived class.
 174     */
 175     virtual wxCoord EstimateTotalHeight() const;
 176
 177     /**
 178         Returns the number of rows the target window contains.
 179
 180         @see SetRowCount()
 181     */
 182     size_t GetRowCount() const;
 183
 184     /**
 185         Returns the index of the first visible row based on the scroll position.
 186     */
 187     size_t GetVisibleRowsBegin() const;
 188
 189     /**
 190         Returns the index of the last visible row based on the scroll position. This
 191         includes the last row even if it is only partially visible.
 192     */
 193     size_t GetVisibleRowsEnd() const;
 194
 195     /**
 196         Returns @true if the given row is currently visible (even if only
 197         partially visible) or @false otherwise.
 198     */
 199     bool IsRowVisible(size_t row) const;
 200
 201     /**
 202         This function must be overridden in the derived class, and should return the
 203         height of the given row in pixels.
 204     */
 205     virtual wxCoord OnGetRowHeight(size_t row) const;
 206
 207     /**
 208         This function doesn't have to be overridden but it may be useful to do so if
 209         calculating the rows' sizes is a relatively expensive operation as it gives
 210         your code a chance to calculate several of them at once and cache the result
 211         if necessary.
 212         @c OnGetRowsHeightHint() is normally called just before
 213         OnGetRowHeight() but you
 214         shouldn't rely on the latter being called for all rows in the interval
 215         specified here. It is also possible that OnGetRowHeight() will be called for
 216         units outside of this interval, so this is really just a hint, not a promise.
 217         Finally, note that rowMin is inclusive, while rowMax is exclusive.
 218     */
 219     virtual void OnGetRowsHeightHint(size_t rowMin, size_t rowMax) const;
 220
 221     /**
 222         Triggers a refresh for just the given row's area of the window if it's visible.
 223     */
 224     virtual void RefreshRow(size_t row);
 225
 226     /**
 227         Triggers a refresh for the area between the specified range of rows given
 228         (inclusively).
 229     */
 230     virtual void RefreshRows(size_t from, size_t to);
 231
 232     /**
 233         Scroll by the specified number of pages which may be positive (to scroll down)
 234         or negative (to scroll up).
 235     */
 236     virtual bool ScrollRowPages(int pages);
 237
 238     /**
 239         Scroll by the specified number of rows which may be positive (to scroll down)
 240         or negative (to scroll up).
 241         Returns @true if the window was scrolled, @false otherwise (for
 242         example, if we're trying to scroll down but we are already showing the last
 243         row).
 244     */
 245     virtual bool ScrollRows(int rows);
 246
 247     /**
 248         Scroll to the specified row. It will become the first visible row in the window.
 249         Returns @true if we scrolled the window, @false if nothing was done.
 250     */
 251     bool ScrollToRow(size_t row);
 252
 253     /**
 254         Set the number of rows the window contains. The derived class must provide the
 255         heights for all rows with indices up to the one given here in it's
 256         OnGetRowHeight() implementation.
 257     */
 258     void SetRowCount(size_t rowCount);
 259 };
 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     @see wxHScrolledWindow, wxHVScrolledWindow, wxVScrolledWindow
 283 */
 284 class wxVarScrollHelperBase
 285 {
 286 public:
 287     /**
 288         Constructor taking the target window to be scrolled by this helper class.
 289         This will attach scroll event handlers to the target window to catch and
 290         handle scroll events appropriately.
 291     */
 292     wxVarScrollHelperBase(wxWindow* winToScroll);
 293
 294     /**
 295         Virtual destructor for detaching scroll event handlers attached with this
 296         helper class.
 297     */
 298     ~wxVarScrollHelperBase();
 299
 300     /**
 301         Translates the logical coordinate given to the current device coordinate.
 302         For example, if the window is scrolled 10 units and each scroll unit
 303         represents 10 device units (which may not be the case since this class allows
 304         for variable scroll unit sizes), a call to this function with a coordinate of
 305         15 will return -85.
 306
 307         @see CalcUnscrolledPosition()
 308     */
 309     int CalcScrolledPosition(int coord) const;
 310
 311     /**
 312         Translates the device coordinate given to the corresponding logical
 313         coordinate. For example, if the window is scrolled 10 units and each scroll
 314         unit represents 10 device units (which may not be the case since this class
 315         allows for variable scroll unit sizes), a call to this function with a
 316         coordinate of 15 will return 115.
 317
 318         @see CalcScrolledPosition()
 319     */
 320     int CalcUnscrolledPosition(int coord) const;
 321
 322     /**
 323         With physical scrolling on (when this is @true), the device origin is
 324         changed properly when a wxPaintDC is prepared,
 325         children are actually moved and laid out properly, and the contents of the
 326         window (pixels) are actually moved. When this is @false, you are
 327         responsible for repainting any invalidated areas of the window yourself to
 328         account for the new scroll position.
 329     */
 330     void EnablePhysicalScrolling(bool scrolling = true);
 331
 332     /**
 333         When the number of scroll units change, we try to estimate the total size of
 334         all units when the full window size is needed (i.e. to calculate the scrollbar
 335         thumb size). This is a rather expensive operation in terms of unit access, so
 336         if the user code may estimate the average size better or faster than we do, it
 337         should override this function to implement its own logic. This function should
 338         return the best guess for the total virtual window size.
 339         Note that although returning a totally wrong value would still work, it risks
 340         resulting in very strange scrollbar behaviour so this function should really
 341         try to make the best guess possible.
 342     */
 343     virtual wxCoord EstimateTotalSize() const;
 344
 345     /**
 346         This function needs to be overridden in the in the derived class to return the
 347         window size with respect to the opposing orientation. If this is a vertical
 348         scrolled window, it should return the height.
 349
 350         @see GetOrientationTargetSize()
 351     */
 352     virtual int GetNonOrientationTargetSize() const;
 353
 354     /**
 355         This function need to be overridden to return the orientation that this helper
 356         is working with, either @c wxHORIZONTAL or @c wxVERTICAL.
 357     */
 358     virtual wxOrientation GetOrientation() const;
 359
 360     /**
 361         This function needs to be overridden in the in the derived class to return the
 362         window size with respect to the orientation this helper is working with. If
 363         this is a vertical scrolled window, it should return the width.
 364
 365         @see GetNonOrientationTargetSize()
 366     */
 367     virtual int GetOrientationTargetSize() const;
 368
 369     /**
 370         This function will return the target window this helper class is currently
 371         scrolling.
 372
 373         @see SetTargetWindow()
 374     */
 375     wxWindow* GetTargetWindow() const;
 376
 377     /**
 378         Returns the index of the first visible unit based on the scroll position.
 379     */
 380     size_t GetVisibleBegin() const;
 381
 382     /**
 383         Returns the index of the last visible unit based on the scroll position. This
 384         includes the last unit even if it is only partially visible.
 385     */
 386     size_t GetVisibleEnd() const;
 387
 388     /**
 389         Returns @true if the given scroll unit is currently visible (even if only
 390         partially visible) or @false otherwise.
 391     */
 392     bool IsVisible(size_t unit) const;
 393
 394     /**
 395         This function must be overridden in the derived class, and should return the
 396         size of the given unit in pixels.
 397     */
 398     virtual wxCoord OnGetUnitSize(size_t unit) const;
 399
 400     /**
 401         This function doesn't have to be overridden but it may be useful to do so if
 402         calculating the units' sizes is a relatively expensive operation as it gives
 403         your code a chance to calculate several of them at once and cache the result
 404         if necessary.
 405         @c OnGetUnitsSizeHint() is normally called just before
 406         OnGetUnitSize() but you
 407         shouldn't rely on the latter being called for all units in the interval
 408         specified here. It is also possible that OnGetUnitSize() will be called for
 409         units outside of this interval, so this is really just a hint, not a promise.
 410         Finally, note that unitMin is inclusive, while unitMax is exclusive.
 411     */
 412     virtual void OnGetUnitsSizeHint(size_t unitMin, size_t unitMax) const;
 413
 414     /**
 415         Recalculate all parameters and repaint all units.
 416     */
 417     virtual void RefreshAll();
 418
 419     /**
 420         Normally the window will scroll itself, but in some rare occasions you might
 421         want it to scroll (part of) another window (e.g. a child of it in order to
 422         scroll only a portion the area between the scrollbars like a spreadsheet where
 423         only the cell area will move).
 424
 425         @see GetTargetWindow()
 426     */
 427     void SetTargetWindow(wxWindow* target);
 428
 429     /**
 430         Update the thumb size shown by the scrollbar.
 431     */
 432     virtual void UpdateScrollbar();
 433
 434     /**
 435         Returns the virtual scroll unit under the device unit given accounting for
 436         scroll position or @c wxNOT_FOUND if none (i.e. if it is below the last
 437         item).
 438     */
 439     int VirtualHitTest(wxCoord coord) const;
 440 };
 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     @see wxHScrolledWindow, wxHVScrolledWindow
 476 */
 477 class wxVScrolledWindow : public wxPanel
 478 {
 479 public:
 480     //@{
 481     /**
 482         This is the normal constructor, no need to call @c Create() after using this
 483         one.
 484         Note that @c wxVSCROLL is always automatically added to our style, there is
 485         no need to specify it explicitly.
 486
 487         @param parent
 488             The parent window, must not be @NULL
 489         @param id
 490             The identifier of this window, wxID_ANY by default
 491         @param pos
 492             The initial window position
 493         @param size
 494             The initial window size
 495         @param style
 496             The window style. There are no special style bits defined for
 497             this class.
 498         @param name
 499             The name for this window; usually not used
 500     */
 501     wxVScrolledWindow();
 502     wxVScrolledWindow(wxWindow* parent, wxWindowID id = wxID_ANY,
 503                       const wxPoint& pos = wxDefaultPosition,
 504                       const wxSize& size = wxDefaultSize,
 505                       long style = 0,
 506                       const wxString& name = wxPanelNameStr);
 507     //@}
 508
 509     /**
 510         Same as the @ref wxvscrolledwindow() "non-default constuctor"
 511         but returns status code: @true if ok, @false if the window couldn't
 512         be created.
 513         Just as with the constructor above, the @c wxVSCROLL style is always used,
 514         there is no need to specify it explicitly.
 515     */
 516     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
 517                 const wxPoint& pos = wxDefaultPosition,
 518                 const wxSize& size = wxDefaultSize,
 519                 long style = 0,
 520                 const wxString& name = wxPanelNameStr);
 521
 522     //@{
 523     /**
 524         The following functions provide backwards compatibility for applications
 525         originally built using wxVScrolledWindow in 2.6 or 2.8. Originally,
 526         wxVScrolledWindow referred to scrolling "lines". We now use "units" in
 527         wxVarScrollHelperBase to avoid implying any orientation (since the functions
 528         are used for both horizontal and vertical scrolling in derived classes). And
 529         in the new wxVScrolledWindow and wxHScrolledWindow classes, we refer to them
 530         as "rows" and "columns", respectively. This is to help clear some confusion
 531         in not only those classes, but also in wxHVScrolledWindow where functions
 532         are inherited from both.
 533         You are encouraged to update any existing code using these function to use
 534         the new replacements mentioned below, and avoid using these functions for
 535         any new code as they are deprecated.
 536
 537         Deprecated for wxVarVScrollHelper::SetRowCount.
 538     */
 539     size_t GetFirstVisibleLine();
 540     const size_t GetLastVisibleLine();
 541     const size_t GetLineCount();
 542     const int HitTest(wxCoord x, wxCoord y);
 543     const int HitTest(const wxPoint& pt);
 544     const virtual wxCoord OnGetLineHeight(size_t line);
 545     const virtual void OnGetLinesHint(size_t lineMin,
 546                                       size_t lineMax);
 547     const virtual void RefreshLine(size_t line);
 548     virtual void RefreshLines(size_t from, size_t to);
 549     virtual bool ScrollLines(int lines);
 550     virtual bool ScrollPages(int pages);
 551     bool ScrollToLine(size_t line);
 552     void SetLineCount(size_t count);
 553     //@}
 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     @see wxHScrolledWindow, wxVScrolledWindow
 590 */
 591 class wxHVScrolledWindow : public wxPanel
 592 {
 593 public:
 594     //@{
 595     /**
 596         This is the normal constructor, no need to call @c Create() after using this
 597         one.
 598         Note that @c wxHSCROLL and @c wxVSCROLL are always automatically added
 599         to our styles, there is no need to specify it explicitly.
 600
 601         @param parent
 602             The parent window, must not be @NULL
 603         @param id
 604             The identifier of this window, wxID_ANY by default
 605         @param pos
 606             The initial window position
 607         @param size
 608             The initial window size
 609         @param style
 610             The window style. There are no special style bits defined for
 611             this class.
 612         @param name
 613             The name for this window; usually not used
 614     */
 615     wxHVScrolledWindow();
 616     wxHVScrolledWindow(wxWindow* parent,
 617                        wxWindowID id = wxID_ANY,
 618                        const wxPoint& pos = wxDefaultPosition,
 619                        const wxSize& size = wxDefaultSize,
 620                        long style = 0,
 621                        const wxString& name = wxPanelNameStr);
 622     //@}
 623
 624     /**
 625         Same as the @ref wxhvscrolledwindow() "non-default constuctor"
 626         but returns status code: @true if ok, @false if the window couldn't
 627         be created.
 628         Just as with the constructor above, the @c wxHSCROLL and @c wxVSCROLL
 629         styles are always used, there is no need to specify it explicitly.
 630     */
 631     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
 632                 const wxPoint& pos = wxDefaultPosition,
 633                 const wxSize& size = wxDefaultSize,
 634                 long style = 0,
 635                 const wxString& name = wxPanelNameStr);
 636 };
 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     @see wxHScrolledWindow, wxHVScrolledWindow, wxVScrolledWindow
 664 */
 665 class wxVarHVScrollHelper : public wxVarVScrollHelper
 666 {
 667 public:
 668     /**
 669         Constructor taking the target window to be scrolled by this helper class.
 670         This will attach scroll event handlers to the target window to catch and
 671         handle scroll events appropriately.
 672     */
 673     wxVarHVScrollHelper(wxWindow* winToScroll);
 674
 675     /**
 676         With physical scrolling on (when this is @true), the device origin is
 677         changed properly when a wxPaintDC is prepared,
 678         children are actually moved and laid out properly, and the contents of the
 679         window (pixels) are actually moved. When this is @false, you are
 680         responsible for repainting any invalidated areas of the window yourself to
 681         account for the new scroll position.
 682
 683         @param vscrolling
 684             Specifies if physical scrolling should be turned on when scrolling
 685         vertically.
 686         @param hscrolling
 687             Specifies if physical scrolling should be turned on when scrolling
 688         horizontally.
 689     */
 690     void EnablePhysicalScrolling(bool vscrolling = true,
 691                                  bool hscrolling = true);
 692
 693     /**
 694         Returns the number of columns and rows the target window contains.
 695
 696         @see SetRowColumnCount()
 697     */
 698     wxSize GetRowColumnCount() const;
 699
 700     /**
 701         Returns the index of the first visible column and row based on the current
 702         scroll position.
 703     */
 704     wxPosition GetVisibleBegin() const;
 705
 706     /**
 707         Returns the index of the last visible column and row based on the scroll
 708         position. This includes any partially visible columns or rows.
 709     */
 710     wxPosition GetVisibleEnd() const;
 711
 712     //@{
 713     /**
 714         Returns @true if both the given row and column are currently visible
 715         (even if only partially visible) or @false otherwise.
 716     */
 717     bool IsVisible(size_t row, size_t column) const;
 718     const bool IsVisible(const wxPosition& pos) const;
 719     //@}
 720
 721     //@{
 722     /**
 723         Triggers a refresh for just the area shared between the given row and column
 724         of the window if it is visible.
 725     */
 726     virtual void RefreshRowColumn(size_t row, size_t column);
 727     virtual void RefreshRowColumn(const wxPosition& pos);
 728     //@}
 729
 730     //@{
 731     /**
 732         Triggers a refresh for the visible area shared between all given rows and
 733         columns (inclusive) of the window. If the target window for both orientations
 734         is the same, the rectangle of cells is refreshed; if the target windows
 735         differ, the entire client size opposite the orientation direction is
 736         refreshed between the specified limits.
 737     */
 738     virtual void RefreshRowsColumns(size_t fromRow, size_t toRow,
 739                                     size_t fromColumn,
 740                                     size_t toColumn);
 741     virtual void RefreshRowsColumns(const wxPosition& from,
 742                                     const wxPosition& to);
 743     //@}
 744
 745     //@{
 746     /**
 747         Scroll to the specified row and column. It will become the first visible row
 748         and column in the window. Returns @true if we scrolled the window,
 749         @false if nothing was done.
 750     */
 751     bool ScrollToRowColumn(size_t row, size_t column);
 752     bool ScrollToRowColumn(const wxPosition& pos);
 753     //@}
 754
 755     /**
 756         Set the number of rows and columns the target window will contain. The
 757         derived class must provide the sizes for all rows and columns with indices up
 758         to the ones given here in it's wxVarVScrollHelper::OnGetRowHeight
 759         and wxVarHScrollHelper::OnGetColumnWidth implementations,
 760         respectively.
 761     */
 762     void SetRowColumnCount(size_t rowCount, size_t columnCount);
 763
 764     //@{
 765     /**
 766         Returns the virtual scroll unit under the device unit given accounting for
 767         scroll position or @c wxNOT_FOUND (for the row, column, or possibly both
 768         values) if none.
 769     */
 770     wxPosition VirtualHitTest(wxCoord x, wxCoord y) const;
 771     const wxPosition  VirtualHitTest(const wxPoint& pos) const;
 772     //@}
 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     @see wxHVScrolledWindow, wxVScrolledWindow
 808 */
 809 class wxHScrolledWindow : public wxPanel
 810 {
 811 public:
 812     //@{
 813     /**
 814         This is the normal constructor, no need to call @c Create() after using this
 815         one.
 816         Note that @c wxHSCROLL is always automatically added to our style, there is
 817         no need to specify it explicitly.
 818
 819         @param parent
 820             The parent window, must not be @NULL
 821         @param id
 822             The identifier of this window, wxID_ANY by default
 823         @param pos
 824             The initial window position
 825         @param size
 826             The initial window size
 827         @param style
 828             The window style. There are no special style bits defined for
 829             this class.
 830         @param name
 831             The name for this window; usually not used
 832     */
 833     wxHScrolledWindow();
 834     wxHScrolledWindow(wxWindow* parent, wxWindowID id = wxID_ANY,
 835                       const wxPoint& pos = wxDefaultPosition,
 836                       const wxSize& size = wxDefaultSize,
 837                       long style = 0,
 838                       const wxString& name = wxPanelNameStr);
 839     //@}
 840
 841     /**
 842         Same as the @ref wxhscrolledwindow() "non-default constuctor"
 843         but returns status code: @true if ok, @false if the window couldn't
 844         be created.
 845         Just as with the constructor above, the @c wxHSCROLL style is always used,
 846         there is no need to specify it explicitly.
 847     */
 848     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
 849                 const wxPoint& pos = wxDefaultPosition,
 850                 const wxSize& size = wxDefaultSize,
 851                 long style = 0,
 852                 const wxString& name = wxPanelNameStr);
 853 };
 854