GUI List Box functions and properties

GUI List Box functions and properties

Clickable property (inherited)
Enabled property (inherited)
Height property (inherited)
ID property (inherited)
OwningGUI property (inherited)
SetPosition (inherited)
SetSize (inherited)
Visible property (inherited)
Width property (inherited)
X property (inherited)
Y property (inherited)

AddItem
Clear
FillDirList
FillSaveGameList
GetItemAtLocation
InsertItemAt
RemoveItem
ItemCount property (list box)
Items property
SelectedIndex property
TopItem property (list box)

AddItem

(Formerly known as ListBoxAdd, which is now obsolete)

ListBox.AddItem(string newitem)

Adds NEWITEM to the specified list box. The item will be appended to the end of the list.

Example:

String input = txtUserInput.Text;
lstChoices.AddItem(input);

will take the input from the user and add it to the listbox.

Clear

(Formerly known as ListBoxClear, which is now obsolete)

ListBox.Clear()

Removes all items from the specified list box.

Example:

lstNoteBook.Clear();

will remove all the items from listbox lstNoteBook.

See Also: ListBox.AddItem

FillDirList

(Formerly known as ListBoxDirList, which is now obsolete)

ListBox.FillDirList(string filemask)

Fills the list box with a list of filenames matching FILEMASK in the current directory. This could be useful if you have various data files and the player can choose which one to load.

FILEMASK is a standard DOS/Windows search expression such as "*.dat" or "data*.*"

Example:

lstSaveGames.FillDirList("agssave.*");

will fill the listbox with the list of the saved games. Note that actually for this task you would use FillSaveGameList instead.

FillSaveGameList

(Formerly known as ListBoxSaveGameList, which is now obsolete)

ListBox.FillSaveGameList()

Fills the specified listbox with the save game list, sorted correctly with the most recent game at the top of the list.

The global savegameindex array is updated with the actual slot numbers of the entries. So, you could do:

int index = lstSaveGames.SelectedIndex;
RestoreGameSlot(savegameindex[index]);

NOTE: The save game list can only hold 20 save games. If ListBox.ItemCount returns 20 and you are doing a Save dialog box, you may want to make the user replace an existing file rather than saving a new one.

Example:

lstSaveGames.FillSaveGameList();

will fill listbox lstSaveGames with the list of the saved games.

GetItemAtLocation

ListBox.GetItemAtLocation(int x, int y)

Determines which item in the list box is at the screen co-ordinates (X,Y). This allows you to find out which item the mouse is hovering over, for instance.

Returns the item index (where the first item is 0), or -1 if the specified co-ordinates are not over any item or are outside the list box.

Example:

int index = lstOptions.GetItemAtLocation(mouse.x, mouse.y);
if (index < 0) {
  Display("The mouse is not over an item!");
}
else {
  String selectedItem = lstOptions.Items[index];
  Display("The mouse is over item '%s'.", selectedItem);
}

will display the item text that the mouse is currently hovering over.

See Also: ListBox.SelectedIndex

InsertItemAt

ListBox.InsertItemAt(int index, string newitem)

Inserts NEWITEM into the specified list box. The item will be inserted before the specified index.

Listbox indexes go from 0 (the first item) to ItemCount - 1 (the last item). The new item will be inserted before the index you specify.

Example:

lstChoices.AddItem("First item");
lstChoices.AddItem("Second item");
lstChoices.InsertItemAt(1, "Third item");

will insert the Third Item in between the First and Second items.

RemoveItem

(Formerly known as ListBoxRemove, which is now obsolete)

ListBox.RemoveItem(int item)

Removes ITEM from the specified list box. ITEM is the list index of the item to remove, starting with 0 for the top item.

If you want to remove all items from the list, then use ListBox.Clear instead.

NOTE: Calling this function causes other items in the list to get re-numbered, so make sure you don't keep around any references from ListBox.SelectedIndex and related functions while using this command.

Example:

lstTest.AddItem("First item");
lstTest.AddItem("Second item");
lstTest.RemoveItem(0);

the list box will now just contain "Second item".

See Also: ListBox.Clear, ListBox.FillDirList

ItemCount property (list box)

(Formerly known as ListBoxGetNumItems, which is now obsolete)

readonly int ListBox.ItemCount

Gets the number of items in the specified listbox. Valid item indexes range from 0 to (numItems - 1).

This property is read-only. To change the item count, use the AddItem and RemoveItem methods.

Example:

int saves = lstSaveGames.ItemCount;

will pass the number of saved games to the int saves.

See Also: ListBox.Items

Items property

(Formerly known as ListBoxGetItemText, which is now obsolete)
(Formerly known as ListBox.GetItemText, which is now obsolete)
(Formerly known as ListBox.SetItemText, which is now obsolete)

String ListBox.Items[index]

Gets/sets the text of the list box item at INDEX.

List box items are numbered starting from 0, so the first item is 0, the second is 1, and so on. The highest allowable index is ItemCount minus 1.

If you want to add a new item to the listbox, use the ListBox.AddItem method.

Example:

String selectedItemText = lstOptions.Items[lstOptions.SelectedIndex];

will get the text of the selected item in the list box.

SelectedIndex property

(Formerly known as ListBoxGetSelected, which is now obsolete)
(Formerly known as ListBoxSetSelected, which is now obsolete)

int ListBox.SelectedIndex

Gets/sets the index into the list of the currently selected item. The first item is 0, second is 1, and so on. If no item is selected, this is set to -1.

You can set this to -1 to remove the highlight (ie. un-select all items).

Example:

String selectedText = lstOptions.Items[lstOptions.SelectedIndex];

will get the text of the selected item in the listbox.

TopItem property (list box)

(Formerly known as ListBoxSetTopItem, which is now obsolete)

int ListBox.TopItem

Gets/sets the top item in the list box. The top item is the first item that is visible within the list box, so changing this effectively scrolls the list up and down.

Indexes for TopItem start from 0 for the first item in the list.

Example:

lstSaveGames.TopItem = 0;

will automatically scroll listbox lstSaveGames back to the top of the list.