]>
git.saurik.com Git - wxWidgets.git/blob - interface/scrolwin.h
d9ac775879c2046c61322c1420d4360af9f53e47
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: documentation for wxScrolledWindow class
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 @class wxScrolledWindow
13 The wxScrolledWindow class manages scrolling for its client area, transforming
14 the coordinates according to the scrollbar positions, and setting the
15 scroll positions, thumb sizes and ranges according to the area in view.
17 Starting from version 2.4 of wxWidgets, there are several ways to use a
18 wxScrolledWindow. In particular, there are now three ways to set the
19 size of the scrolling area:
21 One way is to set the scrollbars directly using a call to
22 wxScrolledWindow::SetScrollbars.
23 This is the way it used to be in any previous version of wxWidgets
24 and it will be kept for backwards compatibility.
26 An additional method of manual control, which requires a little less
27 computation of your own, is to set the total size of the scrolling area by
28 calling either wxWindow::SetVirtualSize,
29 or wxWindow::FitInside, and setting the
30 scrolling increments for it by calling
31 wxScrolledWindow::SetScrollRate.
32 Scrolling in some orientation is enabled by setting a non-zero increment
35 The most automatic and newest way is to simply let sizers determine the
36 scrolling area. This is now the default when you set an interior sizer
37 into a wxScrolledWindow with wxWindow::SetSizer.
38 The scrolling area will be set to the size requested by the sizer and
39 the scrollbars will be assigned for each orientation according to the need
40 for them and the scrolling increment set by
41 wxScrolledWindow::SetScrollRate.
42 As above, scrolling is only enabled in orientations with a non-zero
43 increment. You can influence the minimum size of the scrolled area
44 controlled by a sizer by calling
45 wxWindow::SetVirtualSizeHints.
46 (calling wxScrolledWindow::SetScrollbars
47 has analogous effects in wxWidgets 2.4 -- in later versions it may not continue
48 to override the sizer)
50 Note: if Maximum size hints are still supported by SetVirtualSizeHints, use
51 them at your own dire risk. They may or may not have been removed for 2.4,
52 but it really only makes sense to set minimum size hints here. We should
53 probably replace SetVirtualSizeHints with SetMinVirtualSize or similar
54 and remove it entirely in future.
56 As with all windows, an application can draw onto a wxScrolledWindow using
57 a @ref overview_dcoverview "device context".
59 You have the option of handling the OnPaint handler
60 or overriding the wxScrolledWindow::OnDraw function, which is
61 passed a pre-scrolled device context (prepared by
62 wxScrolledWindow::DoPrepareDC).
64 If you don't wish to calculate your own scrolling, you must call DoPrepareDC
66 within OnDraw, to set the device origin for the device context according to the
70 A wxScrolledWindow will normally scroll itself and therefore its child windows
72 might however be desired to scroll a different window than itself: e.g. when
74 spreadsheet, you will normally only have to scroll the (usually white) cell
76 (usually grey) label area will scroll very differently. For this special
78 call wxScrolledWindow::SetTargetWindow which means that pressing
79 the scrollbars will scroll a different window.
81 Note that the underlying system knows nothing about scrolling coordinates, so
83 functions (mouse events, expose events, refresh calls etc) as well as the
84 position of subwindows
85 are relative to the "physical" origin of the scrolled window. If the user
86 insert a child window at
87 position (10,10) and scrolls the window down 100 pixels (moving the child
88 window out of the visible
89 area), the child window will report a position of (10,-90).
93 Uses a backing pixmap to speed refreshes. Motif only.
100 wxScrollBar, wxClientDC, wxPaintDC, wxVScrolledWindow
102 class wxScrolledWindow
: public wxPanel
113 Window identifier. The value wxID_ANY indicates a default value.
116 Window position. If a position of (-1, -1) is specified then a default position
120 Window size. If a size of (-1, -1) is specified then the window is sized
124 Window style. See wxScrolledWindow.
129 @remarks The window is initially created without visible scrollbars. Call
130 SetScrollbars() to specify how big
131 the virtual window size should be.
134 wxScrolledWindow(wxWindow
* parent
, wxWindowID id
= -1,
135 const wxPoint
& pos
= wxDefaultPosition
,
136 const wxSize
& size
= wxDefaultSize
,
137 long style
= wxHSCROLL
| wxVSCROLL
,
138 const wxString
& name
= "scrolledWindow");
147 Translates the logical coordinates to the device ones. For example, if a window
149 scrolled 10 pixels to the bottom, the device coordinates of the origin are (0,
151 (as always), but the logical coordinates are (0, 10) and so the call to
152 CalcScrolledPosition(0, 10, xx, yy) will return 0 in yy.
154 @sa CalcUnscrolledPosition()
156 void CalcScrolledPosition(int x
, int y
, int * xx
, int * yy
);
159 Translates the device coordinates to the logical ones. For example, if a window
161 scrolled 10 pixels to the bottom, the device coordinates of the origin are (0,
163 (as always), but the logical coordinates are (0, 10) and so the call to
164 CalcUnscrolledPosition(0, 0, xx, yy) will return 10 in yy.
166 @sa CalcScrolledPosition()
168 void CalcUnscrolledPosition(int x
, int y
, int * xx
, int * yy
);
171 Creates the window for two-step construction. Derived classes
172 should call or replace this function. See wxScrolledWindow()
175 bool Create(wxWindow
* parent
, wxWindowID id
= -1,
176 const wxPoint
& pos
= wxDefaultPosition
,
177 const wxSize
& size
= wxDefaultSize
,
178 long style
= wxHSCROLL
| wxVSCROLL
,
179 const wxString
& name
= "scrolledWindow");
182 Call this function to prepare the device context for drawing a scrolled image.
184 sets the device origin according to the current scroll position.
186 DoPrepareDC is called automatically within the default OnPaint() event
187 handler, so your OnDraw() override
188 will be passed a 'pre-scrolled' device context. However, if you wish to draw
190 outside of OnDraw (via OnPaint), or you wish to implement OnPaint yourself, you
192 call this function yourself. For example:
194 void DoPrepareDC(wxDC
& dc
);
197 Enable or disable physical scrolling in the given direction. Physical
198 scrolling is the physical transfer of bits up or down the
199 screen when a scroll event occurs. If the application scrolls by a
200 variable amount (e.g. if there are different font sizes) then physical
201 scrolling will not work, and you should switch it off. Note that you
202 will have to reposition child windows yourself, if physical scrolling
206 If @true, enables physical scrolling in the x direction.
209 If @true, enables physical scrolling in the y direction.
211 @remarks Physical scrolling may not be available on all platforms. Where
212 it is available, it is enabled by default.
214 void EnableScrolling(bool xScrolling
, bool yScrolling
);
217 Get the number of pixels per scroll unit (line), in each direction, as set
218 by SetScrollbars(). A value of zero indicates no
219 scrolling in that direction.
222 Receives the number of pixels per horizontal unit.
225 Receives the number of pixels per vertical unit.
227 @sa SetScrollbars(), GetVirtualSize()
229 void GetScrollPixelsPerUnit(int* xUnit
, int* yUnit
);
232 Get the position at which the visible portion of the window starts.
235 Receives the first visible x position in scroll units.
238 Receives the first visible y position in scroll units.
240 @remarks If either of the scrollbars is not at the home position, x
241 and/or y will be greater than zero. Combined with
242 wxWindow::GetClientSize, the application can use this
243 function to efficiently redraw only the visible
244 portion of the window. The positions are in logical
245 scroll units, not pixels, so to convert to pixels you
246 will have to multiply by the number of pixels per
251 void GetViewStart(int* x
, int* y
);
254 Gets the size in device units of the scrollable window area (as
255 opposed to the client size, which is the area of the window currently
259 Receives the length of the scrollable window, in pixels.
262 Receives the height of the scrollable window, in pixels.
264 @remarks Use wxDC::DeviceToLogicalX and wxDC::DeviceToLogicalY to
265 translate these units to logical units.
267 @sa SetScrollbars(), GetScrollPixelsPerUnit()
269 void GetVirtualSize(int* x
, int* y
);
272 Motif only: @true if the window has a backing bitmap.
277 Called by the default paint event handler to allow the application to define
278 painting behaviour without having to worry about calling
281 Instead of overriding this function you may also just process the paint event
282 in the derived class as usual, but then you will have to call DoPrepareDC()
285 virtual void OnDraw(wxDC
& dc
);
288 This function is for backwards compatibility only and simply calls
289 DoPrepareDC() now. Notice that it is
290 not called by the default paint event handle (DoPrepareDC() is), so
291 overriding this method in your derived class is useless.
293 void PrepareDC(wxDC
& dc
);
296 Scrolls a window so the view start is at the given point.
299 The x position to scroll to, in scroll units.
302 The y position to scroll to, in scroll units.
304 @remarks The positions are in scroll units, not pixels, so to convert to
305 pixels you will have to multiply by the number of
306 pixels per scroll increment. If either parameter is
307 -1, that position will be ignored (no change in that
310 @sa SetScrollbars(), GetScrollPixelsPerUnit()
312 void Scroll(int x
, int y
);
315 Set the horizontal and vertical scrolling increment only. See the pixelsPerUnit
316 parameter in SetScrollbars.
318 void SetScrollRate(int xstep
, int ystep
);
321 Sets up vertical and/or horizontal scrollbars.
323 @param pixelsPerUnitX
324 Pixels per scroll unit in the horizontal direction.
326 @param pixelsPerUnitY
327 Pixels per scroll unit in the vertical direction.
330 Number of units in the horizontal direction.
333 Number of units in the vertical direction.
336 Position to initialize the scrollbars in the horizontal direction, in scroll
340 Position to initialize the scrollbars in the vertical direction, in scroll
344 Will not refresh window if @true.
346 @remarks The first pair of parameters give the number of pixels per
347 'scroll step', i.e. amount moved when the up or down
348 scroll arrows are pressed. The second pair gives the
349 length of scrollbar in scroll steps, which sets the
350 size of the virtual window.
352 @sa wxWindow::SetVirtualSize
354 void SetScrollbars(int pixelsPerUnitX
, int pixelsPerUnitY
,
359 bool noRefresh
= @
false);
362 Call this function to tell wxScrolledWindow to perform the actual scrolling on
363 a different window (and not on itself).
365 void SetTargetWindow(wxWindow
* window
);