View source for HU/Scripting the GUI - Tutorial 3

'''GUI készítése - Tutorial 3 (Görgethető hírek)'''

Ebben a tutoriálban megvizsgáljuk, hogy hogyan hozhatunk létre egy görgethető hírek GUI-t, 
lehetővé téve a gyors és egyszerű szerver frissítések és más szerver információk megjelenítését a játékosnak.
Az összes híreket egy kliens oldali xml fájlban fogjuk tárolni, és néhány egyszerű xml olvasást fogunk használni, hogy betöltjük őket a játékba.

We will then animate the news item to scroll along the bottom of the screen, updating the news text once it has scrolled beyond the edge of the screen.

'''Ne feledje, hogy ez a tutoriál feltételezi azt, hogy tisztában van az [[HU/Introduction to Scripting the GUI|előző tutoriálban]] bemutatott összes tartalommal'''


==A hírek létrehozása==
Kezdésként nyisson meg egy client oldali lua fájlt (ha követte a [[HU/Bevezetés a scriptelésbe|bevezetés a scriptelésbe]] oldalt, akkor ez a gui.lua lesz) amivel majd dolgozni fog.

===A GUI létrehozása===
Az előző tutoriálok használata után most már jól kell ismernie a GUI létrehozásának lépéseit, ezért nem is fogunk túl nagy részleteiben belemenni. 
<syntaxhighlight lang="lua">
function createNewsFeed()
	-- get the screen width and height
	local sWidth, sHeight = guiGetScreenSize()
 
	-- create the gridlist, using some maths to find the bottom-centre of the screen
	local Width,Height = 800,45
	local X = (sWidth/2) - (Width/2)
	local Y = sHeight - (Height/2)
	
	-- the gridlist will act as the background to our news reel
	newsGridlist = guiCreateGridList(X,Y,Width,Height,false)
	
	-- create the label in the same place, but as a child of the gridlist
	-- also make it half the height of the gridlist, as half of the gridlist is off the bottom of the screen
	newsLabel = guiCreateLabel(X,Y,Width,Height/2,"Test text",false,newsGridlist)
	
	-- call our function to read the news out of the xml file
	loadNews()
	
	-- load the first news item in the table
	updateNewsItem(1)
	
	-- define a global variable called 'currentItem' with the value 1
	currentItem = 1
end

addEventHandler("onClientResourceStart",resourceRoot,createNewsFeed)
</syntaxhighlight>
Ne feledje, hogy a címke az a gridlist gyermekeként lett étrehozva. 
Not only is this good practice in general, but it means that we can freely move parts of the label beyond the edge of the gridlist without them showing, which is critical to the visual effect of this tutorial.

Valamint a 'resourceRoot' változó használatát se feledje el. Ez egy olyan MTA változó, amely a használt resource root elem értékét tartalmazza.

A 'currentItem' változóval fogjuk nyomon követni, hogy jelenleg mely híreket jelenítjük meg.

===A hírek megírása===
Most, hogy létrehoztuk a GUI-nkat, szükségünk lesz néhány hírre amivel ezt megtöltjük.
Ehhez egy külsű kliens oldali xml fájlt fogunk használni, hogy beolvassuk a híreket.

Menjen a resource mappába és hozzon létre egy új xml fájlt newsfeed.xml néven (ne felejtse hozzáadni a meta.xml-hez a megfelelő client taggal).

Ebben a fájlban adja meg az alábbi információkat:
<syntaxhighlight lang="lua">
<root>
	<news>This is an example news item.</news>
	<news>From the 'Scripting the GUI' tutorial.</news>
	<news>Showing scrolling news text.</news>
	<news>Written on a GUI news feed.</news>
</root>
</syntaxhighlight>
Ahogy azt láthatja minden hírelemet <news>-ként határoztunk meg, melynek értéke a megjelenítendő hírszöveg.
Nincs korlátozás arra vonatkozóan, hogy mennyi hírelemet adhat hozzá.

===A hírek összegyűjtése===
Miután megírtuk a híreinket, összekell gyűjtenünk őket és tárolni egy táblában a kliens oldalon.
Ezt akkor fogjuk megtenni, amikor a resource elindul, ez megment minket attól, hogy folyamatosan hozzá nyúljunk az xml-hez az új hírek miatt.

Először meg kell adnunk egy táblázatot az elemek tárolásához:
<syntaxhighlight lang="lua">
local newsItems = {}
</syntaxhighlight>
Adja hozzá ezt a sort a script tetejére.
Győzödjön meg arról, hogy nem egy függvényben van benne, különben nem fog működni azon a függvényen kívül (ezt a "local" előtag jelzi).
Ha a script egész részében van meghatározva, akkor az összes függvényben működni fog.


Ezután be kell töltenünk az xml fájlt:
<syntaxhighlight lang="lua">
function loadNews()
	-- load our "newsfeed.xml" file
	local newsfile = xmlLoadFile("newsfeed.xml")
	
	-- if it was successfully loaded
	if newsfile then
	
		-- always remember to unload files once you are finished
		xmlUnloadFile(newsfile)
	end
end
</syntaxhighlight>
'''Ne felejtse el bezárni a fájlt, miután már nem használja őket.'''

Végül hozzáadhatunk több kódot a loadNews függvényünkhoz, hogy beolvassa a híreket a newsItems táblánkba:
<syntaxhighlight lang="lua">
function loadNews()
	local newsfile = xmlLoadFile("newsfeed.xml")
	
	if newsfile then
		-- loop through all the children of the root node (the "news" nodes)
		for index,itemNode in ipairs(xmlNodeGetChildren(newsfile)) do
			-- get the text (the news item) from the node
			local item = xmlNodeGetValue(itemNode)
			
			-- insert it into our newsItems table
			table.insert(newsItems,item)
		end
	
		xmlUnloadFile(newsfile)
	end
end
</syntaxhighlight>
Most ven egy 'newsItems'-nek nevezett táblánk, amely az összes hír szöveget egy xml fájlban tartja.

==A hírek frissítése==
Most, hogy létrehoztuk a GUI-t, és a hírek is készen állnak, írnunk kell még néhány kódot, hogy frissítsük a játékosok számára bemutatott híreket.
Mint azt korábban említettük, a hírek a 'newsLabel' GUI címkéjén fognak megjelenni.

Ehhez egy egyszerű függvényt fogunk írni, hogy megkapjuk a következő hírt a 'newsItems' táblánkból és megjelenítjük a címkénken.
<syntaxhighlight lang="lua">
-- define our function with a newIndex parameter, so that we can pass which news item we want to show
function updateNewsItem(newIndex)
	-- get the new news item from the table
	local item = newsItems[newIndex]
	
	-- update the label text
	guiSetText(newsLabel,item)
	
	-- update the 'currentItem' global variable
	currentItem = newIndex
end
</syntaxhighlight>

===A címke méretezése===
Ahhoz, hogy a híreket a lehető legpontosabban tudjuk görgetni, képesnek kell lennünk arra, hogy a GUI címke ugyanakkora méretű legyen, mint a megjelenített hírek szövege.

Bár ez egy kicsit bonyolultnak tűnhet, de a [[guiLabelGetTextExtent]] fügvénnyel ez nagyon egyszerűen elvégezhető.
Ez jelzi a címkén jelenleg látható szöveg terjedelmét, vagy szélességét.
Szóval néhány az 'updateNewsItems' függvényünkön történő módosítás után ezt kapjuk:
<syntaxhighlight lang="lua">
function updateNewsItem(newIndex)
	local item = newsItems[newIndex]
	
	guiSetText(newsLabel,item)
	
	currentItem = newIndex
	
	-- get the current dimensions of the gui label
	local width,height = guiGetSize(newsLabel,false)
	
	-- get the text width of the label
	local extent = guiLabelGetTextExtent(newsLabel)
	
	-- update the size of the label with the new width (we do not change the height)
	guiSetSize(newsLabel,extent,height,false)
end
</syntaxhighlight>

===A címke elhelyezése===
Now that our GUI label is the correct width, we need to move it to a position where it is ready to scroll onto the screen.

Again, we can do this with a small modification to our 'updateNewsItems' function:
<syntaxhighlight lang="lua">
function updateNewsItem(newIndex)
	local item = newsItems[newIndex]
	
	guiSetText(newsLabel,item)
	
	currentItem = newIndex
	
	local width,height = guiGetSize(newsLabel,false)
	
	local extent = guiLabelGetTextExtent(newsLabel)
	
	guiSetSize(newsLabel,extent,height,false)
	
	-- set the positon to the far right side of the gridlist, ready to scroll on to the left
	guiSetPosition(newsLabel,1,0,true)
end
</syntaxhighlight>
Note the use of '''relative''' position values in the final line of the function. 

In this case, it is far easier than calculating pixel values.

You can use both relative and absolute in the same script if you want to, the only limitation is that you cannot mix them in the same function call. The type of values you are using is defined by the final argument (true or false).
 
This means you cannot do the following and have it set to 400 pixels in, but 0.5% down
<syntaxhighlight lang="lua">
guiSetPosition(yourElement,400,0.5,false)
</syntaxhighlight>
The final argument "false" means both 400 and 0.5 will be read as pixel values.

==Scrolling the News==
The next step is to animate our news feed.

===Looking at Frames===
To do this, we will introduce a new event: [[onClientRender]].
As stated on the [[onClientRender]] wiki page, this event is called every time GTA renders a new frame (ie: very often).

As usual, to use this event we will need to create an event handler for it:
<syntaxhighlight lang="lua">
addEventHandler("onClientRender",root,scrollNews)
</syntaxhighlight>
This will call our scrollNews function every frame, which we will then use to update the position of our news item.

'''Make sure you add this handler after you have defined your scrollNews function.'''

For our purposes, [[onClientRender]] has one main advantage over, for example, [[setTimer]].
As it is called every frame (and therefore is dependant on the players FPS), the movement of the news item will always appear to be completely smooth,
unlike using a timer which would often appear to lag.

===Moving the News===
In our 'updateNewsItem' function, we position the 'newsLabel' to the far right, so we will scroll in from the right to the left.

For this we will simply move the X position by -1 every frame:
<syntaxhighlight lang="lua">
function scrollNews()
	-- if the newsLabel exists
	if newsLabel then
		-- get the current position of the label
		local x,y = guiGetPosition(newsLabel,false)
		
		-- set the new x position of the label as the old position -1
		guiSetPosition(newsLabel,x-1,y,false)
	end
end
</syntaxhighlight>

===Looping around===
Now that our news scrolls across the screen, we need to be able to check when it has scrolled too far to the left
so we can start scrolling from the far-right side again.

We will also need to update the news item, so we should check the next item exists, and if it doesn't, go back to the first.

For this we will use some simple maths in a modification to our 'scrollNews' function:
<syntaxhighlight lang="lua">
function scrollNews()
	local x,y = guiGetPosition(newsLabel,false)
	
	local labelWidth, labelHeight = guiGetSize(newsLabel,false)
	
	-- if the far right position of the label (x + labelWidth) is greater than or equal to 0 (ie: still showing on the gridlist)
	if ((x-1) + labelWidth) >= 0 then
		-- compensate for a small off-by-one bug in MTA
		if x <= 0 then x = x - 1 end
		
		-- update the position as normal
		guiSetPosition(newsLabel,x-1,y,false)
		
	-- otherwise, we move on to the next item and reset the position
	else
		-- get the total number of items in the 'newsItems' table
		local totalItems = #newsItems
		
		-- if the next item on our list does not exist in our table
		if (currentItem + 1) > totalItems then
			-- loop back to the first item in the list
			updateNewsItem(1)
		else
			-- otherwise move onto the next item in the list
			updateNewsItem(currentItem + 1)
		end
	end
end
</syntaxhighlight>
Notice the use of the '#' symbol to get the size of the 'newsItems' table. 
This is the Lua length operator, but it only works on tables that have numerical indexes (like an array or a list).
It also works on strings, eg: #"hello" would return 5.

That completes this section of the tutorial.
For ideas on how to further improve and advance this code, continue reading the next section.


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

===GUI Customisation===
To give your GUI a more unique feel, you have the ability to customise some aspects of your GUI elements.

For ideas on what is possible, browse the [[Client_Scripting_Functions#GUI_functions|MTA GUI functions]].

For the purposes of this tutorial, we will be using Font, Colour and Alpha.

To start, we will change the alpha of the background gridlist GUI element we are using.
To set the alpha, use [[guiSetAlpha]] and pass a value between 1 and 0; 1 being fully opaque and 0 being fully transparent.
<syntaxhighlight lang="lua">
guiSetAlpha(newsGridlist,0.8)
</syntaxhighlight>
Place this line of code in your 'createNewsFeed' function, after your gridlist has been created.

I find an alpha level of 0.8 looks best, however this is personal preference and you can experiment to suit your needs.


Next, we will look at the font of the label text.
To set the font, use [[guiSetFont]] and pass the string name of the font you want to use (available to see on the [[Standard GUI Font Names]] page).
<syntaxhighlight lang="lua">
guiSetFont(newsLabel,"default-bold-small")
</syntaxhighlight>
Place this line of code in your 'createNewsFeed' function, after your label has been created.


Finally, we will look at setting the colour of the label text.
To set the colour, use [[guiLabelSetColor]] and pass the individual red,green and blue values.
<syntaxhighlight lang="lua">
guiLabelSetColor(newsLabel,255,70,0)
</syntaxhighlight>
Place this line of code in your 'createNewsFeed' function, after your label has been created.

This will give your news items an orange-red colour.

===Multiple News Items===
In its current form, this code is only capable of showing one news item at a time.
However, with a few modifications we can show multiple news items at once, one after another.

To begin with, we need to make sure we have a 'newItems' table defined at the very start of our script,
as well as a 'distance' variable that will control the pixel distance between each news item:
<syntaxhighlight lang="lua">
local newsItems = {}
local distance = 30
</syntaxhighlight>
So put these lines at the top of the file.

Next, we will not know how many items we have (and consequently, how many labels we need) until we have loaded the file.
With that in mind, we will move around some of the code in our 'createNewsFeed' function to support this:
<syntaxhighlight lang="lua">
function createNewsFeed()
	-- get the screen width and height
	local sWidth, sHeight = guiGetScreenSize()
 
	-- create the gridlist, using some maths to find the bottom-centre of the screen
	local Width,Height = 800,45
	local X = (sWidth/2) - (Width/2)
	local Y = sHeight - (Height/2)
	
	-- the gridlist will act as the background to our news reel
	newsGridlist = guiCreateGridList(X,Y,Width,Height,false)
	
	guiSetAlpha(newsGridlist,0.8)
	
	-- call our function to read the news out of the xml file, before we create the labels
	loadNews()
		
	-- define a table to hold our labels
	newsLabel = {}
	
	-- now we can loop all our news items, and create a label for each one
	for index,item in ipairs(newsItems) do
	
		-- because we now have one label for every item, we can just set the text here and it wont need to be changed again.
		newsLabel[index] = guiCreateLabel(0,0,Width,Height/2,item,false,newsGridlist)
		
		guiSetFont(newsLabel[index],"default-bold-small")

		guiLabelSetColor(newsLabel[index],255,70,0)		

		-- modify the width of the label to fit the text
		local extent = guiLabelGetTextExtent(newsLabel[index])		
		guiSetSize(newsLabel[index],extent,Height/2,false)
		
		
		-- get the size of the gridlist
		local x,y = guiGetSize(newsGridlist,false)
		
		-- loop from 1 until index-1 in steps of 1
		-- this allows us to loop every label before the label we are currently on
		for i=1, index-1, 1 do
			-- tally up the sizes of all labels before our current one and store them in x
			local width = guiGetSize(newsLabel[i],false)
			x = x + width
		end
		
		-- put a 'distance' pixel gap between each news item
		x = x + (distance*(index-1))
		
		-- set the positon to the far right side of the gridlist, ready to scroll on to the left
		guiSetPosition(newsLabel[index],x,0,false)	
	end	
end
</syntaxhighlight>


Now we need to update our 'updateNewsItem' function to account for having multiple labels:
<syntaxhighlight lang="lua">
function updateNewsItem(newIndex)
	-- find the index of the news item directly infront (in the looping order) of the newIndex item
	local index = newIndex - 1
	if index == 0 then index = #newsItems end
	
	-- find the position of the right-edge of the label directly infront of the newIndex label
	local x = guiGetPosition(newsLabel[index],false) 
	local width = guiGetSize(newsLabel[index],false)
	x = x + width

	-- add a 'distance' pixel gap in
	x = x + distance

	-- check the new position isnt actually on the gridlist (ie: so it wont suddenly appear in the centre of the list)
	local gridlistWidth = guiGetSize(newsGridlist,false)
	
	if x < gridlistWidth then
		-- if it is, simple move it back to the edge
		x = gridlistWidth
	end
	
	-- set the new position
	guiSetPosition(newsLabel[newIndex],x,0,false)
end
</syntaxhighlight>


Finally, we need to make some small adjustments to our 'scrollNews' function:
<syntaxhighlight lang="lua">
function scrollNews()
	if newsItems then
		-- loop every news item
		for index,item in ipairs(newsItems) do
			local x,y = guiGetPosition(newsLabel[index],false)
			
			local labelWidth, labelHeight = guiGetSize(newsLabel[index],false)
			
			-- if the far right position of the label (x + labelWidth) is greater than or equal to 0 (ie: still showing on the gridlist)
			if ((x-1) + labelWidth) >= 0 then
				-- compensate for a small off-by-one bug in MTA
				if x <= 0 then x = x - 1 end
			
				-- update the position as normal
				guiSetPosition(newsLabel[index],x-1,y,false)
				
			-- otherwise, we move on to the next item and reset the position
			else
				updateNewsItem(index)
			end
		end
	end
end
</syntaxhighlight>

You should now have multiple news items scrolling along your news feed simultaneously.

===Globally controlled scroll speed===
As with the 'distance' variable above, we can set a global variable for controlling the scroll speed of the news items as well.
Note that the speed will still be dependant on the players FPS (ie: lower FPS means slightly slower scrolling).

To do this, we simply need to create the variable at the start of our code:
<syntaxhighlight lang="lua">
local scrollSpeed = 1
</syntaxhighlight>
Put this line at the top of your file.

Then, we just replace the instance of "x-1" in our 'scrollNews' function with "x-scrollSpeed":
<syntaxhighlight lang="lua">
function scrollNews()
		...
				-- update the position as normal
				guiSetPosition(newsLabel[index],x-scrollSpeed,y,false)
		...
	end
end
</syntaxhighlight>
That concludes this section of the tutorial.

For previous GUI tutorials, see [[HU/Scripting the GUI - Tutorial 2|GUI készítése - Tutorial 2 (Gates + Keypads)]]

[[Category:GUI_Tutorials]]

[[en:Scripting the GUI - Tutorial 3]]