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