include/wx/scrolwin.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/scrolwin.h
   3 // Purpose:     wxScrolledWindow, wxScrolledControl and wxScrollHelper
   4 // Author:      Vadim Zeitlin
   5 // Modified by:
   6 // Created:     30.08.00
   7 // Copyright:   (c) 2000 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
   8 // Licence:     wxWindows licence
   9 /////////////////////////////////////////////////////////////////////////////
  10
  11 #ifndef _WX_SCROLWIN_H_BASE_
  12 #define _WX_SCROLWIN_H_BASE_
  13
  14 #include "wx/panel.h"
  15
  16 class WXDLLIMPEXP_FWD_CORE wxScrollHelperEvtHandler;
  17 class WXDLLIMPEXP_FWD_BASE wxTimer;
  18
  19 // default scrolled window style: scroll in both directions
  20 #define wxScrolledWindowStyle (wxHSCROLL | wxVSCROLL)
  21
  22 // values for the second argument of wxScrollHelper::ShowScrollbars()
  23 enum wxScrollbarVisibility
  24 {
  25     wxSHOW_SB_NEVER = -1,   // never show the scrollbar at all
  26     wxSHOW_SB_DEFAULT,      // show scrollbar only if it is needed
  27     wxSHOW_SB_ALWAYS        // always show scrollbar, even if not needed
  28 };
  29
  30 // ----------------------------------------------------------------------------
  31 // The hierarchy of scrolling classes is a bit complicated because we want to
  32 // put as much functionality as possible in a mix-in class not deriving from
  33 // wxWindow so that other classes could derive from the same base class on all
  34 // platforms irrespectively of whether they are native controls (and hence
  35 // don't use our scrolling) or not.
  36 //
  37 // So we have
  38 //
  39 //                          wxAnyScrollHelperBase
  40 //                                   |
  41 //                                   |
  42 //                                  \|/
  43 //                           wxScrollHelperBase
  44 //                                   |
  45 //                                   |
  46 //                                  \|/
  47 //      wxWindow               wxScrollHelper
  48 //       |  \                   /        /
  49 //       |   \                 /        /
  50 //       |    _|             |_        /
  51 //       |     wxScrolledWindow       /
  52 //       |                           /
  53 //      \|/                         /
  54 //   wxControl                     /
  55 //         \                      /
  56 //          \                    /
  57 //           _|                |_
  58 //            wxScrolledControl
  59 //
  60 // ----------------------------------------------------------------------------
  61
  62 // This class allows reusing some of wxScrollHelperBase functionality in
  63 // wxVarScrollHelperBase in wx/vscroll.h without duplicating its code.
  64 class WXDLLIMPEXP_CORE wxAnyScrollHelperBase
  65 {
  66 public:
  67     wxEXPLICIT wxAnyScrollHelperBase(wxWindow* win);
  68
  69     // Disable use of keyboard keys for scrolling. By default cursor movement
  70     // keys (including Home, End, Page Up and Down) are used to scroll the
  71     // window appropriately. If the derived class uses these keys for something
  72     // else, e.g. changing the currently selected item, this function can be
  73     // used to disable this behaviour as it's not only not necessary then but
  74     // can actually be actively harmful if another object forwards a keyboard
  75     // event corresponding to one of the above keys to us using
  76     // ProcessWindowEvent() because the event will always be processed which
  77     // can be undesirable.
  78     void DisableKeyboardScrolling() { m_kbdScrollingEnabled = false; }
  79
  80     // Override this function to draw the graphic (or just process EVT_PAINT)
  81     virtual void OnDraw(wxDC& WXUNUSED(dc)) { }
  82
  83     // change the DC origin according to the scroll position.
  84     virtual void DoPrepareDC(wxDC& dc) = 0;
  85
  86     // Simple accessor for the window that is really being scrolled.
  87     wxWindow *GetTargetWindow() const { return m_targetWindow; }
  88
  89
  90     // The methods called from the window event handlers.
  91     void HandleOnChar(wxKeyEvent& event);
  92     void HandleOnPaint(wxPaintEvent& event);
  93
  94 protected:
  95     // the window that receives the scroll events and the window to actually
  96     // scroll, respectively
  97     wxWindow *m_win,
  98              *m_targetWindow;
  99
 100     // whether cursor keys should scroll the window
 101     bool m_kbdScrollingEnabled;
 102 };
 103
 104 // This is the class containing the guts of (uniform) scrolling logic.
 105 class WXDLLIMPEXP_CORE wxScrollHelperBase : public wxAnyScrollHelperBase
 106 {
 107 public:
 108     // ctor must be given the associated window
 109     wxScrollHelperBase(wxWindow *winToScroll);
 110     virtual ~wxScrollHelperBase();
 111
 112     // configure the scrolling
 113     virtual void SetScrollbars(int pixelsPerUnitX, int pixelsPerUnitY,
 114                                int noUnitsX, int noUnitsY,
 115                                int xPos = 0, int yPos = 0,
 116                                bool noRefresh = false );
 117
 118     // scroll to the given (in logical coords) position
 119     //
 120     // notice that for backwards compatibility reasons Scroll() is virtual as
 121     // the existing code could override it but new code should override
 122     // DoScroll() instead
 123     virtual void Scroll(int x, int y) { DoScroll(x, y); }
 124     virtual void Scroll(const wxPoint& pt) { DoScroll(pt.x, pt.y); }
 125
 126     // get/set the page size for this orientation (wxVERTICAL/wxHORIZONTAL)
 127     int GetScrollPageSize(int orient) const;
 128     void SetScrollPageSize(int orient, int pageSize);
 129
 130     // get the number of lines the window can scroll,
 131     // returns 0 if no scrollbars are there.
 132     int GetScrollLines( int orient ) const;
 133
 134     // Set the x, y scrolling increments.
 135     void SetScrollRate( int xstep, int ystep );
 136
 137     // get the size of one logical unit in physical ones
 138     void GetScrollPixelsPerUnit(int *pixelsPerUnitX, int *pixelsPerUnitY) const;
 139
 140     // Set scrollbar visibility: it is possible to show scrollbar only if it is
 141     // needed (i.e. if our virtual size is greater than the current size of the
 142     // associated window), always (as wxALWAYS_SHOW_SB style does) or never (in
 143     // which case you should provide some other way to scroll the window as the
 144     // user wouldn't be able to do it at all)
 145     void ShowScrollbars(wxScrollbarVisibility horz, wxScrollbarVisibility vert)
 146     {
 147         DoShowScrollbars(horz, vert);
 148     }
 149
 150     // Test whether the specified scrollbar is shown.
 151     virtual bool IsScrollbarShown(int orient) const = 0;
 152
 153     // Enable/disable Windows scrolling in either direction. If true, wxWidgets
 154     // scrolls the canvas and only a bit of the canvas is invalidated; no
 155     // Clear() is necessary. If false, the whole canvas is invalidated and a
 156     // Clear() is necessary. Disable for when the scroll increment is used to
 157     // actually scroll a non-constant distance
 158     //
 159     // Notice that calling this method with a false argument doesn't disable
 160     // scrolling the window in this direction, it just changes the mechanism by
 161     // which it is implemented to not use wxWindow::ScrollWindow().
 162     virtual void EnableScrolling(bool x_scrolling, bool y_scrolling);
 163
 164     // Get the view start
 165     void GetViewStart(int *x, int *y) const { DoGetViewStart(x, y); }
 166
 167     wxPoint GetViewStart() const
 168     {
 169         wxPoint pt;
 170         DoGetViewStart(&pt.x, &pt.y);
 171         return pt;
 172     }
 173
 174     // Set the scale factor, used in PrepareDC
 175     void SetScale(double xs, double ys) { m_scaleX = xs; m_scaleY = ys; }
 176     double GetScaleX() const { return m_scaleX; }
 177     double GetScaleY() const { return m_scaleY; }
 178
 179     // translate between scrolled and unscrolled coordinates
 180     void CalcScrolledPosition(int x, int y, int *xx, int *yy) const
 181         {  DoCalcScrolledPosition(x, y, xx, yy); }
 182     wxPoint CalcScrolledPosition(const wxPoint& pt) const
 183     {
 184         wxPoint p2;
 185         DoCalcScrolledPosition(pt.x, pt.y, &p2.x, &p2.y);
 186         return p2;
 187     }
 188
 189     void CalcUnscrolledPosition(int x, int y, int *xx, int *yy) const
 190         {  DoCalcUnscrolledPosition(x, y, xx, yy); }
 191     wxPoint CalcUnscrolledPosition(const wxPoint& pt) const
 192     {
 193         wxPoint p2;
 194         DoCalcUnscrolledPosition(pt.x, pt.y, &p2.x, &p2.y);
 195         return p2;
 196     }
 197
 198     void DoCalcScrolledPosition(int x, int y, int *xx, int *yy) const;
 199     void DoCalcUnscrolledPosition(int x, int y, int *xx, int *yy) const;
 200
 201     // Adjust the scrollbars
 202     virtual void AdjustScrollbars() = 0;
 203
 204     // Calculate scroll increment
 205     int CalcScrollInc(wxScrollWinEvent& event);
 206
 207     // Normally the wxScrolledWindow will scroll itself, but in some rare
 208     // occasions you might want it to scroll [part of] another window (e.g. a
 209     // child of it in order to scroll only a portion the area between the
 210     // scrollbars (spreadsheet: only cell area will move).
 211     void SetTargetWindow(wxWindow *target);
 212
 213     void SetTargetRect(const wxRect& rect) { m_rectToScroll = rect; }
 214     wxRect GetTargetRect() const { return m_rectToScroll; }
 215
 216     virtual void DoPrepareDC(wxDC& dc);
 217
 218     // are we generating the autoscroll events?
 219     bool IsAutoScrolling() const { return m_timerAutoScroll != NULL; }
 220
 221     // stop generating the scroll events when mouse is held outside the window
 222     void StopAutoScrolling();
 223
 224     // this method can be overridden in a derived class to forbid sending the
 225     // auto scroll events - note that unlike StopAutoScrolling() it doesn't
 226     // stop the timer, so it will be called repeatedly and will typically
 227     // return different values depending on the current mouse position
 228     //
 229     // the base class version just returns true
 230     virtual bool SendAutoScrollEvents(wxScrollWinEvent& event) const;
 231
 232     // the methods to be called from the window event handlers
 233     void HandleOnScroll(wxScrollWinEvent& event);
 234     void HandleOnSize(wxSizeEvent& event);
 235     void HandleOnMouseEnter(wxMouseEvent& event);
 236     void HandleOnMouseLeave(wxMouseEvent& event);
 237 #if wxUSE_MOUSEWHEEL
 238     void HandleOnMouseWheel(wxMouseEvent& event);
 239 #endif // wxUSE_MOUSEWHEEL
 240     void HandleOnChildFocus(wxChildFocusEvent& event);
 241
 242 #if WXWIN_COMPATIBILITY_2_8
 243     wxDEPRECATED(
 244         void OnScroll(wxScrollWinEvent& event) { HandleOnScroll(event); }
 245     )
 246 #endif // WXWIN_COMPATIBILITY_2_8
 247
 248 protected:
 249     // get pointer to our scroll rect if we use it or NULL
 250     const wxRect *GetScrollRect() const
 251     {
 252         return m_rectToScroll.width != 0 ? &m_rectToScroll : NULL;
 253     }
 254
 255     // get the size of the target window
 256     wxSize GetTargetSize() const
 257     {
 258         return m_rectToScroll.width != 0 ? m_rectToScroll.GetSize()
 259                                          : m_targetWindow->GetClientSize();
 260     }
 261
 262     void GetTargetSize(int *w, int *h) const
 263     {
 264         wxSize size = GetTargetSize();
 265         if ( w )
 266             *w = size.x;
 267         if ( h )
 268             *h = size.y;
 269     }
 270
 271     // implementation of public methods with the same name
 272     virtual void DoGetViewStart(int *x, int *y) const;
 273     virtual void DoScroll(int x, int y) = 0;
 274     virtual void DoShowScrollbars(wxScrollbarVisibility horz,
 275                                   wxScrollbarVisibility vert) = 0;
 276
 277     // implementations of various wxWindow virtual methods which should be
 278     // forwarded to us (this can be done by WX_FORWARD_TO_SCROLL_HELPER())
 279     bool ScrollLayout();
 280     void ScrollDoSetVirtualSize(int x, int y);
 281     wxSize ScrollGetBestVirtualSize() const;
 282
 283     // change just the target window (unlike SetWindow which changes m_win as
 284     // well)
 285     void DoSetTargetWindow(wxWindow *target);
 286
 287     // delete the event handler we installed
 288     void DeleteEvtHandler();
 289
 290     // this function should be overridden to return the size available for
 291     // m_targetWindow inside m_win of the given size
 292     //
 293     // the default implementation is only good for m_targetWindow == m_win
 294     // case, if we're scrolling a subwindow you must override this method
 295     virtual wxSize GetSizeAvailableForScrollTarget(const wxSize& size)
 296     {
 297         // returning just size from here is wrong but it was decided that it is
 298         // not wrong enough to break the existing code (which doesn't override
 299         // this recently added function at all) by adding this assert
 300         //
 301         // wxASSERT_MSG( m_targetWindow == m_win, "must be overridden" );
 302
 303         return size;
 304     }
 305
 306
 307     double                m_scaleX;
 308     double                m_scaleY;
 309
 310     wxRect                m_rectToScroll;
 311
 312     wxTimer              *m_timerAutoScroll;
 313
 314     // The number of pixels to scroll in horizontal and vertical directions
 315     // respectively.
 316     //
 317     // If 0, means that the scrolling in the given direction is disabled.
 318     int                   m_xScrollPixelsPerLine;
 319     int                   m_yScrollPixelsPerLine;
 320     int                   m_xScrollPosition;
 321     int                   m_yScrollPosition;
 322     int                   m_xScrollLines;
 323     int                   m_yScrollLines;
 324     int                   m_xScrollLinesPerPage;
 325     int                   m_yScrollLinesPerPage;
 326
 327     bool                  m_xScrollingEnabled;
 328     bool                  m_yScrollingEnabled;
 329
 330 #if wxUSE_MOUSEWHEEL
 331     int m_wheelRotation;
 332 #endif // wxUSE_MOUSEWHEEL
 333
 334     wxScrollHelperEvtHandler *m_handler;
 335
 336     wxDECLARE_NO_COPY_CLASS(wxScrollHelperBase);
 337 };
 338
 339 // this macro can be used in a wxScrollHelper-derived class to forward wxWindow
 340 // methods to corresponding wxScrollHelper methods
 341 #define WX_FORWARD_TO_SCROLL_HELPER()                                         \
 342 public:                                                                       \
 343     virtual void PrepareDC(wxDC& dc) { DoPrepareDC(dc); }                     \
 344     virtual bool Layout() { return ScrollLayout(); }                          \
 345     virtual bool CanScroll(int orient) const                                  \
 346         { return IsScrollbarShown(orient); }                                  \
 347     virtual void DoSetVirtualSize(int x, int y)                               \
 348         { ScrollDoSetVirtualSize(x, y); }                                     \
 349     virtual wxSize GetBestVirtualSize() const                                 \
 350         { return ScrollGetBestVirtualSize(); }
 351
 352 // include the declaration of the real wxScrollHelper
 353 #if defined(__WXGTK20__) && !defined(__WXUNIVERSAL__)
 354     #include "wx/gtk/scrolwin.h"
 355 #elif defined(__WXGTK__) && !defined(__WXUNIVERSAL__)
 356     #include "wx/gtk1/scrolwin.h"
 357 #else
 358     #define wxHAS_GENERIC_SCROLLWIN
 359     #include "wx/generic/scrolwin.h"
 360 #endif
 361
 362 // ----------------------------------------------------------------------------
 363 // wxScrolled<T>: a wxWindow which knows how to scroll
 364 // ----------------------------------------------------------------------------
 365
 366 // helper class for wxScrolled<T> below
 367 struct WXDLLIMPEXP_CORE wxScrolledT_Helper
 368 {
 369     static wxSize FilterBestSize(const wxWindow *win,
 370                                  const wxScrollHelper *helper,
 371                                  const wxSize& origBest);
 372 #ifdef __WXMSW__
 373     static WXLRESULT FilterMSWWindowProc(WXUINT nMsg, WXLRESULT origResult);
 374 #endif
 375 };
 376
 377 // Scrollable window base on window type T. This used to be wxScrolledWindow,
 378 // but wxScrolledWindow includes wxControlContainer functionality and that's
 379 // not always desirable.
 380 template<class T>
 381 class wxScrolled : public T,
 382                    public wxScrollHelper,
 383                    private wxScrolledT_Helper
 384 {
 385 public:
 386     wxScrolled() : wxScrollHelper(this) { }
 387     wxScrolled(wxWindow *parent,
 388                wxWindowID winid = wxID_ANY,
 389                const wxPoint& pos = wxDefaultPosition,
 390                const wxSize& size = wxDefaultSize,
 391                long style = wxScrolledWindowStyle,
 392                const wxString& name = wxPanelNameStr)
 393         : wxScrollHelper(this)
 394     {
 395         Create(parent, winid, pos, size, style, name);
 396     }
 397
 398     bool Create(wxWindow *parent,
 399                 wxWindowID winid,
 400                 const wxPoint& pos = wxDefaultPosition,
 401                 const wxSize& size = wxDefaultSize,
 402                 long style = wxScrolledWindowStyle,
 403                 const wxString& name = wxPanelNameStr)
 404     {
 405         m_targetWindow = this;
 406
 407 #ifdef __WXMAC__
 408         this->MacSetClipChildren(true);
 409 #endif
 410
 411         // by default, we're scrollable in both directions (but if one of the
 412         // styles is specified explicitly, we shouldn't add the other one
 413         // automatically)
 414         if ( !(style & (wxHSCROLL | wxVSCROLL)) )
 415             style |= wxHSCROLL | wxVSCROLL;
 416
 417 #ifdef __WXOSX__
 418         bool retval = T::Create(parent, winid, pos, size, style, name);
 419         if ( retval && (style & wxALWAYS_SHOW_SB) )
 420             ShowScrollbars(wxSHOW_SB_ALWAYS, wxSHOW_SB_ALWAYS);
 421         return retval;
 422 #else
 423         if ( style & wxALWAYS_SHOW_SB )
 424             ShowScrollbars(wxSHOW_SB_ALWAYS, wxSHOW_SB_ALWAYS);
 425
 426         return T::Create(parent, winid, pos, size, style, name);
 427 #endif
 428     }
 429
 430 #ifdef __WXMSW__
 431     // we need to return a special WM_GETDLGCODE value to process just the
 432     // arrows but let the other navigation characters through
 433     virtual WXLRESULT MSWWindowProc(WXUINT nMsg, WXWPARAM wParam, WXLPARAM lParam)
 434     {
 435         return FilterMSWWindowProc(nMsg, T::MSWWindowProc(nMsg, wParam, lParam));
 436     }
 437
 438     // Take into account the scroll origin.
 439     virtual void MSWAdjustBrushOrg(int* xOrg, int* yOrg) const
 440     {
 441         CalcUnscrolledPosition(*xOrg, *yOrg, xOrg, yOrg);
 442     }
 443 #endif // __WXMSW__
 444
 445     WX_FORWARD_TO_SCROLL_HELPER()
 446
 447 protected:
 448     virtual wxSize DoGetBestSize() const
 449     {
 450         return FilterBestSize(this, this, T::DoGetBestSize());
 451     }
 452
 453 private:
 454     // VC++ 6 gives warning for the declaration of template member function
 455     // without definition
 456 #ifndef __VISUALC6__
 457     wxDECLARE_NO_COPY_CLASS(wxScrolled);
 458 #endif
 459 };
 460
 461 #ifdef __VISUALC6__
 462     // disable the warning about non dll-interface class used as base for
 463     // dll-interface class: it's harmless in this case
 464     #pragma warning(push)
 465     #pragma warning(disable:4275)
 466 #endif
 467
 468 // for compatibility with existing code, we provide wxScrolledWindow
 469 // "typedef" for wxScrolled<wxPanel>. It's not a real typedef because we
 470 // want wxScrolledWindow to show in wxRTTI information (the class is widely
 471 // used and likelihood of its wxRTTI information being used too is high):
 472 class WXDLLIMPEXP_CORE wxScrolledWindow : public wxScrolled<wxPanel>
 473 {
 474 public:
 475     wxScrolledWindow() : wxScrolled<wxPanel>() {}
 476     wxScrolledWindow(wxWindow *parent,
 477                      wxWindowID winid = wxID_ANY,
 478                      const wxPoint& pos = wxDefaultPosition,
 479                      const wxSize& size = wxDefaultSize,
 480                      long style = wxScrolledWindowStyle,
 481                      const wxString& name = wxPanelNameStr)
 482         : wxScrolled<wxPanel>(parent, winid, pos, size, style, name) {}
 483
 484     DECLARE_DYNAMIC_CLASS_NO_COPY(wxScrolledWindow)
 485 };
 486
 487 typedef wxScrolled<wxWindow> wxScrolledCanvas;
 488
 489 #ifdef __VISUALC6__
 490     #pragma warning(pop)
 491 #endif
 492
 493 #endif // _WX_SCROLWIN_H_BASE_