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