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