Items are the building blocks of a menu. By combining a number of items together and placing them over the top of the menu background we create a functional menu.
Those sections of the definition that define the items are known as the itemDefs. Each itemDef must be inside the menuDef section of the script file for it to be included in the menu.:
#include "ui/menudef.h"
{
menuDef
{
itemDef
{
}
itemDef
{
}
}
}
There can be a maximum of 128 itemDefs in a menuDef. Everything inside the curly brackets of the itemDef is used to define that particular item.
NOTICE : items are draw to the screen in the order that they are defined in the menuDef, with the last item defined being on top. This is very important to remember when placing items in the menuDef, as it will affect the final result drawn to the screen.
Items can be either functional, decorative or a combination of both. Functional items include such things as buttons, sliders and scrolling lists. Decorative items are things like text, graphics and models. Functional items can also contain some of the features of a decorative item, such as graphics.
Items can be thought of as windows that are placed on the menu background, with each window having its own features and area of operation. In order to allow the program to work with these item windows we need to supply some information about the window. This process is very similar to how we provided overall information about the menu itself. In fact, much of the same information is required about the item window as was required by the menu window.
Item Name
One thing that is needed for an item is a name. Since items can be modified by other items and actions, a name is required so the item can be identified. We use the name command to set the item name like this
name <item name>
where <item name> is the name of the item. Unlike menu names, multiple items can share the same name, a feature that can be used when modifying multiple items at once.
Item Group
In addition to a name, an item can also have an optional group name. This is used by other items to modify multiple items at one time, in a similar manner to the way they use the item name to modify multiple items. The group is set by the group command like :
group <group name>
where <group name> is the group name of the item. Multiple items can share the same group name.
Window Area
A item must also have a window area assigned to it so we know where to place it. We use the rect command for this :
rect x y width height
where x and y are the location of the upper left corner of the item window and width and height are its size. The x and y values are calculated relative to the upper left corner of the menu window. For example, if the menu window is defined by
rect 150 10 400 300
and the item window is defined by
rect 10 35 100 120
then the actual item location would be at x = 150+10 = 160 and y = 10+35 = 45.
This information gives us an item definition like :
itemDef
{
name singleBar
rect 349 54 256 30
}
This is an item named "singleBar" which covers an area 256x30 located at (349,54) from the upper left corner of the menu window.
Window Style
Next needed is the style of the window. An item 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 - fill the window with the background color. Also use the fade values to fade the menu in and out.
- 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.
Decoration
An important piece of information we must supply for the item is whether or not it is decorative. Decorative items don't ever receive the focus, don't make a mouseover sound and generally perform no actions. Functional items can receive the focus, make mouseover sounds and perform actions. To define an item as decorative we include the decoration command in the itemDef like so :
decoration
Visiblity
Something else of importance to the program is if the item will be visible when the menu opens. An item that is not visible is not shown when the menu is drawn and you can not interact with it. An item's visiblity can be altered by another item's actions. To tell the program the visiblity status of the item when the menu opens we use the visible command. To make the item visible it is used like :
visible MENU_TRUE
To make the item invisible it is used like :
visible MENU_FALSE
Note : an item can have a visibility status and a disabled status. If an item is visible it is drawn. If not visible, it is not drawn and no interaction can take place. An item that is visible can also be disabled, in which case it is drawn but you can not interact with it. An item that is disabled is tinted with the Disabled Color, if one is defined.
Background
An item can have a background graphic assigned to it that will be drawn in the window area if the window style is WINDOW_STYLE_SHADER. The background is assigned by the background command, used like so :
background <name>
where <name> is either the path and name of the graphic ( "textures/menu/julie_1.tga" ) or the name of the shader to use ( "menu/art/smoke" ).
Item Colors
Along with the background graphic, we can assign two colors to an item. 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.
Borders
If desired it is possible to have borders drawn around the item 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.
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.
Cinematic
On items you can use a Roq movie as a background rather than a graphic. The window style must be WINDOW_STYLE_CINEMATIC for this to work. 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.
Focus Sound
Back in the assetGlobalDef section we defined the global sound to be used when an item receives the focus. If we want, we can define a focus sound for each item that will be used instead of the global sound. This is done with the focusSound command like this :
focusSound <sound name>
where <sound name> is the path and name of the sound you wish played.
Item Text
A string of text can be assigned to an item and information about how it is to be displayed can be set using the text commands. The actual string of text is set using the text command like so :
text <string>
where <string> is a string of text enclosed in quotes (ie. "SINGLE PLAYER"). The text color is set by the item's foreground color ( as set by the forecolor command).
There are a number of commands that are used to tell the program how to display the text string inside the item window.
Alignment
A string of text can be aligned both horizontally and vertically. In the horizontal direction we have two commands to set the alignment. The first command is used to set the point in the text string that we use for the alignment. This is done with the textalign command and we have three points to choose from.
textalign ITEM_ALIGN_LEFT - set the point to the left side of the text
textalign ITEM_ALIGN_CENTER - set the point to the center of the text
textalign ITEM_ALIGN_RIGHT - set the point to the right side of the text
We then use the textalignx command to do the actual alignment. It is used like :
textalignx <distance>
where <distance> is the number of pixels from the left side of the item window to the alignment point in the text. For example :
textalign ITEM_ALIGN_CENTER
textalignx 80
will draw the text so that the center of the text string is 80 pixels from the left side of the item window. Additionally,
textalign ITEM_ALIGN_RIGHT
textalignx 120
will draw the text so that the right side of the text string is 120 pixels from the left side of the item window.
When aligning the text vertically we use the textaligny command as so :
textaligny <distance>
where <distance> is the number of pixels from the top of the item window to the bottom of the text.
Size
The size of the text is set using the textscale command like this :
textscale <scale>
where <scale> is the scale of the text. To figure out the actual point size of the text use this formula :
point size = 48.0 x <scale>
Style
The command textstyle applies certain special effects to the text when it is drawn. There are four different styles you can choose from :
- textstyle ITEM_TEXTSTYLE_NORMAL - normal solid text. This is the default text style.
- textstyle ITEM_TEXTSTYLE_BLINK - fast blinking text, about 2x per second.
- textstyle ITEM_TEXTSTYLE_SHADOWED - drop shadow effect.
- textstyle ITEM_TEXTSTYLE_SHADOWEDMORE - extra shadow effect.
- textstyle ITEM_TEXTSTYLE_NEON - neon colored text.
Text Wrapping
Normally when text is displayed it is not wrapped when it reaches the edge of the item window. Instead it is just displayed outside the window if necessary. It is possible to make the text wrap using one of two commands. By including the wrapped command in the item definition you gain the ablility to force a manual wrap of the text by use of '\r' in the text string. Manual wrapping still ignores the item window's edge. The command is used as :
wrapped
and a text string with manual wrapping would look like :
text "This is a Test of wrapping.\rThis is a new line"
The other text wrapping command is autowrapped, used like :
autowrapped
This will cause the text to automatically wrap around when it reaches the edge of the item window. You can force a manual wrap of the text by including a '\n' in the text, like this :
text "This is a Test of wrapping.\nThis is a new line"
Note, that even with autowrapping enabled, text will be drawn below the bottom of the item window if necessary.
Item Type
In order to use an item as something other than displaying text or graphics we must set the item type using the type command. An item can be one of eleven different types as follows :
- type ITEM_TYPE_TEXT - the default item type. It will display any defined text or background graphic but perform no special action.
- type ITEM_TYPE_BUTTON - a button type. When the mouse is clicked on this item the action command is run.
- type ITEM_TYPE_EDITFIELD - a text entry item where the entered text can be assigned to a cvar.
- type ITEM_TYPE_LISTBOX - a scrolling list box with selectable entries.
- type ITEM_TYPE_OWNERDRAW - draws the object as defined by the ownerdraw command.
- type ITEM_TYPE_NUMERICFIELD - a text entry item where the text is limited to numeric values. The text can be assigned to a cvar.
- type ITEM_TYPE_SLIDER - a slider item using the predefined slider graphics. Min, max and starting values can be defined. Slider value can be assigned to a cvar.
- type ITEM_TYPE_YESNO - a yes/no selection item. It has two states - yes (1) and no (0) that can be assigned to a cvar. Drawn as text (yes or no) using the item's text information.
- type ITEM_TYPE_MULTI - multiple selection item. Clicking on item rotates through a list of values/text strings to choose from.
- type ITEM_TYPE_BIND - used to allow binding keystokes to cvar commands.
- type ITEM_TYPE_MODEL - draws a Quake 3 model as defined by the asset_model command.
Most of these types require information to be provided by other item commands.
Focus and Mouse Scripts
There are a number of script action commands that relate to the item receiving/losing the focus and the mouse moving over/off the item's window. The focus can be obtained either via the keyboard or the mouse moving over the item. When the mouse is moved over an item these scripts are run in this order (if they are defined) :
mouseEnterText { <script> }
mouseEnter { <script> }
onFocus { <script> }
The mouseEnterText command is run when the mouse moves over any text defined in the item. This may not be the entire item window area if the text doesn't cover the entire window. The mouseEnter command is run when the mouse moves over the item window area. The onFocus command is run when the item recieves the focus either from the keyboard or when the mouse moves over the item window area.
When the mouse leaves an item these scripts are run in this order (if they are defined) :
mouseExitText { <script> }
mouseExit { <script> }
leaveFocus { <script> }
The mouseExitText and mouseExit commands are run when the mouse exits the item's window area, even if the item doesn't lose focus. The leaveFocus command is run only when the item actually loses the focus by another item receiving the focus.
To find out more information on the script commands you can use see Script Actions .
Cvars
Assigning to an Item
It is possible to assign a cvar to an item and, in fact, certain types of items require a cvar be assigned. The assignment is done by use of the cvar command used like :
cvar <cvar name>
where <cvar name> is the name of a cvar defined in the program. Only cvars defined in the program can be used, no creating new ones is allowed.
Show/Hide and Enable/Disable
You can also use a cvar to show or hide the item or to enable or disable it. The cvar used for this does not have to be assigned to the item and any cvar can be used. This first step in doing any of these is to test the value of the cvar. This is done with the cvartest command like :
cvartest <cvar name>
where <cvar name> is the name of a cvar defined in the program. The value of the cvar is remembered and used by other commands to do the actual show/hide or enable/disable. These commands are :
- enableCvar { <string> ; ...... ; <string> ; }
- if any of the <string> values match the tested cvar value then enable the item.
- disableCvar { <string> ; ...... ; <string> ; }
- if any of the <string> values match the tested cvar value then disable the item.
- showCvar { <string> ; ...... ; <string> ; }
- if any of the <string> values match the tested cvar value then make the item visible.
- hideCvar { <string> ; ...... ; <string> ; }
- if any of the <string> values match the tested cvar value then make the item not visible.
ownerdrawFlag
The ownerdrawflag command is used to determine if the item should be drawn, based on the status of a program supplied flag. This command does not apply to an item that is already invisible. Such an item will always be invisible, regardless of the result of this command. The ownerdrawflag command only applies to items that are visible as it can make visible items invisible but not make invisible items visible. If the flag provided by the program is true then the item is drawn. If the flag is false then it isn't drawn. The flags for this command are :
- ownerdrawflag UI_SHOW_LEADER - is true if you are the team leader.
- ownerdrawflag UI_SHOW_NOTLEADER - true if you are not the team leader.
- ownerdrawflag UI_SHOW_FAVORITESERVERS - true if you are on a server in your Favorites list.
- ownerdrawflag UI_SHOW_ANYNONTEAMGAME - true if you are playing a non-network nonteam game like FFA.
- ownerdrawflag UI_SHOW_ANYTEAMGAME - true if you are playing a non-network team game.
- ownerdrawflag UI_SHOW_NEWHIGHSCORE - true if you have the new high score in a skirmish game.
- ownerdrawflag UI_SHOW_DEMOAVALIBLE - true if a valid demo file is in the Demos folder.
- ownerdrawflag UI_SHOW_NEWBESTTIME - true if you have the new best time in a skirmish game.
- ownerdrawflag UI_SHOW_FFA - true if game type is FFA.
- ownerdrawflag UI_SHOW_NOTFFA - true if the game type is not FFA.
- ownerdrawflag UI_SHOW_NETANYTEAMGAME - true if you are playing any team game on a network.
- ownerdrawflag UI_SHOW_NETANYNONTEAMGAME - true if you are playing a nonteam game on a network.
- ownerdrawflag UI_SHOW_NOTFAVORITESERVERS - true if you are playing on a server not in your Favorites list.
Multiple ownerdrawflag commands can be used in an item and the flag results will be anded together to determine visibility.
This completes those item commands that are general purpose in nature. The rest of the item commands that are avalible are used to supply information to different types of items than the default ITEM_TYPE_TEXT type.
