View source for HPL1/Content Creation Chapter 10

{{constructionNotice|This page is undergoing major editing, as information is still being gathered and researched. More pages and information will gradually be added.}}

== 10 Graphical User Interface files ==



=== 10.1 Intro ===
'''NOTE:''' Before you begin, make sure you've familiarized yourself with the Extensible Markup Language (XML) before beginning to edit these files. Currently you may only change and replace existing GUI files as they are referenced elsewhere in order for the game to be able to initialize and use them.

Graphical User Interface files are ordinary XML files albeit slightly more advanced than your usual Entity (*.ent) or Heads-Up Display (*.hud) file, GUI files are mostly used to display interfaces on the screen when the player interacts with a certain object (such as a computer or bombs). The most common use however is for the Computer Terminals found throughout Black Plague.

Overture cannot load nor display Graphical User Interface files.

Prior to editing Graphical User Interface (*.gui) files make sure that the language is set to XML in Notepad++.

The following values are used, note that all types have "" around the value:
{| class="wikitable sortable" border=1
| '''String'''	 || A string of letters. "MyName" or "My_Name"
|-
| '''Integer'''	 || A number without decimals "-15"
|-
| '''Vector2'''	 || Two numbers in a row separated by space: "1 1".
|-
| '''Vector3'''	 || Three numbers in a row separated by space: "1 1 1".
|-
| '''Vector4'''	 || Four numbers in a row separated by space: "1 1 1 1".
|-
| '''Boolean'''	 || A data type using "true" or "false" values.
|-
|}

=== 10.2 Script Functions ===
Here are all the valid Scripting Functions available for associating your Graphical User Interface files with. Most of the functions are defined here, think of GUI files as a setting file.

Use these as a reference and look at existing AngelScript files used by the various GUI files.

<syntaxhighlight lang="C++">
void ClickMyFunction(string asName, string asMessage, int alVal)
</syntaxhighlight>
This is the standard syntax used to define various windows and playing back sound.

<syntaxhighlight lang="C++">
void CloseScreenGui();
</syntaxhighlight>
This will kick the player out of the terminal.

<syntaxhighlight lang="C++">
void SetWidgetBool(string asName, string asString, bool abActive);
</syntaxhighlight>
Displays or hides a window.
<br/>
asName name of the window<br/>
asString what string value to change (enabled or visible)<br/>
abActive whether to change the value to true or false<br/>

<syntaxhighlight lang="C++">
void SetAttentionWidget(string asName);
</syntaxhighlight>
Makes the current window active. (Think folder directories or an error message)

<syntaxhighlight lang="C++">
CreateGuiPopUpTrans("string asCat1","string asEntry1",
					"string asCat2","string asEntry2",
					"string asCat3","string asEntry3", 
					"","",
					"string asFunction");
</syntaxhighlight>
Display a simple text window.<br/>
asCat1 Text Category for the toolbar text<br/>
asEntry1 Text Entry for the toolbar text<br/>
asCat2 Text Category for the window text<br/>
asEntry2 Text Entry for the window text<br/>
asCat3 Text Category for the window button<br/>
asEntry3 Text Entry for the window button<br/>
asFunction Must be a valid int xButton function name<br/>

<syntaxhighlight lang="C++">
void MyFunction(int xButton)
</syntaxhighlight>
Defines what sound should be played when pressing a button in the interface.

Valid syntax: "PlayGuiSound(string asName, float afVol)"

<syntaxhighlight lang="C++">
void CreateGuiTextView(	"string asCat1", "string asEntry1", 
				"string asCat2", "string asEntry2","string, asFunction");
</syntaxhighlight>
Creates a text window.

asCat1 Text Category for the toolbar<br/>
asEntry1 Text Entry for the toolbar<br/>
asCat2 Text Category for the actual text<br/>
asEntry2 Text Name for the actual text<br/>
asFunction Must be a valid int xButton function name

<syntaxhighlight lang="C++">
void ViewImage("string asName", "string asCat", "string asEntry");
</syntaxhighlight>
Creates an image window.

asName Name of the image to display. Must match name in the GUI images tag.<br/>
asCat Category for the image window name<br/>
asEntry Entry for the image window name

<syntaxhighlight lang="C++">
void SetWidgetCallback("string asName", "string asButton", "string asFunction");
</syntaxhighlight>
Add a callback that is called when the player interacts with the interface

asName Name of the Widget in the GUI file<br/>
asButton Type of interaction (ButtonPressed, MouseDoubleClick)
=== 10.3 Graphical User Interface reference file ===
Below is a sample that will help you define a GUI file, this file has some of the more basic stuff to creating a computer terminal interface, you can add more advanced stuff as you go through the various existing ones and this documentation.

Due to the nature and structuring of GUI files it is recommended that you only use this as a reference when editing existing GUI files rather than making your own as it can become quite cumbersome.

"ScriptName" Implies what you'd call the function in order to be referenced with the accompanying script file. (I.E VacationPic)<br/>
"FontsTag" Must match the name used in the Fonts tag. (I.E FileTextWhite)<br/>
"ImageTag" Must match the name used in the Images tag. (I.E DeskTop.jpg or Folder.bmp)<br/>
<syntaxhighlight lang="XML">
<GUI>
	<Main SkinFile="String, name of skin (*.skin) file" ScriptFile="String, name of accompanying script (*.hps) file" IsFullScreen="Boolean" />
		
	<Images>
		<Image Name="String, ImageTag" File="String, name of a valid bitmap (*.bmp) file" Offset="0 0" ActiveSize="-1 -1" Color="Vector4, Red, Green, Blue, Alpha values" />

		<Texture Name="String, ScriptName" File="String, name of image (*.jpg) file" Offset="0 0" ActiveSize="-1 -1" Color="Vector4, Red, Green, Blue, Alpha values"/>
	</Images>
	
	<Fonts>
		<Font Name="FileTextWhite" File="verdana.fnt" Size = "11 11" Color="1 1 1 1" />
		<Font Name="FileTextBlack" File="verdana.fnt" Size = "11 11" Color="1 1 1 1" />
		<Font Name="Normal" File="verdana.fnt" Size = "12 12" Color="1 1 1 1" />
		<Font Name="NormalGreen" File="verdana.fnt" Size = "12 12" Color="0 1 0 1" />
		<Font Name="NormalRed" File="verdana.fnt" Size = "12 12" Color="1 0 0 1" />
	</Fonts>		
	
	<Widgets>
		<Image Position="Vector3, position of image" Image="String, ImageTag" Size="Vector2, size of image" >
	  	
	  	<Button Name="CloseTerminal" Position="775 5 1" Size="20 20" Text="X"/>
	  	
	  	<!-- FILES -->
	  	
	  	<Image Name="String, ScriptName" Position="Vector3, icon position" Image="String, ImageTag" Size="Vector2, size of the icon">
	  		<Label Name = "String, ScriptName" Position="Vector3, position of label text" TextCat="String, TextCategory" TextEntry="String, TextEntry" Font="String, must match font name in fonts tag" TextAlign="String, valid alignments are Left, Right and Center" WordWrap="Boolean" Size="Vector2, size of text, in width and height, default"/>
	  	</Image>
	  	
	  	<!-- FOLDER WINDOW -->
	  	
	  	<Window Name="String, ScriptName" Position="Vector3, icon position" Size="Vector2, size of the icon" TextCat="String, TextCategory" TextEntry="String, TextEntry" Visible="Boolean, whether or not the frame should be drawn" Enabled="Boolean, whether or not the window should be enabled">
	  		<Frame Position="Vector3, position of folder window" Size="Vector2, size of folder window" BackgroundColor="Vector4, Red, Gree, Blue, Alpha values" DrawBackground="Boolean, doesn't do anything" DrawFrame="Boolean, does nothing" >
	  			<Image Name="String, ScriptName" Position="Vector3, position of icon" Image="String, ImageTag" Size="Vector2, size of icon">
			  		<Label Name = "String, ScriptName" Position="Vector3, position of text" TextCat="String, TextCategory" TextEntry="String, TextEntry" Font="String, FontsTag" TextAlign="String, valid alignments are Left, Right and Center" WordWrap="Boolean, if the words should wrap around the edges or continue off-screen" Size="Vector2, size of text, in width and height"/>
			  	</Image>
		  	</Frame>
	  		
			<Button Name="String, ScriptName" Position="Vector3, button position" Size="Vector2, size of button in width and height" TextCat="String, TextCategory" TextEntry="String, TextEntry" />	  			  		
	  	</Window>
	  	
	  	<!-- IMAGE WINDOW -->
	  	
	  	<Window Name="String, ScriptName" Position="Vector3, window position" Size="String, size of window" TextCat="String, TextCategory" TextEntry="String, TextEntry" Visible="Boolean, whether or not the frame should be drawn" Enabled="Boolean, whether or not the window should be enabled">
	  		<Frame Position="Vector3, position of image viewer window" Size="Vector2, size of image viewer window" DrawBackground="Boolean, doesn't do anything" DrawFrame="Boolean, does nothing" >
	  			<Image Name="String, ScriptName" Position="Vector3, position of image" Image="String, ImageTag" Size="Vector2, size of image, in width and height" />
	  	  	</Frame>
	  		
			<Button Name="CloseImageWindow" Position="160 340 1" Size="100 30" TextCat="GUI" TextEntry="Close Window" />	  			  		
	  	</Window>
	  </Image>
	</Widgets>
</GUI>
</syntaxhighlight>