Having looked at basic items in the previous section, we are ready to move on to more advanced items. Much of the information we defined in the basic items is used in the advanced items along with some commands specific to certain item types.
Button Items
By changing the type of a basic item to ITEM_TYPE_BUTTON we can create a menu button that does something when we click on it. The basic item we build the button on can be a graphic or text or a combination of the two. Any of the item commands discussed in the basic item section can be used to create the item. To change the item into a button we must set the item type with :
type ITEM_TYPE_BUTTON
This tells the program that when we click on the item's window area it should run the script defined by the action command. This command is used like :
action { <script> }
where <script> is a series of script commands. See Script Actions for more information.
EditField Items
An editfield item is used to allow the entry of text into the menu, such as setting the player name. It is created by adding this to the item definition :
type ITEM_TYPE_EDITFIELD
Since this item type is based on text you must have all the text related commands defined in the item. The basic item text commands that need defining are :
- text
- textstyle
- textscale
- textalign
- textalignx
- textaligny
Backgrounds and borders can be used, just like in any basic item. If you use the text command to define a text string, like this :
text "Name : "
then the text string will be displayed using the basic text commands and the editfield will be situated 8 pixels to the right of the text. The text entered into the editfield will be displayed in the same size and style as the defined text string.
There are also some other commands that are specific to editfields. These are :
- maxChars <value>
- set the maximum number of characters that can be entered into the editfield to <value>. This can be in the range 1 to 255.
-
maxPaintChars <value>
- set the maximum number of characters that will be displayed in the editfield.
The contents of the editfield is stored in the cvar you must assign to the item using the cvar command. This allows other items and menus (plus the rest of the program) to access the editfield text string. If the cvar contains any data it will be displayed in the editfield when the item is drawn. This allows the default cvar values to be shown and edited plus it saves the editfield text string when the current menu is closed.
Numeric Editfield Items
The numeric editfield item is a variation on the normal editfield item. It is identical in every way except that you can only type numeric values into the editfield. Negative numbers are not allowed. You set the item to be a numeric editfield by adding this to the item definition :
type ITEM_TYPE_NUMERICFIELD
Everything else about the item definition is identical to the editfield item.
Slider Item
Sliders are created by setting the type of a basic item to ITEM_TYPE_SLIDER. The slider is made up from the slider graphics that were defined either by default or in the global assets section. The basic item can be a graphic or text or a combination of the two. If it contains text then the slider graphics will be drawn 8 pixels to the right of the text. It is important to make the item window are large enough to hold both the text (if any) and the slider graphics. By default the slider requires an area of 96x16 (you may have changed this in global assets). If the slider graphic is drawn outside the item window area then you won't be able to move the thumb the full length of the slider.
The slider value is passed from the item using a cvar that is attached to the slider using the cvarFloat command. It has the form :
cvarFloat <cvar name> <default> <low> <high>
where <cvar name> is the name of a cvar, <default> is the value to assign to the cvar if it's value is out of range, <low> is the minimum value of the slider and <high> is the maximum. Therefore the slider will select a value to assign to the cvar that ranges from <low> to <high>. If the cvar has a value in this range then the slider thumb will be drawn to reflect this value when the item is first drawn.
Yes/No Item
When you want to have a simple yes or no choice you can use an item whose type is set to ITEM_TYPE_YESNO. This is a text based item which changes it's value from yes to no and back whenever it is clicked. Since this item type is based on text you must have all the text related commands defined in the item. The basic item text commands that need defining are :
- text
- textstyle
- textscale
- textalign
- textalignx
- textaligny
Backgrounds and borders can be used, just like in any basic item. If you use the text command to define a text string, like this :
text "Free Look : "
then the text string will be displayed using the basic text commands and the Yes/No will be situated 8 pixels to the right of the text.
The Yes/No value is stored in the cvar you must assign to the item using the cvar command. This allows other items and menus (plus the rest of the program) to access the value. A Yes sets the cvar to 1, while a No sets it to 0.
When we click to change the Yes/No value we can make it run the script defined by the action command. This command is used like :
action { <script> }
where <script> is a series of script commands. See Script Actions for more information.
Multi Item
When you have multiple choices to make you use an item whose type is set to ITEM_TYPE_MULTI. This type of item rotates through a list of choices when you click on it. Again, this item type is based on text so you must have all the text related commands defined in the item. The basic item text commands that need defining are :
- text
- textstyle
- textscale
- textalign
- textalignx
- textaligny
Backgrounds and borders can be used, just like in any basic item. If you use the text command to define a text string, like this :
text "Model Type : "
then the text string will be displayed using the basic text commands and the current choice will be displayed 8 pixels to the right of the text.
You define the list of choices using the cvarFloatList command or the cvarStringList command.
cvarStringList <display string> <cvar string> ..... <display string> <cvar string>
where each choice consists of a pair of strings, the <display string> which is what is displayed when the choice is drawn, and the <cvar string> which is what is stored in the cvar attached to the item via the cvar command. The cvarFloatList command is very similar :
cvarFloatList <display string> <cvar value > ..... <display string> <cvar value >
where each choice consists of a string and a value, the <display string> which is what is displayed when the choice is drawn, and the <cvar value > which is what is stored in the cvar attached to the item via the cvar command. The <cvar value> is a floating point number rather than a string as in cvarStringList.
There can be a maximum of 32 choices in a cvarStringList or cvarFloatList command.
When we click to change the choice we can make it run the script defined by the action command. This command is used like :
action { <script> }
where <script> is a series of script commands. See Script Actions for more information.
Model Item
A model can be displayed by using an item type of ITEM_TYPE_MODEL. There are a number of model related commands that are used to specify the model and its positioning.
- asset_model <name>
- where <name> is the path and name of the model you wish to attach to the item.
- model_fovx <value>
- Field-Of-Vision along the screen's X (horizontal) axis. Affects horizontal (left-right) stretchiness. Units are degrees, 90 is normal, lesser values cause stretching out, greater values cause shrinking.
- model_fovy <value>
- Field-Of-Vision along the screen's Y (vertical) axis. Affects vertical (up-down) stretchiness. Units are degrees, 90 is normal, lesser values causing stretching out, greater values cause shrinking.
- model_rotation <value>
- model rotation rate where value is the number of milliseconds to wait before rotating the model by one degree. Rotation is around the Y (vertical) axis. A <value> of 0 disables rotation.
- model_angle <value>
- if the model rotation value is non-zero then <value> is the starting angle for the rotation. Otherwise it is the angle the model is rotated to for viewing.
The model will be displayed centered in the item's window area.
OwnerDraw Item
An item is made ownerdraw by setting the type to ITEM_TYPE_OWNERDRAW. This item is used to ask the program to draw something, based on the value defined by the ownerdraw command which is used like :
ownerdraw <value>
Many ownerdraw values also change when you click on them, allowing you to change the current choice. To see the full list of values see here. The types of things that the program can draw includes text, graphics, movies and models. The item must be setup to include the necessary support definitions for the kind of drawing being done. For example, a text ownerdraw must have the proper text commands in the item.
There is one command that is specific to ownerdraw items.
- addColorRange <low> <high> <red> <green> <blue> <alpha>
- this command is used to alter the item's foreground color based on the value of the ownerdraw command. Most ownerdraw commands have a numeric value associated with them, regardless of what is actually displayed on the screen. For example, the ownerdraw UI_SKILL command has a value that ranges from 0 to 4, even though what is displayed is a text string. With the addColorRange command, if the ownerdraw value falls between <low> and <high> then the foreground color of the item is set to the color defined by <red> <green> <blue> <alpha>. There can be multiple addColorRange commands in an item, each with a different <low> to <high> range, to cover all possible ownerdraw values.
Key Bind Item
The key bind item is used to bind a keystroke to a cvar used by the program to perform an action in the game. It is done by setting the item type to ITEM_TYPE_BIND. This item type is based on text so you must have all the text related commands defined in the item. The basic item text commands that need defining are :
- text
- textstyle
- textscale
- textalign
- textalignx
- textaligny
The action cvar is attached to the item by the cvar command. The description of the keystroke bound to the cvar will be drawn 8 pixels to the right of any defined text.
When this item recieves the focus the status of the keybind is set to not waiting for a key to bind. If you click on the item or press Return then the status shifts to waiting for a key to bind. Another item with a type set to ITEM_TYPE_OWNERDRAW and containing ownerdraw UI_KEYBINDSTATUS can be used to display the actual keybind status.
Listbox Item
The listbox item is used to allow a selection from a list of values. The item is made into a list box by setting the type to ITEM_TYPE_LISTBOX. A list box item can have a colored or graphic background and have borders if desired, just like any basic item.
Feeders
A list box can only show list information from a limited number of lists maintained by the program. You specify what list you are using by use of the feeder command. It is used as follows :
feeder <value>
where <value> determines which list you are specifying. When you attach a feeder to an item, the program tracks which object in the list you have selected and makes this avalible to other items. The program itself maintains and updates the list so you don't have to it manually. The lists you can select by <value> are :
- FEEDER_HEADS
- FEEDER_Q3HEADS
- FEEDER_MAPS
- FEEDER_ALLMAPS
- FEEDER_SERVERS
- a text list of servers found. This sets the info for the current server. This feeder returns 6 columns of information for the item to display :
- Host Name
- Map Name
- Number of Clients
- Game Type
- Ping
- Punkbuster
- FEEDER_SERVERSTATUS
- a text list of the server's players information. This feeder returns 4 columns of information :
- client number
- client score
- client ping
- client name
- FEEDER_FINDPLAYER
- a text list of servers that contain the name of the player you are searching for.
- FEEDER_PLAYERLIST
- a text list of all players in the game.
- FEEDER_TEAMLIST
- a text list of all the teams in the game.
- FEEDER_MODS
- a text list of all avalible mods.
- FEEDER_CINEMATICS
- a text list of all the Roq movies avalible in the video directory.
- FEEDER_DEMOS
- a text list of all avalible demos.
- FEEDER_SAVE
- a text list of all saved games.
Elements
Once you have decided on the feeder to use with the list box you must set the type of object (or element) shown in the list. A list can have either text elements or graphic elements and you set the type using the elementtype command. For text elements you use :
elementtype LISTBOX_TEXT
while for graphic elements you use :
elementtype LISTBOX_IMAGE
In many cases, the feeder will determine the element type, since most feeders return text information. There are feeders, however, that will return either a graphic or text to match the defined element type.
Next you have to define the width and height of each element in the list. If you have graphic elements then the image will be stretched/shrunk to fit the area you define. Text elements only use the element height to space each line in the list. The width and height of each element is set by :
elementwidth <width>
elementheight <height>
For text elements you must make sure that the height is great enough that the lines of text don't overlap. If you have text elements you must set the text size and style using the textscale and textstyle commands.
Selectablity
In some cases you may wish to make it so you can't select any elements in a list box, while still retaining the ability to scroll through the list. To do this include :
notselectable
in the item definition.
Horizontal Scrolling
By default all list boxes are vertical scrolling, with the scroll bar on the right side of the box. However, if you have set the element type to LISTBOX_IMAGE, it is possible to make the list box scroll horizontally. This places the scroll bar on the bottom of the list box. To do this add :
horizontalscroll
to the item definition. This does not work with text element types and nothing will be displayed.
Outline Color
When you have a text element type you can define a color that will be used to highlight the currently selected line in the list box. This color is defined by :
outlinecolor 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. Since the text is tinted with this color by drawing a box of the color overtop of it you must use a fairly transparent color in order to see the text underneath. An alpha of 0.25 seems to work okay.
Columns
Several feeders return more than one piece of text information in each line. To display this properly you must provide column information so that each piece of text is placed correctly on the line. This is done with the columns command use as so :
columns <number> <offset> <width> <max chars> ..... <offset> <width> <max chars>
where <number> is the number of columns being defined. Each column is defined using three values :
- <offset> - the number of pixels from the left side of the list box to the left side of the column.
- <width> - the width and height in pixels of a possible graphic - not currently used.
- <max chars> - the maximum number of characters to display in the column.
If <max chars> is set to 0 then the text in that column will not be displayed.
Double Clicking
The doubleClick command is used to run a script action when the user double clicks on an object in the list. This command is used like :
doubleClick { <script> }
where <script> is a script action. To find out more information on the script commands you can use see Script Actions .
