Scroll List

A library for displaying and getting input from a scrollable list.

File:
ScrollList.lib
Version:
1.0
Author:
Marcus Johansson

Contents

Details
Constants
Sub routines


Details

With this library you can create and display a list of text items. The list has a scrollbar and buttons that can be used if the list is longer than the defined visual height.

The library was created just because I wanted to display a list of lobbies in a game using the p2p extension in a user friendly fashion. But there might be other uses for it, who knows?


Constants

Items that can be assigned a color with SetScrollListColor

Name
Description
SL_ROW_EVEN_COLOR
Background color for even rows in the list.
SL_ROW_ODD_COLOR
Background color for odd rows in the list.
SL_ROW_OVER_COLOR
Background color for item in the list that the mouse pointer hovers over.
SL_ROW_SELECTED_COLOR
Background color for selected item in the list.
SL_BUTTON_BG_COLOR
Button bar background color.
SL_BUTTON_HIGHLIGHT_COLOR
Button highlight color.
SL_BUTTON_SHADOW_COLOR
Button shadow color.
SL_SCROLLBAR_BG_COLOR
Scroll bar background color.


Subroutines

Name
Parameters
Brief description
procedure
CreateScrollList
&fields?[], x, y, w, visibleLines, fontID, imgID
Create scroll list.
procedure
SetScrollListColor
item, r, g, b
Set color used for a specific type of item.
procedure
SetScrollListColorWithAlpha
item, r, g, b, a
Set color with transparency used for a specific type of item.
procedure
GenerateScrollListButtonImage
size
Generate an image for (rather ugly) square buttons of specified side length.
procedure
LoadScrollListImage
filename$
Load an image to be used for the buttons and the scroll bar.
procedure
SetScrollListImage
img
Set image an image to be used for the buttons and the scroll bar.
procedure
UpdateScrollList
Update the scroll list.
procedure
DrawScrollList
Draw the scroll list.
function
GetScrollListSelectedIndex
Get the selected item index.
function
GetScrollListOverIndex
Get the index of the item that the mouse pointer is hovering over.
procedure
SetScrollListSelectedIndex
index, scrollTo
Set the selected item index.


Subroutine documentation

procedure CreateScrollList ( &fields?[], x, y, w, visibleLines, fontID, imgID )

Create a scroll list from an object array. Every element must have a string field named txt. This is the text that's displayed in the list.

Parameter
Mode
Description
&fields?[]
In
Object array representing the list.
x
In
X coordinate of the list.
y
In
Y coordinate of the list.
w
In
Width of the list, excluding the width of the scroll bar.
visibleLines
In
Number of visible lines. The actual height depends on the font used.
fontID
In
Font to use.
imgID
In
ID of the image that will be created for button and scroll bar graphics.

[ Back ]


procedure SetScrollListColor ( item, r, g, b )

If you don't want to use the default colors, you should call this function prior to CreateScrollList or GenerateScrollListButtonImage.

Parameter
Mode
Description
item
In
Should be one of the constants: SL_ROW_EVEN_COLOR, SL_ROW_ODD_COLOR, SL_ROW_OVER_COLOR, SL_ROW_SELECTED_COLOR, SL_BUTTON_BG_COLOR, SL_BUTTON_HIGHLIGHT_COLOR, SL_BUTTON_SHADOW_COLOR or SL_SCROLLBAR_BG_COLOR.
r
In
Red color component [0..255]
g
In
Green color component [0..255]
b
In
Blue color component [0..255]

[ Back ]


procedure SetScrollListColorWithAlpha ( item, r, g, b, a )

If you don't want to use the default colors, you should call this function prior to CreateScrollList or GenerateScrollListButtonImage.

Parameter
Mode
Description
item
In
Should be one of the constants: SL_ROW_EVEN_COLOR, SL_ROW_ODD_COLOR, SL_ROW_OVER_COLOR, SL_ROW_SELECTED_COLOR, SL_BUTTON_BG_COLOR, SL_BUTTON_HIGHLIGHT_COLOR, SL_BUTTON_SHADOW_COLOR or SL_SCROLLBAR_BG_COLOR.
r
In
Red color component [0..255].
g
In
Green color component [0..255].
b
In
Blue color component [0..255].
a
In
Alpha color component [0..255].

[ Back ]


procedure GenerateScrollListButtonImage ( size )

if you want to use other than the default colors, you have to use SetScrollListColor before calling this function. If no button image exists, this function will automaticly be called from CreateScrollList.

Parameter
Mode
Description
size
In
Side length of square button.

[ Back ]


procedure LoadScrollListImage ( filename$ )

The image will be loaded with the ID that was passed to CreateScrollList if that function has been called earlier, else the default image ID, -13, will be used. Look at the image in the assets folder to understand how the image is used (it contains 5 columns and 3 rows).

Parameter
Mode
Description
filename$
In
Image filename.

[ Back ]


procedure SetScrollListImage ( img )

Look at the image in the assets folder to understand how the image is used (it contains 5 columns and 3 rows).

Parameter
Mode
Description
img
In
Image ID of an existing image.

[ Back ]


procedure UpdateScrollList ( )

You need to call this once every update frame while the list is active.

[ Back ]


procedure DrawScrollList ( )

This will render the scroll list.

[ Back ]


function GetScrollListSelectedIndex ( )

Returns the selected item index (starting at 0). If no item has been selected, -1 is returned.

Return value
Item index.

[ Back ]


function GetScrollListOverIndex ( )

Returns the selected item index (starting at 0) that the mouse pointer is currently hovering over. If mouse pointer isn't over any item in the list, -1 is returned.

Return value
Item index.

[ Back ]


procedure SetScrollListSelectedIndex ( index, scrollTo )

Set the selected item to specific index (starting at 0). if scrollTo is set to true, the list will also scroll to the item.

Parameter
Mode
Description
index
In
Index of item to select.
scrollTo
In
Set to true if the list should scroll to the item.

[ Back ]


Generated with NLDoc 20160715.