PT-BR/Introducão ao GUI scripting

	Aviso: Este artigo necessita de revisão, pois está incompleto.

Um importante recurso do MTA:SA é capacidade de criar uma GUI (Graphical User Interface) personalizada. Uma GUI consiste em janelas, botões, caixas de edição, caixas de verificação e etc. Em outras palavras, todos os componentes presentes em janelas do Windows, por exemplo. Eles podem ser exibidos enquanto o usuário está no jogo, em vez de eles precisarem usar comandos tradicionais.

Obs: É de extrema importância dar uma olhada na Introdução ao Scripting porque muitas perguntas que poderão surgir neste tutorial provavelmente estão relacionados a falta de conceitos básicos de scripting.

Admin Console GUI

Tutorial: Janela de Login

Neste tutorial, vamos fazer uma janela de login bem simples, com duas caixas de entrada (input boxes) e um botão (button). A janela aparecerá quando o jogador entrar no jogo, e quando o botão de login for clicado, o jogador nasce no mapa. Usarenos o modo de jogo que foi criado no artigo Introdução ao Scripting. Se você procedeu com o mesmo e tem o script em mãos, precisará remover ou comentar a linha spawnPlayer da função joinHandler, pois iremos criar uma jenela para realizar tal ação.

Criando a janela

Todo o scripting GUI deverá ser feito no lado do cliente. Também é recomendado colocar esses arquivos em uma pasta separada, em prol de manter uma melhor organização.

Vá até o diretório ../server/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 fazer isto, iremos utilizar guiCreateWindow:

function criarJanelaDeLogin()
	-- definir a posição X e Y
	local x = 0.375
	local y = 0.375
	-- definir a largura e altura
	local largura = 0.25
	local altura = 0.25
	-- criar a janela e defini-la na variável 'janelaLogin'
	-- clique no nome da função para ler a sua documentação
	janelaLogin = guiCreateWindow(x, y, largura, altura, "Efetue o Login", true)
end

Relativo e Absoluto

Nota-se que o último argumento colocado em guiCreateWindow é true. Isto indica que as coordenadas e dimensões da janela são relativas, o que significa que é uma porcentagem do tamanho total da tela. Em outras palavras, se o lado esquerdo da tela é 0, e a extrema-direita é 1. Desta maneira, a posição X valendo 0.5 representaria o ponto central da tela. De forma análoga, se a parte superior da tela é 0 e a inferior é 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, exemplo: Se a largura for 0.5, a janela será a metade da largura da tela.

Caso não queira utilizar valores relativos, poderá optar por absolutos ao colocar false no argumento. Os valores absolutos são calculados como o número total de pixels do canto superior esquerdo do elemento o qual o componente GUI está subordinado. Se nenhum elemento pai for especificado, este será a própria tela. Neste caso, se tivermos uma resolução de tela de 1920x1200, o lado esquerdo será 0 pixel e o de extrema-direita, será 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, exemplo: Caso a largura seja 50, a janela terá os exatos 50 pixels de largura. Com um pouco de matemática, e usando a função guiGetScreenSize, você poderá calcular as posições absolutas corretamente.

As diferenças entre o uso de valores relativos e absolutos é muito simples. Se uma for GUI criada usando valores absolutos, cada unidade valerá um pixel. Enquanto os valores relativos usarão a porcentagem para definir essas posições.

Absoluto é geralmente mais fácil de usar quando a edição do código for feita a mão. Entretanto, a escolha do tipo de medida dependerá da finalidade do componente GUI.

Uma das principais razões de se utilizar valores relativos é para evitar que as janelas fiquem fora da tela ou em posições nada desejáveis. Um GUI que foi feito, por exemplo, na resolução de 1080p e for posicionada no canto superior direito com valores absolutos, ficará fora da tela caso esse script fosse executado em 720p. Oras, porque posicionarei uma janela nas coordenadas (1080, 0) se a tela do sujeito só vai até 720 pixels no eixo x? Simplesmente não vai funcionar.

Neste tutorial, obviamente usaremos valores relativos para a tela de login, e seus componentes, ficarem exatamente onde é preciso.

Adicionando os componentes

Vamos adicionar:

• Textos (labels), para mostrar o que é cada campo - usuário, senha
• Caixas de edição (edit boxes), para que o usuário possa inserir seus dados
• Um botão para efetuar o login

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

Note que agora iremos adicionar mais instruções para a função criarJanelaDeLogin. Portanto, esta não é uma nova função, e sim uma substituta da qual você já tem.

function criarJanelaDeLogin()
	local x = 0.375
	local y = 0.375
	local largura = 0.25
	local altura = 0.25
	wdwLogin = guiCreateWindow(x, y, largura, altura, "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', representando a janela
	-- Ou seja, ele será o elemento pai (parent) deste texto (label)
	-- Assim toda os valores de tamanho serão relativos a esta janela
	guiCreateLabel(x, y, largura, altura, "Usuário:", true, wdwLogin)

	-- Alterar o valor de y, assim o segundo label ficará ligeiramente abaixo do primeiro
	largura = 0.25
	y = 0.5
	guiCreateLabel(x, y, largura, altura, "Senha:", true, wdwLogin)

	-- Valores para as entradas
	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 a 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

Em nosso script, quando usamos a função para criar cada componente da janela, definimos a variável wdwLogin no último argumento. Isso significa que esses componentes estão contidos na janela. Em inglês dizemos que ele é um child element e a janela é um parent element..

Isto é muito útil porque não só significa que todos os componentes estão anexados à janela e irão mover-se com ela. Além disso, todas as alterações realizadas na janela serão aplicadas a todos os elementos subordinados, ou elementos filhos. Para ocultamos a janela, simplesmente usaremos a função:

guiSetVisible(wdwLogin, false) -- Isso fará com que todos os elementos subordinado fiquem invisíveis também. O conjunto só será mostrado quando for preciso.