1 /////////////////////////////////////////////////////////////////////////////
2 // Name: include/wx/scrolwin.h
3 // Purpose: wxScrolledWindow, wxScrolledControl and wxScrollHelper
4 // Author: Vadim Zeitlin
8 // Copyright: (c) 2000 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
12 #ifndef _WX_SCROLWIN_H_BASE_
13 #define _WX_SCROLWIN_H_BASE_
17 class WXDLLIMPEXP_FWD_CORE wxScrollHelperEvtHandler
;
18 class WXDLLIMPEXP_FWD_BASE wxTimer
;
20 // default scrolled window style: scroll in both directions
21 #define wxScrolledWindowStyle (wxHSCROLL | wxVSCROLL)
23 // values for the second argument of wxScrollHelper::ShowScrollbars()
24 enum wxScrollbarVisibility
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
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.
44 // wxWindow wxScrollHelperNative
48 // | wxScrolledWindow /
57 // ----------------------------------------------------------------------------
59 class WXDLLIMPEXP_CORE wxScrollHelper
62 // ctor must be given the associated window
63 wxScrollHelper(wxWindow
*winToScroll
);
64 virtual ~wxScrollHelper();
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 );
72 // scroll to the given (in logical coords) position
73 void Scroll(int x
, int y
) { DoScroll(x
, y
); }
74 void Scroll(const wxPoint
& pt
) { DoScroll(pt
.x
, pt
.y
); }
76 // get/set the page size for this orientation (wxVERTICAL/wxHORIZONTAL)
77 int GetScrollPageSize(int orient
) const;
78 void SetScrollPageSize(int orient
, int pageSize
);
80 // get the number of lines the window can scroll,
81 // returns 0 if no scrollbars are there.
82 int GetScrollLines( int orient
) const;
84 // Set the x, y scrolling increments.
85 void SetScrollRate( int xstep
, int ystep
);
87 // get the size of one logical unit in physical ones
88 virtual void GetScrollPixelsPerUnit(int *pixelsPerUnitX
,
89 int *pixelsPerUnitY
) const;
91 // Set scrollbar visibility: it is possible to show scrollbar only if it is
92 // needed (i.e. if our virtual size is greater than the current size of the
93 // associated window), always (as wxALWAYS_SHOW_SB style does) or never (in
94 // which case you should provide some other way to scroll the window as the
95 // user wouldn't be able to do it at all)
96 void ShowScrollbars(wxScrollbarVisibility horz
, wxScrollbarVisibility vert
)
98 DoShowScrollbars(horz
, vert
);
101 // Enable/disable Windows scrolling in either direction. If true, wxWidgets
102 // scrolls the canvas and only a bit of the canvas is invalidated; no
103 // Clear() is necessary. If false, the whole canvas is invalidated and a
104 // Clear() is necessary. Disable for when the scroll increment is used to
105 // actually scroll a non-constant distance
106 virtual void EnableScrolling(bool x_scrolling
, bool y_scrolling
);
108 // Get the view start
109 void GetViewStart(int *x
, int *y
) const { DoGetViewStart(x
, y
); }
111 wxPoint
GetViewStart() const
114 DoGetViewStart(&pt
.x
, &pt
.y
);
118 // Set the scale factor, used in PrepareDC
119 void SetScale(double xs
, double ys
) { m_scaleX
= xs
; m_scaleY
= ys
; }
120 double GetScaleX() const { return m_scaleX
; }
121 double GetScaleY() const { return m_scaleY
; }
123 // translate between scrolled and unscrolled coordinates
124 void CalcScrolledPosition(int x
, int y
, int *xx
, int *yy
) const
125 { DoCalcScrolledPosition(x
, y
, xx
, yy
); }
126 wxPoint
CalcScrolledPosition(const wxPoint
& pt
) const
129 DoCalcScrolledPosition(pt
.x
, pt
.y
, &p2
.x
, &p2
.y
);
133 void CalcUnscrolledPosition(int x
, int y
, int *xx
, int *yy
) const
134 { DoCalcUnscrolledPosition(x
, y
, xx
, yy
); }
135 wxPoint
CalcUnscrolledPosition(const wxPoint
& pt
) const
138 DoCalcUnscrolledPosition(pt
.x
, pt
.y
, &p2
.x
, &p2
.y
);
142 virtual void DoCalcScrolledPosition(int x
, int y
, int *xx
, int *yy
) const;
143 virtual void DoCalcUnscrolledPosition(int x
, int y
, int *xx
, int *yy
) const;
145 // Adjust the scrollbars
146 virtual void AdjustScrollbars(void);
148 // Calculate scroll increment
149 virtual int CalcScrollInc(wxScrollWinEvent
& event
);
151 // Normally the wxScrolledWindow will scroll itself, but in some rare
152 // occasions you might want it to scroll [part of] another window (e.g. a
153 // child of it in order to scroll only a portion the area between the
154 // scrollbars (spreadsheet: only cell area will move).
155 virtual void SetTargetWindow(wxWindow
*target
);
156 virtual wxWindow
*GetTargetWindow() const;
158 void SetTargetRect(const wxRect
& rect
) { m_rectToScroll
= rect
; }
159 wxRect
GetTargetRect() const { return m_rectToScroll
; }
161 // Override this function to draw the graphic (or just process EVT_PAINT)
162 virtual void OnDraw(wxDC
& WXUNUSED(dc
)) { }
164 // change the DC origin according to the scroll position.
165 virtual void DoPrepareDC(wxDC
& dc
);
167 // are we generating the autoscroll events?
168 bool IsAutoScrolling() const { return m_timerAutoScroll
!= NULL
; }
170 // stop generating the scroll events when mouse is held outside the window
171 void StopAutoScrolling();
173 // this method can be overridden in a derived class to forbid sending the
174 // auto scroll events - note that unlike StopAutoScrolling() it doesn't
175 // stop the timer, so it will be called repeatedly and will typically
176 // return different values depending on the current mouse position
178 // the base class version just returns true
179 virtual bool SendAutoScrollEvents(wxScrollWinEvent
& event
) const;
181 // the methods to be called from the window event handlers
182 void HandleOnScroll(wxScrollWinEvent
& event
);
183 void HandleOnSize(wxSizeEvent
& event
);
184 void HandleOnPaint(wxPaintEvent
& event
);
185 void HandleOnChar(wxKeyEvent
& event
);
186 void HandleOnMouseEnter(wxMouseEvent
& event
);
187 void HandleOnMouseLeave(wxMouseEvent
& event
);
189 void HandleOnMouseWheel(wxMouseEvent
& event
);
190 #endif // wxUSE_MOUSEWHEEL
191 void HandleOnChildFocus(wxChildFocusEvent
& event
);
193 // FIXME: this is needed for now for wxPlot compilation, should be removed
195 void OnScroll(wxScrollWinEvent
& event
) { HandleOnScroll(event
); }
198 // get pointer to our scroll rect if we use it or NULL
199 const wxRect
*GetScrollRect() const
201 return m_rectToScroll
.width
!= 0 ?
&m_rectToScroll
: NULL
;
204 // get the size of the target window
205 wxSize
GetTargetSize() const
207 return m_rectToScroll
.width
!= 0 ? m_rectToScroll
.GetSize()
208 : m_targetWindow
->GetClientSize();
211 void GetTargetSize(int *w
, int *h
) const
213 wxSize size
= GetTargetSize();
220 // implementation of public methods with the same name
221 virtual void DoGetViewStart(int *x
, int *y
) const;
222 virtual void DoScroll(int x
, int y
);
223 virtual void DoShowScrollbars(wxScrollbarVisibility horz
,
224 wxScrollbarVisibility vert
);
226 // implementations of various wxWindow virtual methods which should be
227 // forwarded to us (this can be done by WX_FORWARD_TO_SCROLL_HELPER())
229 void ScrollDoSetVirtualSize(int x
, int y
);
230 wxSize
ScrollGetBestVirtualSize() const;
232 // change just the target window (unlike SetWindow which changes m_win as
234 void DoSetTargetWindow(wxWindow
*target
);
236 // delete the event handler we installed
237 void DeleteEvtHandler();
239 // calls wxScrollHelperEvtHandler::ResetDrawnFlag(), see explanation
240 // in wxScrollHelperEvtHandler::ProcessEvent()
241 void ResetDrawnFlag();
243 // helper of AdjustScrollbars(): does the work for the single scrollbar
245 // notice that the parameters passed by non-const references are modified
247 void AdjustScrollbar(int orient
,
253 wxScrollbarVisibility visibility
);
255 // this function should be overridden to return the size available for
256 // m_targetWindow inside m_win of the given size
258 // the default implementation is only good for m_targetWindow == m_win
259 // case, if we're scrolling a subwindow you must override this method
260 virtual wxSize
GetSizeAvailableForScrollTarget(const wxSize
& size
)
262 // returning just size from here is wrong but it was decided that it is
263 // not wrong enough to break the existing code (which doesn't override
264 // this recently added function at all) by adding this assert
266 // wxASSERT_MSG( m_targetWindow == m_win, "must be overridden" );
278 wxRect m_rectToScroll
;
280 wxTimer
*m_timerAutoScroll
;
282 int m_xScrollPixelsPerLine
;
283 int m_yScrollPixelsPerLine
;
284 int m_xScrollPosition
;
285 int m_yScrollPosition
;
288 int m_xScrollLinesPerPage
;
289 int m_yScrollLinesPerPage
;
291 bool m_xScrollingEnabled
;
292 bool m_yScrollingEnabled
;
296 #endif // wxUSE_MOUSEWHEEL
298 wxScrollHelperEvtHandler
*m_handler
;
300 wxScrollbarVisibility m_xVisibility
,
303 DECLARE_NO_COPY_CLASS(wxScrollHelper
)
306 // this macro can be used in a wxScrollHelper-derived class to forward wxWindow
307 // methods to corresponding wxScrollHelper methods
308 #define WX_FORWARD_TO_SCROLL_HELPER() \
310 virtual void PrepareDC(wxDC& dc) { DoPrepareDC(dc); } \
311 virtual bool Layout() { return ScrollLayout(); } \
312 virtual void DoSetVirtualSize(int x, int y) \
313 { ScrollDoSetVirtualSize(x, y); } \
314 virtual wxSize GetBestVirtualSize() const \
315 { return ScrollGetBestVirtualSize(); }
317 // include the declaration of wxScrollHelperNative if needed
318 #if defined(__WXGTK20__) && !defined(__WXUNIVERSAL__)
319 #include "wx/gtk/scrolwin.h"
320 #elif defined(__WXGTK__) && !defined(__WXUNIVERSAL__)
321 #include "wx/gtk1/scrolwin.h"
323 typedef wxScrollHelper wxScrollHelperNative
;
326 // ----------------------------------------------------------------------------
327 // wxScrolled<T>: a wxWindow which knows how to scroll
328 // ----------------------------------------------------------------------------
330 // helper class for wxScrolled<T> below
331 struct WXDLLIMPEXP_CORE wxScrolledT_Helper
333 static wxSize
FilterBestSize(const wxWindow
*win
,
334 const wxScrollHelperNative
*helper
,
335 const wxSize
& origBest
);
337 static WXLRESULT
FilterMSWWindowProc(WXUINT nMsg
, WXLRESULT origResult
);
341 // Scrollable window base on window type T. This used to be wxScrolledWindow,
342 // but wxScrolledWindow includes wxControlContainer functionality and that's
343 // not always desirable.
345 class WXDLLIMPEXP_CORE wxScrolled
: public T
,
346 public wxScrollHelperNative
,
347 private wxScrolledT_Helper
350 wxScrolled() : wxScrollHelperNative(this) { }
351 wxScrolled(wxWindow
*parent
,
352 wxWindowID winid
= wxID_ANY
,
353 const wxPoint
& pos
= wxDefaultPosition
,
354 const wxSize
& size
= wxDefaultSize
,
355 long style
= wxScrolledWindowStyle
,
356 const wxString
& name
= wxPanelNameStr
)
357 : wxScrollHelperNative(this)
359 Create(parent
, winid
, pos
, size
, style
, name
);
362 bool Create(wxWindow
*parent
,
364 const wxPoint
& pos
= wxDefaultPosition
,
365 const wxSize
& size
= wxDefaultSize
,
366 long style
= wxScrolledWindowStyle
,
367 const wxString
& name
= wxPanelNameStr
)
369 m_targetWindow
= this;
372 this->MacSetClipChildren(true);
375 this->Connect(wxEVT_PAINT
, wxPaintEventHandler(wxScrolled
::OnPaint
));
377 // by default, we're scrollable in both directions (but if one of the
378 // styles is specified explicitly, we shouldn't add the other one
380 if ( !(style
& (wxHSCROLL
| wxVSCROLL
)) )
381 style
|= wxHSCROLL
| wxVSCROLL
;
383 return T
::Create(parent
, winid
, pos
, size
, style
, name
);
386 // we need to return a special WM_GETDLGCODE value to process just the
387 // arrows but let the other navigation characters through
389 virtual WXLRESULT
MSWWindowProc(WXUINT nMsg
, WXWPARAM wParam
, WXLPARAM lParam
)
391 return FilterMSWWindowProc(nMsg
, T
::MSWWindowProc(nMsg
, wParam
, lParam
));
395 WX_FORWARD_TO_SCROLL_HELPER()
398 virtual wxSize
DoGetBestSize() const
400 return FilterBestSize(this, this, T
::DoGetBestSize());
404 // this is needed for wxEVT_PAINT processing hack described in
405 // wxScrollHelperEvtHandler::ProcessEvent()
406 void OnPaint(wxPaintEvent
& event
)
408 // the user code didn't really draw the window if we got here, so set
409 // this flag to try to call OnDraw() later
414 // VC++ 6 gives warning for the declaration of template member function
415 // without definition
416 #if !defined(__VISUALC__) || wxCHECK_VISUALC_VERSION(7)
417 DECLARE_NO_COPY_CLASS(wxScrolled
)
421 // VC++ <= 6 requires this; it's unlikely any other specializations would
422 // be needed by user code _and_ they were using VC6, so we list only wxWindow
423 // (typical use) and wxPanel (wxScrolledWindow use) specializations here
424 WXDLLIMPEXP_TEMPLATE_INSTANCE_CORE( wxScrolled
<wxPanel
> )
425 WXDLLIMPEXP_TEMPLATE_INSTANCE_CORE( wxScrolled
<wxWindow
> )
427 // for compatibility with existing code, we provide wxScrolledWindow
428 // "typedef" for wxScrolled<wxPanel>. It's not a real typedef because we
429 // want wxScrolledWindow to show in wxRTTI information (the class is widely
430 // used and likelihood of its wxRTTI information being used too is high):
431 class WXDLLIMPEXP_CORE wxScrolledWindow
: public wxScrolled
<wxPanel
>
434 wxScrolledWindow() : wxScrolled
<wxPanel
>() {}
435 wxScrolledWindow(wxWindow
*parent
,
436 wxWindowID winid
= wxID_ANY
,
437 const wxPoint
& pos
= wxDefaultPosition
,
438 const wxSize
& size
= wxDefaultSize
,
439 long style
= wxScrolledWindowStyle
,
440 const wxString
& name
= wxPanelNameStr
)
441 : wxScrolled
<wxPanel
>(parent
, winid
, pos
, size
, style
, name
) {}
443 DECLARE_DYNAMIC_CLASS_NO_COPY(wxScrolledWindow
)
446 typedef wxScrolled
<wxWindow
> wxScrolledCanvas
;
448 #endif // _WX_SCROLWIN_H_BASE_