<table border="0" cellpadding="0" cellspacing="0" width="700">
<tbody>
<tr>
<td width="700"><table id="toc" summary="Contents">
<tbody>
<tr>
<td><div id="toctitle">
<h2>Contents</h2></div>
<ul>
<li class="toclevel-1"><a href="#Introduction"><span class="tocnumber">1</span> <span class="toctext">Introduction</span></a></li>
<li class="toclevel-1"><a href="#Setting_Up"><span class="tocnumber">2</span> <span class="toctext">Setting Up</span></a></li>
<li class="toclevel-1"><a href="#Adding_Controls"><span class="tocnumber">3</span> <span class="toctext">Adding Controls</span></a></li>
<li class="toclevel-1"><a href="#Adding_Functionality"><span class="tocnumber">4</span> <span class="toctext">Adding Functionality</span></a></li>
<li class="toclevel-1"><a href="#Scripting_Hooks"><span class="tocnumber">5</span> <span class="toctext">Scripting Hooks</span></a></li>
<li class="toclevel-1"><a href="#Conclusion"><span class="tocnumber">6</span> <span class="toctext">Conclusion</span></a></li>
</ul></td>
</tr>
</tbody>
</table>
<a name="Introduction" id="Introduction"></a>
<h2> <span class="mw-headline">Introduction</span></h2>
<p><img alt="Image:5_FinalGui.jpg" src="5_Images/5_FinalGui.jpg" border="0" height="361" width="529" /> </p>
<p><br />
This project will cover the list control, how to add, remove and insert
items in to the list. We will make an interactive demo showing how and
where to put the scripts for this project to function. Find out how to
make selections, multi-selections and display the results. </p>
<p><br />
Suggested Reading: </p>
<ul>
<li><a href="../Overview/Introduction.html">GUI Editor Overview</a> </li>
<li><a href="../Overview/Interface.html">GUI Interface</a> </li>
<li><a href="../../Scripting/Overview/Introduction.html">TorqueScript Reference</a> </li>
<li><a href="Firstgui.html">GUI Tutorial 1</a> </li>
<li><a href="Controls.html">GUI Tutorial 2</a></li>
<li><a href="Console.html">GUI Tutorial 3</a> </li>
<li><a href="Gameoverlay.html">GUI Tutorial 4</a> </li>
</ul>
<p><br />
Covered in this tutorial: </p>
<ul>
<li>Introduce the List Control </li>
<li>Single and multi-selection </li>
<li>How to populate your list </li>
<li>Adding an Item </li>
<li>Removing an Item </li>
<li>Inserting an Item </li>
</ul><br>
<a name="Setting_Up" id="Setting_Up"></a>
<h2> <span class="mw-headline">Setting Up</span></h2>
<p>Open your tutorial project and start the GUI Editor. Create a new Gui called <b>testList</b> using the GUI Class
type <b>GuiControl</b>. From the controls library add a <b>GuiWindowCtrl</b> to the editor work space.
Resize so as to fit a few buttons and a list similar to the above image. </p>
<p><br />
GuiWindow property text: <b>My List</b> </p>
<p><br />
Now we are ready to add our controls to the new window. </p><br>
<a name="Adding_Controls" id="Adding_Controls"></a>
<h2> <span class="mw-headline">Adding Controls</span></h2>
<p><b>STEP 1:</b> First we will add our buttons to the window. Select
the <b>GuiWindowCtrl</b> control and add a <b>GuiButtonCtrl</b> from the library.
Reduce its width a little,
then copy / paste another 6 copies and move them so that you have
something similar to the following image. </p>
<p><br />
<b>Hint: GuiButtonCtrl</b> is located in the <b>Library > Buttons</b> category.
</p>
<p><br />
<img alt="Image:5_InitialLayout.jpg" src="5_Images/5_InitialLayout.jpg" border="0" height="364" width="478" /> </p>
<p><br />
Remember to use the toolbar align tools to help keep you GUI layout uniform and neat. </p>
<p><br />
<i><b>HINT</b>: You may want to turn on Toggle Center Smart Snapping from the tool bar to help align the controls.</i> </p>
<p><img alt="Image:5_SmartSnapping.jpg" src="5_Images/5_SmartSnapping.jpg"
border="0" /> </p>
<p><br />
<b>STEP 2:</b> Next we need to set the button properties; </p>
<p><br />
<b>button 1</b> property text: <b>Populate</b> </p>
<p><b>button 2</b> property text: <b>Show Selection</b> </p>
<p><b>button 3</b> property text: <b>Add</b> </p>
<p><b>button 4</b> property text: <b>Remove</b> </p>
<p><b>button 5</b> property text: <b>Insert</b> </p>
<p><b>button 6</b> property text: <b>Clear List</b> </p>
<p><b>button 7</b> property text: <b>Select Multi</b> </p>
<p><br />
Save your new GUI to <b>game/art/gui</b> as <b>testList.gui</b> </p>
<p><br />
<b>STEP 3:</b> Next we need to add 2 <b>GuiPanelCtrl</b> controls and a few <b>GuiTextCtrl</b> controls. Set new controls' properties as follows: </p>
<p><br />
<b>text 1</b> property text: <b>Item Selected</b> </p>
<p><b>text 2</b> property text: <b>Item Text</b> </p>
<p><br />
<b>text 3</b> property text: <b>00</b> </p>
<p><b>text 3</b> property name: <b>lblItemSelected</b> </p>
<p><br />
<b>text 4</b> property text: <b>00</b> </p>
<p><b>text 4</b> property name: <b>lblItemText</b> </p>
<p><br />
<b>text 5</b> property text: <b>Multi Selected</b> </p>
<p><br />
How it looks so far: </p>
<p><br />
<img alt="Image:5_PrelimGui.jpg" src="5_Images/5_PrelimGui.jpg" border="0" height="349" width="478" /> </p><br>
<p><b>Remember to save often.</b> </p>
<p><br />
<b>STEP 4:</b> Now to add the last few controls. From the Library,
create a <b>GuiScrollCtrl</b> and place it in the center space. Add another
<b>GuiTextCtrl</b>, a <b>GuiTextEditCtrl</b> under the item Text section and a
<b>GuiMLTextCtrl</b> under the <b>Multi Selected</b> text. </p>
<p><br />
<img alt="Image:5_MLTextCtrl.jpg" src="5_Images/5_MLTextCtrl.jpg" border="0" height="351" width="480" /> </p>
<p><br />
<b>Properties:</b> </p>
<p><br />
<b>GuiTextCtrl</b> property text: <b>Enter</b> </p>
<p><b>GuiTextEditCtrl</b> property name: <b>txtEnter</b> </p>
<p><b>GuiMLTextCtrl</b> property name: <b>lblMLSelected</b> </p>
<p><br />
<b>STEP 5:</b> Select the <b>GuiScrollCtrl</b> so that it is highlighted and
add a <b>GuiListBoxCtrl</b> to the scroll control, this scroll control must
become the container for the List box. </p>
<p><br />
<b>GuiListBoxCtrl</b> property name: <b>lstTestList</b> </p>
<p><br />
That takes care of all our controls. Save your GUI and close down the project. Time to get into some script. </p><br>
<a name="Adding_Functionality" id="Adding_Functionality"></a>
<h2> <span class="mw-headline">Adding Functionality</span></h2>
<p><b>STEP 1</b>: Create a new script file in <b>game/scripts/gui</b> and name it <b>testList.cs</b> and open it in your favorite script editor. </p>
<p><br />
<i><b>NOTE</b>: The list control is indexed from 0 for the first entry.</i> </p>
<p><br />
The list control exposes a few methods for us to use in
populating and controlling list content. We are going to use the
following: </p>
<p><br />
GuiListBoxCtrl.addItem( itemContent ) </p>
<p>GuiListBoxCtrl.deleteItem( itemNumber ) </p>
<p>GuiListBoxCtrl.insertItem( itemContent, itemNumber ) </p>
<p>GuiListBoxCtrl.getItemText( itemNumber ) </p>
<p>GuiListBoxCtrl.clearItems() </p>
<p>GuiListBoxCtrl.getSelCount() </p>
<p>GuiListBoxCtrl.getSelectedItem() </p>
<p>GuiListBoxCtrl.getSelectedItems() </p>
<p>Copy the following script to your new <b>testList.cs:</b> </p>
<pre>function testList::addItem()
{
lstTestList.addItem(txtEnter.getValue());
}
//Insert An Item at the selection
function testList::insertItem()
{
lstTestList.insertItem(txtEnter.getValue(),lstTestList.getSelectedItem());
}
//Remove a selected Item
function testList::removeItem()
{
lstTestList.deleteItem(lstTestList.getSelectedItem());
}
//Fill list with content
function testList::populate()
{
for(%i = 0;%i < 10;%i++)
{
lstTestList.addItem( "Option " @%i);
}
}
//show selected content
function testList::getSelectedContent()
{
%item = lstTestList.getSelectedItem();
lblItemSelected.setValue(%item );
lblItemText.setValue(lstTestList.getItemText(%item ));
}
//Clear the list of items
function testList::clearList()
{
lstTestList.clearItems();
}
//Display multiselected items
function testList::multiSelect()
{
//number of selected items
%count = lstTestList.getSelCount();
//returns a space delimited list of all the selected items indexes in the list
%options = lstTestList.getSelectedItems();
// parse selected items list
for(%item = 0;%item <%count;%item++)
{
%option = getWord(%options,%item);
%t = lstTestList.getItemText(%option);
%text =%text @%t @ "\n";
lblMLSelected.setValue(%text );
}
}
STEP 2: Next we need to add our new script to the engine, open the game/scripts/client/init.cs and
add the following under the section named // Execute the GUI scripts and functions:
exec("scripts/gui/testList.cs");
We also need to add our gui to this file. Under // Load up the shell GUIs add the following:
exec("art/gui/testList.gui");
Save of your files and run your project. Open the testList GUI once again.
For the final part of this tutorial we need to add the ability to
call our new functions from the respective buttons. Set the buttons
properties as follows:
button "Populate" property Command: testList.populate();
button "Show Selection" property Command: testList.getSelectedContent();
button "Add" property Command: testList.addItem();
button "Remove" property Command: testList.removeItem();
button "Insert" property Command: testList.insertItem();
button "Clear List" property Command: testList.clearList();
button "Select Multi" property Command: testList.multiSelect();
Remember to save your GUI. Preview your GUI and try out the
buttons, enter some text into the text edit box and try add, insert
etc. To multi-select hold down shift while selecting list items, then press
the Select Multi button.
In this tutorial, you learned the following concepts:
- Introduce the List Control
- Single and multi-selection
- How to populate your list
- Adding an Item
- Removing an Item
- Inserting an Item
In the next tutorial we will create an advanced graphical representation of a GUI.