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