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