The Basics
The GUI editor can be started from the console with the editguis command. You can also start it via the command line by adding the +editguis parameter.
The GUI editor contains four main areas: the GUI display, the Navigator, the Transformer, and the Properties window.
The GUI display is the main working area of the editor. This area displays all of the *Def elements in the GUI including the Desktop. The basic display properties of this area can be modified under View>Options. *Def elements appear on the display as blue frames with handle controls on the sides and corners.
The properties of a windowDef (rect, visible, etc.) are displayed in the Properties window. A separate Properties dialog can be brought up by hitting alt + Enter or double-clicking on the element. The Properties dialog contains three tabs: General, Image, and Text. All of these contain basic properties of the element which will be discussed individually in subsequent sections. The properties of an element can also be changed in the Properties window by clicking in the desired space to change a value, or clicking in an empty space to add a new property.
The Navigator displays the *Def element tree of the GUI. The elements are layered and nested such that elements that are further down the tree are in a higher order than previous elements, and elements that are nested inside others are indented under their parent elements. Parent elements can be collapsed and expanded by clicking the arrow that appears to the left of them in the Navigator. For an element to be visible in its entirety, its parent window must be as large or bigger in size than the child element. The order of elements and their parent-child relationships can be changed within the Navigator -- see the section below on Working with Elements.
The scripts that are associated with a windowDef appear in a separate editing area that can be brought up by hitting ctrl + Enter or by right-clicking on an element in either the display area or the Navigator and selecting "Scripts". See Scripting Actions and Animations for more information on scripts.
Basic GUI Structure and the Desktop
In this document, windowDef is used to refer to any of the *Def elements since they share nearly all of the same properties. If something is different, it’ll be noted.
GUIs are made up of individual elements, most of which are windowDefs. There are also choiceDefs, editDefs, and other *Defs that are described below. All windowDefs are contained in the Desktop, which is the master GUI parent element. When a windowDef is created, it’s nested under the Desktop. WindowDefs can be nested within other windowDefs, creating a parent-child relationship.
A windowDef contains flags and scripts. The flags are values that determine basic properties of the windowDef such as size, visibility, color, etc. Scripts are nested inside the windowDef's braces and are executed depending on the circumstances.
The Desktop also contains all the definitions for floats, vec4s, and namedEvents (see section 6).
If you use the GUI editor, you generally won’t be manually writing a windowDef (although you could open a plain text file and hand-script a GUI this way). But it’s useful to know what the basic windowDef scripting looks like in case you have to go into the scripting text itself and manipulate things. The following example is what the scripting looks like for a couple of simple windowDefs in a GUI:
windowDef element1
{
rect 0,0,640,480
visible 1
backcolor 1,1,0,1
}
windowDef element2
{
rect 0,0,300,300
visible 1
backcolor 1,1,0,0.5
text “this is some text”
textscale 0.5
forecolor 1,1,1,1
}
The following example would be a windowDef that also contains some scripting that performs actions:
windowDef element1
{
rect 0,0,640,480
visible 1
backcolor 1,1,0,1
onMouseEnter
{
set “backcolor” “1,1,1,1” ;
}
onMouseExit
{
set “backcolor” “1,1,1,0.5” ;
}
}
See definitions on what each of the possible flags of a windowDef are.
There are two kinds of GUIs that can be created in the Quake 4 GUI system: menu and HUD GUIs and world GUIs. Menu and HUD GUIs are used as the basic game UI, while world GUIs are screens that players can walk up to and use in-game to solve puzzles, get information, or move around in the world (i.e., an elevator GUI that lets the player select a floor to move to).
Working with Elements
To move *Def elements around the display area, simply click and drag the element and move. To resize, simple click and drag a *Def element's control handle. The position and size of an element can also be controlled by the Properties dialog.
To make an element the child of another element, first select the desired parent element. Then holding CTRL, select the desired child element. Then either right-click and select Arrange>Make Child or hit CTRL + \. To reverse this action, repeat the process using the Desktop as the desired parent element. When selecting elements, the first element selected will always be the parent element when the action is taken. Multiple children elements can be made by selecting more than one element after first selecting the parent element.
The layer order of elements can be changed in the Navigator. To do so, select an element and then either right-click and choose Arrange and then an option to move to front, back, or bring forward or backward. This can also be accomplished via the keyboard shortcuts displayed in the right-click menu.
The GUI editor also allows you to resize or move elements by using another element as a point of reference. To make two elements the same size, select the first element, which will be used as the point of reference, and then holding down CTRL select the second element, which will be resized. Right-click and select Align>Make Same Size. Select width, height, or both to resize. Multiple elements can be selected; the first element selected will always be the point of reference and all other selected elements will be resized accordingly. The Align option also allows you to align multiple elements along a primary element's left side, right side, top, bottom, or center. As with other actions, the first element will always be used as the point of reference and subsequently selected elements will be aligned accordingly.
Working with Textures
Elements reference materials with the background property. All materials used in GUIs must be sized in powers of 2. Materials can be simple textures, or they can be shaders defined in the .mtr file. A default shader will be used if the path used is not a shader path, but a path directly to an image. This default shader will be a 32bit alpha blend image shader. Even when referencing a direct image, it is best to leave off the .tga at the end of the path.
Using the Viewer
Hitting CTRL + T will display the GUI Viewer. This window shows the loaded GUI exactly as it would appear in-game, allowing you to test your GUI's functionality.
Editor Options
There are several display options under the View tab. Zooming in and out is self-explanatory. Hide/Show will hide or show selected elements, or will unhide all elements. Show Outlines will show outlines for all elements in the GUI. Show Grid will display the grid, which is customizable under View>Options. Snap to Grid will snap an element's position to the grid. Show Safe Area is used only for GUIs developed for consoles and displays the region which elements must stay inside in order to not be potentially clipped off by a TV screen.
There are two options under the Tools menu option. Viewer has already been discussed. Reload Materials (CTRL + M) will reload the textures used in your GUI. This is especially helpful if you've changed a texture and want to quickly refresh your GUI to see the change.
The Localize Current GUI option takes all text strings in the GUI and saves them out as "#str_xxxxxx" values referenced in *.lang files. This is used to ensure easy GUI localization for other languages.