Gaetan Piette: /* Adding the components */

2013-06-30T12:30:11Z

Adding the components

← Older revision		Revision as of 12:30, 30 June 2013
Line 42:		Line 42:
	Pour les buts de cette introduction nous utiliserons des valeurs relatives.		Pour les buts de cette introduction nous utiliserons des valeurs relatives.

	===~~Adding the components~~===		===Ajouter les composants===
	Next, we'll add the text labels (saying "username:" and "password:"), edit boxes (for entering your data) and a button to log in.		Next, we'll add the text labels (saying "username:" and "password:"), edit boxes (for entering your data) and a button to log in.

Citizen: Created page with " Une des grandes caractéristiques de MTA:SA c'est d'avoir la possibilité de personnaliser l'interface. Plus couramment appelé GUI(Graphic User Interface)...."

2012-03-30T12:48:34Z

Created page with " Une des grandes caractéristiques de MTA:SA c'est d'avoir la possibilité de personnaliser l'interface. Plus couramment appelé GUI(Graphic User Interface)...."

New page

Une des grandes caractéristiques de MTA:SA c'est d'avoir la possibilité de personnaliser l'interface. Plus couramment appelé GUI(Graphic User Interface). L'interface graphique se compose de fenêtres, bouton, les boîtes d'édition, des cases à cocher ... Les GUI peuvent être affichés lorsque l'utilisateur est en jeu.

[[Image:AdminGUI.png|thumb|Le panel admin(GUI)]]

==Un tutoriel pour créer une fenêtre de connexion==
Dans ce tutoriel, nous allons faire une fenêtre de connexion simple avec deux boites de saisie et un bouton.
La fenêtre apparaîtra lorsque le joueur rejoindra le jeu et une fois que le joueur appuiera sur le bouton.

===Créer la fenêtre de connexion===
Tous les GUI doivent être crée dans le coté client. Pour vous simplifier la vie, créez votre code dans des dossiers séparé.
Les fichiers client vous les mettez dans le dossier client que vous avez créer.

Allez sur /Votre Server MTA/mods/deathmatch/resources/votreserver/, et créez un dossier du nom de "login".
Puis dans ce répertoire créer le dosser "client". (login/client)
Créez un fichier texte et nommez le "gui.lua".

Dans ce fichier nous allons écrire une fonction pour créer notre fenêtre. Pour créer une fenetre vous allez devoir utiliser [[guiCreateWindow]]:
<syntaxhighlight lang="lua">
function createLoginWindow()
-- on définie les positions de la fenêtre
local X = 0.375
local Y = 0.375
-- on définie la taille de la fenêtre
local Width = 0.25
local Height = 0.25
-- créez la fenêtre et sauvegardez cette élément sous la variable 'wdwLogin'
-- cliquez sur le nom de la fonction pour regarder sa documentation
wdwLogin = guiCreateWindow(X, Y, Width, Height, "Veuillez vous connecter", true)
end
</syntaxhighlight>

===Relatif et Absolu ===
Notez que l'argument final passé à guiCreateWindow dans l'exemple ci-dessus est ''true''. Cela indique que l'ensemble et les dimensions de la fenêtre sont ''relative'', en signifiant qu'ils sont un ''percentage'' de la grandeur d'écran totale. Cela signifie que si le côté gauche lointain de l'écran est 0 et le droit lointain est 1, une position X de 0.5 représenterait le point de centre de l'écran. De même si le haut de l'écran est 0 et le fond est 1, une position Y de 0.2 serait 20 % de la voie en bas l'écran. Les mêmes principes s'appliquent tant à Largeur qu'à Hauteur aussi (avec une valeur de Largeur de 0.5 sens la fenêtre sera la moitié aussi large que l'écran).

L'alternative à l'utilisation des valeurs relatives utilise absolu (en passant ''false'' au lieu de ''true'' pour guiCreateWindow). Les valeurs absolues sont calculées comme le nombre total de pixels du coin gauche-supérieur du parent (si aucun parent d'élément gui n'est spécifié, le parent est l'écran lui-même). Si nous supposons une résolution d'écran de 1920x1200, le côté gauche lointain de l'écran étant 0 pixels et le droit lointain étant 1920 pixels, une position X de 960 représentera le point de centre de l'écran. De même si le haut de l'écran est 0 pixels et le fond est 1200, une position Y de 20 serait 20 pixels en bas du haut de l'écran. La même pomme de principes tant à la Largeur qu'à la Hauteur aussi (avec une valeur de Largeur de 50 sens la fenêtre sera 50 pixels larges). Vous pouvez utiliser guiGetScreenSize et des petites mathématiques pour calculer certaines positions absolues.

Les différences entre l'utilisation des valeurs relatives et absolues sont tout à fait simples; les valeurs absolues utilisatrices de données de gui resteront toujours exactement la même grandeur de pixel et la position, pendant que les valeurs relatives utilisatrices de données de gui seront toujours un pourcentage de sa grandeur parentale.

L'absolu est généralement plus facile de maintenir en révisant le code à la main, pourtant votre choix de type dépend de la situation dont vous l'utilisez.

Pour les buts de cette introduction nous utiliserons des valeurs relatives.

===Adding the components===
Next, we'll add the text labels (saying "username:" and "password:"), edit boxes (for entering your data) and a button to log in.

To create buttons we use [[guiCreateButton]] and to create edit boxes use [[guiCreateEdit]]:

'''Note that we are now writing more code for our existing 'createLoginWindow' function. This is not a new function and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
function createLoginWindow()
local X = 0.375
local Y = 0.375
local Width = 0.25
local Height = 0.25
wdwLogin = guiCreateWindow(X, Y, Width, Height, "Please Log In", true)

-- define new X and Y positions for the first label
X = 0.0825
Y = 0.2
-- define new Width and Height values for the first label
Width = 0.25
Height = 0.25
-- create the first label, note the final argument passed is 'wdwLogin' meaning the window
-- we created above is the parent of this label (so all the position and size values are now relative to the position of that window)
guiCreateLabel(X, Y, Width, Height, "Username", true, wdwLogin)
-- alter the Y value, so the second label is slightly below the first
Y = 0.5
guiCreateLabel(X, Y, Width, Height, "Password", true, wdwLogin)

X = 0.415
Y = 0.2
Width = 0.5
Height = 0.15
edtUser = guiCreateEdit(X, Y, Width, Height, "", true, wdwLogin)
Y = 0.5
edtPass = guiCreateEdit(X, Y, Width, Height, "", true, wdwLogin)
-- set the maximum character length for the username and password fields to 50
guiEditSetMaxLength(edtUser, 50)
guiEditSetMaxLength(edtPass, 50)

X = 0.415
Y = 0.7
Width = 0.25
Height = 0.2
btnLogin = guiCreateButton(X, Y, Width, Height, "Log In", true, wdwLogin)

-- make the window invisible
guiSetVisible(wdwLogin, false)
end
</syntaxhighlight>
Note that every GUI component created is a child of the window, this is done by specifying the parent element (wdwLogin, in this case) when creating the component.

This is very useful because not only does it mean that all the components are attached to the window and will move with it, but also that any changes done to the parent window will be applied down the tree to these child components. For example, we can now hide all of the GUI we just created by simply hiding the window:
<syntaxhighlight lang="lua">
guiSetVisible(wdwLogin, false) --hides all the GUI we made so we can show them to the player at the appropriate moment.
</syntaxhighlight>

===Using the function we wrote===
The createLoginWindow function is now complete, but it won't do anything until we call it. It is recommended to create all GUI when the client resource starts, hide them, and show them to the player later when needed. Therefore, we'll write an event handler for "[[onClientResourceStart]]" to create the window:
<syntaxhighlight lang="lua">
-- attach the event handler to the root element of the resource
-- this means it will only trigger when its own resource is started
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
createLoginWindow()
end
)
</syntaxhighlight>

As this is a log in window, we now need to show the window when the player joins the game.
This can be done using the same event, "[[onClientResourceStart]]", so we can modify the above code to include showing the window:

'''Note that we are now writing more code for our existing 'onClientResourceStart' handler. This is not a new event handler and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
-- create the log in window and its components
createLoginWindow()

-- output a brief welcome message to the player
outputChatBox("Welcome to My MTA:SA Server, please log in.")

-- if the GUI was successfully created, then show the GUI to the player
if (wdwLogin ~= nil) then
guiSetVisible(wdwLogin, true)
else
-- if the GUI hasnt been properly created, tell the player
outputChatBox("An unexpected error has occurred and the log in GUI has not been created.")
end

-- enable the players cursor (so they can select and click on the components)
showCursor(true)
-- set the input focus onto the GUI, allowing players (for example) to press 'T' without the chatbox opening
guiSetInputEnabled(true)
end
)
</syntaxhighlight>

Note that we have a simple security check before making the window visible, so in the unlikely event that the window has not been created, meaning wdwLogin is not a valid element, we don't get an error and just inform the player what has happened.
In the next step, we will create the button functionality for the log in button.

==Scripting the button==
Now that we have created our GUI and shown it to the player, we need to make it work.

===Detecting the click===
When the player clicks on any part of the GUI, the event "[[onClientGUIClick]]" will be triggered for the GUI component you clicked on. This allows us to easily detect any clicks on the GUI elements we want to use.
For example, we can attach the event to the btnLogin button to catch any clicks on it:
<syntaxhighlight lang="lua">
-- attach the event onClientGUIClick to btnLogin and set it to trigger the 'clientSubmitLogin' function
addEventHandler("onClientGUIClick", btnLogin, clientSubmitLogin, false)
</syntaxhighlight>
'''Note the final argument passed is "false". This indicates that the event will only trigger directly on btnLogin, not if the event has propagated up or down the tree. Setting this to "true" while attaching to gui elements will mean that clicking on any element in the same branch will trigger this event.'''

This line of code can now be added inside the createLoginWindow function. It is a common mistake to try and attach events to non-existant GUI elements, so make sure you always attach your events '''after''' the gui element (in this case, the button) has been created:

'''Note that we are now writing more code for our existing 'createLoginWindow' function.'''
<syntaxhighlight lang="lua">
function createLoginWindow()
-- create all our GUI elements
...

-- now add our onClientGUIClick event to the button we just created
addEventHandler("onClientGUIClick", btnLogin, clientSubmitLogin, false)
</syntaxhighlight>

===Managing the click===
Now that we can detect when the player clicks on the button, we need to write code to manage what happens when they do.
In our [[onClientGUIClick]] event handle, we told it to call the function clientSubmitLogin whenever btnLogin is clicked.
Therefore, we can now use the function clientSubmitLogin to control what happens when the button is clicked:
<syntaxhighlight lang="lua">
-- create the function and define the 'button' and 'state' parameters
-- (these are passed automatically by onClientGUIClick)
function clientSubmitLogin(button,state)
-- if our login button was clicked with the left mouse button, and the state of the mouse button is up
if button == "left" and state == "up" then
-- move the input focus back onto the game (allowing players to move around, open the chatbox, etc)
guiSetInputEnabled(false)
-- hide the window and all the components
guiSetVisible(wdwLogin, false)
-- hide the mouse cursor
showCursor(false)
end
end
</syntaxhighlight>
Now, when the button is clicked, the window will be hidden and all controls will be returned to the player. Next, we will tell the server to allow the player to spawn.

===Triggering the server===
Triggering the server can be done using [[triggerServerEvent]]. This allows you to trigger a specified event on the server from the client. The same can be done in reverse using [[triggerClientEvent]].
Here, we use the [[triggerServerEvent]] function to call our own custom event on the server, named "submitLogin", which will then control the spawning of the player serverside.

'''Note that we are now writing more code for our existing 'clientSubmitLogin' function. This is not a new function and is meant to replace what you already have.'''
<syntaxhighlight lang="lua">
function clientSubmitLogin(button,state)
if button == "left" and state == "up" then
-- get the text entered in the 'username' field
local username = guiGetText(edtUser)
-- get the text entered in the 'password' field
local password = guiGetText(edtPass)

-- if the username and password both exist
if username and password then
-- trigger the server event 'submitLogin' and pass the username and password to it
triggerServerEvent("submitLogin", getRootElement(), username, password)

-- hide the gui, hide the cursor and return control to the player
guiSetInputEnabled(false)
guiSetVisible(wdwLogin, false)
showCursor(false)
else
-- otherwise, output a message to the player, do not trigger the server
-- and do not hide the gui
outputChatBox("Please enter a username and password.")
end
end
end
</syntaxhighlight>

===Creating the serverside event===
At this point we now have all the code needed on the client side, so open up your serverside 'script.lua' file (from the [[Scripting Introduction|Introduction to Scripting]]) or another suitable serverside file to work with.

On the server side, recall that we are spawning the player as soon as they login.
So, first of all, we will need to define the custom event that we used before on the client. This can be done using [[addEvent]] and [[addEventHandler]].
<syntaxhighlight lang="lua">
-- create our loginHandler function, with username and password parameters (passed from the client gui)
function loginHandler(username,password)

end

-- define our custom event, and allow it to be triggered from the client ('true')
addEvent("submitLogin",true)
-- add an event handler so that when submitLogin is triggered, the function loginHandler is called
addEventHandler("submitLogin",root,loginHandler)
</syntaxhighlight>

===Logging in===
Now we have a function that is called through the custom event 'submitLogin', we can start to work on logging in and spawning the player, using our 'loginHandler' function:
<syntaxhighlight lang="lua">
function loginHandler(username,password)
-- check that the username and password are correct
if username == "user" and password == "apple" then
-- the player has successfully logged in, so spawn them
if (client) then
spawnPlayer(client, 1959.55, -1714.46, 10)
fadeCamera(client, true)
setCameraTarget(client, client)
outputChatBox("Welcome to My Server.", client)
end
else
-- if the username or password are not correct, output a message to the player
outputChatBox("Invalid username and password. Please re-connect and try again.",client)
end
end

addEvent("submitLogin",true)
addEventHandler("submitLogin",root,loginHandler)
</syntaxhighlight>
'''For the purposes of this tutorial, a very basic username and password system is shown. For a more comprehensive alternative, you can use the Account System or a MySQL database.'''

Also note the use of the variable "client", it's an internal variable used by MTA to identify the player who triggered the event.

Finally, do not forget to include the new gui.lua file in the meta.xml of the main resource, and label it as a client script:
<syntaxhighlight lang="xml">
<script src="client/gui.lua" type="client" />
</syntaxhighlight>

At this point, we now have a basic login window that checks the player's username and password when the login button is clicked. If they are correct, the player is automatically spawned.

For further help with GUI, see the [[:Category:GUI_Tutorials|GUI tutorials]].

[[Category:GUI_Tutorials]]
[[it:Introduzione_allo_scripting_della_GUI]]
[[ru:Introduction to Scripting the GUI]]

FR/Introduction GUI - Revision history

Gaetan Piette: /* Adding the components */

Citizen: Created page with " Une des grandes caractéristiques de MTA:SA c'est d'avoir la possibilité de personnaliser l'interface. Plus couramment appelé GUI(Graphic User Interface)...."