1 \section{\class{wxScrolledWindow
}}\label{wxscrolledwindow
}
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.
7 As with all windows, an application can draw onto a wxScrolledWindow using a
\helpref{device context
}{dcoverview
}.
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
}).
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
17 \wxheading{Derived from
}
19 \helpref{wxPanel
}{wxpanel
}\\
20 \helpref{wxWindow
}{wxwindow
}\\
21 \helpref{wxEvtHandler
}{wxevthandler
}\\
22 \helpref{wxObject
}{wxobject
}
24 \wxheading{Include files
}
28 \wxheading{Window styles
}
31 \begin{twocollist
}\itemsep=
0pt
32 \twocolitem{\windowstyle{wxRETAINED
}}{Uses a backing pixmap to speed refreshes. Motif only.
}
35 See also
\helpref{window styles overview
}{windowstyles
}.
39 Use wxScrolledWindow for applications where the user scrolls by a fixed amount, and
40 where a `page' can be interpreted to be the current visible portion of the window. For
41 more sophisticated applications, use the wxScrolledWindow implementation as a guide
42 to build your own scroll behaviour.
46 \helpref{wxScrollBar
}{wxscrollbar
},
\helpref{wxClientDC
}{wxclientdc
},
\helpref{wxPaintDC
}{wxpaintdc
}
48 \latexignore{\rtfignore{\wxheading{Members
}}}
50 \membersection{wxScrolledWindow::wxScrolledWindow
}\label{wxscrolledwindowconstr
}
52 \func{}{wxScrolledWindow
}{\void}
56 \func{}{wxScrolledWindow
}{\param{wxWindow*
}{ parent
},
\param{wxWindowID
}{id = -
1},
\rtfsp
57 \param{const wxPoint\&
}{pos = wxDefaultPosition
},
\param{const wxSize\&
}{size = wxDefaultSize
},
\rtfsp
58 \param{long
}{ style = wxHSCROLL
\pipe wxVSCROLL
},
\param{const wxString\&
}{name = ``scrolledWindow"
}}
62 \wxheading{Parameters
}
64 \docparam{parent
}{Parent window.
}
66 \docparam{id
}{Window identifier. A value of -
1 indicates a default value.
}
68 \docparam{pos
}{Window position. If a position of (-
1, -
1) is specified then a default position
71 \docparam{size
}{Window size. If a size of (-
1, -
1) is specified then the window is sized
74 \docparam{style
}{Window style. See
\helpref{wxScrolledWindow
}{wxscrolledwindow
}.
}
76 \docparam{name
}{Window name.
}
80 The window is initially created without visible scrollbars.
81 Call
\helpref{wxScrolledWindow::SetScrollbars
}{wxscrolledwindowsetscrollbars
} to
82 specify how big the virtual window size should be.
84 \membersection{wxScrolledWindow::
\destruct{wxScrolledWindow
}}
86 \func{}{\destruct{wxScrolledWindow
}}{\void}
90 \membersection{wxScrolledWindow::CalcScrolledPosition
}\label{wxscrolledwindowcalcscrolledposition
}
92 \constfunc{void
}{CalcScrolledPosition
}{
98 Translates the logical coordinates to the device ones. For example, if a window is
99 scrolled
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
101 CalcScrolledPosition(
0,
0, \&xx, \&yy) will return
10 in yy.
105 \helpref{CalcUnscrolledPosition
}{wxscrolledwindowcalcunscrolledposition
}
107 \membersection{wxScrolledWindow::CalcUnscrolledPosition
}\label{wxscrolledwindowcalcunscrolledposition
}
109 \constfunc{void
}{CalcUnscrolledPosition
}{
115 Translates the device coordinates to the logical ones. For example, if a window is
116 scrolled
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
118 CalcUnscrolledPosition(
0,
10, \&xx, \&yy) will return
0 in yy.
122 \helpref{CalcScrolledPosition
}{wxscrolledwindowcalcscrolledposition
}
124 \membersection{wxScrolledWindow::Create
}\label{wxscrolledwindowcreate
}
126 \func{bool
}{Create
}{\param{wxWindow*
}{ parent
},
\param{wxWindowID
}{id = -
1},
\rtfsp
127 \param{const wxPoint\&
}{pos = wxDefaultPosition
},
\param{const wxSize\&
}{size = wxDefaultSize
},
\rtfsp
128 \param{long
}{ style = wxHSCROLL
\pipe wxVSCROLL
},
\param{const wxString\&
}{name = ``scrolledWindow"
}}
130 Creates the window for two-step construction. Derived classes
131 should call or replace this function. See
\helpref{wxScrolledWindow::wxScrolledWindow
}{wxscrolledwindowconstr
}\rtfsp
134 \membersection{wxScrolledWindow::EnableScrolling
}\label{wxscrolledwindowenablescrolling
}
136 \func{void
}{EnableScrolling
}{\param{const bool
}{ xScrolling
},
\param{const bool
}{ yScrolling
}}
138 Enable or disable physical scrolling in the given direction. Physical
139 scrolling is the physical transfer of bits up or down the
140 screen when a scroll event occurs. If the application scrolls by a
141 variable amount (e.g. if there are different font sizes) then physical
142 scrolling will not work, and you should switch it off.
144 \wxheading{Parameters
}
146 \docparam{xScrolling
}{If TRUE, enables physical scrolling in the x direction.
}
148 \docparam{yScrolling
}{If TRUE, enables physical scrolling in the y direction.
}
152 Physical scrolling may not be available on all platforms. Where it is available, it is enabled
155 \membersection{wxScrolledWindow::GetScrollPixelsPerUnit
}\label{wxscrolledwindowgetscrollpixelsperunit
}
157 \constfunc{void
}{GetScrollPixelsPerUnit
}{\param{int*
}{xUnit
},
\param{int*
}{yUnit
}}
159 Get the number of pixels per scroll unit (line), in each direction, as set
160 by
\helpref{wxScrolledWindow::SetScrollbars
}{wxscrolledwindowsetscrollbars
}. A value of zero indicates no
161 scrolling in that direction.
163 \wxheading{Parameters
}
165 \docparam{xUnit
}{Receives the number of pixels per horizontal unit.
}
167 \docparam{yUnit
}{Receives the number of pixels per vertical unit.
}
171 \helpref{wxScrolledWindow::SetScrollbars
}{wxscrolledwindowsetscrollbars
},
\rtfsp
172 \helpref{wxScrolledWindow::GetVirtualSize
}{wxscrolledwindowgetvirtualsize
}
174 \membersection{wxScrolledWindow::GetVirtualSize
}\label{wxscrolledwindowgetvirtualsize
}
176 \constfunc{void
}{GetVirtualSize
}{\param{int*
}{x
},
\param{int*
}{y
}}
178 Gets the size in device units of the scrollable window area (as
179 opposed to the client size, which is the area of the window currently
182 \wxheading{Parameters
}
184 \docparam{x
}{Receives the length of the scrollable window, in pixels.
}
186 \docparam{y
}{Receives the height of the scrollable window, in pixels.
}
190 Use
\helpref{wxDC::DeviceToLogicalX
}{wxdcdevicetologicalx
} and
\helpref{wxDC::DeviceToLogicalY
}{wxdcdevicetologicaly
}\rtfsp
191 to translate these units to logical units.
195 \helpref{wxScrolledWindow::SetScrollbars
}{wxscrolledwindowsetscrollbars
},
\rtfsp
196 \helpref{wxScrolledWindow::GetScrollPixelsPerUnit
}{wxscrolledwindowgetscrollpixelsperunit
}
198 \membersection{wxScrolledWindow::IsRetained
}\label{wxscrolledwindowisretained
}
200 \constfunc{bool
}{IsRetained
}{\void}
202 Motif only: TRUE if the window has a backing bitmap.
204 \membersection{wxScrolledWindow::PrepareDC
}\label{wxscrolledwindowpreparedc
}
206 \func{void
}{PrepareDC
}{\param{wxDC\&
}{dc
}}
208 Call this function to prepare the device context for drawing a scrolled image. It
209 sets the device origin according to the current scroll position.
211 PrepareDC is called automatically within the default wxScrolledWindow::OnPaint event
212 handler, so your
\helpref{wxScrolledWindow::OnDraw
}{wxscrolledwindowondraw
} override
213 will be passed a 'pre-scrolled' device context. However, if you wish to draw from
214 outside of OnDraw (via OnPaint), or you wish to implement OnPaint yourself, you must
215 call this function yourself. For example:
218 void MyWindow::OnEvent(wxMouseEvent& event)
223 dc.SetPen
(*wxBLACK_PEN);
225 event.Position(&x, &y);
226 if (xpos > -1 && ypos > -1 && event.Dragging())
228 dc.DrawLine(xpos, ypos, x, y);
235 \membersection{wxScrolledWindow::OnDraw}\label{wxscrolledwindowondraw}
237 \func{virtual void}{OnDraw}{\param{wxDC\& }{dc}}
239 Called by the default paint event handler to allow the application to define
240 painting behaviour without having to worry about calling
241 \helpref{wxScrolledWindow::PrepareDC}{wxscrolledwindowpreparedc}.
243 Instead of overriding this function you may also just process the paint event
244 in the derived class as usual, but then you will have to call PrepareDC()
247 \membersection{wxScrolledWindow::Scroll}\label{wxscrolledwindowscroll}
249 \func{void}{Scroll}{\param{int}{ x}, \param{int}{ y}}
251 Scrolls a window so the view start is at the given point.
253 \wxheading{Parameters}
255 \docparam{x}{The x position to scroll to, in scroll units.}
257 \docparam{y}{The y position to scroll to, in scroll units.}
261 The positions are in scroll units, not pixels, so to convert to pixels you
262 will have to multiply by the number of pixels per scroll increment.
263 If either parameter is -1, that position will be ignored (no change in
268 \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars},\rtfsp
269 \helpref{wxScrolledWindow::GetScrollPixelsPerUnit}{wxscrolledwindowgetscrollpixelsperunit}
271 \membersection{wxScrolledWindow::SetScrollbars}\label{wxscrolledwindowsetscrollbars}
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}}
277 Sets up vertical and/or horizontal scrollbars.
279 \wxheading{Parameters}
281 \docparam{pixelsPerUnitX}{Pixels per scroll unit in the horizontal direction.}
283 \docparam{pixelsPerUnitY}{Pixels per scroll unit in the vertical direction.}
285 \docparam{noUnitsX}{Number of units in the horizontal direction.}
287 \docparam{noUnitsY}{Number of units in the vertical direction.}
289 \docparam{xPos}{Position to initialize the scrollbars in the horizontal direction, in scroll units.}
291 \docparam{yPos}{Position to initialize the scrollbars in the vertical direction, in scroll units.}
295 The first pair of parameters give the number of pixels per `scroll step', i.e. amount
296 moved when the up or down scroll arrows are pressed.
297 The second pair gives the length of scrollbar in scroll steps, which sets the size of the virtual
300 {\it xPos} and {\it yPos} optionally specify a position to scroll to immediately.
302 For example, the following gives a window horizontal and vertical
303 scrollbars with 20 pixels per scroll step, and a size of 50 steps (1000
304 pixels) in each direction.
307 window->SetScrollbars(20, 20, 50, 50);
310 wxScrolledWindow manages the page size itself,
311 using the current client window size as the page size.
313 Note that for more sophisticated scrolling applications, for example where
314 scroll steps may be variable according to the position in the document, it will be
315 necessary to derive a new class from wxWindow, overriding {\bf OnSize} and
316 adjusting the scrollbars appropriately.
318 \membersection{wxScrolledWindow::ViewStart}\label{wxscrolledwindowviewstart}
320 \constfunc{void}{ViewStart}{\param{int* }{x}, \param{int* }{ y}}
322 Get the position at which the visible portion of the window starts.
324 \wxheading{Parameters}
326 \docparam{x}{Receives the first visible x position in scroll units.}
328 \docparam{y}{Receives the first visible y position in scroll units.}
332 If 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},
334 the application can use this function to efficiently redraw only the
335 visible portion of the window. The positions are in logical scroll
336 units, not pixels, so to convert to pixels you will have to multiply
337 by the number of pixels per scroll increment.
341 \helpref{wxScrolledWindow::SetScrollbars}{wxscrolledwindowsetscrollbars}