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