The section of the script file that defines the menu is called the menuDef section. This will give us a script file that looks like this :
#include "ui/menudef.h"
{
menuDef
{
}
}
We will leave out the assetGlobalDef section for clarity's sake. Everything between the curly braces after menuDef is used to define the menu. A menu is made up of one or more menu items plus some overall menu information. We'll look at the overall menu information first.
When a menu is defined we must tell the program some information about it in order for it to work. The most important bit of information the program needs is the name of the menu. Without a name the program can not find the menu to run it. The menu name is set using the name command like this :
name "main"
to define a menu called main, which is the default starting menu. Every menu name must be unique - two menus can not have the same name.
Next we have to tell the program what area of the screen the menu will cover. In Quake 3 all menus are based on a screen size of 640x480 so a menu that covers the entire screen would would start at location (0,0) and have a width of 640 and a height of 480. The rect command is used to set the area the menu covers and is in the form :
rect x y width height
where x and y are the upper left corner locations and width and height is the area size. A menu that covers the entire screen would be defined by :
rect 0 0 640 480
A menu like the Quit menu, which pops up over an underlying menu, would have an area definition like :
rect 204 122 235 235
which defines a box 235x235 in size, who's upper left corner is located at (204,122).
If you are defining the main menu you must use the fullScreen command instead of the rect command. When used as follows :
fullScreen MENU_TRUE
it creates a menu that covers the entire screen and any rect command will be ignored. The first menu run by the program (the "main" menu) must be set to be full screen this way. If you don't use this command then your menu will not work properly. Also, if you close a full screen menu and open another menu then that menu must also be set to be full screen. It is imperative that a full screen menu be open at all times or the menu system will not work.
These two bits of information, the name and the menu area, are all that are really required by the program to run the menu. This gives us a minimal menu script that looks like :
#include "ui/menudef.h"
{
menuDef
{
name "main"
fullScreen MENU_TRUE
}
}
There are many other commands though, that can be used to add customization and functionality to the menu. Let's take a look at them next.
Background
Any menu that is defined to be full screen (using fullScreen MENU_TRUE) must have a background graphic defined unless the menu items cover the entire screen. The menu background is defined using the background command in the form :
background <name>
where <name> is either the path and name of the graphic ( "ui/assets/fakkback.tga" ) or the name of the shader to use ( "menubackground" ). If no background is defined the Quake 3 default shader is used. All of the rest of the menu is drawn on top of this background.
Menu Color
A menu can have two colors assigned to it that will be used by other menu commands. These are the background color and the foreground color, which are set using the backcolor and forecolor commands respectively. These commands are used like :
backcolor red green blue alpha
forecolor red green blue alpha
where the range of the colors and alpha is 0 to 1. See here for more information on color values in Quake 3.
Menu Fading
Normally the values used for menu fading are set in the assetGlobalDef section but they can be set for individual menus as well. The speed and amount of the fade is controlled by three values, fadeClamp, fadeAmount and fadeCycle. See here for details on the values used. Fading is not applied to full screen menus.
Cinematic
On menus that are not full screen you can use a Roq movie as a background rather than a graphic. To define which movie you want, use the cinematic command as so :
cinematic <movie>
where <movie> is the name of the Roq file but not the path. All movies must be placed in the video directory or this command will not find them.
Window Style
The area the menu covers is called a menu window and you can customize how this window is drawn. A window can have one of six different styles, which is set by the style command. The window styles you can use are :
- style WINDOW_STYLE_EMPTY - this is the default window style and nothing special is done with it.
- style WINDOW_STYLE_FILLED - if no background graphic is defined then fill the window with the background color. If a background graphic is defined and the menu is defined to be full screen then fill the window with the graphic but tint it with the background color. Also use the fade values to fade the menu in and out, if the menu is not full screen.
- style WINDOW_STYLE_GRADIENT - use the gradiant bar graphic, colored with the background color to fill the window. The graphic is stretched to fit the window size.
- style WINDOW_STYLE_SHADER - fill the window with the background graphic, tinting it with the foreground color if one has been defined.
- style WINDOW_STYLE_TEAMCOLOR - fill the window with the color of the team you are on. A Team Arena specific window style.
- style WINDOW_STYLE_CINEMATIC - fill the window with the movie defined by the cinematic command. This does not work on full screen menus.
Window Borders
In addition to the style, you can set borders around the window. There are five different border types you can choose from, set by the border command as follows :
- border WINDOW_BORDER_NONE - the default border type which draws nothing.
- border WINDOW_BORDER_FULL - draws a border on all four sides of the window.
- border WINDOW_BORDER_HORZ - draws a border on the top and bottom only.
- border WINDOW_BORDER_VERT - draws a border on the sides only.
- border WINDOW_BORDER_KCGRADIENT - draws a gradiant border on the top and bottom of the window using the gradiant bar graphic tinted by the border color.
When a border is drawn on a window the actual size of the window is shrunk to fit inside the border. This is important to the placement of menu items, which base their location on the upper left corner of the menu window. Therefore, when you use borders, the upper left corner of the menu window is inside the border, not in its original location.
The thickness of the border is set by the bordersize command and is used like :
bordersize <value>
where <value> is the thickness in pixels.
The color of the border is set by the bordercolor command as follows :
bordercolor red green blue alpha
where the range of the colors and alpha is 0 to 1. See here for more information on color values in Quake 3. If the window style is set to WINDOW_STYLE_TEAMCOLOR then the border color is ignored and the team color is used instead.
Focus Color
When an item receives the focus from the keyboard or mouse you can specify the color to which the text in the item should change. This is set by the focusColor command and works like this :
focusColor red green blue alpha
where the range of the colors and alpha is 0 to 1. See here for more information on color values in Quake 3. Team Arena uses a yellow focus color set by this :
focusColor 1 .75 0 1
The text will pulse slowly when it has the focus.
Disabled Color
If you have menu items that can be disabled and enabled you need to have a way to indicate what the item state is. This is done by setting a color for text in disabled items using the disablecolor command like this :
disableColor red green blue alpha
where the range of the colors and alpha is 0 to 1. See here for more information on color values in Quake 3.
Open Script
When a menu is opened it is possible to have the program run a special script to allow you to setup things the way you want. This can be used to start the menu music playing, hide certain menu items and activate others, plus other actions. This is all accomplished using the onOpen command. It is used like this :
onOpen { script command ; ... ; script command }
where you have a series of script commands separated by semicolons and enclosed in curly brackets. To find out more information on the script commands you can use see Script Actions .
Close Script
When the menu is closed it is also possible to have a special script run to allow you to do some cleanup work, such as stopping the menu music. This is accomplished using the onClose command. It is used like this :
onClose { script command ; ... ; script command }
where you have a series of script commands separated by semicolons and enclosed in curly brackets. To find out more information on the script commands you can use seeScript Actions .
Escape Script
Another important thing you can do is have a special script run when the ESC key is pressed. This is normally used to close the current menu and open another but you are not limited to just these actions. This is done using the onESC command. It is used like this :
onESC { script command ; ... ; script command }
where you have a series of script commands separated by semicolons and enclosed in curly brackets. To find out more information on the script commands you can use see Script Actions .
Out of Bounds Click
A feature that may be useful in some situations is the out of bounds click flag. If this flag is set for a menu, then clicking outside the menu window will cause the menu to be closed. To set the flag, use the command as so :
outOfBoundsClick
This command can only be used on non-full screen, non-popup menus..
Popup Menu
If a menu is not a full screen menu then it can be of two types - popup or non-popup. A popup menu does not allow any items in underlying menus to get the focus. Only items in the popup menu can get the focus. A non-popup menu allows items in underlying menus to get the focus. By default menus are non-popup but they can be set to popup status by using this command :
popup
