]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/scrolwin.tex
A little clarification
[wxWidgets.git] / docs / latex / wx / scrolwin.tex
1 \section{\class{wxScrolledWindow}}\label{wxscrolledwindow}
2
3 The wxScrolledWindow class manages scrolling for its client area, transforming
4 the coordinates according to the scrollbar positions, and setting the
5 scroll positions, thumb sizes and ranges according to the area in view.
6
7 Starting from version 2.4 of wxWindows, there are several ways to use a
8 wxScrolledWindow. In particular, there are now three ways to set the
9 size of the scrolling area:
10
11 One way is to set the scrollbars directly using a call to
12 \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars}.
13 This is the way it used to be in any previous version of wxWindows
14 and it will be kept for backwards compatibility.
15
16 An additional method of manual control, which requires a little less
17 computation of your own, is to set the total size of the scrolling area by
18 calling either \helpref{wxWindow::SetVirtualSize}{wxwindowsetvirtualsize},
19 or \helpref{wxWindow::FitInside}{wxwindowfitinside}, and setting the
20 scrolling increments for it by calling
21 \helpref{wxScrolledWindow::SetScrollRate}{wxscrolledwindowsetscrollrate}.
22 Scrolling in some orientation is enabled by setting a non zero increment
23 for it.
24
25 The most automatic and newest way is to simply let sizers determine the
26 scrolling area. This is now the default when you set an interior sizer
27 into a wxScrolledWindow with \helpref{wxWindow::SetSizer}{wxwindowsetsizer}.
28 The scrolling area will be set to the size requested by the sizer and
29 the scrollbars will be assigned for each orientation according to the need
30 for them and the scrolling increment set by
31 \helpref{wxScrolledWindow::SetScrollRate}{wxscrolledwindowsetscrollrate}.
32 As above, scrolling is only enabled in orientations with a non-zero
33 increment. You can influence the minimum size of the scrolled area
34 controlled by a sizer by calling
35 \helpref{wxWindow::SetVirtualSizeHints}{wxwindowsetvirtualsizehints}.
36 (calling \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars}
37 has analogous effects in wxWindows 2.4 -- in later versions it may not continue
38 to override the sizer)
39
40 Note: if Maximum size hints are still supported by SetVirtualSizeHints, use
41 them at your own dire risk. They may or may not have been removed for 2.4,
42 but it really only makes sense to set minimum size hints here. We should
43 probably replace SetVirtualSizeHints with SetMinVirtualSize or similar
44 and remove it entirely in future.
45
46 As with all windows, an application can draw onto a wxScrolledWindow using
47 a \helpref{device context}{dcoverview}.
48
49 You have the option of handling the OnPaint handler
50 or overriding the \helpref{OnDraw}{wxscrolledwindowondraw} function, which is passed
51 a pre-scrolled device context (prepared by \helpref{PrepareDC}{wxscrolledwindowpreparedc}).
52
53 If you don't wish to calculate your own scrolling, you must call PrepareDC when not drawing from
54 within OnDraw, to set the device origin for the device context according to the current
55 scroll position.
56
57 A wxScrolledWindow will normally scroll itself and therefore its child windows as well. It
58 might however be desired to scroll a different window than itself: e.g. when designing a
59 spreadsheet, you will normally only have to scroll the (usually white) cell area, whereas the
60 (usually grey) label area will scroll very differently. For this special purpose, you can
61 call \helpref{SetTargetWindow}{wxscrolledwindowsettargetwindow} which means that pressing
62 the scrollbars will scroll a different window.
63
64 Note that the underlying system knows nothing about scrolling coordinates, so that all system
65 functions (mouse events, expose events, refresh calls etc) as well as the position of subwindows
66 are relative to the "physical" origin of the scrolled window. If the user insert a child window at
67 position (10,10) and scrolls the window down 100 pixels (moving the child window out of the visible
68 area), the child window will report a position of (10,-90).
69
70
71 \wxheading{Derived from}
72
73 \helpref{wxPanel}{wxpanel}\\
74 \helpref{wxWindow}{wxwindow}\\
75 \helpref{wxEvtHandler}{wxevthandler}\\
76 \helpref{wxObject}{wxobject}
77
78 \wxheading{Include files}
79
80 <wx/scrolwin.h>
81
82 \wxheading{Window styles}
83
84 \twocolwidtha{5cm}
85 \begin{twocollist}\itemsep=0pt
86 \twocolitem{\windowstyle{wxRETAINED}}{Uses a backing pixmap to speed refreshes. Motif only.}
87 \end{twocollist}
88
89 See also \helpref{window styles overview}{windowstyles}.
90
91 \wxheading{Remarks}
92
93 Use wxScrolledWindow for applications where the user scrolls by a fixed amount, and
94 where a `page' can be interpreted to be the current visible portion of the window. For
95 more sophisticated applications, use the wxScrolledWindow implementation as a guide
96 to build your own scroll behaviour.
97
98 \wxheading{See also}
99
100 \helpref{wxScrollBar}{wxscrollbar}, \helpref{wxClientDC}{wxclientdc},\\
101 \helpref{wxPaintDC}{wxpaintdc}, \helpref{wxVScrolledWindow}{wxvscrolledwindow}
102
103 \latexignore{\rtfignore{\wxheading{Members}}}
104
105 \membersection{wxScrolledWindow::wxScrolledWindow}\label{wxscrolledwindowconstr}
106
107 \func{}{wxScrolledWindow}{\void}
108
109 Default constructor.
110
111 \func{}{wxScrolledWindow}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id = -1},\rtfsp
112 \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
113 \param{long}{ style = wxHSCROLL \pipe wxVSCROLL}, \param{const wxString\& }{name = ``scrolledWindow"}}
114
115 Constructor.
116
117 \wxheading{Parameters}
118
119 \docparam{parent}{Parent window.}
120
121 \docparam{id}{Window identifier. A value of -1 indicates a default value.}
122
123 \docparam{pos}{Window position. If a position of (-1, -1) is specified then a default position
124 is chosen.}
125
126 \docparam{size}{Window size. If a size of (-1, -1) is specified then the window is sized
127 appropriately.}
128
129 \docparam{style}{Window style. See \helpref{wxScrolledWindow}{wxscrolledwindow}.}
130
131 \docparam{name}{Window name.}
132
133 \wxheading{Remarks}
134
135 The window is initially created without visible scrollbars.
136 Call \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars} to
137 specify how big the virtual window size should be.
138
139 \membersection{wxScrolledWindow::\destruct{wxScrolledWindow}}
140
141 \func{}{\destruct{wxScrolledWindow}}{\void}
142
143 Destructor.
144
145 \membersection{wxScrolledWindow::CalcScrolledPosition}\label{wxscrolledwindowcalcscrolledposition}
146
147 \constfunc{void}{CalcScrolledPosition}{
148 \param{int }{x},
149 \param{int }{y},
150 \param{int *}{xx}
151 \param{int *}{yy}}
152
153 Translates the logical coordinates to the device ones. For example, if a window is
154 scrolled 10 pixels to the bottom, the device coordinates of the origin are (0, 0)
155 (as always), but the logical coordinates are (0, 10) and so the call to
156 CalcScrolledPosition(0, 10, \&xx, \&yy) will return 0 in yy.
157
158 \wxheading{See also}
159
160 \helpref{CalcUnscrolledPosition}{wxscrolledwindowcalcunscrolledposition}
161
162 \pythonnote{The wxPython version of this methods accepts only two
163 parameters and returns xx and yy as a tuple of values.}
164
165 \perlnote{In wxPerl this method takes two parameters and returns a
166 2-element list {\tt ( xx, yy )}.}
167
168 \membersection{wxScrolledWindow::CalcUnscrolledPosition}\label{wxscrolledwindowcalcunscrolledposition}
169
170 \constfunc{void}{CalcUnscrolledPosition}{
171 \param{int }{x},
172 \param{int }{y},
173 \param{int *}{xx}
174 \param{int *}{yy}}
175
176 Translates the device coordinates to the logical ones. For example, if a window is
177 scrolled 10 pixels to the bottom, the device coordinates of the origin are (0, 0)
178 (as always), but the logical coordinates are (0, 10) and so the call to
179 CalcUnscrolledPosition(0, 0, \&xx, \&yy) will return 10 in yy.
180
181 \wxheading{See also}
182
183 \helpref{CalcScrolledPosition}{wxscrolledwindowcalcscrolledposition}
184
185 \pythonnote{The wxPython version of this methods accepts only two
186 parameters and returns xx and yy as a tuple of values.}
187
188 \perlnote{In wxPerl this method takes two parameters and returns a
189 2-element list {\tt ( xx, yy )}.}
190
191 \membersection{wxScrolledWindow::Create}\label{wxscrolledwindowcreate}
192
193 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID }{id = -1},\rtfsp
194 \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
195 \param{long}{ style = wxHSCROLL \pipe wxVSCROLL}, \param{const wxString\& }{name = ``scrolledWindow"}}
196
197 Creates the window for two-step construction. Derived classes
198 should call or replace this function. See \helpref{wxScrolledWindow::wxScrolledWindow}{wxscrolledwindowconstr}\rtfsp
199 for details.
200
201 \membersection{wxScrolledWindow::EnableScrolling}\label{wxscrolledwindowenablescrolling}
202
203 \func{void}{EnableScrolling}{\param{const bool}{ xScrolling}, \param{const bool}{ yScrolling}}
204
205 Enable or disable physical scrolling in the given direction. Physical
206 scrolling is the physical transfer of bits up or down the
207 screen when a scroll event occurs. If the application scrolls by a
208 variable amount (e.g. if there are different font sizes) then physical
209 scrolling will not work, and you should switch it off. Note that you
210 will have to reposition child windows yourself, if physical scrolling
211 is disabled.
212
213 \wxheading{Parameters}
214
215 \docparam{xScrolling}{If true, enables physical scrolling in the x direction.}
216
217 \docparam{yScrolling}{If true, enables physical scrolling in the y direction.}
218
219 \wxheading{Remarks}
220
221 Physical scrolling may not be available on all platforms. Where it is available, it is enabled
222 by default.
223
224 \membersection{wxScrolledWindow::GetScrollPixelsPerUnit}\label{wxscrolledwindowgetscrollpixelsperunit}
225
226 \constfunc{void}{GetScrollPixelsPerUnit}{\param{int* }{xUnit}, \param{int* }{yUnit}}
227
228 Get the number of pixels per scroll unit (line), in each direction, as set
229 by \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars}. A value of zero indicates no
230 scrolling in that direction.
231
232 \wxheading{Parameters}
233
234 \docparam{xUnit}{Receives the number of pixels per horizontal unit.}
235
236 \docparam{yUnit}{Receives the number of pixels per vertical unit.}
237
238 \wxheading{See also}
239
240 \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars},\rtfsp
241 \helpref{wxScrolledWindow::GetVirtualSize}{wxscrolledwindowgetvirtualsize}
242
243 \pythonnote{The wxPython version of this methods accepts no
244 parameters and returns a tuple of values for xUnit and yUnit.}
245
246 \perlnote{In wxPerl this method takes no parameters and returns a
247 2-element list {\tt ( xUnit, yUnit )}.}
248
249 \membersection{wxScrolledWindow::GetViewStart}\label{wxscrolledwindowgetviewstart}
250
251 \constfunc{void}{GetViewStart}{\param{int* }{x}, \param{int* }{ y}}
252
253 Get the position at which the visible portion of the window starts.
254
255 \wxheading{Parameters}
256
257 \docparam{x}{Receives the first visible x position in scroll units.}
258
259 \docparam{y}{Receives the first visible y position in scroll units.}
260
261 \wxheading{Remarks}
262
263 If either of the scrollbars is not at the home position, {\it x} and/or
264 \rtfsp{\it y} will be greater than zero. Combined with \helpref{wxWindow::GetClientSize}{wxwindowgetclientsize},
265 the application can use this function to efficiently redraw only the
266 visible portion of the window. The positions are in logical scroll
267 units, not pixels, so to convert to pixels you will have to multiply
268 by the number of pixels per scroll increment.
269
270 \wxheading{See also}
271
272 \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars}
273
274 \pythonnote{The wxPython version of this methods accepts no
275 parameters and returns a tuple of values for x and y.}
276
277 \perlnote{In wxPerl this method takes no parameters and returns a
278 2-element list {\tt ( x, y )}.}
279
280 \membersection{wxScrolledWindow::GetVirtualSize}\label{wxscrolledwindowgetvirtualsize}
281
282 \constfunc{void}{GetVirtualSize}{\param{int* }{x}, \param{int* }{y}}
283
284 Gets the size in device units of the scrollable window area (as
285 opposed to the client size, which is the area of the window currently
286 visible).
287
288 \wxheading{Parameters}
289
290 \docparam{x}{Receives the length of the scrollable window, in pixels.}
291
292 \docparam{y}{Receives the height of the scrollable window, in pixels.}
293
294 \wxheading{Remarks}
295
296 Use \helpref{wxDC::DeviceToLogicalX}{wxdcdevicetologicalx} and \helpref{wxDC::DeviceToLogicalY}{wxdcdevicetologicaly}\rtfsp
297 to translate these units to logical units.
298
299 \wxheading{See also}
300
301 \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars},\rtfsp
302 \helpref{wxScrolledWindow::GetScrollPixelsPerUnit}{wxscrolledwindowgetscrollpixelsperunit}
303
304 \pythonnote{The wxPython version of this methods accepts no
305 parameters and returns a tuple of values for x and y.}
306
307 \perlnote{In wxPerl this method takes no parameters and returns a
308 2-element list {\tt ( x, y )}.}
309
310 \membersection{wxScrolledWindow::IsRetained}\label{wxscrolledwindowisretained}
311
312 \constfunc{bool}{IsRetained}{\void}
313
314 Motif only: true if the window has a backing bitmap.
315
316 \membersection{wxScrolledWindow::PrepareDC}\label{wxscrolledwindowpreparedc}
317
318 \func{void}{PrepareDC}{\param{wxDC\& }{dc}}
319
320 Call this function to prepare the device context for drawing a scrolled image. It
321 sets the device origin according to the current scroll position.
322
323 PrepareDC is called automatically within the default wxScrolledWindow::OnPaint event
324 handler, so your \helpref{wxScrolledWindow::OnDraw}{wxscrolledwindowondraw} override
325 will be passed a 'pre-scrolled' device context. However, if you wish to draw from
326 outside of OnDraw (via OnPaint), or you wish to implement OnPaint yourself, you must
327 call this function yourself. For example:
328
329 \begin{verbatim}
330 void MyWindow::OnEvent(wxMouseEvent& event)
331 {
332 wxClientDC dc(this);
333 PrepareDC(dc);
334
335 dc.SetPen(*wxBLACK_PEN);
336 float x, y;
337 event.Position(&x, &y);
338 if (xpos > -1 && ypos > -1 && event.Dragging())
339 {
340 dc.DrawLine(xpos, ypos, x, y);
341 }
342 xpos = x;
343 ypos = y;
344 }
345 \end{verbatim}
346
347 \membersection{wxScrolledWindow::OnDraw}\label{wxscrolledwindowondraw}
348
349 \func{virtual void}{OnDraw}{\param{wxDC\& }{dc}}
350
351 Called by the default paint event handler to allow the application to define
352 painting behaviour without having to worry about calling
353 \helpref{wxScrolledWindow::PrepareDC}{wxscrolledwindowpreparedc}.
354
355 Instead of overriding this function you may also just process the paint event
356 in the derived class as usual, but then you will have to call PrepareDC()
357 yourself.
358
359 \membersection{wxScrolledWindow::Scroll}\label{wxscrolledwindowscroll}
360
361 \func{void}{Scroll}{\param{int}{ x}, \param{int}{ y}}
362
363 Scrolls a window so the view start is at the given point.
364
365 \wxheading{Parameters}
366
367 \docparam{x}{The x position to scroll to, in scroll units.}
368
369 \docparam{y}{The y position to scroll to, in scroll units.}
370
371 \wxheading{Remarks}
372
373 The positions are in scroll units, not pixels, so to convert to pixels you
374 will have to multiply by the number of pixels per scroll increment.
375 If either parameter is -1, that position will be ignored (no change in
376 that direction).
377
378 \wxheading{See also}
379
380 \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars},\rtfsp
381 \helpref{wxScrolledWindow::GetScrollPixelsPerUnit}{wxscrolledwindowgetscrollpixelsperunit}
382
383 \membersection{wxScrolledWindow::SetScrollbars}\label{wxscrolledwindowsetscrollbars}
384
385 \func{void}{SetScrollbars}{\param{int}{ pixelsPerUnitX}, \param{int}{ pixelsPerUnitY},\rtfsp
386 \param{int}{ noUnitsX}, \param{int}{ noUnitsY},\rtfsp
387 \param{int }{xPos = 0}, \param{int}{ yPos = 0},\rtfsp
388 \param{bool }{noRefresh = false}}
389
390 Sets up vertical and/or horizontal scrollbars.
391
392 \wxheading{Parameters}
393
394 \docparam{pixelsPerUnitX}{Pixels per scroll unit in the horizontal direction.}
395
396 \docparam{pixelsPerUnitY}{Pixels per scroll unit in the vertical direction.}
397
398 \docparam{noUnitsX}{Number of units in the horizontal direction.}
399
400 \docparam{noUnitsY}{Number of units in the vertical direction.}
401
402 \docparam{xPos}{Position to initialize the scrollbars in the horizontal direction, in scroll units.}
403
404 \docparam{yPos}{Position to initialize the scrollbars in the vertical direction, in scroll units.}
405
406 \docparam{noRefresh}{Will not refresh window if true.}
407
408 \wxheading{Remarks}
409
410 The first pair of parameters give the number of pixels per `scroll step', i.e. amount
411 moved when the up or down scroll arrows are pressed.
412 The second pair gives the length of scrollbar in scroll steps, which sets the size of the virtual
413 window.
414
415 {\it xPos} and {\it yPos} optionally specify a position to scroll to immediately.
416
417 For example, the following gives a window horizontal and vertical
418 scrollbars with 20 pixels per scroll step, and a size of 50 steps (1000
419 pixels) in each direction.
420
421 \begin{verbatim}
422 window->SetScrollbars(20, 20, 50, 50);
423 \end{verbatim}
424
425 wxScrolledWindow manages the page size itself,
426 using the current client window size as the page size.
427
428 Note that for more sophisticated scrolling applications, for example where
429 scroll steps may be variable according to the position in the document, it will be
430 necessary to derive a new class from wxWindow, overriding {\bf OnSize} and
431 adjusting the scrollbars appropriately.
432
433 \wxheading{See also}
434
435 \helpref{wxWindow::SetVirtualSize}{wxwindowsetvirtualsize}
436
437 \membersection{wxScrolledWindow::SetScrollRate}\label{wxscrolledwindowsetscrollrate}
438
439 \func{void}{SetScrollRate}{\param{int}{ xstep}, \param{int}{ ystep}}
440
441 Set the horizontal and vertical scrolling increment only. See the pixelsPerUnit
442 parameter in SetScrollbars.
443
444 \membersection{wxScrolledWindow::SetTargetWindow}\label{wxscrolledwindowsettargetwindow}
445
446 \func{void}{SetTargetWindow}{\param{wxWindow* }{window}}
447
448 Call this function to tell wxScrolledWindow to perform the actual scrolling on
449 a different window (and not on itself).
450