include/wx/scrolwin.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        include/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/window.h"
  16
  17 class WXDLLEXPORT wxScrollHelperEvtHandler;
  18 class WXDLLEXPORT wxTimer;
  19
  20 WXDLLEXPORT_DATA(extern const wxChar*) wxPanelNameStr;
  21
  22 // default scrolled window style: scroll in both directions
  23 #define wxScrolledWindowStyle (wxHSCROLL | wxVSCROLL)
  24
  25 // ----------------------------------------------------------------------------
  26 // The hierarchy of scrolling classes is a bit complicated because we want to
  27 // put as much functionality as possible in a mix-in class not deriving from
  28 // wxWindow so that other classes could derive from the same base class on all
  29 // platforms irrespectively of whether they are native controls (and hence
  30 // don't use our scrolling) or not.
  31 //
  32 // So we have
  33 //
  34 //                             wxScrollHelper
  35 //                                   |
  36 //                                   |
  37 //                                  \|/
  38 //      wxWindow            wxScrollHelperNative
  39 //       |  \                   /        /
  40 //       |   \                 /        /
  41 //       |    _|             |_        /
  42 //       |     wxScrolledWindow       /
  43 //       |                           /
  44 //      \|/                         /
  45 //   wxControl                     /
  46 //         \                      /
  47 //          \                    /
  48 //           _|                |_
  49 //            wxScrolledControl
  50 //
  51 // ----------------------------------------------------------------------------
  52
  53 class WXDLLEXPORT wxScrollHelper
  54 {
  55 public:
  56     // ctor must be given the associated window
  57     wxScrollHelper(wxWindow *winToScroll);
  58     virtual ~wxScrollHelper();
  59
  60     // configure the scrolling
  61     virtual void SetScrollbars(int pixelsPerUnitX, int pixelsPerUnitY,
  62                                int noUnitsX, int noUnitsY,
  63                                int xPos = 0, int yPos = 0,
  64                                bool noRefresh = false );
  65
  66     // scroll to the given (in logical coords) position
  67     virtual void Scroll(int x, int y);
  68
  69     // get/set the page size for this orientation (wxVERTICAL/wxHORIZONTAL)
  70     int GetScrollPageSize(int orient) const;
  71     void SetScrollPageSize(int orient, int pageSize);
  72
  73     // Set the x, y scrolling increments.
  74     void SetScrollRate( int xstep, int ystep );
  75
  76     // get the size of one logical unit in physical ones
  77     virtual void GetScrollPixelsPerUnit(int *pixelsPerUnitX,
  78                                         int *pixelsPerUnitY) const;
  79
  80     // Enable/disable Windows scrolling in either direction. If true, wxWidgets
  81     // scrolls the canvas and only a bit of the canvas is invalidated; no
  82     // Clear() is necessary. If false, the whole canvas is invalidated and a
  83     // Clear() is necessary. Disable for when the scroll increment is used to
  84     // actually scroll a non-constant distance
  85     virtual void EnableScrolling(bool x_scrolling, bool y_scrolling);
  86
  87     // Get the view start
  88     virtual void GetViewStart(int *x, int *y) const;
  89
  90     // Set the scale factor, used in PrepareDC
  91     void SetScale(double xs, double ys) { m_scaleX = xs; m_scaleY = ys; }
  92     double GetScaleX() const { return m_scaleX; }
  93     double GetScaleY() const { return m_scaleY; }
  94
  95     // translate between scrolled and unscrolled coordinates
  96     void CalcScrolledPosition(int x, int y, int *xx, int *yy) const
  97         {  DoCalcScrolledPosition(x, y, xx, yy); }
  98     wxPoint CalcScrolledPosition(const wxPoint& pt) const
  99     {
 100         wxPoint p2;
 101         DoCalcScrolledPosition(pt.x, pt.y, &p2.x, &p2.y);
 102         return p2;
 103     }
 104
 105     void CalcUnscrolledPosition(int x, int y, int *xx, int *yy) const
 106         {  DoCalcUnscrolledPosition(x, y, xx, yy); }
 107     wxPoint CalcUnscrolledPosition(const wxPoint& pt) const
 108     {
 109         wxPoint p2;
 110         DoCalcUnscrolledPosition(pt.x, pt.y, &p2.x, &p2.y);
 111         return p2;
 112     }
 113
 114     virtual void DoCalcScrolledPosition(int x, int y, int *xx, int *yy) const;
 115     virtual void DoCalcUnscrolledPosition(int x, int y, int *xx, int *yy) const;
 116
 117     // Adjust the scrollbars
 118     virtual void AdjustScrollbars(void);
 119
 120     // Calculate scroll increment
 121     virtual int CalcScrollInc(wxScrollWinEvent& event);
 122
 123     // Normally the wxScrolledWindow will scroll itself, but in some rare
 124     // occasions you might want it to scroll [part of] another window (e.g. a
 125     // child of it in order to scroll only a portion the area between the
 126     // scrollbars (spreadsheet: only cell area will move).
 127     virtual void SetTargetWindow(wxWindow *target);
 128     virtual wxWindow *GetTargetWindow() const;
 129
 130     void SetTargetRect(const wxRect& rect) { m_rectToScroll = rect; }
 131     wxRect GetTargetRect() const { return m_rectToScroll; }
 132
 133     // Override this function to draw the graphic (or just process EVT_PAINT)
 134     virtual void OnDraw(wxDC& WXUNUSED(dc)) { }
 135
 136     // change the DC origin according to the scroll position.
 137     virtual void DoPrepareDC(wxDC& dc);
 138
 139     // are we generating the autoscroll events?
 140     bool IsAutoScrolling() const { return m_timerAutoScroll != NULL; }
 141
 142     // stop generating the scroll events when mouse is held outside the window
 143     void StopAutoScrolling();
 144
 145     // this method can be overridden in a derived class to forbid sending the
 146     // auto scroll events - note that unlike StopAutoScrolling() it doesn't
 147     // stop the timer, so it will be called repeatedly and will typically
 148     // return different values depending on the current mouse position
 149     //
 150     // the base class version just returns true
 151     virtual bool SendAutoScrollEvents(wxScrollWinEvent& event) const;
 152
 153     // the methods to be called from the window event handlers
 154     void HandleOnScroll(wxScrollWinEvent& event);
 155     void HandleOnSize(wxSizeEvent& event);
 156     void HandleOnPaint(wxPaintEvent& event);
 157     void HandleOnChar(wxKeyEvent& event);
 158     void HandleOnMouseEnter(wxMouseEvent& event);
 159     void HandleOnMouseLeave(wxMouseEvent& event);
 160 #if wxUSE_MOUSEWHEEL
 161     void HandleOnMouseWheel(wxMouseEvent& event);
 162 #endif // wxUSE_MOUSEWHEEL
 163
 164     // FIXME: this is needed for now for wxPlot compilation, should be removed
 165     //        once it is fixed!
 166     void OnScroll(wxScrollWinEvent& event) { HandleOnScroll(event); }
 167
 168 protected:
 169     // get pointer to our scroll rect if we use it or NULL
 170     const wxRect *GetScrollRect() const
 171     {
 172         return m_rectToScroll.width != 0 ? &m_rectToScroll : NULL;
 173     }
 174
 175     // get the size of the target window
 176     wxSize GetTargetSize() const
 177     {
 178         return m_rectToScroll.width != 0 ? m_rectToScroll.GetSize()
 179                                          : m_targetWindow->GetClientSize();
 180     }
 181
 182     void GetTargetSize(int *w, int *h)
 183     {
 184         wxSize size = GetTargetSize();
 185         if ( w )
 186             *w = size.x;
 187         if ( h )
 188             *h = size.y;
 189     }
 190
 191     // implementations of various wxWindow virtual methods which should be
 192     // forwarded to us (this can be done by WX_FORWARD_TO_SCROLL_HELPER())
 193     bool ScrollLayout();
 194     void ScrollDoSetVirtualSize(int x, int y);
 195     wxSize ScrollGetBestVirtualSize() const;
 196     wxSize ScrollGetWindowSizeForVirtualSize(const wxSize& size) const;
 197
 198     // change just the target window (unlike SetWindow which changes m_win as
 199     // well)
 200     void DoSetTargetWindow(wxWindow *target);
 201
 202     // delete the event handler we installed
 203     void DeleteEvtHandler();
 204
 205
 206     double                m_scaleX;
 207     double                m_scaleY;
 208
 209     wxWindow             *m_win,
 210                          *m_targetWindow;
 211
 212     wxRect                m_rectToScroll;
 213
 214     wxTimer              *m_timerAutoScroll;
 215
 216     int                   m_xScrollPixelsPerLine;
 217     int                   m_yScrollPixelsPerLine;
 218     int                   m_xScrollPosition;
 219     int                   m_yScrollPosition;
 220     int                   m_xScrollLines;
 221     int                   m_yScrollLines;
 222     int                   m_xScrollLinesPerPage;
 223     int                   m_yScrollLinesPerPage;
 224
 225     bool                  m_xScrollingEnabled;
 226     bool                  m_yScrollingEnabled;
 227
 228 #if wxUSE_MOUSEWHEEL
 229     int m_wheelRotation;
 230 #endif // wxUSE_MOUSEWHEEL
 231
 232     wxScrollHelperEvtHandler *m_handler;
 233
 234     DECLARE_NO_COPY_CLASS(wxScrollHelper)
 235 };
 236
 237 // this macro can be used in a wxScrollHelper-derived class to forward wxWindow
 238 // methods to corresponding wxScrollHelper methods
 239 #define WX_FORWARD_TO_SCROLL_HELPER()                                         \
 240     virtual void PrepareDC(wxDC& dc) { DoPrepareDC(dc); }                     \
 241     virtual bool Layout() { return ScrollLayout(); }                          \
 242     virtual void DoSetVirtualSize(int x, int y)                               \
 243         { ScrollDoSetVirtualSize(x, y); }                                     \
 244     virtual wxSize GetBestVirtualSize() const                                 \
 245         { return ScrollGetBestVirtualSize(); }                                \
 246     virtual wxSize GetWindowSizeForVirtualSize(const wxSize& size) const      \
 247         { return ScrollGetWindowSizeForVirtualSize(size); }
 248
 249 // include the declaration of wxScrollHelperNative if needed
 250 #if defined(__WXGTK__) && !defined(__WXUNIVERSAL__)
 251     #include "wx/gtk/scrolwin.h"
 252 #else
 253     typedef wxScrollHelper wxScrollHelperNative;
 254 #endif
 255
 256 // ----------------------------------------------------------------------------
 257 // wxScrolledWindow: a wxWindow which knows how to scroll
 258 // ----------------------------------------------------------------------------
 259
 260 class WXDLLEXPORT wxScrolledWindow : public wxPanel,
 261                                      public wxScrollHelperNative
 262 {
 263 public:
 264     wxScrolledWindow() : wxScrollHelperNative(this) { }
 265     wxScrolledWindow(wxWindow *parent,
 266                      wxWindowID winid = wxID_ANY,
 267                      const wxPoint& pos = wxDefaultPosition,
 268                      const wxSize& size = wxDefaultSize,
 269                      long style = wxScrolledWindowStyle,
 270                      const wxString& name = wxPanelNameStr)
 271         : wxScrollHelperNative(this)
 272     {
 273         Create(parent, winid, pos, size, style, name);
 274     }
 275
 276     virtual ~wxScrolledWindow();
 277
 278     bool Create(wxWindow *parent,
 279                 wxWindowID winid,
 280                 const wxPoint& pos = wxDefaultPosition,
 281                 const wxSize& size = wxDefaultSize,
 282                 long style = wxScrolledWindowStyle,
 283                 const wxString& name = wxPanelNameStr);
 284
 285     WX_FORWARD_TO_SCROLL_HELPER()
 286
 287 protected:
 288     // this is needed for wxEVT_PAINT processing hack described in
 289     // wxScrollHelperEvtHandler::ProcessEvent()
 290     void OnPaint(wxPaintEvent& event);
 291
 292     // we need to return a special WM_GETDLGCODE value to process just the
 293     // arrows but let the other navigation characters through
 294 #ifdef __WXMSW__
 295     virtual WXLRESULT MSWWindowProc(WXUINT nMsg, WXWPARAM wParam, WXLPARAM lParam);
 296 #endif // __WXMSW__
 297
 298 private:
 299     DECLARE_DYNAMIC_CLASS_NO_COPY(wxScrolledWindow)
 300     DECLARE_EVENT_TABLE()
 301 };
 302
 303 #endif // _WX_SCROLWIN_H_BASE_
 304