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