ListBox

The ListBox window element provides an automated way of viewing large tables of data without manually allocating large numbers of window elements for the display.

Summary
ListBoxThe ListBox window element provides an automated way of viewing large tables of data without manually allocating large numbers of window elements for the display.
Implementation DetailsA listbox is comprised of three main components.
XML DefinitionThis is the ListBox xml definition.
XML Tag
Required Attributes
Optional Attributes
rowdefThe name of a Window to use as a template for each row in the display.
scrollbarThe name of a <VerticalScrollBar> to use if the number of items in the list extends past the number of visible items.
rowcountThe maximum number of items in the list to display.
visiblerowsThe number of rows visible on the display at a time.
rowspacingSize of the space to leave between rows.
Elements
ListDataThis element describes how the data should be displayed in each row.
Functions
Functions
ListBoxSetDataTable()Sets the data table to use to get the list data.
ListBoxGetDataIndex()Returns the data-table index that is currently display on a particular row index.
ListBoxSetDisplayOrder()Sets the order in which the data list is displayed.
ListBoxSetVisibleRowCount()Sets the maximum number of rows that can be displayed on the screen at once.

Implementation Details

Elements

A listbox is comprised of three main components.

  • A lua array (table with values [1]...[n]) that contains your data structures.
  • A Window definition that defines the format for a single row in the table display.  This Window may have as many child elements as you wish.
  • A VerticalScrollbar definition to use to scroll through items in the list when needed.

Data Population

The List Box will automatically populate text and icon elements within the row through the ListData binding that you set up as part of the XML definition.  You can display:

Labels and Buttons with...

  • Text (as width string values)
  • Numbers (as the plain value, or formatted with commas)

DynamicImages with....

  • Icons (based on an valid Icon id )

Sorting and Filtering

The list is populated with data from lua by the <SetDisplayOrder> function.  This call allows you determine which sub-set of data you wish to display, and in which order.  You can craft your own lua-sort functions to fit your specific needs.

XML Definition

This is the ListBox xml definition.

Summary
XML Tag
Required Attributes
Optional Attributes
rowdefThe name of a Window to use as a template for each row in the display.
scrollbarThe name of a <VerticalScrollBar> to use if the number of items in the list extends past the number of visible items.
rowcountThe maximum number of items in the list to display.
visiblerowsThe number of rows visible on the display at a time.
rowspacingSize of the space to leave between rows.
Elements
ListDataThis element describes how the data should be displayed in each row.

XML Tag

<ListBox>
....
</ListBox>

Required Attributes

  • none

Optional Attributes

rowdef

The name of a Window to use as a template for each row in the display.  Child elements of this Window are refereced by the windowname param in the ListData elememt.

Expects

A string value, which is the name of a valid Window.

Default Value

  • ””

Notes

  • none

scrollbar

The name of a <VerticalScrollBar> to use if the number of items in the list extends past the number of visible items.

Expects

A string value, which is the name of a valid <VerticalScrollBar>.

Default Value

  • ””

Notes

  • none

rowcount

The maximum number of items in the list to display.

Expects

A number value

Default Value

  • 0

Notes

  • none

visiblerows

The number of rows visible on the display at a time.

Expects

A number value

Default Value

  • 0

Notes

  • none

rowspacing

Size of the space to leave between rows.

Expects

A number value

Default Value

  • 0

Notes

  • none

Elements

ListData

This element describes how the data should be displayed in each row.

Syntax

<ListData table="InteractionWindow.storedata" populationfunction="InteractionWindow.SetStoreItemPrices">
   <ListColumns>
        <ListColumn windowname="ItemPicIconBase" variable="iconNum" format="icon" />
        <ListColumn windowname="ItemName" variable="name" format="wstring"/>
        <ListColumn windowname="ItemCost" variable="cost" format="number"  />
    </ListColumns>
</ListData>
tableThe name of the Lua-Table varaible that will contain the list data.
populationfunctionAn optional callback function to allow lua to modify how the rows are displayed.

The ListColumns connect the row’s UI elements to specific data members.  When the list box is updated/scrolled, these window elements are updated automatically to display the data.

windownameThe name of a child-element of the rowdef.
varaibleThe name of a lua-variable within each index of the data table.
formatThe data-type of the variable (Values: icon, wstring, number )
styleThe style for number displays.  (Values: default, comma )

Notes

  • none

Functions

Summary
Functions
ListBoxSetDataTable()Sets the data table to use to get the list data.
ListBoxGetDataIndex()Returns the data-table index that is currently display on a particular row index.
ListBoxSetDisplayOrder()Sets the order in which the data list is displayed.
ListBoxSetVisibleRowCount()Sets the maximum number of rows that can be displayed on the screen at once.

Functions

ListBoxSetDataTable()

Sets the data table to use to get the list data.

Parameters

editBoxName(string) The name of the EditBox.
dataTable(string) The name of a valid lua table.

Returns

nil = no return value

Related XML

Notes

  • none

Example

ListBoxSetDataTable("AbilitiesWindowAbilityList", AbilitiesWindow.moraleList )

ListBoxGetDataIndex()

Returns the data-table index that is currently display on a particular row index.

Parameters

listBoxName(string) The name of the ListBox.
rowIndex(number) The row index on the list box ( 1 -> max vis rows )

Returns

dataIndex(number) The index in the ListData lua table.

Related XML

Notes

  • none

Example

local dataIndex = ListBoxGetDataIndex("AbilitiesWindowAbilityList" )

ListBoxSetDisplayOrder()

Sets the order in which the data list is displayed.  This function allows you to both sort and filter in lua.

Parameters

listBoxName(string) The name of the ListBox.
displayOrder(number-table) The data-indicies in the order that they should be displayed.

Returns

nilno return value

Related XML

Notes

  • none

Example

local displayOrder = {}
table.insert(displayOrder, 5) -- add the 5th item from the source data table
LuaSetDisplayOrder("AbilitiesWindowAbilityList", displayOrder )

ListBoxSetVisibleRowCount()

Sets the maximum number of rows that can be displayed on the screen at once.

Parameters

listBoxName(string) The name of the ListBox.
visibleRows(number) Sets the max number of rows to display at once.

Returns

nilno return value

Related XML

Notes

  • none

Example

ListBoxSetVisibleRowCount("AbilitiesWindowAbilityList", 10 )
Window is the base level window definition.
The VerticalScrollbar provides a windows-style scroll bar.
This element describes how the data should be displayed in each row.
The Label window element is the primary text-drawing element for the Interface.
The button element automates generic button functionality, such as swapping texture and font colors automatically according to mouse over and state.
The DynamicImage provides a rectangular shaped display for a texture.
This element defines the data for a single icon.
The name of a Window to use as a template for each row in the display.
The number of rows visible on the display at a time.
The maximum number of items in the list to display.