]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/scrolwin.tex
Added periods
[wxWidgets.git] / docs / latex / wx / scrolwin.tex
... / ...
CommitLineData
1\section{\class{wxScrolledWindow}}\label{wxscrolledwindow}
2
3The wxScrolledWindow class manages scrolling for its client area, transforming
4the coordinates according to the scrollbar positions, and setting the
5scroll positions, thumb sizes and ranges according to the area in view.
6
7Starting from version 2.4 of wxWidgets, there are several ways to use a
8wxScrolledWindow. In particular, there are now three ways to set the
9size of the scrolling area:
10
11One way is to set the scrollbars directly using a call to
12\helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars}.
13This is the way it used to be in any previous version of wxWidgets
14and it will be kept for backwards compatibility.
15
16An additional method of manual control, which requires a little less
17computation of your own, is to set the total size of the scrolling area by
18calling either \helpref{wxWindow::SetVirtualSize}{wxwindowsetvirtualsize},
19or \helpref{wxWindow::FitInside}{wxwindowfitinside}, and setting the
20scrolling increments for it by calling
21\helpref{wxScrolledWindow::SetScrollRate}{wxscrolledwindowsetscrollrate}.
22Scrolling in some orientation is enabled by setting a non-zero increment
23for it.
24
25The most automatic and newest way is to simply let sizers determine the
26scrolling area. This is now the default when you set an interior sizer
27into a wxScrolledWindow with \helpref{wxWindow::SetSizer}{wxwindowsetsizer}.
28The scrolling area will be set to the size requested by the sizer and
29the scrollbars will be assigned for each orientation according to the need
30for them and the scrolling increment set by
31\helpref{wxScrolledWindow::SetScrollRate}{wxscrolledwindowsetscrollrate}.
32As above, scrolling is only enabled in orientations with a non-zero
33increment. You can influence the minimum size of the scrolled area
34controlled 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
40Note: if Maximum size hints are still supported by SetVirtualSizeHints, use
41them at your own dire risk. They may or may not have been removed for 2.4,
42but it really only makes sense to set minimum size hints here. We should
43probably replace SetVirtualSizeHints with SetMinVirtualSize or similar
44and remove it entirely in future.
45
46As with all windows, an application can draw onto a wxScrolledWindow using
47a \helpref{device context}{dcoverview}.
48
49You have the option of handling the OnPaint handler
50or overriding the \helpref{OnDraw}{wxscrolledwindowondraw} function, which is
51passed a pre-scrolled device context (prepared by
52\helpref{DoPrepareDC}{wxscrolledwindowdopreparedc}).
53
54If you don't wish to calculate your own scrolling, you must call DoPrepareDC when not drawing from
55within OnDraw, to set the device origin for the device context according to the current
56scroll position.
57
58A wxScrolledWindow will normally scroll itself and therefore its child windows as well. It
59might however be desired to scroll a different window than itself: e.g. when designing a
60spreadsheet, 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
62call \helpref{SetTargetWindow}{wxscrolledwindowsettargetwindow} which means that pressing
63the scrollbars will scroll a different window.
64
65Note that the underlying system knows nothing about scrolling coordinates, so that all system
66functions (mouse events, expose events, refresh calls etc) as well as the position of subwindows
67are relative to the "physical" origin of the scrolled window. If the user insert a child window at
68position (10,10) and scrolls the window down 100 pixels (moving the child window out of the visible
69area), 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
94See also \helpref{window styles overview}{windowstyles}.
95
96\wxheading{Remarks}
97
98Use wxScrolledWindow for applications where the user scrolls by a fixed amount, and
99where a `page' can be interpreted to be the current visible portion of the window. For
100more sophisticated applications, use the wxScrolledWindow implementation as a guide
101to 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
115Default 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
121Constructor.
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
130is chosen.}
131
132\docparam{size}{Window size. If a size of (-1, -1) is specified then the window is sized
133appropriately.}
134
135\docparam{style}{Window style. See \helpref{wxScrolledWindow}{wxscrolledwindow}.}
136
137\docparam{name}{Window name.}
138
139\wxheading{Remarks}
140
141The window is initially created without visible scrollbars.
142Call \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars} to
143specify how big the virtual window size should be.
144
145
146\membersection{wxScrolledWindow::\destruct{wxScrolledWindow}}\label{wxscrolledwindowdtor}
147
148\func{}{\destruct{wxScrolledWindow}}{\void}
149
150Destructor.
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
161Translates the logical coordinates to the device ones. For example, if a window is
162scrolled 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
164CalcScrolledPosition(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
171parameters and returns xx and yy as a tuple of values.}
172
173\perlnote{In wxPerl this method takes two parameters and returns a
1742-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
185Translates the device coordinates to the logical ones. For example, if a window is
186scrolled 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
188CalcUnscrolledPosition(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
195parameters and returns xx and yy as a tuple of values.}
196
197\perlnote{In wxPerl this method takes two parameters and returns a
1982-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
207Creates the window for two-step construction. Derived classes
208should call or replace this function. See \helpref{wxScrolledWindow::wxScrolledWindow}{wxscrolledwindowctor}\rtfsp
209for details.
210
211
212\membersection{wxScrolledWindow::EnableScrolling}\label{wxscrolledwindowenablescrolling}
213
214\func{void}{EnableScrolling}{\param{bool}{ xScrolling}, \param{bool}{ yScrolling}}
215
216Enable or disable physical scrolling in the given direction. Physical
217scrolling is the physical transfer of bits up or down the
218screen when a scroll event occurs. If the application scrolls by a
219variable amount (e.g. if there are different font sizes) then physical
220scrolling will not work, and you should switch it off. Note that you
221will have to reposition child windows yourself, if physical scrolling
222is 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
232Physical scrolling may not be available on all platforms. Where it is available, it is enabled
233by default.
234
235
236\membersection{wxScrolledWindow::GetScrollPixelsPerUnit}\label{wxscrolledwindowgetscrollpixelsperunit}
237
238\constfunc{void}{GetScrollPixelsPerUnit}{\param{int* }{xUnit}, \param{int* }{yUnit}}
239
240Get the number of pixels per scroll unit (line), in each direction, as set
241by \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars}. A value of zero indicates no
242scrolling 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
256parameters and returns a tuple of values for xUnit and yUnit.}
257
258\perlnote{In wxPerl this method takes no parameters and returns a
2592-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
266Get 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
276If 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},
278the application can use this function to efficiently redraw only the
279visible portion of the window. The positions are in logical scroll
280units, not pixels, so to convert to pixels you will have to multiply
281by 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
288parameters and returns a tuple of values for x and y.}
289
290\perlnote{In wxPerl this method takes no parameters and returns a
2912-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
298Gets the size in device units of the scrollable window area (as
299opposed to the client size, which is the area of the window currently
300visible).
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
310Use \helpref{wxDC::DeviceToLogicalX}{wxdcdevicetologicalx} and \helpref{wxDC::DeviceToLogicalY}{wxdcdevicetologicaly}\rtfsp
311to 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
319parameters and returns a tuple of values for x and y.}
320
321\perlnote{In wxPerl this method takes no parameters and returns a
3222-element list {\tt ( x, y )}.}
323
324
325\membersection{wxScrolledWindow::IsRetained}\label{wxscrolledwindowisretained}
326
327\constfunc{bool}{IsRetained}{\void}
328
329Motif 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
336Call this function to prepare the device context for drawing a scrolled image. It
337sets the device origin according to the current scroll position.
338
339DoPrepareDC is called automatically within the default wxScrolledWindow::OnPaint event
340handler, so your \helpref{wxScrolledWindow::OnDraw}{wxscrolledwindowondraw} override
341will be passed a 'pre-scrolled' device context. However, if you wish to draw from
342outside of OnDraw (via OnPaint), or you wish to implement OnPaint yourself, you must
343call this function yourself. For example:
344
345\begin{verbatim}
346void 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
368Called by the default paint event handler to allow the application to define
369painting behaviour without having to worry about calling
370\helpref{wxScrolledWindow::DoPrepareDC}{wxscrolledwindowdopreparedc}.
371
372Instead of overriding this function you may also just process the paint event
373in the derived class as usual, but then you will have to call DoPrepareDC()
374yourself.
375
376
377\membersection{wxScrolledWindow::PrepareDC}\label{wxscrolledwindowpreparedc}
378
379\func{void}{PrepareDC}{\param{wxDC\& }{dc}}
380
381This 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
384overriding 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
391Scrolls 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
401The positions are in scroll units, not pixels, so to convert to pixels you
402will have to multiply by the number of pixels per scroll increment.
403If either parameter is -1, that position will be ignored (no change in
404that 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
419Sets 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
439The first pair of parameters give the number of pixels per `scroll step', i.e. amount
440moved when the up or down scroll arrows are pressed.
441The second pair gives the length of scrollbar in scroll steps, which sets the size of the virtual
442window.
443
444{\it xPos} and {\it yPos} optionally specify a position to scroll to immediately.
445
446For example, the following gives a window horizontal and vertical
447scrollbars with 20 pixels per scroll step, and a size of 50 steps (1000
448pixels) in each direction.
449
450\begin{verbatim}
451 window->SetScrollbars(20, 20, 50, 50);
452\end{verbatim}
453
454wxScrolledWindow manages the page size itself,
455using the current client window size as the page size.
456
457Note that for more sophisticated scrolling applications, for example where
458scroll steps may be variable according to the position in the document, it will be
459necessary to derive a new class from wxWindow, overriding {\bf OnSize} and
460adjusting 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
471Set the horizontal and vertical scrolling increment only. See the pixelsPerUnit
472parameter in SetScrollbars.
473
474
475\membersection{wxScrolledWindow::SetTargetWindow}\label{wxscrolledwindowsettargetwindow}
476
477\func{void}{SetTargetWindow}{\param{wxWindow* }{window}}
478
479Call this function to tell wxScrolledWindow to perform the actual scrolling on
480a different window (and not on itself).
481