Scripting the GUI - Tutorial 1

Scripting the Gui - Tutorial 1 (Gridlists)

In this tutorial we will explore the use of gridlists in creating a vehicle selection screen, with optional clientside vehicle xml data reading.

Note that this tutorial assumes you are familiar with all the content covered in the Previous tutorial.

Setting up the Vehicle Selection

Creating the GUI

To begin, open up a clientside lua file (if you have been following the Scripting Introduction, this is gui.lua) to work with.

In this file, we will start writing our function for creating the GUI. As covered in the Previous tutorial, there are 2 value type options available when creating gui: relative and absolute.

For the purposes of this tutorial, we will be using absolute values.

This will create a simple GUI with a window, gridlist and button:

function createVehicleSelection()
	-- get the screen width and height
	local sWidth, sHeight = guiGetScreenSize()
	
	-- use some simple maths to position the window in the centre of the screen
	local Width,Height = 376,259
	local X = (sWidth/2) - (Width/2)
	local Y = (sHeight/2) - (Height/2)
	windowVehicleSelection = guiCreateWindow(X,Y,Width,Height,"Vehicle Selection Window",false)
	
	gridlistVehicleSelection = guiCreateGridList(10,26,357,192,false,windowVehicleSelection)
	-- add a "Vehicle" and a "Type" collumn to the gridlist
	guiGridListAddColumn(gridlistVehicleSelection,"Vehicle",0.2)
	guiGridListAddColumn(gridlistVehicleSelection,"Type",0.2)
	
	-- set the default width of the columns to roughly half the size of the gridlist (each)
	guiGridListSetColumnWidth(gridlistVehicleSelection,1,0.4,true)
	guiGridListSetColumnWidth(gridlistVehicleSelection,2,0.5,true)
	
	buttonCreate = guiCreateButton(121,227,120,20,"Create",false,windowVehicleSelection)
	
	-- add the event handler for when the button is clicked
	addEventHandler("onClientGUIClick",buttonCreate,createVehicleHandler,false)
	
	-- hide the GUI
	guiSetVisible(windowVehicleSelection,false)
	
	-- this will add all the vehicle options onto the gridlist, it is explained later in this tutorial
	populateGridlist()
end

We now also need to call this function somewhere, otherwise the GUI will never be created. As in previous tutorials, to do this we can use onClientResourceStart.

-- when the resource is started, create the GUI and hide it
addEventHandler("onClientResourceStart",getResourceRootElement(getThisResource()),
	function()
		createVehicleSelection()
	end
)

Showing the GUI

Unlike in previous tutorials, we want players to be able to open this window whenever they chose, not when the resource starts. So, we can add a Command to do this.

-- create the function that will show the window
function showVehicleSelection()
	-- if the window isnt visible, show it
	if not guiGetVisible(windowVehicleSelection) then
		guiSetVisible(windowVehicleSelection,true)
		
		showCursor(true,true)
	end
end

-- add the command /vehicleselection and set it to call the showVehicleSelection function
addCommandHandler("vehicleselection",showVehicleSelection)

Populating the Gridlist from a table

Now that we have our basic GUI created, we need to fill the gridlist with all of our vehicles.

To begin with, we will do this using a simple clientside table. Later in the tutorial, we will explore expanding this method to use .xml files for storing information. To begin, we must create a small table containing a selection of vehicles that we can spawn.

The table contains vehicles in the format ["description"] = vehicle_id :

-- create the table and fill it with a selection of vehicle ids and names
local vehicleSelectionTable = {
	["Sparrow"] = 469,
	["Stuntplane"] = 513,
	["BF-400"] = 581,
	["Freeway"] = 463,
	["Speeder"] = 452,
	["Jester"] = 559,
	["Sabre"] = 475,
	["Police Ranger"] = 599,
	["Utility Van"] = 552,
	["Tug"] = 583
}

Place this code at the very top of your file (it does not need to be inside a function).

Next, we can write our "populateGridlist" function which will fill the Gridlist with all the vehicles in the table. To do this we simply need to loop through all the values in the table, adding each one to the gridlist as we go. We will also set hidden data using guiGridListSetItemData to store the vehicle id:

function populateGridlist()
	-- loop through the table
	for name,vehicle in pairs(vehicleSelectionTable) do
		-- add a new row to the gridlist
		local row = guiGridListAddRow(gridlistVehicleSelection)

		-- set the text in the first column to the vehicle name
		guiGridListSetItemText(gridlistVehicleSelection,row,1,name,false,false)
		-- set the text in the second column to the vehicle type
		guiGridListSetItemText(gridlistVehicleSelection,row,2,getVehicleType(vehicle),false,false)
		
		-- set the data for gridlist slot as the vehicle id
		guiGridListSetItemData(gridlistVehicleSelection,row,1,tostring(vehicle))
	end
end

Managing the click

Now that we have our GUI completed, we need to be able to catch any clicks made on the "create" button. We have attached the onClientGUIClick event to buttonCreate already, so now we need to write the function that it calls. In this function we do some basic error checking, such as making sure a vehicle has been selected in the list. We can then use some maths to find a position infront of the player and send the server this information to spawn the vehicle (using triggerServerEvent)

function createVehicleHandler(button,state)
	if button == "left" and state == "up" then
		-- get the selected item in the gridlist
		local row,col = guiGridListGetSelectedItem(gridlistVehicleSelection)
		
		-- if something is selected
		if row and col and row ~= -1 and col ~= -1 then
			-- get the vehicle id data from the gridlist that is selected
			local selected = guiGridListGetItemData(gridlistVehicleSelection,row,col)
			
			-- make sure the vehicle id is a number not a string
			selected = tonumber(selected)
						
			-- get the players position and rotation
			local rotz = getPedRotation(getLocalPlayer())
			local x,y,z = getElementPosition(getLocalPlayer())
			-- find the position directly infront of the player
			x = x + ( math.cos ( math.rad ( rotz+90 ) ) * 3)
			y = y + ( math.sin ( math.rad ( rotz+90 ) ) * 3)
			
			if selected and x and y and z then
				-- trigger the server
				triggerServerEvent("createVehicleFromGUI",getRootElement(),selected,x,y,z)
				
				-- hide the gui and the cursor
				guiSetVisible(windowVehicleSelection,false)
				showCursor(false,false)
			else
				outputChatBox("Invalid arguments.")
			end
		else
			-- otherwise, output a message to the player
			outputChatBox("Please select a vehicle.")
		end
	end
end

Creating the Vehicle

At this point we now have all the code needed on the client side, so open up a serverside .lua file to work with.

On the server side, we will first of all need to define the custom event that we triggered before from the client. This can be done using addEvent and addEventHandler. Finally we will need a small function for creating the vehicle:

function createMyVehicle(vehicleid,x,y,z)
	-- check all the arguments exist
	if vehicleid and x and y and z then
		createVehicle(vehicleid,x,y,z)
	end
end

addEvent("createVehicleFromGUI",true)
addEventHandler("createVehicleFromGUI",root,createMyVehicle)

Note the use of the "root" variable. This is an MTA variable containing the root element; every resource has one.

This completes the first section of the tutorial. You should now have a basic, working vehicle spawn script.

In the second section, we will cover collapsible gridlist data and clientside xml file reading.

Expanding the code

This section will detail several ways to improve upon the code you now have.

Importing Data

One big improvement over the previously mentioned method is to use external files to store the vehicle information, allowing us to much more quickly and easily manage large amounts of data. For this tutorial, we will use a clientside xml file to hold the information.

First of all you will need to create your xml file, so navigate to your resources directory and create a new file named vehicles.xml:

For the purpose of this example, we will include only a small fraction of the total vehicles, however the file can easily be expanded to include them all.

If you are unsure of xml data structures, you can browse the MTA xml functions for help.

<root>
	<group type="Bikes">
		<vehicle id="581" name="BF-400"/>
		<vehicle id="463" name="Freeway"/>
		<vehicle id="481" name="BMX"/>
	</group>
	<group type="Boats">
		<vehicle id="472" name="Coastguard"/>
		<vehicle id="452" name="Speeder"/>
	</group>
	<group type="Helicopters">
		<vehicle id="487" name="Maverick"/>
		<vehicle id="469" name="Sparrow"/>	
	</group>
	<group type="Planes">
		<vehicle id="593" name="Dodo"/>
		<vehicle id="513" name="Stuntplane"/>	
	</group>
	<group type="Sports Cars">
		<vehicle id="565" name="Flash"/>
		<vehicle id="559" name="Jester"/>
		<vehicle id="477" name="ZR-350"/>	
	</group>
	<group type="2-Door">
		<vehicle id="474" name="Hermes"/>
		<vehicle id="475" name="Sabre"/>
	</group>
	<group type="Emergency">
		<vehicle id="416" name="Ambulance"/>
		<vehicle id="599" name="Police ranger"/>
	</group>
	<group type="Industrial">
		<vehicle id="573" name="Dune"/>
		<vehicle id="552" name="Utility van"/>	
	</group>
	<group type="Misc">
		<vehicle id="457" name="Caddy"/>
		<vehicle id="583" name="Tug"/>
	</group>
</root>

Once you have created your file, do not forget to add it to the meta.xml of your resource with the appropriate client tag.

Note the group "type" tag. This is an arbitrary description of the vehicles contained within the group and can be renamed or added as any text. Similarly, the vehicle "name" tag is also just a textual description of the vehicle and does not need to be the exact vehicle name.

Now that we have the data, we can import it into the game and display it in the GUI. If you are following on from the first section of this tutorial, this new code will replace what is inside your existing 'populateGridlist' function. First, we need to load the file:

function populateGridlist()
	-- load the file and save the root node value it returns
	local rootnode = xmlLoadFile("vehicles.xml")
	
	-- check that the file exists and has been correctly loaded
	if rootnode then		
		-- unload the xml file
		xmlUnloadFile(rootnode)
	end
end

Always make sure you unload any files once you are finished using them.

We can now start collecting the data from the file and entering it into our gridlist. We can do this by looping through the xml data (in a similar manner to looping through the vehicle table earlier in this tutorial) and adding each entry into the list.

function populateGridlist()
	local rootnode = xmlLoadFile("vehicles.xml")
	
	if rootnode then		
		-- first, we find every "group" node (they are direct children of the root)
		for _,group in ipairs(xmlNodeGetChildren(rootnode)) do
			-- add a new row to the gridlist
			local row = guiGridListAddRow(gridlistVehicleSelection)

			-- get the group name
			local name = xmlNodeGetAttribute(group,"type")
			
			-- set the text in the first column to the group type and indicate it is a section ('true')
			-- (sections on gridlists show up in bold and cannot be clicked)
			guiGridListSetItemText(gridlistVehicleSelection,row,1,name,true,false)			
		
			-- then, for every group that we find, loop all of its children (the vehicle nodes)
			-- and add them into the gridlist
			for _,vehicle in ipairs(xmlNodeGetChildren(group)) do
				-- add a new row to the gridlist
				row = guiGridListAddRow(gridlistVehicleSelection)

				-- get the vehicle name and id
				name = xmlNodeGetAttribute(vehicle,"name")
				local id = xmlNodeGetAttribute(vehicle,"id")
				
				-- set the text in the first column to the vehicle name
				guiGridListSetItemText(gridlistVehicleSelection,row,1,name,false,false)
				-- set the text in the second column to the vehicle type
				guiGridListSetItemText(gridlistVehicleSelection,row,2,getVehicleType(tonumber(id)),false,false)		
				
				-- finally, set the vehicle id as data so we can access it later
				guiGridListSetItemData(gridlistVehicleSelection,row,1,tostring(id))
			end
		end	
	
		-- unload the xml file now that we are finished
		xmlUnloadFile(rootnode)
	end
end

Note the use of for loops in the code with xmlNodeGetChildren. This saves us a lot of time and effort as we do not have to manually code each group and vehicle into the list.

You should now have a fully working vehicle selection menu, reading all of its data from a clientside xml file. Next, we will examine how to generate the appearance of collapsing and expanding sections in a gridlist.

Collapsing/Expanding the Gridlist

Allowing sections of the gridlist to be collapsed or expanded gives much more control over the visible content to the user. This frees up space on the screen and makes the whole menu much more comfortable to use.

Loading the data

To be able to achieve this effect (as it is not a natural feature of gridlists) we will need to load the vehicle information into a table (from the xml file), rather than directly including it all in the gridlist. If you are following on from a previous section of this tutorial, this new code will replace what is inside your existing 'populateGridlist' function.

This works in much the same way the previous xml loading example does, only this time instead of saving the data into the gridlist, we save it into a table entry instead. We also set the custom data "header" on the gridlist slots to denote which gridlist entries are our "group" entries and which are vehicles.

function populateGridlist()
	local rootnode = xmlLoadFile("vehicles.xml")
	
	-- create a blank global table to store our imported data
	vehicleTable = {}
	
	if rootnode then		
		for _,group in ipairs(xmlNodeGetChildren(rootnode)) do
			-- create an entry in the gridlist for every vehicle "group"
			local row = guiGridListAddRow(gridlistVehicleSelection)

			local name = xmlNodeGetAttribute(group,"type")
			
			guiGridListSetItemText(gridlistVehicleSelection,row,1,name,false,false)	

			-- add an entry containing the group name into the table
			vehicleTable[name] = {}
			
			-- we will use the custom data "header" to indicate that this entry can be expanded/collapsed
			guiGridListSetItemData(gridlistVehicleSelection,row,1,"header")	
		
			-- then, for every group that we find, loop all of its children (the vehicle nodes) and store them in a table
			for _,vehicle in ipairs(xmlNodeGetChildren(group)) do
				local vname = xmlNodeGetAttribute(vehicle,"name")
				local id = xmlNodeGetAttribute(vehicle,"id")			
			
				-- insert both the vehicle id and the vehicle description into the table
				table.insert(vehicleTable[name],{id,vname})
			end
		end	
	
		-- set element data on the gridlist so we know which group is currently showing
		setElementData(gridlistVehicleSelection,"expanded","none")
	
		-- unload the xml file now that we are finished
		xmlUnloadFile(rootnode)
	end
end

Now that we have all the data stored, we can quickly manipulate it when neccessary.

Managing the double click

To enable the player to simply double click on a group name to expand/collapse it we need to use the onClientGUIDoubleClick event. If we attach it to the gridlist, we can then catch any double clicks on the group names in it:

-- attach the onClientGUIDoubleClick event to the gridlist and set it to call processDoubleClick
addEventHandler("onClientGUIDoubleClick",gridlistVehicleSelection,processDoubleClick,false)

Add this line of code in your createVehicleSelection, after the gridlist has been created.

As the gridlist items are not separate GUI elements, we must capture all clicks from anywhere on the gridlist then process them to filter out the ones we do not want. This can be done by checking if an item is selected, then checking if the item is one of our "group" values (using our previously mentioned "header" data):

function processDoubleClick(button,state)
	if button == "left" and state == "up" then
		local row,col = guiGridListGetSelectedItem(gridlistVehicleSelection)
		
		-- if something in the gridlist has been selected
		if row and col and row ~= -1 and col ~= -1 then		
			-- if it is a header
			if guiGridListGetItemData(gridlistVehicleSelection,row,col) == "header" then
				local selected = guiGridListGetItemText(gridlistVehicleSelection,row,col)
				
				-- call the function to collapse or expand the menu and pass which section it is as an argument
				changeGridlistState(selected)
			end
		end
	end
end

Once we have narrowed down the double clicks to only those done on our group headers, we can expand/collapse them appropriately. This can be done by simply setting new text values in the gridlist according to the newly expanded/collapsed group, which creates the convincing illusion of collapsable menus.

Note that much of the following code is reused from previous areas of this tutorial. While it is generally bad practice to clone sections of code in this way, for the purposes of this example it is far easier to understand.

function changeGridlistState(group)
	if group then
		-- if the group is already expanded, we want to collapse it
		if getElementData(gridlistVehicleSelection,"expanded") == group then
			-- first, we clear all previous data from the gridlist
			guiGridListClear(gridlistVehicleSelection)
			
			-- now, loop all the group entries in the vehicle table that we created earlier
			for group,_ in pairs(vehicleTable) do
				-- add each group to the list and mark them with "header"			
				local row = guiGridListAddRow(gridlistVehicleSelection)
				
				guiGridListSetItemText(gridlistVehicleSelection,row,1,group,false,false)	
				guiGridListSetItemData(gridlistVehicleSelection,row,1,"header")	
			end
			
			-- update the data to indicate that no groups are currently expanded
			setElementData(gridlistVehicleSelection,"expanded","none")
			
		-- otherwise, we want to expand it
		else
			guiGridListClear(gridlistVehicleSelection)
			
			local row = guiGridListAddRow(gridlistVehicleSelection)
			
			guiGridListSetItemText(gridlistVehicleSelection,row,1,group,false,false)	
			guiGridListSetItemData(gridlistVehicleSelection,row,1,"header")				
			
			-- loop every vehicle in the specified groups table
			for _,vehicle in ipairs(vehicleTable[group]) do
				-- add them to the gridlist and set the vehicle id as data
				row = guiGridListAddRow(gridlistVehicleSelection)
			
				-- format a "-" into the string to make it visually easier to distinguish between groups and vehicles
				guiGridListSetItemText(gridlistVehicleSelection,row,1,"- "..vehicle[2],false,false)	
				guiGridListSetItemText(gridlistVehicleSelection,row,2,getVehicleType(tonumber(vehicle[1])),false,false)	
											
				guiGridListSetItemData(gridlistVehicleSelection,row,1,tostring(vehicle[1]))
			end	

			-- update the data to indicate which group is currently expanded
			setElementData(gridlistVehicleSelection,"expanded",group)			
		end
	end
end

This comletes the second section of the tutorial.

For further GUI tutorials, see Tutorial 2 (Gates and Keypads)