wxRuby Documentation Home

Wx::ScrollBar

A ScrollBar is a control that represents a horizontal or vertical scrollbar. It is distinct from the two scrollbars that some windows provide automatically, but the two types of scrollbar share the way events are received.

Derived from

Control

Window

EvtHandler

Object

Remarks

A scrollbar has the following main attributes: range, thumb size, page size, and position.

The range is the total number of units associated with the view represented by the scrollbar. For a table with 15 columns, the range would be 15.

The thumb size is the number of units that are currently visible. For the table example, the window might be sized so that only 5 columns are currently visible, in which case the application would set the thumb size to 5. When the thumb size becomes the same as or greater than the range, the scrollbar will be automatically hidden on most platforms.

The page size is the number of units that the scrollbar should scroll by, when `paging’ through the data. This value is normally the same as the thumb size length, because it is natural to assume that the visible window size defines a page.

The scrollbar position is the current thumb position.

Most applications will find it convenient to provide a function called AdjustScrollbars which can be called initially, from an OnSize event handler, and whenever the application data changes in size. It will adjust the view, object and page size according to the size of the window and the size of the data.

Window styles

SB_HORIZONTAL Specifies a horizontal scrollbar.
SB_VERTICAL Specifies a vertical scrollbar.

See also window styles overview.

scrolevt.inc

See also

Scrolling overview, Event handling overview, ScrolledWindow

Methods

ScrollBar.new

ScrollBar.new(Window parent,  Integer id, 
              Point pos = DEFAULT_POSITION, 
              Size size = DEFAULT_SIZE, 
              Integer style = SB_HORIZONTAL, 
              Validator validator = DEFAULT_VALIDATOR, 
              String name = "scrollBar")

Constructor, creating and showing a scrollbar.

Parameters

See also

ScrollBar#create, Validator

destructor()

Destructor, destroying the scrollbar.

ScrollBar#create

Boolean create(Window parent,  Integer id, 
               Point pos = DEFAULT_POSITION, 
               Size size = DEFAULT_SIZE, 
               Integer style = SB_HORIZONTAL, 
               Validator validator = DEFAULT_VALIDATOR, 
               String name = "scrollBar")

Scrollbar creation function called by the scrollbar constructor. See ScrollBar.new for details.

ScrollBar#get_range

Integer get_range()

Returns the length of the scrollbar.

See also

ScrollBar#set_scrollbar

ScrollBar#get_page_size

Integer get_page_size()

Returns the page size of the scrollbar. This is the number of scroll units that will be scrolled when the user pages up or down. Often it is the same as the thumb size.

See also

ScrollBar#set_scrollbar

ScrollBar#get_thumb_position

Integer get_thumb_position()

Returns the current position of the scrollbar thumb.

See also

ScrollBar#set_thumb_position

ScrollBar#get_thumb_size

Integer get_thumb_size()

Returns the thumb or `view’ size.

See also

ScrollBar#set_scrollbar

ScrollBar#set_object_length

set_object_length(Integer objectLength)

Sets the object length for the scrollbar. This is the total object size (virtual size). You must call set_view_length before calling SetObjectLength.

Parameters

Remarks

Example: you are implementing scrollbars on a text window, where text lines have a maximum width of 100 characters. Your text window has a current width of 60 characters. So the view length is 60, and the object length is 100. The scrollbar will then enable you to scroll to see the other 40 characters.

You will need to call SetViewLength and SetObjectLength whenever there is a change in the size of the window (the view size) or the size of the contents (the object length).

See also

ScrollBar#get_object_length

ScrollBar#set_page_size

set_page_size(Integer pageSize)

Sets the page size for the scrollbar. This is the number of scroll units which are scrolled when the user pages down (clicks on the scrollbar outside the thumbtrack area).

Parameters

Remarks

At present, this needs to be called before other set functions.

See also

ScrollBar#get_page_size

ScrollBar#set_thumb_position

set_thumb_position(Integer viewStart)

Sets the position of the scrollbar.

Parameters

See also

ScrollBar#get_thumb_position

ScrollBar#set_scrollbar

set_scrollbar(Integer position,  Integer thumbSize, 
              Integer range, 
              Integer pageSize, 
              Boolean refresh = true)

Sets the scrollbar properties.

Parameters

Remarks

Let’s say you wish to display 50 lines of text, using the same font. The window is sized so that you can only see 16 lines at a time.

You would use:

scrollbar->SetScrollbar(0, 16, 50, 15);

The page size is 1 less than the thumb size so that the last line of the previous page will be visible on the next page, to help orient the user.

Note that with the window at this size, the thumb position can never go above 50 minus 16, or 34.

You can determine how many lines are currently visible by dividing the current view size by the character height in pixels.

When defining your own scrollbar behaviour, you will always need to recalculate the scrollbar settings when the window size changes. You could therefore put your scrollbar calculations and SetScrollbar call into a function named AdjustScrollbars, which can be called initially and also from a SizeEvent event handler function.

See also

Scrolling overview, Window#set_scrollbar, ScrolledWindow

ScrollBar#set_view_length

set_view_length(Integer viewLength)

Sets the view length for the scrollbar.

Parameters

See also

ScrollBar#get_view_length

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