PT-BR/Introducão ao GUI scripting

2014-02-16T21:36:49Z

Rômulo Neves:

Um importante recurso no MTA:SA é a capacidade de script GUI (Graphic User Interface/Interface Gráfica do Usuário) personalizado. A GUI consiste de janelas, botões, caixas de edição, caixas de verificação... Quase todos os componentes padrão do formulário em ambientes gráficos. Eles podem ser exibidos enquanto o usuário está em jogo (in game), e usado para entradas (inputs) e saídas (outputs) no lugar dos comandos tradicionais.

[[Image:AdminGUI.png|thumb|Admin Console GUI]]

==Um tutorial para fazer uma janela de login==
Neste tutorial, vamos fazer uma janela de login simples, com duas caixas de entrada (input boxes) e um botão. A janela aparece quando o jogador entra no jogo, e quando o botão é clicado, o jogador é gerado no jogo. O tutorial vai continuar o modo de jogo que fizemos no [[PT-BR/Introducao_ao_Scripting|Introdução ao Scripting]] ''(Se você já usou o [[PT-BR/Introducao_ao_Scripting|Introdução ao Scripting]], você precisará remover ou comentar a linha [[spawnPlayer]] da função "joinHandler" em seu código, como iremos substituí-lo por uma GUI alternativa neste tutorial)''. Nós também vamos dar uma olhada no scripting do lado client (client-side).

===Criando a janela===
Toda a GUI deve ser feita do lado client. Também é uma boa prática manter todos os scripts do lado client em uma pasta separada.

Vá até o diretório /SeuServerMTA/mods/deathmatch/resources/, e crie uma pasta chamada "client". Sob o diretório /client/, crie um arquivo de texto com o nome "gui.lua".

Neste arquivo vamos escrever uma função que cria a janela. Para criar uma janela, iremos utilizar [[guiCreateWindow]]:
<syntaxhighlight lang="lua">
function criarJanelaDeLogin()
-- definir a posição X e Y da janela
local X = 0.375
local Y = 0.375
-- definir a largura e altura da janela
local Largura = 0.25
local Altura = 0.25
-- criar a janela e salvar o valor de seu elemento na variável 'wdwLogin'
-- clique no nome da função para ler a sua documentação
wdwLogin = guiCreateWindow(X, Y, Largura, Altura, "Por favor efetue o Login", true)
end
</syntaxhighlight>

===Relativo e Absoluto===
Nota-se que o último argumento colocado em guiCreateWindow no exemplo acima é ''true''. Isto indica que as coordenadas e dimensões da janela são '''relativa''', o que significa que é uma ''porcentagem'' do tamanho total da tela. Isto significa que se o lado esquerdo da tela é 0, e a extrema-direita é 1, uma posição X de 0.5 representaria o ponto central da tela. Similarmente, se a parte superior da tela é 0 e no fundo é 1, uma posição Y de 0.2 seria 20% do caminho para baixo da tela. Os mesmos princípios se aplicam para largura e altura, bem como (com um valor de largura de 0.5 significa que a janela será a metade da largura da tela).

A outra alternativa de utilizar valores relativos é utilizar '''absolutos''' (colocando ''false'' ao invés de true em guiCreateWindow). Os valores absolutos são calculados como o número total de pixels do canto superior esquerdo de seu elemento pai (se nenhum elemento pai gui for especificado, o pai será a própria tela). Se tivermos uma resolução de tela de 1920x1200, o lado esquerdo da tela sendo 0 pixel e os extrema-direita, sendo 1920 pixels, uma posição X de 960 representará o ponto central da tela. Similarmente, se a parte superior da tela é de 0 pixel e o fundo é de 1200, uma posição Y de 20 seria de 20 pixels para baixo a partir da parte superior da tela. Os mesmos princípios se aplicam a largura e altura, bem como (com um valor de largura de 50 ou seja, a janela será de 50 pixels de largura). ''Você pode usar [[guiGetScreenSize]] e um pouco de matemática para calcular certas posições absolutas.''

As diferenças entre o uso de valores relativos e absolutos é muito simples; gui criada usando valores absolutos será sempre exatamente o mesmo tamanho de pixel e posição, enquanto gui criado usando valores relativos será sempre uma porcentagem do tamanho do seu parent.

Absoluto é geralmente mais fácil de usar quando a edição do código é á mão, no entanto a escolha do tipo depende da situação que você está usando para isso.

Para esta presente introdução iremos utilizar valores relativos.

===Adicionando os componentes===
Em seguida, vamos adicionar os rótulos de texto (labels) (dizendo "username:" e "senha:"), caixas de edição (edit boxes) (para inserir seus dados) e um botão para efetuar login.

Para criar botões você deve usar [[guiCreateButton]] e para criar caixas de edição você deve usar [[guiCreateEdit]]:

'''Note que agora iremos escrever mais código para a nossa função atual 'criarJanelaDeLogin'. Esta não é uma nova função e se destina a substituir o que você já tem.'''
<syntaxhighlight lang="lua">
function criarJanelaDeLogin()
local X = 0.375
local Y = 0.375
local Largura = 0.25
local Altura = 0.25
wdwLogin = guiCreateWindow(X, Y, Largura, Altura, "Por favor efetue o Login", true)

-- definir as novas posições X e Y para o primeiro label
X = 0.0391
Y = 0.1979
-- definir o novo valor de largura e altura para o primeiro label
Largura = 0.3672
Altura = 0.25
-- criar o primeiro label, note que o último argumento passado é 'wdwLogin', que significa a janela
-- o que criámos acima é o parent deste rótulo de texto (label)
-- (assim toda a posição e os valores de tamanho são agora relativo para a posição dessa janela)
guiCreateLabel(X, Y, Largura, Altura, "Nome de Usuario", true, wdwLogin)
-- altere o valor de Y, assim o segundo label esteja ligeiramente abaixo do primeiro
Largura = 0.25
Y = 0.5
guiCreateLabel(X, Y, Largura, Altura, "Senha", true, wdwLogin)

X = 0.415
Y = 0.2
Largura = 0.5
Altura = 0.15
editUsuario = guiCreateEdit(X, Y, Largura, Altura, "", true, wdwLogin)
Y = 0.5
edtSenha = guiCreateEdit(X, Y, Largura, Altura, "", true, wdwLogin)
-- definir o tamanho máximo de caracteres do nome de usuário e Senha para 50
guiEditSetMaxLength(editUsuario, 50)
guiEditSetMaxLength(edtSenha, 50)

X = 0.415
Y = 0.7
Largura = 0.25
Altura = 0.2
btnLogin = guiCreateButton(X, Y, Largura, Altura, "Login", true, wdwLogin)

-- tornar a janela invisível
guiSetVisible(wdwLogin, false)
end
</syntaxhighlight>
Note que cada componente GUI criado é um filho da janela, isto é feito através da especificação do elemento pai (wdwLogin, neste caso) ao criar o componente.

Isto é muito útil porque não só significa que todos os componentes estão anexados à janela e irá mover-se com ela, mas também que todas as alterações feitas para a janela pai será aplicada para todos os elementos filho. Por exemplo, agora podemos ocultar toda a GUI que acabamos de criar, basta ocultar a janela:
<syntaxhighlight lang="lua">
guiSetVisible(wdwLogin, false) -- oculta toda a GUI que fizemos para que possamos mostrá-los para o jogador, quando for preciso.
</syntaxhighlight>

===Usando a função criada anteriormente===
A função criarJanelaDeLogin agora está completa, mas nada vai acontecer até que nós a chamamos. È Recomendado criar toda a GUI quando o recurso client for iniciado, então será ocultada, e mostrará para o jogador quando necessário. Portanto, vamos escrever um manipulador de eventos para "[[onClientResourceStart]]" para criar a janela:
<syntaxhighlight lang="lua">
-- anexar o manipulador de eventos para o elemento raiz (root element) do recurso
-- isso significa que ele só irá desencadear (trigger) quando seu próprio recurso é iniciado
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
criarJanelaDeLogin()
end
)
</syntaxhighlight>
Como este é uma janela de login, agora precisamos mostrar a janela quando o jogador entra no jogo.
Isto pode ser feito usando o mesmo evento, "[[onClientResourceStart]]", para que possamos modificar o código acima e incluir para mostrar a janela:

'''Observe que agora estamos escrevendo mais código para o nosso manipulador 'onClientResourceStart' existente. Este não é um novo manipulador de eventos e se destina a substituir o que você já tem.'''
<syntaxhighlight lang="lua">
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()),
function ()
-- criar a janela de login e seus componentes
criarJanelaDeLogin()

-- saída de uma mensagem de boas-vindas ao jogador
outputChatBox("Bem-vindo ao meu servidor MTA:SA, por favor efetue o login.")

-- se a GUI foi criada com êxito, então, mostrar a GUI para o jogador
if (wdwLogin ~= nil) then
guiSetVisible(wdwLogin, true)
else
-- se a GUI não foi criada corretamente, notificar o jogador
outputChatBox("Um erro inesperado ocorreu e a janela de login não foi criada.")
end

-- habilitar o cursor para os jogadores (para que eles possam selecionar e clique sobre os componentes)
showCursor(true)
-- definir o foco de entrada para a GUI, permitindo que os jogadores (por exemplo) para pressione 'T', sem que o chatbox abra
guiSetInputEnabled(true)
end
)
</syntaxhighlight>

Note que temos uma simples verificação de segurança antes de tornar a janela visível, no caso improvável de que a janela não foi criada, significa que wdwLogin não é um elemento válido, nós não temos um erro. e apenas informamos o jogador o que aconteceu.
Na próxima etapa, vamos criar a funcionalidade para o botão de login.

==Programando o botão==
Agora que nós criamos nossa GUI e mostrou-a para o jogador, é preciso programa-la para que possa funcionar.

===Detectando o clique===
Quando o jogador clica em qualquer parte da GUI, o evento "[[onClientGUIClick]]" será acionado para o componente GUI que você clicou. Isso nos permite facilmente detectar quaisquer cliques sobre o elemento GUI que deseja usar.
Por exemplo, podemos anexar o evento para o botão btnLogin para obter todos os cliques sobre ele:
<syntaxhighlight lang="lua">
-- anexar o evento onClientGUIClick para btnLogin e definir-lo para chamar a função 'submeterLoginClient'
addEventHandler("onClientGUIClick", btnLogin, submeterLoginClient, false)
</syntaxhighlight>
'''Observe o argumento final passado é "false". Isto indica que o evento só irá acionar diretamente sobre btnLogin, não se o evento tem propagado para cima ou para baixo da árvore. Se configurado para "true", enquanto anexado ao elemento gui significa que se clicar em qualquer elemento no mesmo ramo vai disparar esse evento.'''

Esta linha de código agora pode ser adicionada dentro da função criarJanelaDeLogin. É um erro comum, tentar anexar eventos a elementos GUI inexistentes, então certifique-se sempre de anexar os seus eventos '''depois''' o elemento gui (neste caso, o botão) foi criado:

'''Note que vamos agora escrever mais código para a nossa função 'criarJanelaDeLogin'.'''
<syntaxhighlight lang="lua">
function criarJanelaDeLogin()
-- criar todos os nossos elementos da GUI
...

-- agora adicionar o evento onClientGUIClick para o botão que acabamos de criar
addEventHandler("onClientGUIClick", btnLogin, submeterLoginClient, false)
</syntaxhighlight>

===Gerenciando o clique===
Agora que podemos detectar quando o jogador clica no botão, é preciso escrever o código para gerenciar o que acontece quando ele é clicado.
Em nosso manipulador de eventos [[onClientClick]], a função submeterLoginClient sempre será chamada quando o botão btnLogin for clicado.
Portanto, agora podemos usar a função submeterLoginClient para controlar o que acontece quando o botão é clicado:
<syntaxhighlight lang="lua">
-- criar a função e definir os parâmetros para 'botão' (button) e 'estado' (state)
-- (eles são passados automaticamente pelo onClientGUIClick)
function submeterLoginClient(button,state)
-- se o nosso botão de login foi clicado com o botão esquerdo do mouse, eo estado do botão do mouse é up
if button == "left" and state == "up" then
-- mover o foco de entrada de volta para o jogo (permitindo aos jogadores para se movimentar, abrir o chat, etc)
guiSetInputEnabled(false)
-- ocultar a janela e todos os componentes
guiSetVisible(wdwLogin, false)
-- desabilitar o cursor do mouse
showCursor(false)
end
end
</syntaxhighlight>
Agora, quando o botão é clicado, a janela será ocultada e todos os controles serão permitidos para o jogador. Em seguida, vamos ligar com o lado server para permitir que o jogador execute spawn.

===Chamando o lado server===
Chamando o lado server pode ser feito usando [[triggerServerEvent]]. Isto lhe permite chamar um evento especificado no server através do client. Se quiser chamar o client através do server pode ser feito usando [[triggerClientEvent]].
Aqui, usamos a função [[triggerServerEvent]] para chamar o nosso evento personalizado no lado server, chamado "submeterLogin", que irá controlar a função de spawn que é do lado server.

'''Note que iremos agora escrever mais código para a nossa função 'submeterLoginClient'. Esta não é uma nova função e se destina a substituir o que você já tem.'''
<syntaxhighlight lang="lua">
function submeterLoginClient(button,state)
if button == "left" and state == "up" then
-- obter o texto inserido no campo 'nomeDeUsuario'
local nomeDeUsuario = guiGetText(editUsuario)
-- obter o texto inserido no campo 'senha'
local senha = guiGetText(edtSenha)

-- se o nome de usuário e senha existem
if nomeDeUsuario and senha then
-- acionar o evento server 'submeterLogin' e passar o nome de usuário e senha para ele
triggerServerEvent("submeterLogin", getRootElement(), nomeDeUsuario, senha)

-- ocultar a gui, desabilitar o cursor e retornar o controle para o jogador
guiSetInputEnabled(false)
guiSetVisible(wdwLogin, false)
showCursor(false)
else
-- caso contrário, irá sair uma mensagem para o jogador, se o nome de usuário e/ou senha não existem
-- e não ocultar a gui
outputChatBox("Por favor, digite o nome de usuário e senha.")
end
end
end
</syntaxhighlight>

===Criando o evento do lado server===
Neste ponto nós temos agora todos os códigos necessários no lado do client, então abra seu arquivo do lado server 'script.lua' (do [[PT-BR/Introducao_ao_Scripting|Introdução ao Scripting]]) ou outro arquivo do lado server adequado para trabalhar.

No lado do servidor, lembre-se que o jogador executará o spawn assim que entrar.
Então, em primeiro lugar, teremos que definir o evento personalizado que iremos usar antes no client. Isto pode ser feito usando [[addEvent]] e [[AddEventHandler]].
<syntaxhighlight lang="lua">
-- criar nossa função loginHandler, com parâmetros 'username' e 'senha' (passado pelo client gui)
function loginHandler(username,senha)

end

-- definir o nosso evento personalizado e permitir que ele seja acionado a partir do cliente ('true')
addEvent("submeterLogin",true)
-- adicionar um manipulador de eventos para quando 'submeterLogin' for acionado, a função 'loginHandler' é chamada
addEventHandler("submeterLogin",root,loginHandler)
</syntaxhighlight>

===Efetuando login===
Agora, temos uma função que é chamada através do evento personalizado 'submeterLogin', podemos começar a trabalhar com o login e spawn do jogador, usando a nossa função 'loginHandler':
<syntaxhighlight lang="lua">
function loginHandler(username,senha)
-- verificar se o nome de usuário e senha estão corretos
if username == "user" and senha == "apple" then
-- se o jogador foi logado com sucesso, então gerar ele no jogo
if (client) then
spawnPlayer(client, 1959.55, -1714.46, 10)
fadeCamera(client, true)
setCameraTarget(client, client)
outputChatBox("Bem-vindo ao servidor.", client)
end
else
-- se o nome de usuário ou senha não estão corretos, informar para o jogador
outputChatBox("Nome de usuário e senha inválidos. Por favor, tente novamente.",client)
end
end

addEvent("submeterLogin",true)
addEventHandler("submeterLogin",root,loginHandler)
</syntaxhighlight>
'''Para os fins deste tutorial, um sistema de username e senha muito básico é mostrado. Para uma alternativa mais compreensiva, você pode usar o Sistema de Conta ou um banco de dados MySQL.'''

Observe também o uso da variável "client", é uma variável interna usada pelo MTA para identificar o jogador que disparou o evento.

Finalmente, não se esqueça de incluir o arquivo gui.lua novo no meta.xml do recurso principal, e nomeá-lo como um script client:
<syntaxhighlight lang="xml">
<script src="client/gui.lua" type="client" />
</syntaxhighlight>

Neste ponto, temos agora uma janela de login básico que verifica nome de usuário do jogador e senha quando o botão de login é clicado. Se eles estiverem corretos, o jogador é automaticamente gerado no jogo.

Para mais ajuda com GUI, consulte [[:Category:GUI_Tutorials|Tutoriais GUI]].

[[Category:GUI_Tutorials]]

[[en:Introduction to Scripting the GUI]]
[[es:Introducción a la Programación de GUI]]
[[it:Introduzione_allo_scripting_della_GUI]]
[[ru:Introduction to Scripting the GUI]]

Multi Theft Auto: Wiki - User contributions [en]

PT-BR/Introducão ao GUI scripting