Quake III: Team Arena Menu Files: itemDef { ... }

5. itemDef { ... }

An itemDef describes on item member of a menu. The following keywords are recognized inside an itemDef:

Sets a name for the item. Manipulation of an item is done through its name. Names can correspond with a menu name, but since actions are carried out based on matching names, this could be used to create both awesome effects and terrible side-effects.

5.2 text [string]

Use the provided string as a text to display

Programmer's (mod) note: This item largely corresponds to "label" items of other GUIs).

5.3 group [string]

Sets a group name for the item. This grouping also allows the manipulation of many items simultaneously (such as hiding the radio buttons together).

Programmer's (mod) note: Primary use is in implementing radio buttons (where selecting one button in the group deselects all others in the same group).

See also: `itemDef::name', `menuDef::name'.

5.4 asset_model [string]

Displays a Q3A model. The provided string indicates the path name of a model to display. View the pk3s to see the expected path names.

5.5 asset_shader [string]

Apparently not used (ineffectual).

5.6 model_origin [float] [float] [float]

Apparently not used (ineffectual).

5.7 model_fovx [float]

Field-Of-Vision along the screen's X (horizontal) axis. Affects horizontal (left-right) "stretchiness". Units are degress, 90 is "normal", lesser values cause "stretching out", greater values cause "shrinking". Most monitors have an aspect ratio of 4:3, so this value should be 3/4 of model_fovy (3 * fovx == 4 * fovy).

5.8 model_fovy [float]

Field-Of-Vision along the screen's Y (vertical) axis. Affects vertical (up-down) "stretchiness". Units are degress, 90 is "normal", lesser values cause "stretching out", greater values cause "shrinking".. Most monitors have an aspect ratio of 4:3, so this value should be 4/3 of model_fovx (3 * fovx = 4 * fovy).

5.9 model_rotation [int]

Model rotation rate. Units is number of milliseconds to wait before rotating model by 1 degree (i.e. milliseconds per degree). Value of zero disables rotation. (thanks thnom)

5.10 model_angle [int]

View model from a fixed angle (angle around Z-axis, i.e. on X-Y plane). If model_rotation is non-zero, this value acts as the base (starting) angle for rotation. XXX: what does 0 mean? head-on?

5.11 rect [rect]

Defines a rectangular area within a menu. The item's rect is positioned relative to the menu's rect; i.e. the menu's rect acts as a "mini-screen" for the coordinates of item rect. This shifting eases the relocating of menus; menus can be moved without having to recalculate the positions of its items. The size of a "unit" is the same as that used by the menu; i.e. no squishing-into-the-rect. x = 640 still means move 640 "pixels" over to the right, even if off-screen.

5.12 style [int]

Fill style of the rect. Values are listed in Values for ``style''. Vaejor's earlier tests had Q3 crashing when the value was 5 (WINDOW_STYLE_CINEMATIC); the reason was that no RoQ file was provided in a `cinematic' field.

5.13 decoration

Presence of this keyword declares whether this item is a decoration item or not. Non-decoration items would be hotspots, buttons, sliders, etc., items that cause actions to happen. Decoration items would be menu border graphics, logos, animation boxes, etc.

SweetnutZ points out that anything without this keyword will make mouseover sound and other assorted things.

5.14 notselectable [int]

Makes a List Box element unselectable. Used to make List Boxes display only.

5.15 wrapped

Enforces manual text wrapping of the text provided in the `text' field. The two-character sequence ``\r'' (backslash, r) causes a manual and forced wrap (newline) in texts.

SweetnutZ provides an example:


  autowrapped
  text "here is line one of the text\r"
       "here is line two of text\r"
       "here is line three, etc etc etc"

5.16 autowrapped

Enforces auto-wrapping of the text provided by the `text' field. This keyword causes the text to automatically wrap to fit within the rect.

5.17 horizontalscroll

Makes a List Box scroll horiziontally rather than vertically. Only applicable if the List Box is displaying graphical elements.

5.18 type [int]

Sets the item type. If not specified, the default is ITEM_TYPE_TEXT. See also: Values for item ``type''.

5.19 elementwidth [float]

Related to the width of elements inside an image listbox. SweetnutZ points out that Q3 head icons are 32 pixels wide, so ``elementwidth 32;'' would be used for an image listbox of Q3 head icons.

5.20 elementheight [float]

As with `elementwidth', but with element height.

5.21 feeder [float]

The game builds many types of lists internally (so that it may be re-updated, sorted, modified, etc.). Feeders provide a hook to this internal list for the menu system. Items that use feeders have a list that reflect this internal list. The specific internal list to use is indicated by the given parameter.

Items that use a feeder are specially flagged to follow their selection. That is to say, when you select an object in the list, the internal list "learns" which item you have just selected. This maintains the parallel of states between the internal list and the list presented by the menu system.

SweetnutZ verifies the linking into the game code for listbox data, but I'm still stumped on the use of a float, instead of int.

5.22 elementtype [int]

Specifies the type of element in a listbox, either text ("LISTBOX_TEXT", 0) or image ("LISTBOX_IMAGE", 1).

5.23 columns [int] [int] ...

First integer is the number of columns. Following that are sets of three integers, one set for each column just mentioned. Each set of three integers consists of the following:

offset from the left of the item rect in pixels.
width of graphic if not text context (use 0 otherwise). Used only in HUD.
maximum number of characters to display at a time.

5.24 border [int]

Sets a border style for the item.

5.25 borderSize [float]

Sets the thickness of the border. The border is drawn on the inside of the item rect.

5.26 visible [int]

Sets the visibility of the item. "0" prevents it from being drawn, "1" (or any other value) causes it to be drawn.

5.27 ownderdraw [int]

Like the menu's ownerdraw, this statement makes a request to the Q3A engine to draw something within the item rect.

5.28 align [int]

The only uses found for this have been in the default HUDs, in conjunction with the CG_AREA_POWERUP ownerdraw. The two known values are 0 (HUD_VERTICAL) and 1 (HUD_HORIZONTAL). These affect the way multiple powerups are drawn, whether vertically (aligned to the bottom, sorted in sequence of remaining times) or horizontally (from left to right?).

5.29 textalign [int]

Determines where the horizontal alignment point is applied to text. Values are:

0 ITEM_ALIGN_LEFT: Left side of text.
1 ITEM_ALIGN_CENTER: Center of text.
2 ITEM_ALIGN_RIGHT: Right side of text.

5.30 textalignx [float]

Horizontal text alignment in pixels (of 640 max) from left edge of rect to alignment point of text.

5.31 textaligny [float]

Vertical text alignment in pixels (of 480 max) from top edge of rect to bottom of text.

5.32 textscale [float]

Scale the text size. A scale of 1.0 is 48 pixels tall (1.0 = 48, 0.5 = 24, 0.25 = 12, 0.2 = 10; textscale = height / 48).

This statement has special effects on certain ownerdraws. The known ones with such special effects are CG_PLAYER_AMMO_VALUE, CG_PLAYER_HEALTH, and CG_PLAYER_ARMOR_VALUE. Each of these show a plain number if textScale is less than 0.75. Otherwise, they show a "full-size" element of a fixed size:

CG_PLAYER_AMMO_VALUE: 128x48 box showing all available ammo types and counts
CG_PLAYER_HEALTH: 128x24 horizontal graphical bar indicating health level.
CG_PLAYER_ARMOR_VALUE: 128x24 horizontal graphical bar indicating armor level.

5.33 textstyle [int]

Specifies a special effect to the text.

5.34 backcolor [color]

Sets background color for the item when `style' is set to WINDOW_STYLE_FILLED.

5.35 forecolor [color]

Sets foreground color for the item. Most prominent use is setting text color, although it also influences the color of any alpha-valued images.

5.36 bordercolor [color]

Sets border color.

5.37 outlinecolor [color]

This keyword works with text listbox. The selected text is highlighted with the given color. However, the outlining is done by drawing a box over the selection with the given color, so the best course of action is to use a very transparent color, such as "1 0 0 0.25".

5.38 background [string]

Provided string is taken as a shader name or image file to display as the item's background, confined within the item rect.

Rect's `style' has to be set to WINDOW_STYLE_SHADER. The background image is scaled, ignoring aspect ratios, to fill the rect. In other words, the image is distorted as needed to fill the rect completely. See also menuDef background.

5.39 onFocus { [script] }

The given script is run when the item gets focus. This happens when the mouse rolls over it, the keyboard is used to move over to it (arrow keys), or focus is forcefully thrust upon it by another script.

5.40 leaveFocus { [script] }

The provided script is run when the item loses focus. Note that when a menu closes, its last focused item runs its `leaveFocus'.

5.41 mouseEnter { [script] }

Runs the provided script when the mouse enter the item's rect.

5.42 mouseExit { [script] }

Runs the provided script when the mouse leaves the item's rect.

5.43 mouseEnterText { [script] }

Runs the provided script when the mouse touches text in item.

`itemDef::type', ITEM_TYPE_BUTTON, `itemDef::mouseExitText', `itemDef::mouseEnter', itemDef::mouseExit', Script actions.

5.44 mouseExitText { [script] }

Runs the provided script when the mouse leaves text in item.

5.45 action { [script] }

Runs the provided script when the mouse clicks in/on the item rect or when the Enter key is pressed while item has focus.

5.46 special [float]

Used in the HUD to set spacing on powerup item display.

5.47 cvar [string]

This keyword indicates a cvar to alter, with the various ways of altering indicated in other statements (e.g. cvarFloat, cvarStrList, cvarFloatList, etc.)

For use in assigning keybinds, `type' has to be set to ITEM_TYPE_BIND, the `text' field holds the prompt (e.g. "Move forward:"), and `cvar' is the command to assign (e.g. "+forward").

5.48 maxChars [int]

Maximum number of characters in an editfield.

5.49 maxPaintChars [int]

Maximum number of characters to show in an editfield.

5.50 focusSound [string]

Sound to play when item receives focus.

5.51 cvarFloat [string] [float] [float] [float]

Set a cvar to a float value. The values correspond to:

Cvar name
Default value
Minimum value
Maximum value

This has commonly appeared in association with slider bars ("type ITEM_TYPE_SLIDER"). Best guess is that the lesser (left) extreme of the slider is assocated with ``minimum'', the greater (right) extreme associated with ``maximum'', and the starting position of the slider at ``default''.

5.52 cvarStrList { [string] [string] < [string] [string] < [string] [string] ... > > }

Used in Multi item (ITEM_TYPE_MULTI) to rotate through a list of values. Rotation occurs when the item is clicked (i.e. selecting). The strings are provided in pairs. The first of the pair is the string to display in the item when the pair is selected. The second of the pair is the string to store in the cvar.

The cvar specified by `cvar' is used to store the second value of the selected pair.

Example:


cvarStrList { "Lightmap", "0", "Vertex Lighing", "1" }

This example would rotate between two values. The strings "Lightmap" and "Vertex Lighting" are shown, while the actual values "0" and "1" are assigned.

5.53 cvarFloatList { [string]

Works on the same principle as cvarStrList, except it stores float values instead of strings.

5.54 addColorRange [float] [float] [color]

Values are:

Low
High
Color value (RGBA)

Applies to ownerdraw elements that have an ``obvious'' numerical value, such as health, armor, and scores. This keyword allows the ownerdraw element to be displayed in different colors depending on its numerical value. If the numerical value falls within ``low'' and ``high'' (inclusive), the item uses the (foreground) color that is listed. There can be as many uses of this statement as needed to cover the appropriate range of values, up to a hard limit of 10. After 10, additional uses are ignored. Note that this hardlimit can be changed in mods by mod authors. If any ranges overlap, the range listed later takes precedence.

Usage is best described by an example.


itemDef {
  ownerdraw CG_PLAYER_HEALTH;
  addColorRange -999 24 1 0 0 1  //Red
  addColorRange  25 100 0 1 0 1  //Green
  addColorRange 101 999 1 1 1 1  //White
}

The above draws the player's health. If the health value is within -999 to 24 (inclusive), the health value shows in red. If the health value is within 25 to 100 (inclusive), the health value shows in green. 101 and above (and up to 999), the health value shows in white.

5.55 ownerdrawFlag [int]

Asks for a flag value (true/false) from the Q3A engine, and shows (on "true") or hides (on "false") the item based on the value. If the item was already invisible ("visible 0"), this item is not drawn regardless of ownerdrawFlag. Values for ownerdrawFlag are listed in Values for cgame ``ownerdrawFlag''

Next Previous Contents