ListBox Objects

#Overview ListBoxes are really great. They're sortof boxy, and they list things. Also, they have scroll bars built right in. Convenient! ListBox objects can only be created after you have a gui object, by calling the gui's addListBox method. They are the most boring of all elements, capable of doing nothing but sitting there, saying stuff.

Members:

Properties

posX, posY, width, height

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

list

The list of items in the ListBox, as an array. You should probably not modify this after creation, as Gopher hasn't properly finished the code to handle changing them dynamically. This will be sorted in the near future.

style

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

gui

the gui object this ListBox is contained by.

Methods

listbox:hide()

Hides the ListBox

listbox:show()

Unhides, or shows, the ListBox .

listbox:draw()

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

listbox:select(index)

Set the selected item to the specified index into the listbox's current list. Will scroll if needed to ensure the selected item is displayed.

listbox:getSelected()

Returns the text of the selected item in the list.

listbox:updateList(list)

Replaces the current list with your new list and redraws.

### 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.

onChange(listBox,prevIndex,selectedIndex)

Called whenever the selected item on the list changes, whether by clicking, arrow keys, or the select() method.

onDoubleClick(listBox,mouseX,mouseY,button)

Called when you double-click on the list box.

onEnter(listBox)

Called when the user presses the the enter/return key while the listBox has focus on an item.

Styles

Styles specific to ListBoxes are applied in gui style sheets using the element "listbox". ListBoxes are focusable, so the listbox:focus selector can be used to control the border style. The ListBox uses Labels and a ScrollBar internally; these will have their class set to "listbox," allowing them to be styled separately from normal labels and scroll bars. The selected item in the list is highlighted by a selected style, with the selector "label.listbox:selected".

The ListBoxes and their sub-elements 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 ListBox object, ex, "listbox.text-color=0x00ffff" would make the listbox text bright cyan.

For more general information on styles, see the styles page

###Style Properties This table lists the properties for the listbox selector only; see the pages on labels and scroll bars for the properties that affect those elements. The contained labels and scroll bars will have the class "listbox" allowing them to be styled directly, ex, "label.listbox" will style only labels that part of listboxes.

Propery	Value Type	Description
border	boolean	should this gui have a border
border-top	boolean	is there a border on the top edge?
border-buttom	boolean	bottom...
border-left	boolean	left
border-right	boolean	The right border should usually be off; it will be covered by the scroll bar either way.
border-color-fg	int1	the fg color of characters in the border
border-color-bg	int1	the bg color used for the border
border-ch-top	char2	the character or unicode hex value used for top border
border-ch-bottom	char2	character used for the bottom border
border-ch-left	char2	character used to draw the left border
border-ch-right	char2	character used to draw the right border
border-ch-corner-topleft	char2	character used to draw the top-left corner
border-ch-corner-bottomleft	char2	character used to draw the bottom-left corner
border-ch-corner-topright	char2	character used to draw the top-right corner
border-ch-corner-bottomright	char2	character used to draw the bottom-right corner

¹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 single-character strings, like "+", or hexadecimal unicode identifiers in the format "U+xxxx", ex, U+263a is a smiley face symbol.