VerticalScrollbar
The VerticalScrollbar provides a windows-style scroll bar. This Window element is an automated combination of several other window components.
| VerticalScrollbar | The VerticalScrollbar provides a windows-style scroll bar. |
| Implementation Details | The VerticalScrollbar is a combination window element that automates a scroll bar functionality. |
| XML Definition | This is the VerticalScrollbar xml definition. |
| XML Tag | |
| Required Attributes | Required for the window element to create itself properly. |
| up | Name of the Button definition to use for the up button. |
| down | Name of the Button definition to use for the down button. |
| thumb | Name of the VerticalResizeImage definition to use for the scaling scrollbar thumb. |
| gutter | Name of the VerticalResizeImage definition to use for the background for the scroll area. |
| Optional Elements | |
| UpOffset | The offset for the UpButton from the top of the scrollbar window. |
| DownOffset | The offset for the DownButton from the bottom left of the scrollbar window. |
| ThumbOffset | The offset for the Thumb from the topleft of the scrollbar window. |
| ActiveZoneOffset | The ActiveZone is the area outside of the scrollbar’s dimensions that you can still click and drag the scrollbar. |
| Window Callbacks | These are the VerticalScrollBar specific callback events. |
| Callbacks | |
| OnScrollPosChanged | Called when the scroll position has changed. |
| Functions | |
| Functions | |
| VerticalScrollbarSetScrollPosition() | Sets the current scroll position |
| VerticalScrollbarGetScrollPosition() | Returns the current scroll position |
| VerticalScrollbarSetMaxScrollPosition() | Sets the maximum scroll position |
| VerticalScrollbarGetMaxScrollPosition() | Returns the maximum scroll position. |
| VerticalScrollbarSetPageSize() | Sets the page size. |
| VerticalScrollbarGetPageSize() | Returns the page size. |
| VerticalScrollbarSetLineSize() | Sets the line size. |
| VerticalScrollbarGetLineSize() | Returns the line size. |
Implementation Details
The VerticalScrollbar is a combination window element that automates a scroll bar functionality. While scroll bars can be used independently, they are most often used as a component of other scrolling windows such as the ListBox, ScrollWindow, or <TextLogDisplay>.
Components
- A Button definition for the up arrow.
- A Button definition for the down arrow.
- A VerticalResizeImage for the background of the scrollbar.
- A VerticalResizeImage for the scroll thumb.
When a scrollbar is sized, the background image resizes to fit it’s dimensions. When used as part of annother window element, the scrollbar’s thumb will automatically size and position itself to reflect it’s parent window’s data.
When using a scrollbar on it’s own through lua, you need to set the following values according to your data
| lineSize | The height of a single line. (Use VerticalScrollbarSetLineSize() and VerticalScrollbarGetLineSize()) |
| pageSize | The height for a full page. (Use VerticalScrollbarSetPageSize() and <VerticalScrollbarGetPageLineSize()>) |
| maxScroll | The maximum value of your scroll range. (Use VerticalScrollbarSetMaxScrollPosition() and VerticalScrollbarGetMaxScrollPosition()) |
XML Definition
This is the VerticalScrollbar xml definition.
| XML Tag | |
| Required Attributes | Required for the window element to create itself properly. |
| up | Name of the Button definition to use for the up button. |
| down | Name of the Button definition to use for the down button. |
| thumb | Name of the VerticalResizeImage definition to use for the scaling scrollbar thumb. |
| gutter | Name of the VerticalResizeImage definition to use for the background for the scroll area. |
| Optional Elements | |
| UpOffset | The offset for the UpButton from the top of the scrollbar window. |
| DownOffset | The offset for the DownButton from the bottom left of the scrollbar window. |
| ThumbOffset | The offset for the Thumb from the topleft of the scrollbar window. |
| ActiveZoneOffset | The ActiveZone is the area outside of the scrollbar’s dimensions that you can still click and drag the scrollbar. |
thumb
Name of the VerticalResizeImage definition to use for the scaling scrollbar thumb.
Expects
A string value, which is the name of a valid VerticalResizeImage.
Default Value
- ””
gutter
Name of the VerticalResizeImage definition to use for the background for the scroll area.
Expects
A string value, which is the name of a valid VerticalResizeImage.
Default Value
- ””
UpOffset
The offset for the UpButton from the top of the scrollbar window.
Syntax
<UpOffset x="2" y="0" />
| x | The x pixel offset from the top left corner of the window |
| y | The y pixel offset from the top left corner of the window |
Defaults
| x | 0 |
| y | 0 |
DownOffset
The offset for the DownButton from the bottom left of the scrollbar window.
Syntax
<DownOffset x="2" y="0" />
| x | The x pixel offset from the bottom left corner of the window |
| y | The y pixel offset from the bottom left corner of the window |
Defaults
| x | 0 |
| y | 0 |
ThumbOffset
The offset for the Thumb from the topleft of the scrollbar window.
Syntax
<UpOffset x="2" y="0" />
| x | The x pixel offset from the top left corner of the window |
| y | The y pixel offset from the top left corner of the window |
Defaults
| x | 0 |
| y | 0 |
ActiveZoneOffset
The ActiveZone is the area outside of the scrollbar’s dimensions that you can still click and drag the scrollbar. Windows seems to have an active zone of about 100 pixels on either side of a scrollbar.
Syntax
<ActiveZoneOffset x="100" y="0" />
| x | The x pixel distance on either side of the scrollbar. |
| y | The y pixel distance on either side of the scrollbar. |
Defaults
| x | 0 |
| y | 0 |
Window Callbacks
These are the VerticalScrollBar specific callback events.
| Callbacks | |
| OnScrollPosChanged | Called when the scroll position has changed. |
OnScrollPosChanged
Called when the scroll position has changed.
Syntax
SomeVerticalScrollBar.OnScrollPosChanged( scrollPos )
| scrollPos | (number) The current scroll position ( 1 through the the scroll size / page size ). |
Functions
| Functions | |
| VerticalScrollbarSetScrollPosition() | Sets the current scroll position |
| VerticalScrollbarGetScrollPosition() | Returns the current scroll position |
| VerticalScrollbarSetMaxScrollPosition() | Sets the maximum scroll position |
| VerticalScrollbarGetMaxScrollPosition() | Returns the maximum scroll position. |
| VerticalScrollbarSetPageSize() | Sets the page size. |
| VerticalScrollbarGetPageSize() | Returns the page size. |
| VerticalScrollbarSetLineSize() | Sets the line size. |
| VerticalScrollbarGetLineSize() | Returns the line size. |
VerticalScrollbarSetScrollPosition()
Sets the current scroll position
Parameters
| verticalScrollbarName | (string) The name of the VerticalScrollbar. |
| scrollPos | (number) The current scroll position. |
Returns
| nil | No return value |
Notes
- none
Example
VerticalScrollbarSetScrollPosition("SomeScrollBar", 0 )VerticalScrollbarGetScrollPosition()
Returns the current scroll position
Parameters
| verticalScrollbarName | (string) The name of the VerticalScrollbar. |
Returns
| scrollPos | (number) The current scroll position. |
Notes
- none
Example
local scrollPos = VerticalScrollbarGetScrollPosition( "SomeScrollBar" )
VerticalScrollbarSetMaxScrollPosition()
Sets the maximum scroll position
Parameters
| verticalScrollbarName | (string) The name of the VerticalScrollbar. |
| maxScrollPos | (number) The maximum scroll position. |
Returns
| nil | No return value |
Notes
- none
Example
VerticalScrollbarSetMaxScrollPosition("SomeScrollBar", 100 )VerticalScrollbarGetMaxScrollPosition()
Returns the maximum scroll position.
Parameters
| verticalScrollbarName | (string) The name of the VerticalScrollbar. |
Returns
| maxScrollPos | (number) The maximum scroll position. |
Related XML
Notes
- none
Example
local maxScrollPos = VerticalScrollbarGetMaxScrollPosition("SomeScrollBar" )VerticalScrollbarSetPageSize()
Sets the page size.
Parameters
| verticalScrollbarName | (string) The name of the VerticalScrollbar. |
| pageSize | (number) The page size. |
Returns
| nil | No return value |
Notes
- none
Example
VerticalScrollbarSetPageSize("SomeScrollBar", 10 )VerticalScrollbarGetPageSize()
Returns the page size.
Parameters
| verticalScrollbarName | (string) The name of the VerticalScrollbar. |
Returns
| pageSize | (number) The current page size. |
Related XML
Notes
- none
Example
local pageSize = VerticalScrollbarGetPageSize("SomeScrollBar" )VerticalScrollbarSetLineSize()
Sets the line size.
Parameters
| verticalScrollbarName | (string) The name of the VerticalScrollbar. |
| lineSize | (number) The line size. |
Returns
| nil | No return value |
Notes
- none
Example
VerticalScrollbarSetLineSize("SomeScrollBar", 10 )