interface/wx/scrolwin.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        scrolwin.h
   3 // Purpose:     interface of wxScrolled template
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     Possible values for the second argument of wxScrolled::ShowScrollbars().
  11  */
  12 enum wxScrollbarVisibility
  13 {
  14     wxSHOW_SB_NEVER = -1,   ///< Never show the scrollbar at all.
  15     wxSHOW_SB_DEFAULT,      ///< Show scrollbar only if it is needed.
  16     wxSHOW_SB_ALWAYS        ///< Always show scrollbar, even if not needed.
  17 };
  18
  19 /**
  20
  21     The wxScrolled class manages scrolling for its client area, transforming
  22     the coordinates according to the scrollbar positions, and setting the
  23     scroll positions, thumb sizes and ranges according to the area in view.
  24
  25     There are two commonly used (but not the only possible!) specializations of
  26     this class:
  27
  28     - ::wxScrolledWindow, aka wxScrolled<wxPanel>, is equivalent to
  29       ::wxScrolledWindow from earlier versions. Derived from wxPanel, it shares
  30       wxPanel's behaviour with regard to TAB traversal and focus handling. Use
  31       this if the scrolled window will have child controls.
  32
  33     - ::wxScrolledCanvas, aka wxScrolled<wxWindow>, derives from wxWindow and
  34       so doesn't handle children specially. This is suitable e.g. for
  35       implementing scrollable controls such as tree or list controls.
  36
  37     Starting from version 2.4 of wxWidgets, there are several ways to use a
  38     ::wxScrolledWindow (and now wxScrolled). In particular, there are
  39     three ways to set the size of the scrolling area:
  40
  41     One way is to set the scrollbars directly using a call to SetScrollbars().
  42     This is the way it used to be in any previous version of wxWidgets and it
  43     will be kept for backwards compatibility.
  44
  45     An additional method of manual control, which requires a little less
  46     computation of your own, is to set the total size of the scrolling area by
  47     calling either wxWindow::SetVirtualSize(), or wxWindow::FitInside(), and
  48     setting the scrolling increments for it by calling SetScrollRate().
  49     Scrolling in some orientation is enabled by setting a non-zero increment
  50     for it.
  51
  52     The most automatic and newest way is to simply let sizers determine the
  53     scrolling area. This is now the default when you set an interior sizer into
  54     a wxScrolled with wxWindow::SetSizer().  The scrolling area will be
  55     set to the size requested by the sizer and the scrollbars will be assigned
  56     for each orientation according to the need for them and the scrolling
  57     increment set by SetScrollRate().  As above, scrolling is only enabled in
  58     orientations with a non-zero increment.  You can influence the minimum size
  59     of the scrolled area controlled by a sizer by calling
  60     wxWindow::SetVirtualSizeHints(). (Calling SetScrollbars() has analogous
  61     effects in wxWidgets 2.4 -- in later versions it may not continue to
  62     override the sizer.)
  63
  64     Note that if maximum size hints are still supported by
  65     wxWindow::SetVirtualSizeHints(), use them at your own dire risk. They may
  66     or may not have been removed for 2.4, but it really only makes sense to set
  67     minimum size hints here.  We should probably replace
  68     wxWindow::SetVirtualSizeHints() with wxWindow::SetMinVirtualSize() or
  69     similar and remove it entirely in future.
  70
  71     @todo review docs for this class replacing SetVirtualSizeHints() with
  72           SetMinClientSize().
  73
  74     As with all windows, an application can draw onto a wxScrolled using a
  75     @ref overview_dc "device context".
  76
  77     You have the option of handling the OnPaint handler or overriding the
  78     wxScrolled::OnDraw() function, which is passed a pre-scrolled device
  79     context (prepared by wxScrolled::DoPrepareDC()).
  80
  81     If you don't wish to calculate your own scrolling, you must call
  82     DoPrepareDC() when not drawing from within OnDraw(), to set the device
  83     origin for the device context according to the current scroll position.
  84
  85     A wxScrolled will normally scroll itself and therefore its child windows
  86     as well. It might however be desired to scroll a different window than
  87     itself: e.g. when designing a spreadsheet, you will normally only have to
  88     scroll the (usually white) cell area, whereas the (usually grey) label area
  89     will scroll very differently. For this special purpose, you can call
  90     SetTargetWindow() which means that pressing the scrollbars will scroll a
  91     different window.
  92
  93     Note that the underlying system knows nothing about scrolling coordinates,
  94     so that all system functions (mouse events, expose events, refresh calls
  95     etc) as well as the position of subwindows are relative to the "physical"
  96     origin of the scrolled window. If the user insert a child window at
  97     position (10,10) and scrolls the window down 100 pixels (moving the child
  98     window out of the visible area), the child window will report a position
  99     of (10,-90).
 100
 101     @beginStyleTable
 102     @style{wxRETAINED}
 103            Uses a backing pixmap to speed refreshes. Motif only.
 104     @endStyleTable
 105
 106
 107     @beginEventEmissionTable{wxScrollWinEvent}
 108     @event{EVT_SCROLLWIN(func)}
 109         Process all scroll events.
 110     @event{EVT_SCROLLWIN_TOP(func)}
 111         Process @c wxEVT_SCROLLWIN_TOP scroll-to-top events.
 112     @event{EVT_SCROLLWIN_BOTTOM(func)}
 113         Process @c wxEVT_SCROLLWIN_BOTTOM scroll-to-bottom events.
 114     @event{EVT_SCROLLWIN_LINEUP(func)}
 115         Process @c wxEVT_SCROLLWIN_LINEUP line up events.
 116     @event{EVT_SCROLLWIN_LINEDOWN(func)}
 117         Process @c wxEVT_SCROLLWIN_LINEDOWN line down events.
 118     @event{EVT_SCROLLWIN_PAGEUP(func)}
 119         Process @c wxEVT_SCROLLWIN_PAGEUP page up events.
 120     @event{EVT_SCROLLWIN_PAGEDOWN(func)}
 121         Process @c wxEVT_SCROLLWIN_PAGEDOWN page down events.
 122     @event{EVT_SCROLLWIN_THUMBTRACK(func)}
 123         Process @c wxEVT_SCROLLWIN_THUMBTRACK thumbtrack events
 124         (frequent events sent as the user drags the thumbtrack).
 125     @event{EVT_SCROLLWIN_THUMBRELEASE(func)}
 126         Process @c wxEVT_SCROLLWIN_THUMBRELEASE thumb release events.
 127     @endEventTable
 128
 129     @note
 130         Don't confuse wxScrollWinEvents generated by this class with
 131         wxScrollEvent objects generated by wxScrollBar and wxSlider.
 132
 133
 134     @remarks
 135     Use wxScrolled for applications where the user scrolls by a fixed amount,
 136     and where a 'page' can be interpreted to be the current visible portion of
 137     the window. For more sophisticated applications, use the wxScrolled
 138     implementation as a guide to build your own scroll behaviour or use
 139     wxVScrolledWindow or its variants.
 140
 141     @since The wxScrolled template exists since version 2.9.0. In older versions,
 142            only ::wxScrolledWindow (equivalent of wxScrolled<wxPanel>) was
 143            available.
 144
 145     @library{wxcore}
 146     @category{miscwnd}
 147
 148     @see wxScrollBar, wxClientDC, wxPaintDC,
 149          wxVScrolledWindow, wxHScrolledWindow, wxHVScrolledWindow,
 150 */
 151 template<class T>
 152 class wxScrolled : public T
 153 {
 154 public:
 155     /// Default constructor.
 156     wxScrolled();
 157
 158     /**
 159         Constructor.
 160
 161         @param parent
 162             Parent window.
 163         @param id
 164             Window identifier. The value @c wxID_ANY indicates a default value.
 165         @param pos
 166             Window position. If a position of ::wxDefaultPosition is specified
 167             then a default position is chosen.
 168         @param size
 169             Window size. If a size of ::wxDefaultSize is specified then the
 170             window is sized appropriately.
 171         @param style
 172             Window style. See wxScrolled.
 173         @param name
 174             Window name.
 175
 176         @remarks The window is initially created without visible scrollbars.
 177                  Call SetScrollbars() to specify how big the virtual window
 178                  size should be.
 179     */
 180     wxScrolled(wxWindow* parent, wxWindowID id = -1,
 181                const wxPoint& pos = wxDefaultPosition,
 182                const wxSize& size = wxDefaultSize,
 183                long style = wxHSCROLL | wxVSCROLL,
 184                const wxString& name = "scrolledWindow");
 185
 186     /**
 187         Translates the logical coordinates to the device ones. For example, if
 188         a window is scrolled 10 pixels to the bottom, the device coordinates of
 189         the origin are (0, 0) (as always), but the logical coordinates are (0,
 190         10) and so the call to CalcScrolledPosition(0, 10, xx, yy) will return
 191         0 in yy.
 192
 193         @beginWxPerlOnly
 194         In wxPerl this method takes two parameters and returns a
 195         2-element list (xx, yy).
 196         @endWxPerlOnly
 197
 198         @see CalcUnscrolledPosition()
 199     */
 200     void CalcScrolledPosition(int x, int y, int* xx, int* yy) const;
 201     wxPoint CalcScrolledPosition(const wxPoint& pt) const;
 202
 203     /**
 204         Translates the device coordinates to the logical ones. For example, if
 205         a window is scrolled 10 pixels to the bottom, the device coordinates of
 206         the origin are (0, 0) (as always), but the logical coordinates are (0,
 207         10) and so the call to CalcUnscrolledPosition(0, 0, xx, yy) will return
 208         10 in yy.
 209
 210         @beginWxPerlOnly
 211         In wxPerl this method takes two parameters and returns a
 212         2-element list (xx, yy).
 213         @endWxPerlOnly
 214
 215         @see CalcScrolledPosition()
 216     */
 217     void CalcUnscrolledPosition(int x, int y, int* xx, int* yy) const;
 218     wxPoint CalcUnscrolledPosition(const wxPoint& pt) const;
 219
 220     /**
 221         Creates the window for two-step construction. Derived classes
 222         should call or replace this function. See wxScrolled::wxScrolled()
 223         for details.
 224     */
 225     bool Create(wxWindow* parent, wxWindowID id = -1,
 226                 const wxPoint& pos = wxDefaultPosition,
 227                 const wxSize& size = wxDefaultSize,
 228                 long style = wxHSCROLL | wxVSCROLL,
 229                 const wxString& name = "scrolledWindow");
 230
 231     /**
 232         Disable use of keyboard keys for scrolling.
 233
 234         By default cursor movement keys (including Home, End, Page Up and Down)
 235         are used to scroll the window appropriately. If the derived class uses
 236         these keys for something else, e.g. changing the currently selected
 237         item, this function can be used to disable this behaviour as it's not
 238         only not necessary then but can actually be actively harmful if another
 239         object forwards a keyboard event corresponding to one of the above keys
 240         to us using ProcessWindowEvent() because the event will always be
 241         processed which can be undesirable.
 242
 243         @since 2.9.1
 244     */
 245     void DisableKeyboardScrolling();
 246
 247     /**
 248         Call this function to prepare the device context for drawing a scrolled
 249         image.
 250
 251         It sets the device origin according to the current scroll position.
 252         DoPrepareDC() is called automatically within the default @c wxEVT_PAINT
 253         event handler, so your OnDraw() override will be passed an already
 254         'pre-scrolled' device context. However, if you wish to draw from
 255         outside of OnDraw() (e.g. from your own @c wxEVT_PAINT handler), you
 256         must call this function yourself.
 257
 258         For example:
 259         @code
 260         void MyWindow::OnEvent(wxMouseEvent& event)
 261         {
 262           wxClientDC dc(this);
 263           DoPrepareDC(dc);
 264
 265           dc.SetPen(*wxBLACK_PEN);
 266           float x, y;
 267           event.Position(&x, &y);
 268           if (xpos > -1 && ypos > -1 && event.Dragging())
 269           {
 270             dc.DrawLine(xpos, ypos, x, y);
 271           }
 272           xpos = x;
 273           ypos = y;
 274         }
 275         @endcode
 276
 277         Notice that the function sets the origin by moving it relatively to the
 278         current origin position, so you shouldn't change the origin before
 279         calling DoPrepareDC() or, if you do, reset it to (0, 0) later. If you
 280         call DoPrepareDC() immediately after device context creation, as in the
 281         example above, this problem doesn't arise, of course, so it is
 282         customary to do it like this.
 283     */
 284     void DoPrepareDC(wxDC& dc);
 285
 286     /**
 287         Enable or disable physical scrolling in the given direction. Physical
 288         scrolling is the physical transfer of bits up or down the
 289         screen when a scroll event occurs. If the application scrolls by a
 290         variable amount (e.g. if there are different font sizes) then physical
 291         scrolling will not work, and you should switch it off. Note that you
 292         will have to reposition child windows yourself, if physical scrolling
 293         is disabled.
 294
 295         @param xScrolling
 296             If @true, enables physical scrolling in the x direction.
 297         @param yScrolling
 298             If @true, enables physical scrolling in the y direction.
 299
 300         @remarks Physical scrolling may not be available on all platforms. Where
 301                  it is available, it is enabled by default.
 302     */
 303     void EnableScrolling(bool xScrolling, bool yScrolling);
 304
 305     /**
 306         Set the scrollbar visibility.
 307
 308         By default the scrollbar in the corresponding direction is only shown
 309         if it is needed, i.e. if the virtual size of the scrolled window in
 310         this direction is greater than the current physical window size. Using
 311         this function the scrollbar visibility can be changed to be:
 312             - wxSHOW_SB_ALWAYS: To always show the scrollbar, even if it is
 313                 not needed currently (wxALWAYS_SHOW_SB style can be used during
 314                 the window creation to achieve the same effect but it applies
 315                 in both directions).
 316             - wxSHOW_SB_NEVER: To never show the scrollbar at all. In this case
 317                 the program should presumably provide some other way for the
 318                 user to scroll the window.
 319             - wxSHOW_SB_DEFAULT: To restore the default behaviour described
 320                 above.
 321
 322         @param horz
 323             The desired visibility for the horizontal scrollbar.
 324         @param vert
 325             The desired visibility for the vertical scrollbar.
 326
 327         @since 2.9.0
 328      */
 329     void ShowScrollbars(wxScrollbarVisibility horz, wxScrollbarVisibility vert);
 330
 331     /**
 332         Get the number of pixels per scroll unit (line), in each direction, as
 333         set by SetScrollbars(). A value of zero indicates no scrolling in that
 334         direction.
 335
 336         @param xUnit
 337             Receives the number of pixels per horizontal unit.
 338         @param yUnit
 339             Receives the number of pixels per vertical unit.
 340
 341         @beginWxPerlOnly
 342         In wxPerl this method takes no parameters and returns a
 343         2-element list (xUnit, yUnit).
 344         @endWxPerlOnly
 345
 346         @see SetScrollbars(), GetVirtualSize()
 347     */
 348     void GetScrollPixelsPerUnit(int* xUnit, int* yUnit) const;
 349
 350     /**
 351         Get the position at which the visible portion of the window starts.
 352
 353         @param x
 354             Receives the first visible x position in scroll units.
 355         @param y
 356             Receives the first visible y position in scroll units.
 357
 358         @remarks
 359             If either of the scrollbars is not at the home position, @a x
 360             and/or @a y will be greater than zero.
 361             Combined with wxWindow::GetClientSize(), the application can use this
 362             function to efficiently redraw only the visible portion of the window.
 363             The positions are in logical scroll units, not pixels, so to convert
 364             to pixels you will have to multiply by the number of pixels per scroll
 365             increment.
 366
 367         @beginWxPerlOnly
 368         In wxPerl this method takes no parameters and returns a
 369         2-element list (x, y).
 370         @endWxPerlOnly
 371
 372         @see SetScrollbars(), Scroll()
 373     */
 374     void GetViewStart(int* x, int* y) const;
 375
 376     /**
 377         This is a simple overload of GetViewStart(int*,int*); see that function
 378         for more info.
 379     */
 380     wxPoint GetViewStart() const;
 381
 382     /**
 383         Gets the size in device units of the scrollable window area (as
 384         opposed to the client size, which is the area of the window currently
 385         visible).
 386
 387         @param x
 388             Receives the length of the scrollable window, in pixels.
 389         @param y
 390             Receives the height of the scrollable window, in pixels.
 391
 392         @remarks Use wxDC::DeviceToLogicalX() and wxDC::DeviceToLogicalY() to
 393                  translate these units to logical units.
 394
 395         @beginWxPerlOnly
 396         In wxPerl this method takes no parameters and returns a
 397         2-element list (xUnit, yUnit).
 398         @endWxPerlOnly
 399
 400         @see SetScrollbars(), GetScrollPixelsPerUnit()
 401     */
 402     void GetVirtualSize(int* x, int* y) const;
 403
 404     /**
 405         Motif only: @true if the window has a backing bitmap.
 406     */
 407     bool IsRetained() const;
 408
 409     /**
 410         Called by the default paint event handler to allow the application to
 411         define painting behaviour without having to worry about calling
 412         DoPrepareDC().
 413
 414         Instead of overriding this function you may also just process the paint
 415         event in the derived class as usual, but then you will have to call
 416         DoPrepareDC() yourself.
 417     */
 418     virtual void OnDraw(wxDC& dc);
 419
 420     /**
 421         This function is for backwards compatibility only and simply calls
 422         DoPrepareDC() now. Notice that it is not called by the default paint
 423         event handle (DoPrepareDC() is), so overriding this method in your
 424         derived class is useless.
 425     */
 426     void PrepareDC(wxDC& dc);
 427
 428     /**
 429         Scrolls a window so the view start is at the given point.
 430
 431         @param x
 432             The x position to scroll to, in scroll units.
 433         @param y
 434             The y position to scroll to, in scroll units.
 435
 436         @remarks The positions are in scroll units, not pixels, so to convert to
 437                  pixels you will have to multiply by the number of
 438                  pixels per scroll increment. If either parameter is
 439                  ::wxDefaultCoord (-1), that position will be ignored (no change
 440                  in that direction).
 441
 442         @see SetScrollbars(), GetScrollPixelsPerUnit()
 443     */
 444     void Scroll(int x, int y);
 445
 446     /**
 447         This is an overload of Scroll(int,int); see that function for more info.
 448     */
 449     void Scroll(const wxPoint& pt);
 450
 451     /**
 452         Set the horizontal and vertical scrolling increment only. See the
 453         pixelsPerUnit parameter in SetScrollbars().
 454     */
 455     void SetScrollRate(int xstep, int ystep);
 456
 457     /**
 458         Sets up vertical and/or horizontal scrollbars.
 459
 460         The first pair of parameters give the number of pixels per 'scroll
 461         step', i.e. amount moved when the up or down scroll arrows are pressed.
 462         The second pair gives the length of scrollbar in scroll steps, which
 463         sets the size of the virtual window.
 464
 465         @a xPos and @a yPos optionally specify a position to scroll to
 466         immediately.
 467
 468         For example, the following gives a window horizontal and vertical
 469         scrollbars with 20 pixels per scroll step, and a size of 50 steps (1000
 470         pixels) in each direction:
 471         @code
 472         window->SetScrollbars(20, 20, 50, 50);
 473         @endcode
 474
 475         wxScrolled manages the page size itself, using the current client
 476         window size as the page size.
 477
 478         Note that for more sophisticated scrolling applications, for example
 479         where scroll steps may be variable according to the position in the
 480         document, it will be necessary to derive a new class from wxWindow,
 481         overriding OnSize() and adjusting the scrollbars appropriately.
 482
 483         @param pixelsPerUnitX
 484             Pixels per scroll unit in the horizontal direction.
 485         @param pixelsPerUnitY
 486             Pixels per scroll unit in the vertical direction.
 487         @param noUnitsX
 488             Number of units in the horizontal direction.
 489         @param noUnitsY
 490             Number of units in the vertical direction.
 491         @param xPos
 492             Position to initialize the scrollbars in the horizontal direction,
 493             in scroll units.
 494         @param yPos
 495             Position to initialize the scrollbars in the vertical direction, in
 496             scroll units.
 497         @param noRefresh
 498             Will not refresh window if @true.
 499
 500         @see wxWindow::SetVirtualSize()
 501     */
 502     void SetScrollbars(int pixelsPerUnitX, int pixelsPerUnitY,
 503                        int noUnitsX,
 504                        int noUnitsY,
 505                        int xPos = 0,
 506                        int yPos = 0,
 507                        bool noRefresh = false);
 508
 509     /**
 510         Call this function to tell wxScrolled to perform the actual scrolling
 511         on a different window (and not on itself).
 512
 513         This method is useful when only a part of the window should be
 514         scrolled. A typical example is a control consisting of a fixed header
 515         and the scrollable contents window: the scrollbars are attached to the
 516         main window itself, hence it, and not the contents window must be
 517         derived from wxScrolled, but only the contents window scrolls when the
 518         scrollbars are used. To implement such setup, you need to call this
 519         method with the contents window as argument.
 520
 521         Notice that if this method is used, GetSizeAvailableForScrollTarget()
 522         method must be overridden.
 523     */
 524     void SetTargetWindow(wxWindow *window);
 525     wxWindow *GetTargetWindow() const;
 526
 527
 528     void SetTargetRect(const wxRect& rect);
 529     wxRect GetTargetRect() const;
 530
 531     int GetScrollPageSize(int orient) const;
 532     void SetScrollPageSize(int orient, int pageSize);
 533     int GetScrollLines( int orient ) const;
 534     void SetScale(double xs, double ys);
 535     double GetScaleX() const;
 536     double GetScaleY() const;
 537
 538     virtual void AdjustScrollbars();
 539
 540     /**
 541        Are we generating the autoscroll events?
 542      */
 543     bool IsAutoScrolling() const;
 544
 545     /**
 546        Stop generating the scroll events when mouse is held outside the
 547        window.
 548      */
 549     void StopAutoScrolling();
 550
 551     /**
 552        This method can be overridden in a derived class to forbid sending the
 553        auto scroll events - note that unlike StopAutoScrolling() it doesn't
 554        stop the timer, so it will be called repeatedly and will typically
 555        return different values depending on the current mouse position
 556
 557        The base class version just returns true.
 558     */
 559     virtual bool SendAutoScrollEvents(wxScrollWinEvent& event) const;
 560
 561
 562 protected:
 563     /**
 564         Function which must be overridden to implement the size available for
 565         the scroll target for the given size of the main window.
 566
 567         This method must be overridden if SetTargetWindow() is used (it is
 568         never called otherwise). The implementation should decrease the @a size
 569         to account for the size of the non-scrollable parts of the main window
 570         and return only the size available for the scrollable window itself.
 571         E.g. in the example given in SetTargetWindow() documentation the
 572         function would subtract the height of the header window from the
 573         vertical component of @a size.
 574      */
 575     virtual wxSize GetSizeAvailableForScrollTarget(const wxSize& size);
 576 };
 577
 578
 579 /**
 580     Scrolled window derived from wxPanel.
 581
 582     See wxScrolled for a detailed description.
 583
 584     @note Note that because this class derives from wxPanel, it shares its
 585           behaviour with regard to TAB traversal and focus handling (in
 586           particular, it forwards focus to its children). If you don't want
 587           this behaviour, use ::wxScrolledCanvas instead.
 588
 589     @note ::wxScrolledWindow is an alias for wxScrolled<wxPanel> since version
 590           2.9.0. In older versions, it was a standalone class.
 591
 592     @library{wxcore}
 593     @category{miscwnd}
 594
 595     @see wxScrolled, ::wxScrolledCanvas
 596 */
 597 typedef wxScrolled<wxPanel> wxScrolledWindow;
 598
 599 /**
 600     Alias for wxScrolled<wxWindow>. Scrolled window that doesn't have children
 601     and so doesn't need or want special handling of TAB traversal.
 602
 603     @since 2.9.0
 604
 605     @library{wxcore}
 606     @category{miscwnd}
 607
 608     @see wxScrolled, ::wxScrolledWindow
 609 */
 610 typedef wxScrolled<wxWindow> wxScrolledCanvas;