VGUI2: Creating a panel

Requerimientos

Haber leido y comprendido (o comprender):

• VGUI Documentation(en)
• HUD Elements(en)

Codigos:

• C++ (!!!!)
• Script

Este tutorial es sobre crear una interfaz simple e interactiva:

Entendiendo como funciona VGUI2

Cada dialogo VGUI2 que ves mientras usas juegos basados en source es llamado, básicamente, Panel.

Cada Panel consiste en tres componentes:

• Scheme (Esquema)
• Control Settings (Propiedades de control)
• Code (Código)

The Scheme - El Esquema

El esquema es un archivo de configuración general que almacena información sobre el color de ciertos elementos como botones, comboboxes, labels, etc. Un archivo de esquema típico es SourceScheme.res, por ejemplo. Si planeas crear un panel semejante a los otros paneles en el menu, deberías usar el mismo archivo de esquema que ellos usan.

Control Settings - Propiedades de Control

El archivo de las propiedades de control almacena información sobre la posición relativa de tu panel y de sus elementos.

Cada panel tiene su propio archivo de recuersos. Para crearlos, hay dos maneras: Puedes crear uno por tu cuenta usando un editor como notepad, o puedes usar Valves InGame Resource Editor.

Código

El código es la parte más importante de un panel, desde el código se decide que hacer si el usuario clickea un botón. Para crear y destruir un panel, se usa código. Afortunadamente puedes establecer muchas más cosas que en el(los)archivo(s) de recursos. El códido es la cosa más importante de este tutorial.

Creando un panel

Ok, let us assume we want to create a door, for real this time. Since we are not able to create a door from scratch, the first thing we do is to step by at the building centre. What we ask for, is a basic door. It works, but we have still plans to customize it.

Empezando

La clase panel es la clase base de todos los elementos VGUI2. Para obtener una visión general acerca de todos los elementos VGUI2, demos un vistazo dentro de la carpeta vgui_elements. Por supuesto, no solo compramos un poco de madera en nuestro centro local de construcción.

La clase importante es la clase EditablePanel que hereda desde la clase Panel. Nuestro panel será una nueva clase que hereda desde la clase EditablePanel. Esto resulta en diversas ventajas: podemos codificar metodos relativos al contenido del panel, podemos sobreescribir métodos de la clase base y muchas más cosas útiles.

Puedes crear un nuevo archivo MyPanel.cpp debajo de Source Files dentro del proyecto client.

MyPanel.cpp

// //Los siguientes archivos include son necesarios para compilar tu MyPanel.cpp.
#include "cbase.h"
#include "IMyPanel.h"
using namespace vgui;
#include <vgui/IVGui.h>
#include <vgui_controls/Frame.h>

//CMyPanel class: Tutorial example class
class CMyPanel : public vgui::Frame
{
	DECLARE_CLASS_SIMPLE(CMyPanel, vgui::Frame); 
	//CMyPanel : This Class / vgui::Frame : BaseClass

	CMyPanel(vgui::VPANEL parent); 	// Constructor
	~CMyPanel(){};				// Destructor

protected:
	//VGUI overrides:
	virtual void OnTick();
	virtual void OnCommand(const char* pcCommand);

private:
	//Other used VGUI control Elements:

};

El constructor: El argumento es vgui::VPANEL parent. Después de leer la VGUI Documentation(en), deberias saber que todo panel tiene un padre y porque lo tiene.

Bajo el codigo de arriba, añade:

// Constuctor: Initializes the Panel
CMyPanel::CMyPanel(vgui::VPANEL parent)
: BaseClass(NULL, "MyPanel")
{
	SetParent( parent );
	
	SetKeyBoardInputEnabled( true );
	SetMouseInputEnabled( true );
	
	SetProportional( true );
	SetTitleBarVisible( true );
	SetMinimizeButtonVisible( false );
	SetMaximizeButtonVisible( false );
	SetCloseButtonVisible( false );
	SetSizeable( false );
	SetMoveable( false );
	SetVisible( true );


	SetScheme(vgui::scheme()->LoadSchemeFromFile("resource/SourceScheme.res", "SourceScheme"));

	LoadControlSettings("resource/UI/MyPanel.res");

	vgui::ivgui()->AddTickSignal( GetVPanel(), 100 );
	
	DevMsg("MyPanel has been constructed\n");
}

Las primeras lineas son bastante sencillas de entender. SetScheme es usada para establecer el la fuente del esquema, que es el esquema estándart para Half-Life 2. Conseguimos un puntero al esquema llamando a LoadSchemeFromFile(...). La función LoadControlSettings es usada para cargar el archivo de configuraciones de control de resolución. La última línea esta explicada en la codumentación VGUI2.

Siguiendo al codigo expuesto arriba, añade:

//Class: CMyPanelInterface Class. Used for construction.
class CMyPanelInterface : public IMyPanel
{
private:
	CMyPanel *MyPanel;
public:
	CMyPanelInterface()
	{
		MyPanel = NULL;
	}
	void Create(vgui::VPANEL parent)
	{
		MyPanel = new CMyPanel(parent);
	}
	void Destroy()
	{
		if (MyPanel)
		{
			MyPanel->SetParent( (vgui::Panel *)NULL);
			delete MyPanel;
		}
	}
};
static CMyPanelInterface g_MyPanel;
IMyPanel* mypanel = (IMyPanel*)&g_MyPanel;

A continuación puedes crear IMyPanel.h en el mismo directorio.

IMyPanel.h

// IMyPanel.h
class IMyPanel
{
public:
	virtual void		Create( vgui::VPANEL parent ) = 0;
	virtual void		Destroy( void ) = 0;
};

extern IMyPanel* mypanel;

Llamando al Panel

Para llamar al panel, añadimos unas pocas lineas en el archivo vgui_int.cpp. Vgui_int.cpp incluye funciones que llaman a todos los paneles. La función VGui_CreateGlobalPanels() es donde la adición de los paneles tiene lugar.

Este es el punto donde debes decidir cuando se abrirá tu panel. Puedes crear el panel para que pueda ser accedido durante el juego, o puedes crearlo como panel para el menú principal.

Asumo que quieres crear un panel para el juego.

Asi que, después de incluir el panel, deberías añadir

mypanel->Create(gameParent);

y comprobar si gameParent ha sido declarado en lo alto de la función, si no lo a sido, entonces añade

VPANEL gameParent = enginevgui->GetPanel( PANEL_CLIENTDLL );

Nota: Para tener tu pantalla apareciendo en el juego como los menús de comras del Counter-Strike o la selección de equipo, cambia PANEL_CLIENTDLL por PANEL_INGAMESCREENS , de otra manera solo será visible cuando presiones la tecla Escape para ir al menú del juego.

Entonces añade:

mypanel->Destroy();

a la función VGui_Shutdown().

Si planeas crear un panel para el menú principal, necesitas poner esto en la función de construcción(VGui_CreateGlobalPanels()):

VPANEL GameUiDll = enginevgui->GetPanel( PANEL_GAMEUIDLL);
mypanel->Create(GameUiDll);

Esto hará que el panel aparezca cuando empiece el mod.

Propiedades de control

Todo está funcionando, asi que inicia el juego y comprueba si ves el panel. Ahora tienes la opción de apretar CTRL+ALT+SHIFT+B de cara a usar el VGUI2 Builder. Puedes arratrar alrededor del panel y establecer algunas propiedades así como añadir algunos elementos. No olvides guardar tu trabajo después.

Añadiendo Elementos

Hay dos formas de añadir nuevos elementos. Una forma es usar el VGUI2 Builder. Pero desde que VGUI2 Builder. no viene con todos los elementos esenciales, deberías añadir elementos en tu código. Por tanto, tienes elección entre alrededor de 50 elementos, individualmente almacenados en la carpeta vgui_controls. De hecho, incluso esto es bastante sencillo. Añade un puntero en la declaración de la clase. Aqui hay un ejemplo:

vgui::TextEntry* m_pTime; // Declaración de la Clase Panel, sección privada.

Añade esto al constructor del panel:

m_pTime = new vgui::TextEntry(this, "MyTextEntry");
m_pTime->SetPos(15, 310);
m_pTime->SetSize(50, 20);

También tendrás que añadir el siguiente include para conseguir el constructor de TextEntry:

#include <vgui_controls/TextEntry.h>

Otras cosas

Vamos a hacer algunas cosas de consola. Por ejemplo, podríamos necesitar una variable que nos permitiera establecer el estado de nuestro panel.
Aqui hay un ejemplo:

MyPanel.cpp

Bajo todo el otro código, añade:

ConVar cl_showmypanel("cl_showmypanel", "1", FCVAR_CLIENTDLL, "Establece el estado de myPanel <state>");

Este código no necesita ninguna explicación, así que continuamos añadiendo un metodo a nuestra clase:

void CMyPanel::OnTick()
{
	BaseClass::OnTick();
	SetVisible(cl_showmypanel.GetBool()); //CL_SHOWMYPANEL / 1 BY DEFAULT
}

Un comando para cambiar el panel a encendido o apagado:

CON_COMMAND(ToggleMyPanel, "Toggles myPanel on or off")
{
	cl_showmypanel.SetValue(!cl_showmypanel.GetBool());
};

Elementos Interactivos

En la última parte de este tutorial añadiremos alguna funcionalidad a un botón.

void CMyPanel::OnCommand(const char* pcCommand)
{
	if(!Q_stricmp(pcCommand, "turnoff"))
		cl_showmypanel.SetValue(0);
}

Puedes añadir un botón (usando el Built-in Editor) y establecer el valor de comando del botón a "turnoff" (apagado). si el jugador clickea este botón el panel desaparece.

Menú Principal

Para enlazar tu nuevo panel desde el menú principal, abre GameMenu.res en tu carpeta /resource/. Añade:

	"5"
	{
		"label" "My Panel"
		"command" "engine ToggleMyPanel"
		"notmulti" "1"
	}

Y cambia ConVar cl_showmypanel("cl_showmypanel", "1", FCVAR_CLIENTDLL, "Sets the state of myPanel <state>");

A: ConVar cl_showmypanel("cl_showmypanel", "0", FCVAR_CLIENTDLL, "Sets the state of myPanel <state>");

Así no saltará como un pop-up antes de que el usuario haga click en el botón.

Quizá quieras añadir mypanel->Activate(); bajo cl_showmypanel.SetValue(!cl_showmypanel.GetBool());. Esto establecerá el foco en tu panel. Para poder utilizar el comando Activate(), necesitarás añadir:

	void Activate( void )
	{
		if ( MyPanel )
		{
			MyPanel->Activate();
		}
	}

Bajo:

	void Destroy( void )
	{
		if ( MyPanel )
		{
			MyPanel->SetParent( (vgui::Panel *)NULL );
			delete MyPanel;
		}
	}

En MyPanel.cpp.

Y añadir:

virtual void		Activate( void ) = 0;

Bajo:

virtual void		Destroy( void ) = 0;

En IMyPanel.h.

Si quieres que el usuario sea capaz de cerrar tu panel sin haber clickeado sobre el menú de opciones de My Panel, añade un botón con el comando "turnoff" (apagado) a tu panel.

See also

• VGUI: Making GameUI Panels(en) is an alternative tutorial on the same thing.
• Modifying Source GameUI(en) is a lighter dose of creating your own UI.