GUI List Box functions and properties

GUI List Box functions and properties

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
GetItemText
RemoveItem
SetItemText
ItemCount property (list box)
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.GetText(input);
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 buffer;
  lstOptions.GetItemText(index, buffer);
  Display("The mouse is over item '%s'.", buffer);
}

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

See Also: ListBox.SelectedIndex

GetItemText

(Formerly known as ListBoxGetItemText, which is now obsolete)

ListBox.GetItemText(int item, string buffer)

Fills BUFFER with the text from list item number ITEM in the listbox. This is useful for finding out the name of the option the user selected.

Remember that list box items are numbered starting from 0, so the first item is 0, the second is 1, and so on.

Example:

string buffer;
lstOptions.GetItemText(lstOptions.SelectedIndex, buffer);

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

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

SetItemText

ListBox.SetItemText(int item, string newText)

Changes the text of ITEM in the listbox to be NEWTEXT. This allows you to change the text of an existing item; to add a new item to the list, use the AddItem function.

Remember that list box items are numbered starting from 0, so the first item is 0, the second is 1, and so on.

Example:

string buffer;
lstOptions.SetItemText(lstOptions.SelectedIndex, "Touched!");

will change the currently selected item to read "Touched!".

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

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 buffer;
lstOptions.GetItemText(lstOptions.SelectedIndex, buffer);

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.

Browser Based Help. Published by chm2web software.