## wxScrollBar

A wxScrollBar 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

wxControl
wxWindow
wxEvtHandler
wxObject

Include files

<wx/scrolbar.h>

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

wxSB_HORIZONTAL | Specifies a horizontal scrollbar.
wxSB_VERTICAL | Specifies a vertical scrollbar.

See also window styles overview.

Event handling

To process input from a scrollbar, use one of these event handler macros to direct input to member functions that take a wxScrollEvent argument:

EVT_COMMAND_SCROLL(id, func) | Catch all scroll commands.
EVT_COMMAND_SCROLL_TOP(id, func) | Catch a command to put the scroll thumb at the maximum position.
EVT_COMMAND_SCROLL_BOTTOM(id, func) | Catch a command to put the scroll thumb at the maximum position.
EVT_COMMAND_SCROLL_LINEUP(id, func) | Catch a line up command.
EVT_COMMAND_SCROLL_LINEDOWN(id, func) | Catch a line down command.
EVT_COMMAND_SCROLL_PAGEUP(id, func) | Catch a page up command.
EVT_COMMAND_SCROLL_PAGEDOWN(id, func) | Catch a page down command.
EVT_COMMAND_SCROLL_THUMBTRACK(id, func) | Catch a thumbtrack command (continuous movement of the scroll thumb).

See also

Scrolling overview, Event handling overview, wxScrolledWindow

Members

wxScrollBar::wxScrollBar
wxScrollBar::~wxScrollBar
wxScrollBar::Create
wxScrollBar::GetRange
wxScrollBar::GetPageSize
wxScrollBar::GetThumbPosition
wxScrollBar::GetThumbLength
wxScrollBar::SetThumbPosition
wxScrollBar::SetScrollbar

### wxScrollBar::wxScrollBar

wxScrollBar()

Default constructor.

wxScrollBar(wxWindow* parent, wxWindowID id, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxSB_HORIZONTAL, const wxValidator& validator = wxDefaultValidator, const wxString& name = "scrollBar")

Constructor, creating and showing a scrollbar.

Parameters

parent

Parent window. Must not be NULL.

id

Window identifier. A value of -1 indicates a default value.

pos

Window position. If the position (-1, -1) is specified then a default position is chosen.

size

Window size. If the default size (-1, -1) is specified then a default size is chosen.

style

Window style. See wxScrollBar.

validator

Window validator.

name

Window name.

See also

wxScrollBar::Create, wxValidator

### wxScrollBar::~wxScrollBar

void ~wxScrollBar()

Destructor, destroying the scrollbar.

### wxScrollBar::Create

bool Create(wxWindow* parent, wxWindowID id, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxSB_HORIZONTAL, const wxValidator& validator = wxDefaultValidator, const wxString& name = "scrollBar")

Scrollbar creation function called by the scrollbar constructor. See wxScrollBar::wxScrollBar for details.

### wxScrollBar::GetRange

int GetRange() const

Returns the length of the scrollbar.

See also

wxScrollBar::SetScrollbar

### wxScrollBar::GetPageSize

int GetPageSize() const

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

wxScrollBar::SetScrollbar

### wxScrollBar::GetThumbPosition

int GetThumbPosition() const

Returns the current position of the scrollbar thumb.

See also

wxScrollBar::SetThumbPosition

### wxScrollBar::GetThumbLength

int GetThumbLength() const

Returns the thumb or 'view' size.

See also

wxScrollBar::SetScrollbar

### wxScrollBar::SetThumbPosition

void SetThumbPosition(int viewStart)

Sets the position of the scrollbar.

Parameters

viewStart

The position of the scrollbar thumb.

See also

wxScrollBar::GetThumbPosition

### wxScrollBar::SetScrollbar

virtual void SetScrollbar(int position, int thumbSize, int range, int pageSize, const bool refresh = TRUE)

Sets the scrollbar properties.

Parameters

position

The position of the scrollbar in scroll units.

thumbSize

The size of the thumb, or visible portion of the scrollbar, in scroll units.

range

The maximum position of the scrollbar.

pageSize

The size of the page size in scroll units. This is the number of units the scrollbar will scroll when it is paged up or down. Often it is the same as the thumb size.

refresh

TRUE to redraw the scrollbar, FALSE otherwise.

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 wxWindow::OnSize event handler function.

See also

Scrolling overview, wxWindow::SetScrollbar, wxScrolledWindow