1wxScrolledWindow(3)        Erlang Module Definition        wxScrolledWindow(3)
2
3
4

NAME

6       wxScrolledWindow - The wxScrolled (not implemented in wx) class manages
7       scrolling for its client area, transforming the  coordinates  according
8       to  the  scrollbar  positions,  and setting the scroll positions, thumb
9       sizes and ranges according to the area in view.
10

DESCRIPTION

12       There are two commonly used (but not the  only  possible!)  specializa‐
13       tions of this class:
14
15       Note:  See  wxScrolled::Create() (not implemented in wx) if you want to
16       use wxScrolled (not implemented in wx) with a custom class.
17
18       Starting from version 2.4 of wxWidgets, there are several ways to use a
19       ?wxScrolledWindow (and now wxScrolled (not implemented in wx)). In par‐
20       ticular, there are three ways to set the size of the scrolling area:
21
22       One way is to set the scrollbars directly using a  call  to  setScroll‐
23       bars/6. This is the way it used to be in any previous version of wxWid‐
24       gets and it will be kept for backwards compatibility.
25
26       An additional method of manual control, which requires  a  little  less
27       computation of your own, is to set the total size of the scrolling area
28       by calling either wxWindow:setVirtualSize/3,  or  wxWindow:fitInside/1,
29       and setting the scrolling increments for it by calling setScrollRate/3.
30       Scrolling in some orientation is enabled by setting a  non-zero  incre‐
31       ment for it.
32
33       The most automatic and newest way is to simply let sizers determine the
34       scrolling area. This is now the default when you set an interior  sizer
35       into a wxScrolled (not implemented in wx) with wxWindow:setSizer/3. The
36       scrolling area will be set to the size requested by the sizer  and  the
37       scrollbars  will be assigned for each orientation according to the need
38       for them and the scrolling increment set by setScrollRate/3. As  above,
39       scrolling  is  only  enabled in orientations with a non-zero increment.
40       You can influence the minimum size of the scrolled area controlled by a
41       sizer  by  calling wxWindow::SetVirtualSizeHints(). (Calling setScroll‐
42       bars/6 has analogous effects in wxWidgets 2.4 - in  later  versions  it
43       may not continue to override the sizer.)
44
45       Note  that  if  maximum  size  hints  are  still  supported  by  wxWin‐
46       dow::SetVirtualSizeHints(), use them at your own dire risk. They may or
47       may  not  have  been removed for 2.4, but it really only makes sense to
48       set  minimum  size  hints  here.  We  should  probably  replace  wxWin‐
49       dow::SetVirtualSizeHints()  with wxWindow::SetMinVirtualSize() or simi‐
50       lar and remove it entirely in future.
51
52       As with all windows, an application can draw onto a wxScrolled (not im‐
53       plemented in wx) using a device context.
54
55       You  have  the option of handling the OnPaint handler or overriding the
56       wxScrolled::OnDraw() (not implemented in wx) function, which is  passed
57       a pre-scrolled device context (prepared by doPrepareDC/2).
58
59       If you don't wish to calculate your own scrolling, you must call doPre‐
60       pareDC/2 when not drawing from within OnDraw() (not implemented in wx),
61       to  set  the device origin for the device context according to the cur‐
62       rent scroll position.
63
64       A wxScrolled (not implemented in wx) will normally  scroll  itself  and
65       therefore  its  child  windows  as well. It might however be desired to
66       scroll a different window than itself: e.g. when  designing  a  spread‐
67       sheet,  you  will normally only have to scroll the (usually white) cell
68       area, whereas the (usually grey) label area will  scroll  very  differ‐
69       ently.  For  this special purpose, you can call setTargetWindow/2 which
70       means that pressing the scrollbars will scroll a different window.
71
72       Note that the underlying system knows nothing about  scrolling  coordi‐
73       nates,  so  that all system functions (mouse events, expose events, re‐
74       fresh calls etc) as well as the position of subwindows are relative  to
75       the  "physical"  origin  of  the  scrolled window. If the user insert a
76       child window at position (10,10) and scrolls the window down 100 pixels
77       (moving  the  child  window  out of the visible area), the child window
78       will report a position of (10,-90).
79
80       Styles
81
82       This class supports the following styles:
83
84       Note: Don't confuse wxScrollWinEvents  generated  by  this  class  with
85       wxScrollEvent objects generated by wxScrollBar and wxSlider.
86
87       Remark:  Use  wxScrolled (not implemented in wx) for applications where
88       the user scrolls by a fixed amount, and where a 'page'  can  be  inter‐
89       preted  to  be  the current visible portion of the window. For more so‐
90       phisticated applications, use the wxScrolled (not  implemented  in  wx)
91       implementation  as  a  guide  to build your own scroll behaviour or use
92       wxVScrolledWindow (not implemented in wx) or its variants.
93
94       Since: The wxScrolled (not implemented in  wx)  template  exists  since
95       version 2.9.0. In older versions, only ?wxScrolledWindow (equivalent of
96       wxScrolled<wxPanel>) was available.
97
98       See: wxScrollBar, wxClientDC, wxPaintDC, wxVScrolledWindow (not  imple‐
99       mented in wx), wxHScrolledWindow (not implemented in wx), wxHVScrolled‐
100       Window (not implemented in wx)
101
102       This class is derived (and can use functions)  from:  wxPanel  wxWindow
103       wxEvtHandler
104
105       wxWidgets docs: wxScrolledWindow
106

EVENTS

108       Event  types  emitted from this class: scrollwin_top, scrollwin_bottom,
109       scrollwin_lineup, scrollwin_linedown, scrollwin_pageup, scrollwin_page‐
110       down, scrollwin_thumbtrack, scrollwin_thumbrelease
111

DATA TYPES

113       wxScrolledWindow() = wx:wx_object()
114

EXPORTS

116       new() -> wxScrolledWindow()
117
118              Default constructor.
119
120       new(Parent) -> wxScrolledWindow()
121
122              Types:
123
124                 Parent = wxWindow:wxWindow()
125
126       new(Parent, Options :: [Option]) -> wxScrolledWindow()
127
128              Types:
129
130                 Parent = wxWindow:wxWindow()
131                 Option =
132                     {winid, integer()} |
133                     {pos, {X :: integer(), Y :: integer()}} |
134                     {size, {W :: integer(), H :: integer()}} |
135                     {style, integer()}
136
137              Constructor.
138
139              Remark:  The window is initially created without visible scroll‐
140              bars. Call setScrollbars/6 to specify how big the virtual window
141              size should be.
142
143       calcScrolledPosition(This, Pt) -> {X :: integer(), Y :: integer()}
144
145              Types:
146
147                 This = wxScrolledWindow()
148                 Pt = {X :: integer(), Y :: integer()}
149
150       calcScrolledPosition(This, X, Y) ->
151                               {Xx :: integer(), Yy :: integer()}
152
153              Types:
154
155                 This = wxScrolledWindow()
156                 X = Y = integer()
157
158              Translates the logical coordinates to the device ones.
159
160              For  example,  if  a window is scrolled 10 pixels to the bottom,
161              the device coordinates of the origin are (0, 0) (as always), but
162              the  logical  coordinates  are  (0, 10) and so the call to Calc‐
163              ScrolledPosition(0, 10, xx, yy) will return 0 in yy.
164
165              See: calcUnscrolledPosition/3
166
167       calcUnscrolledPosition(This, Pt) ->
168                                 {X :: integer(), Y :: integer()}
169
170              Types:
171
172                 This = wxScrolledWindow()
173                 Pt = {X :: integer(), Y :: integer()}
174
175       calcUnscrolledPosition(This, X, Y) ->
176                                 {Xx :: integer(), Yy :: integer()}
177
178              Types:
179
180                 This = wxScrolledWindow()
181                 X = Y = integer()
182
183              Translates the device coordinates to the logical ones.
184
185              For example, if a window is scrolled 10 pixels  to  the  bottom,
186              the device coordinates of the origin are (0, 0) (as always), but
187              the logical coordinates are (0, 10) and so the call  to  CalcUn‐
188              scrolledPosition(0, 0, xx, yy) will return 10 in yy.
189
190              See: calcScrolledPosition/3
191
192       enableScrolling(This, XScrolling, YScrolling) -> ok
193
194              Types:
195
196                 This = wxScrolledWindow()
197                 XScrolling = YScrolling = boolean()
198
199              Enable or disable use of wxWindow:scrollWindow/4 for scrolling.
200
201              By default, when a scrolled window is logically scrolled, wxWin‐
202              dow:scrollWindow/4 is called  on  the  underlying  window  which
203              scrolls the window contents and only invalidates the part of the
204              window newly brought into view. If false is passed as  an  argu‐
205              ment,  then this "physical scrolling" is disabled and the window
206              is entirely invalidated  whenever  it  is  scrolled  by  calling
207              wxWindow:refresh/2.
208
209              It  should be rarely necessary to disable physical scrolling, so
210              this method shouldn't be called in normal circumstances.
211
212       getScrollPixelsPerUnit(This) ->
213                                 {XUnit :: integer(), YUnit :: integer()}
214
215              Types:
216
217                 This = wxScrolledWindow()
218
219              Get the number of pixels per scroll unit (line), in each  direc‐
220              tion, as set by setScrollbars/6.
221
222              A value of zero indicates no scrolling in that direction.
223
224              See: setScrollbars/6, wxWindow:getVirtualSize/1
225
226       getViewStart(This) -> {X :: integer(), Y :: integer()}
227
228              Types:
229
230                 This = wxScrolledWindow()
231
232              This  is  a simple overload of GetViewStart(int*,int*); see that
233              function for more info.
234
235       doPrepareDC(This, Dc) -> ok
236
237              Types:
238
239                 This = wxScrolledWindow()
240                 Dc = wxDC:wxDC()
241
242              Call this function to prepare the device context for  drawing  a
243              scrolled image.
244
245              It  sets the device origin according to the current scroll posi‐
246              tion. doPrepareDC/2 is called automatically within  the  default
247              wxEVT_PAINT  event handler, so your OnDraw() (not implemented in
248              wx) override will be passed  an  already  'pre-scrolled'  device
249              context.  However,  if you wish to draw from outside of OnDraw()
250              (not implemented in wx) (e.g. from  your  own  wxEVT_PAINT  han‐
251              dler), you must call this function yourself.
252
253              For example:
254
255              Notice that the function sets the origin by moving it relatively
256              to the current origin position, so you shouldn't change the ori‐
257              gin  before calling doPrepareDC/2 or, if you do, reset it to (0,
258              0) later. If you call  doPrepareDC/2  immediately  after  device
259              context  creation, as in the example above, this problem doesn't
260              arise, of course, so it is customary to do it like this.
261
262       prepareDC(This, Dc) -> ok
263
264              Types:
265
266                 This = wxScrolledWindow()
267                 Dc = wxDC:wxDC()
268
269              This function is for backwards  compatibility  only  and  simply
270              calls doPrepareDC/2 now.
271
272              Notice  that  it is not called by the default paint event handle
273              (doPrepareDC/2 is), so overriding this method  in  your  derived
274              class is useless.
275
276       scroll(This, Pt) -> ok
277
278              Types:
279
280                 This = wxScrolledWindow()
281                 Pt = {X :: integer(), Y :: integer()}
282
283              This  is  an  overload  of  scroll/3; see that function for more
284              info.
285
286       scroll(This, X, Y) -> ok
287
288              Types:
289
290                 This = wxScrolledWindow()
291                 X = Y = integer()
292
293              Scrolls a window so the view start is at the given point.
294
295              Remark: The positions are in scroll units,  not  pixels,  so  to
296              convert  to  pixels  you  will have to multiply by the number of
297              pixels per scroll increment. If either parameter is  ?wxDefault‐
298              Coord (-1), that position will be ignored (no change in that di‐
299              rection).
300
301              See: setScrollbars/6, getScrollPixelsPerUnit/1
302
303       setScrollbars(This, PixelsPerUnitX, PixelsPerUnitY, NoUnitsX,
304                     NoUnitsY) ->
305                        ok
306
307              Types:
308
309                 This = wxScrolledWindow()
310                 PixelsPerUnitX = PixelsPerUnitY = NoUnitsX = NoUnitsY = inte‐
311                 ger()
312
313       setScrollbars(This, PixelsPerUnitX, PixelsPerUnitY, NoUnitsX,
314                     NoUnitsY,
315                     Options :: [Option]) ->
316                        ok
317
318              Types:
319
320                 This = wxScrolledWindow()
321                 PixelsPerUnitX = PixelsPerUnitY = NoUnitsX = NoUnitsY = inte‐
322                 ger()
323                 Option =
324                     {xPos, integer()} | {yPos, integer()} | {noRefresh, bool‐
325                 ean()}
326
327              Sets up vertical and/or horizontal scrollbars.
328
329              The  first  pair  of  parameters  give  the number of pixels per
330              'scroll step', i.e. amount moved when the up or down scroll  ar‐
331              rows  are pressed. The second pair gives the length of scrollbar
332              in scroll steps, which sets the size of the virtual window.
333
334              xPos and yPos optionally specify a position to scroll to immedi‐
335              ately.
336
337              For  example, the following gives a window horizontal and verti‐
338              cal scrollbars with 20 pixels per scroll step, and a size of  50
339              steps (1000 pixels) in each direction:
340
341              wxScrolled (not implemented in wx) manages the page size itself,
342              using the current client window size as the page size.
343
344              Note that for more sophisticated scrolling applications, for ex‐
345              ample  where scroll steps may be variable according to the posi‐
346              tion in the document, it will be necessary to derive a new class
347              from  wxWindow, overriding OnSize() and adjusting the scrollbars
348              appropriately.
349
350              See: wxWindow:setVirtualSize/3
351
352       setScrollRate(This, Xstep, Ystep) -> ok
353
354              Types:
355
356                 This = wxScrolledWindow()
357                 Xstep = Ystep = integer()
358
359              Set the horizontal and vertical scrolling increment only.
360
361              See the pixelsPerUnit parameter in setScrollbars/6.
362
363       setTargetWindow(This, Window) -> ok
364
365              Types:
366
367                 This = wxScrolledWindow()
368                 Window = wxWindow:wxWindow()
369
370              Call this function to tell wxScrolled (not implemented in wx) to
371              perform  the  actual scrolling on a different window (and not on
372              itself).
373
374              This method is useful when only a part of the window  should  be
375              scrolled.  A  typical example is a control consisting of a fixed
376              header and the scrollable contents window:  the  scrollbars  are
377              attached  to  the main window itself, hence it, and not the con‐
378              tents window must be derived from wxScrolled (not implemented in
379              wx),  but  only  the contents window scrolls when the scrollbars
380              are used. To implement such setup, you need to call this  method
381              with the contents window as argument.
382
383              Notice  that  if this method is used, GetSizeAvailableForScroll‐
384              Target() (not implemented in wx) method must be overridden.
385
386       destroy(This :: wxScrolledWindow()) -> ok
387
388              Destroys the object.
389
390
391
392wxWidgets team.                    wx 2.2.1                wxScrolledWindow(3)
Impressum