ScrollBar Objects

#Overview ScrollBars come in horizontal and vertical varieties. ScrollBar objects can only be created after you have a gui object, by calling the gui's addScrollBarH or addScrollBarV methods. They are used internally by several more advanced components, like ListBoxes and TextBoxes, but can be used independently for custom purposes. You can scroll one step at a time by clicking the buttons at the ends, a page at a time by clicking in the space between the scroll grip and the button, or click and drag the scroll grip to scroll more quickly. You set a maximum scroll value, scrollMax, and they will call their provided onScroll function whenever they are scrolled.

Members:

Properties

posX, posY, width, height

The position and dimensions of the ScrollBar, with position in it's gui's internal coordinates.

scrollMax

The maximum scroll value, defining the range of scroll coordinates. This is not related to the size of the scroll bar on screen, but should be set based on what you are doing with the scrolled value, such as the total number of items in a list box.

scrollPos

The current scrolled position (in the scroll coordinates, not in screen characters; will be between 1 and scrollMax, inclusive)

style

The style table to use on this label. If unset, inherits from it's parent gui.

gui

the gui object this label is contained by.

Methods

scrollbar:hide()

Hides the scrollbar.

scrollbar:show()

Unhides, or shows, the scrollbar.

scrollbar:draw()

Forces the scrollbar to be redrawn immediately. Useful if you've been directly manipulating it's style or properties from code and need those changes to update.

Handlers

Handlers are properties that can be set to functions that will be called when certain events happen. Some handlers are common to all components, like onClick, while others are specific to certain types, like onScroll. However, some common handlers are implemented internally, and overriding them can cause undesired results. Only those events listed on these pages for a given element type should be assigned in your programs.

onScroll(scrollbar,scrollPos)

Called whenever the scrollbar is scrolled, by clicking or dragging.

Styles

Styles specific to ScrollBars are applied in gui style sheets using the element "scrollbar". At present, ScrollBars have no states, so there are no valid gss :state modifiers that will affect gui styling.

ScrollBars will inherit the style table used by their containing gui, unless they are explicitly given their own style table. Individual style properties can also be set as values directly on the object, ex, "scrollbar.grip-color-fg=0x00ffff" would make the scroll bar's grip bright cyan.

For more general information on styles, see the styles page

###Style Properties

Propery	Value Type	Description
button-color-fg	int1	foreground color of the buttons at the ends
button-color-bg	int1	background color of the buttons at the ends
button-ch-up	char2	character drawn for "up" button on vertical bars
button-ch-down	char2	character drawn for "down" button on vertical bars
button-ch-left	char2	character drawn for "left" button on horizontal bars
button-ch-right	char2	character drawn for "right" button on horizontal bars
grip-color-fg	int1	foreground color of the scroll bar's grip
grip-color-bg	int1	background color of the scroll bar's grip
grip-ch-v	char2	character used for the grip on vertical bars
grip-ch-h	char2	character used for the grip on horizontal bars
bar-color-fg	int1	foreground color of the bar itself, between buttons and grip
bar-color-bg	int1	background color of the bar itself, between buttons and grip
bar-ch	char2	character used for the bar itself, between buttons and grip

¹colors are 24-bit, with 8 bits each R, G, and B, and can be given as normal integers, like 0 (which would be black), or hex values, like 0xff0000 (red).

¹Characters can be specified as strings, like "x", or as hexadecimal unicode values, in the format "U+xxxx," for example, a 50% gradient is U+2592