wxRuby Documentation Home


The ScrolledWindow class manages scrolling for its client area, transforming the coordinates according to the scrollbar positions, and setting the scroll positions, thumb sizes and ranges according to the area in view. There are several ways to set the size of the scrolling area.

Manual Control of Scrolling

One way is to set the scrollbars directly using a call to ScrolledWindow#set_scrollbars. This requires you to calculate the scrolling area size and increments yourself.

An additional method of manual control, which requires a little less computation of your own, is to set the total size of the scrolling area by calling either Window#set_virtual_size, or Window#fit_inside, and setting the scrolling increments for it by calling ScrolledWindow#set_scroll_rate. Scrolling in some orientation is enabled by setting a non zero increment for it.

Controlling Scrolling with Sizers

The most automatic way is to simply let sizers determine the scrolling area. This is now the default when you set an interior sizer into a ScrolledWindow with Window#set_sizer. The scrolling area will be set to the size requested by the sizer and the scrollbars will be assigned for each orientation according to the need for them and the scrolling increment set by ScrolledWindow#set_scroll_rate. As above, scrolling is only enabled in orientations with a non-zero increment. You can influence the minimum size of the scrolled area controlled by a sizer by calling Window#set_virtual_size_hints.

Drawing upon a ScrolledWindow

As with all windows, an application can draw onto a ScrolledWindow using a device context.

You have the option of handling the OnPaint handler or overriding the on_draw function, which is passed a pre-scrolled device context (prepared by do_prepare_dc).

If you don’t wish to calculate your own scrolling, you must call DoPrepareDC when not drawing from within OnDraw, to set the device origin for the device context according to the current scroll position.

A ScrolledWindow will normally scroll itself and therefore its child windows as well. It might however be desired to scroll a different window than itself: e.g. when designing a spreadsheet, you will normally only have to scroll the (usually white) cell area, whereas the (usually grey) label area will scroll very differently. For this special purpose, you can call set_target_window which means that pressing the scrollbars will scroll a different window.

Note that the underlying system knows nothing about scrolling coordinates, so that all system functions (mouse events, expose events, refresh calls etc) as well as the position of subwindows are relative to the “physical” origin of the scrolled window. If the user insert a child window at position (10,10) and scrolls the window down 100 pixels (moving the child window out of the visible area), the child window will report a position of (10,-90).

Derived from






Use ScrolledWindow for applications where the user scrolls by a fixed amount, and where a `page’ can be interpreted to be the current visible portion of the window. For more sophisticated applications, use the ScrolledWindow implementation as a guide to build your own scroll behaviour.

See also

ScrollBar, ClientDC,

PaintDC, VScrolledWindow



ScrolledWindow.new(Window parent,  Integer id = -1, 
                   Point pos = DEFAULT_POSITION, 
                   Size size = DEFAULT_SIZE, 
                   Integer style = HSCROLL VSCROLL, 
                   String name = "scrolledWindow")




The window is initially created without visible scrollbars. Call ScrolledWindow#set_scrollbars to specify how big the virtual window size should be.




[ Integer x, Integer y ] calc_scrolled_position(Integer x,    Integer y)

Translates the logical coordinates to the device ones. For example, if a window is scrolled 10 pixels to the bottom, the device coordinates of the origin are (0, 0) (as always), but the logical coordinates are (0, 10) and so the call to calc_scrolled_position(0, 10) will return [ 0, 0 ]

See also



[ Integer x, Integer y ] calc_unscrolled_position( Integer x, Integer y)

Translates the device coordinates to the logical ones. For example, if a window is scrolled 10 pixels to the bottom, the device coordinates of the origin are (0, 0) (as always), but the logical coordinates are (0, 10) and so the call to calc_unscrolled_position(0, 0) will return [0, 10].

See also



Boolean create(Window parent,  Integer id = -1, 
               Point pos = DEFAULT_POSITION, 
               Size size = DEFAULT_SIZE, 
               Integer style = HSCROLL VSCROLL, 
               String name = "scrolledWindow")

Creates the window for two-step construction. Derived classes should call or replace this function. See ScrolledWindow.new for details.


enable_scrolling(Boolean xScrolling,  Boolean yScrolling)

Enable or disable physical scrolling in the given direction. Physical scrolling is the physical transfer of bits up or down the screen when a scroll event occurs. If the application scrolls by a variable amount (e.g. if there are different font sizes) then physical scrolling will not work, and you should switch it off. Note that you will have to reposition child windows yourself, if physical scrolling is disabled.



Physical scrolling may not be available on all platforms. Where it is available, it is enabled by default.


[ Integer x_unit, Integer y_unit ] get_scroll_pixels_per_unit()

Get the number of pixels per scroll unit (line), in each direction, as set by ScrolledWindow#set_scrollbars. A value of zero indicates no scrolling in that direction.

See also

ScrolledWindow#set_scrollbars, ScrolledWindow#get_virtual_size


[ Integer x, Integer y ] get_view_start()

Get the x and y position at which the visible portion of the window starts.


If either of the scrollbars is not at the home position, x_ and/or _y will be greater than zero. Combined with Window#get_client_size, the application can use this function to efficiently redraw only the visible portion of the window. The positions are in logical scroll units, not pixels, so to convert to pixels you will have to multiply by the number of pixels per scroll increment.


[ Integer x, Integer y ] get_virtual_size()

Gets the size in device units of the scrollable window area (as opposed to the client size, which is the area of the window currently visible). Use DC#device_to_logical_x and DC#device_to_logical_y to convert these units to logical units.


Boolean is_retained()

Motif only: true if the window has a backing bitmap.


do_prepare_dc(DC dc)

Call this function to prepare the device context for drawing a scrolled image. It sets the device origin according to the current scroll position.

This method is called automatically within the default on_paint event handler, so your on_draw override will be passed a ‘pre-scrolled’ device context. However, if you wish to draw from outside of on_draw (via on_paint), or you wish to implement on_paint yourself, you must call this function yourself.


on_draw(DC dc)

Called by the default paint event handler to allow the application to define painting behaviour without having to worry about calling ScrolledWindow#do_prepare_dc.

Instead of overriding this function you may also just process the paint event in the derived class as usual, but then you will have to call do_prepare_dc() yourself


on_draw(DC dc)

This function is for backwards compatibility only and simply calls do_prepare_dc now. Overriding this method in your derived class is useless.


scroll(Integer x, Integer y)

Scrolls a window so the view start is at the given point. x_ and _y are scroll units not pixels, so to convert to pixels you will have to multiply by the number of pixels per scroll increment (see get_scroll_pixels_per_unit.

If either parameter is -1, that position will be ignored – there will be no change in that direction.


set_scroll_bars(Integer pixels_per_unit_x, Integer pixels_per_unit_y,
                    Integer no_units_x, Integer no_units_y,
                    Integer pos_x = 0, Integer pos_y = 0,
                    Boolean no_refresh = false)

Sets up vertical and/or horizontal scrollbars. This method accepts three pairs of parameters for the x and y axes.

In addition no_refresh, if true, means the window will not be refreshed.

The following example would set up the scrollbars to create a virtual scrolling area of 1000 pixels wide by 500 pixels wide, scrolling in increments of 20 pixels. The initial view position would be offset by 100 pixels in the horizontal direction:

scrollwin.set_scroll_bars(20, 20, 50, 25, 100, 0)


set_scroll_rate(Integer x_step, Integer y_step)

Sets the horizontal and vertical scrolling rate only. See the pixels per unit parameters to set_scroll_bars


set_target_window(Window window)

Call this function to tell a ScrolledWindow to perform the actual scrolling on a different window (and not on itself). This is useful, for example, where there are elements that should remain fixed within the scrolling area – for example, the row and column headers within a grid or spreadsheet-like widget.

[This page automatically generated from the Textile source at Wed Sep 09 02:21:23 +0100 2009]