Difference between revisions of "VGUI2: Creating a panel"

From Valve Developer Community
Jump to: navigation, search
m (See also)
m (Requirements)
Line 9: Line 9:
*[[HUD Elements]]
*[[HUD Elements]]
Can code:
Can code:
*C++ (!!!!)
This tutorial is about creating a simple interactive interface
This tutorial is about creating a simple interactive interface

Revision as of 00:18, 14 August 2012



Have read and understood (or understand):

Can code:

  • C++
  • Script

This tutorial is about creating a simple interactive interface

Understanding how VGUI2 works

Every VGUI2 dialog that you see while using source based games is basically called a Panel.

Every Panel consists of three components:

  • Scheme
  • Control Settings
  • Code

The Scheme

The scheme is a general configuration file which stores information about the colors of certain elements such as buttons, combo boxes, labels, etc. A typical scheme file is SourceScheme.res, for example. If you plan to create a panel which looks like the other panels in the menu you should use the same scheme file as they do.

Control Settings

The control settings file stores information about the relative position of your panel and its elements.

Every panel has a very own resource file. To create a resource file, there are two ways: Either you create one on your own using an editor like notepad, or you use Valves InGame Resource Editor.


The code is the most important part of a panel, since the code decides what to do if the user clicks a button. To create and destroy the panel, you use the code. Fortunately you can set a lot more things than in the resource file(s). Code is the most important thing in this tutorial.

Creating a 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.

Starting Off

The panel class is the base class of all VGUI2 elements. To get a rough overview about all the VGUI2 elements, have a look into the vgui_elements folder. Of course, we don't just buy some wood in our local building centre.

The important class is the EditablePanel class that inherits from the Panel class. Our panel will be a new class which inherits from the EditablePanel class. This results in several advantages: We can code methods related to the content of the panel, we can overwrite the methods of the base classes and do much more useful stuff.

You can create a new file MyPanel.cpp underneath the Source Files inside the client project.


 //The following include files are necessary to allow your MyPanel.cpp to compile.
 #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
 	//VGUI overrides:
 	virtual void OnTick();
 	virtual void OnCommand(const char* pcCommand);
 	//Other used VGUI control Elements:

The constructor: The argument is vgui::VPANEL parent. After reading the VGUI Documentation, you should know that every panel has a parent and why it has a parent.

Underneath the above code, add:

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

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


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

The first lines are pretty easy to understand. SetScheme is used to set the source scheme, which is the standard scheme for Half-Life 2. We get a pointer to the scheme by calling LoadSchemeFromFile(...). The LoadControlSettings function is used to load the control settings resolution file. The last line is explained in the VGUI2 documentation.

The SetProportional( false ); function decides to make the panel big or small, having it set to true will cause your panel to have big fonts, controls etc.

Underneath the above code, add:

//Class: CMyPanelInterface Class. Used for construction.
class CMyPanelInterface : public IMyPanel
	CMyPanel *MyPanel;
		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;

Next you can create IMyPanel.h in the same folder.


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

extern IMyPanel* mypanel;

Calling the panel

To call the panel, we add a few lines to the vgui_int.cpp file. Vgui_int.cpp includes functions which call all the panels. The VGui_CreateGlobalPanels() function is where the addition takes place.

This is the point, where you have to decide when the panel should show up. Either you create a panel that can be accessed during the game, or you create a panel for the main menu.

I assume that you want to create a panel for the game.

So, after including the panel, you should add


and check to see if gameParent has been declared at the top of the function, if it hasn't then add

VPANEL gameParent = enginevgui->GetPanel( PANEL_CLIENTDLL );

Note: To have your screen appear in-game like the Counter-Strike buy menus or team selection menus, change PANEL_CLIENTDLL to PANEL_INGAMESCREENS , otherwise it will be visible only when you press Escape to go to the game menu.

Note: Dont forget to add

#include "IMyPanel.h"

to vgui_int.cpp file.

Then add


to the VGui_Shutdown() function.

If you plan to create a panel for the main menu, you need to put this into the construction function (VGui_CreateGlobalPanels()):

VPANEL GameUiDll = enginevgui->GetPanel( PANEL_GAMEUIDLL);

This will cause the panel to appear when you start your mod.

The control settings

Everything is working, so start the game, and check if you see your panel. Now you have the chance to press CTRL+ALT+SHIFT+B in order to use the VGUI2 Builder. You can drag around the panel and set some properties as well as adding some elements. Do not forget to save your work afterwards.

Adding elements

There are two ways to add new elements. The one way is to use the VGUI2 Builder. Since the VGUI2 Builder doesn’t come with all the essential elements, you should add elements in your code. Therefore, you have the choice in-between 50 elements, individually stored in the vgui_controls folder. Indeed, even this is pretty easy. You add a pointer into the class declaration. Here is an example:

vgui::TextEntry* m_pTime; // Panel class declaration, private section

Add this to the panels constructor:

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

You'll also have to add the following include to get the constructors for TextEntry:

#include <vgui_controls/TextEntry.h>

Other stuff

Let's do some console stuff. For example, we could need a variable which allows us to set the state of our panel.
Here is an example:


Underneath all of the other code, add:

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

This code doesn’t need some explanation, so we continue by adding a method to our class:

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

A command to toggle the panel on or off:

CON_COMMAND(ToggleMyPanel, "Toggles myPanel on or off")

Interactive Elements

In the last part of this tutorial we will add some functionality to a button.

void CMyPanel::OnCommand(const char* pcCommand)
	if(!Q_stricmp(pcCommand, "turnoff"))

You can add a button (using the built-in editor) and set the command value of the button to "turnoff". If the player clicks this button, well, the panel disappers.

Main Menu

To link to your new panel from the main menu, open up GameMenu.res in your /resource/ folder. Add:

		"label" "My Panel"
		"command" "engine ToggleMyPanel"
		"notmulti" "1"

And change

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


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

So that it won't pop up before the user clicks it.

You may also want to add
. This will

focus on your panel. To be able to use the Activate() command, you will need to add:

	void Activate( void )
		if ( MyPanel )


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

In MyPanel.cpp.

And add:

virtual void		Activate( void ) = 0;


virtual void		Destroy( void ) = 0;

In IMyPanel.h.

If you want the user to be able to close your panel without having to click the My Panel menu option, add a Button with the command "turnoff" to your panel.

See also