GUI List Boxes

Revision as of 22:50, 5 January 2010 by SIMU-NOVA (Talk)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search


Creating a new dropdown or combo box


A dropdown box is a simple list of items which may be chosen. A combo box differs in that the header portion contains an editable Text Input Box, and thus users may enter arbitrary text as the value. By and large, the term 'dropdown box' will be used to refer to both here.

The default prototype for each is the same: _dropDownBox. Setting the boolean field editableDropDownBox to true will turn a dropdown box into a combo box. You are of course encouraged to create your own prototype with your own art, based on a class which should inherit the _GUIDropDownBox class.

Dropdown boxes consist of three main parts: the dropdown box itself, the dropdown list, and the dropdown items contained by the list. Each of these relevant parts has its own class and class methods script associated with it, which again, you are encouraged to override with prototypes using your own art and subclasses.

Adding elements to a dropdown or combo box

At some point, you will presumably want to populate your dropdown with list elements. This can be done one of two ways, dynamically or predetermined.

Dropdown boxes are most frequently dynamic GUI controls, in that their available options are not determined and set until after the control has been created. However, it is possible to place the options into the dropdown list in the GUI Editor, if your choices can be predetermined, simply by adding a dropdown item control for each option to the list's clientarea.

  method _populateListBox(myListBox as NodeRef of Class GUIControl, items as List of String)

This accepts a list of string and generates list items for the dropdown or combo box for each item in that list of string. If you do this, and want some or all of your items to have scripts associated with them (see below), then you will need to also build a lookuplist that contains an entry for each item you want to have a script, as well as the associated scriptref, as per the following function:

 GUIListBoxes:populateListBoxScripts(myListBox as NodeRef of Class GUIControl, scripts as LookupList indexed by String of ScriptRef)

The other way to add items is one at a time, via the following:

 GUIListBoxes:addListBoxItem(myListBox as NodeRef of Class GUIControl, item as String, myScript as ScriptRef)

Note that adding a single list item requires that a scriptref be included for the item, but that scriptref can simply be NONE, when that constant is fully implemented. Since it is not, for now, use the populate function instead.

Finally, you may use the following function to define the text which is initially visible in the collapsed list box. Note that this does not automatically create a list item with this text, so that you may place the list box's purpose in the "title", such as "Select your favorite muppet..."

 GUIListBoxes:setListBoxValue(myListBox as NodeRef of Class GUIControl, title as String)

Additional list box utilities

 GUIListBoxes:autoSetListBoxSize(myListBox as NodeRef of Class GUIControl)

autoSetDropDownSize will assess the size of the list box's parent, as well as all current list elements and the title, and will attempt to determine the best width for the list box. This does not currently work very well if the list box's parent is created in the same script call, as the parent will not be resized yet, so will most likely force an unnecessarily small maximum width on the list box.

It is quite alright to set the width of the main list box control manually, as well.

Note that list boxes are always 20 pixels tall, and should not be made taller, as this creates bad mojo. They should therefore never be set to any dockModes except NONE (their default), TOP, or BOTTOM.

 GUIListBoxes:clearListBox(myListBox as NodeRef of Class GUIControl)

As one might infer, this will destroy all list items within a list box, including the title.

 GUIListBoxes:getListBoxValue(myListBox as NodeRef of Class GUIControl) as String

This function will return a string containing the list box's currently selected list item, which may include the list box's original title, if one was specified and no item has been selected yet. Exception scripts should be prepared to handle an empty string, or one containing the default title.

Speaking of exception scripts, as previously mentioned, when populating the list box with items, it is possible to specify a script for any or all items. An item with a script will, when selected, attempt to make a callback to the following function in its script.

 shared function onListBoxSelection(myListItem as string)

Each item in a list box may have its own script, or none at all. Note that these callbacks are made at the time of selection, much like a javaScript onChange event.

The following is an example of how to create and populate a list box.

function testDropDownBox()
  window as NodeRef of Class GUIControl = createNodeFromPrototype("window") = true = "aaronTestWindow"
  window.position.x = 200
  window.position.y = 200
  window.size.x = 400
  window.size.y = 400
  // make dropdown
  dropdown as NodeRef of Class GUIControl = createNodeFromPrototype("dropDownBox") = true
  clientarea as NodeRef of Class GUIControl = findGUIControlByName(window, "clientarea")
  add back dropdown to clientarea.children
  GUIListBoxes:setListBoxTitle(dropdown, "Aaron's DropDown Test")
  dropdown.position.x = 20
  dropdown.position.y = 40 = "dropDownTest"
  // add some items
  items as List of String
  i as Integer = 1
  while (i <= 20)
    add back "longer item " + i to items
    i = i + 1
  GUIListBoxes:populateListBox(dropdown, items)
  // add scripts to a few items
  scripts as LookupList indexed by String of ScriptRef
  scripts["item 1"] = basegui
  scripts["item 8"] = basegui
  scripts["item 14"] = aarontest
  scripts["item 17"] = basegui
  GUIListBoxes:populateListBoxScripts(dropdown, scripts)
//  GUIListBoxes:autoSetListBoxSize(dropdown)

To Do


Add an additional callback to capture keypress events on combo box titles. But not today..

It is possible to set up an entire list box, including any and all list items, via XML instead of dynamically via script. Add documentation for this.

Try to figure out a way to autogenerate a unique name for list boxes on creation which won't be resource-intensive. onLayout might work.

Personal tools