May 8, 2006 Updates
Fadein and Fadeout commands
If you have ever tried to use the Fadein and Fadeout commands to create a menu effect you probably were dissappointed. While the idea of being able to fade out one menu and fade in another is great, in practice it didn't work. Only certain types of items were affected by fading and Fadein doesn't work correctly even then unless the item's foreground color had an alpha of 0 when starting the fade in.
While developing a menu system for a Quake 3 based game, I wanted to use these commands to fade portions of a menu in and out to give it a Doom 3 menu effect. To achieve this I extended the scope of Fadein and Fadeout so they worked with all types of items rather than just the few that they normally affect.
A few steps must be followed for this to work correctly. First of all, you must explictly define the foreground color for an item being faded. If you don't use the forecolor command in an item the foreground color is set by default to white but in order for fading to work properly you must now add the command forecolor 1 1 1 1 to those items. This is only required for items that are to be faded.
Secondly, to fade in items you first must set their foreground alpha to 0. The correct way to do this is to use the new script command clearAlpha. This command is used as follows :
clearAlpha <name> ;
where <name> is the item name or a group name. By using this command before using Fadein you will properly clear the foreground alpha of the item(s) and, more importantly, allow List Boxes to fade in correctly. An example of this is as follows :
onOpen
{
clearAlpha box ;
fadein box ;
}
This will fade in all items in the group named box, regardless of the item type, when the menu is opened.
CvarStrBoxList command
The CvarStrBoxList command is used in the dropdown combo box item to define the display string and cvar string pairs, as explained here. There is a problem with this command if you want to enclose both strings in quotes, which you would do if the display string contained a space in it. For example doing this :
CvarStrBoxList { "Quake III Servers" "baseq3" "Team Arena Servers" "missionpack" }
will cause the program to crash, even though everything looks okay. The correct way to do this is to separate each string with a comma rather than a space, like the following :
CvarStrBoxList { "Quake III Servers","baseq3","Team Arena Servers","missionpack" }
You must also place the entire command on one line, rather than spacing it over multiple lines as was done in the Combo box example.
Combo Box action
The dropdown combo box has been modified slightly so the action script is only executed if you make a selection in the dropdown list. Previously, the action script was run any time the combo box item was clicked on.
List Box action
The scrolling List Box has been modified so clicking on the scroll bar or scroll arrows does not cause the action script to be executed. The action script is run only when you click on an item in the list.
May 8, 2006 New Features
clearFocus command
A new script command, named clearFocus, is used to remove the focus from all items in a menu. This can be useful at times, especially when reopening a menu, so an item does not retain the focus from a previous activation. It is used as follows :
clearFocus MENU_TRUE ;
An example is :
onOpen
{
clearFocus MENU_TRUE ;
}
which will remove the focus from all items when the menu is opened.
disableFocus and enableFocus commands
During certain menu actions it can be desirable to temporarily stop an item or group of items from being able to receive the focus. The script commands disableFocus and enableFocus are designed to accomplish this. They are used as follows :
disableFocus <name> ;
enableFocus <name> ;
where name is an item name or the name of a group. Once you use disableFocus to stop an item from recieving the focus you must use the enableFocus command on it before it can ever receive the focus again. An example of temporarily disabling an item's focus is as follows :
action
{
disableFocus box ;
}
and an example of re-enabling it is :
action
{
enableFocus box ;
}
It is important to note that once an item as had it's focus disabled it will remain disabled even if the menu is closed and reopened again.
uiScript addelfavorite command
This command is a combination of two other uiScript commands, uiScript addfavorite and uiScript delfavorite. When this command is executed it checks the value of the ui_netsource cvar and, if it set to Internet, adds the current server to the Favorites list. If the value of the cvar is set to Favorite then it deletes the current server from the Favorites list. It is used as follows :
action
{
uiScript addelfavorite ;
}
This command allows a single button to do double duty in adding and deleting favorites.
uiScript update <cvar> commands
There are two new uiScript update <cvar> commands designed to allow the construction of a totally graphical menu system. One is used when selecting the game type when creating a game and the other is used when selecting the server source when joining a game.
Currently, if you want to select the game type when creating a game you must use the ownerdraw UI_NETGAMETYPE command in the selecting item rather than just modifying the ui_netgametype cvar directly. The reason for this is that certain information in the program must be updated after the cvar is modified in order for the change to properly take place. By executing the uiScript update "ui_netgametype" command after changing the cvar value the required information is correctly altered. This allows the use of a dropdown combo box to select the game type as in the following :
itemDef
{
name gametype
group items
type ITEM_TYPE_COMBO
cvar "ui_netGametype"
cvarFloatBoxList { "Free For All" 0 "Duel" 1 "Team Free For All" 2 "Capture the Flag" 3 }
rect 400 135 154 16
align ITEM_ALIGN_LEFT
comboalignx 18
comboaligny 1
combobackcolor .4 .4 .4 1
combotextcolor 1 .75 0 1
combotextscale .22
forecolor 1 1 1 1
textscale .21
textStyle ITEM_TEXTSTYLE_SHADOWED
textalign ITEM_ALIGN_CENTER
textalignx 85
textaligny 12
visible MENU_TRUE
action
{
uiScript update "ui_netGametype" ;
}
}
The same problem exists with the ui_netsource cvar, which is used to select the source for the server list. You must use the ownerdraw UI_NETSOURCE command in the selecting item because certain information must be updated after modifying the cvar. By executing the uiScript update "ui_netsource" command after directly changing the cvar value the required information will be correctly altered. Again, this will allow the use of a dropdown combo box to select the server list source as follows :
itemDef
{
name gamesource
group item
type ITEM_TYPE_COMBO
cvar "ui_netsource"
cvarFloatBoxList { "Local Lan" 0 "Internet" 2 "Favorites List" 3 }
rect 42 238 154 16
align ITEM_ALIGN_LEFT
comboalignx 18
comboaligny 1
combobackcolor 0 0 0 1
combotextcolor 1 .75 0 1
combotextscale .22
forecolor 1 1 1 1
textscale .21
textStyle ITEM_TEXTSTYLE_SHADOWED
textalign ITEM_ALIGN_CENTER
textalignx 85
textaligny 12
visible MENU_TRUE
action
{
uiScript update "ui_netSource" ;
}
}
Transitioning commands
The transition command can be used to create some very nice effects in a menu. It can cause a menu item to change it's position and to alter it's width and height. The biggest problem with this command is there is no way to tell when the transition has ended. While this not a problem in some uses, it can be in others. For instance, if you want a menu to use a transition when you close it (ala Doom 3) you want to wait until the transition is finished before closing the menu. To achieve this a new command named xtransition has been created. It's use is as follows :
xtransition <name> <rectFrom> <rectTo> <time> <amount>
- a simple animation effect that changes the size of any items whose name or group name matches <name>. The other parameters are :
- <rectFrom> - the starting window area of the item in the normal rectangle form of :
- <rectTo> - the ending size of the window area of the item in normal rectangle form
- <time> - the number of milliseconds between size changes
- <amount> - the amount of change in size each time
- This effect continues until all sides of the item window area reach the correct size.
This is identical to the transition command. Where xtransition differs is when the transition ends.
What we want to do after the transition ends is to execute another script. If we are planning to close the menu after the transition is finished then it would be done in a script executed at that time. To do this there are more new commands. The xtransition command can only be used in four different locations - inside the onOpen script, the onEsc script, an item's action script or a List Box's doubleClick script. Depending on where the xtransition command is used we utilize a different command.
If the xtransition command is used in the onOpen script then, when it is finished, the opentransitionend script is executed. This script can contain any of the usual script commands except another xtransition. Doing that will cause an infinite loop that will lockup the program. An example is :
onOpen
{
hide buttons ;
xtransition mainbar 460 260 180 194 460 98 180 208 2 50 ;
clearAlpha exitgraphic ;
fadein exitgraphic ;
clearAlpha logo ;
fadein logo ;
}
opentransitionEnd
{
show buttons ;
}
We hide the items in the group named buttons while the transition is taking place and then show them again when it is done.
If the xtransition command is used in the onEsc script then, when it is finished, the esctransitionend script is executed. Again, this script can contain any of the usual script commands except another xtransition. An example is :
onEsc
{
xtransition mainbar 460 98 180 208 460 260 180 194 2 50 ;
}
esctransitionEnd
{
close credits ;
open main ;
}
This example waits until the transition is done before closing the credits menu and opening the main menu.
If the xtransition command is used in an item's action script or in the doubleClick script then the ontransitionend script in that item is run when the transition ends. This is an important point. Regardless of what item or items are affected by the transition the script that is executed when the transition ends is always the ontransitionend script in the item where the xtransition command was executed. An example is :
action
{
play "ui/sound/buttonclick.wav"
hide playtext ;
xtransition mainbar 460 98 180 208 460 260 180 194 2 50 ;
fadeout exitgraphic ;
fadeout logo ;
}
ontransitionEnd
{
close main ;
open play ;
}
This transition takes place when a button item is clicked on, running it's action script. After the transition ends the main menu is closed and the play menu is opened.
If desired, you can combine transition commands and an xtransition command in one script. This allows transitions on many different items but still gives you an end of transition script. An example :
onOpen
{
playlooped "ui/sound/theme.wav" ;
hide buttons ;
hide movie ;
hide boxback ;
transition movieframe 124 130 270 202 124 130 270 202 2 50 ;
transition movie 142 154 237 153 142 154 237 153 2 50 ;
transition title 60 32 520 52 60 32 520 52 2 50 ;
transition lowerright 460 304 180 176 460 304 180 176 2 50 ;
transition lowerleft 2 390 460 90 2 390 460 90 2 50 ;
transition nofix 500 368 114 80 500 368 114 80 2 50 ;
transition backgraphic 484 311 120 33 484 311 120 33 2 50 ;
xtransition playbar 460 260 180 194 460 98 180 208 2 50 ;
clearAlpha backgraphic ;
clearAlpha movieframecover ;
fadein backgraphic ;
fadein movieframecover ;
hide movie ;
hide movieframe ;
}
opentransitionEnd
{
show buttons ;
show movie ;
show movieframe ;
hide movieframecover ;
}
By using the xtransition command on the last transition to end, the script will be run after all movement is over. Only one xtransition command should be used in a script to avoid running the end of transition script multiple times.
The xtransition command can also be used as a timer to run a script after a certain amount of time. This has uses when you wish to fade out some items and then fade in other items, all in the same menu. Since the fade commands don't run a script when they end you can use the xtransition command to subsitute. The trick here is to create an item that displays a totally transparent graphic like the following :
itemDef
{
name blankbar
style WINDOW_STYLE_SHADER
rect 460 98 280 260
background "ui/graphics/blank.tga"
visible MENU_FALSE
decoration
}
The blank.tga file is totally transparent so it will never show when it is displayed. You could also add the forecolor 1 1 1 0 command to the item to make any graphic transparent. By doing an xtransition on this item nothing will appear on the screen but the end of transition script will still be executed. If the amount of time required to do the transition is matched to the other action you are doing (ie. fading out some items) then a script is run when the action is complete. An example :
action
{
xtransition blankbar 460 98 180 208 460 260 180 194 2 50 ;
fadeout box ;
fadeout apply ;
}
ontransitionEnd
{
fadein advbox ;
fadein advapply ;
}
The speed of the transition done to the blankbar item has been matched to the speed of the fadeout command so they both finish at the same time. Therefore, when the fadeout is complete the ontransitionend script is executed, causing other items to fade in. This technique can be applied to other actions than the fading commands.
There is one last aspect of transitioning that has to be addressed to make it completely usable. While an item is transitioning it is possible to click on it and have it run it's action script. It's also possible to click on another, nontransitioning, item, have it execute it's action script and mess up the transition. What is needed is a way to stop all keyboard and mouse button input while a transition is in progress. The cvar ui_transitionkey has been created to do this. If this cvar is set to 1 then all keyboard/mouse button input is blocked while a transition is happening. By default the cvar is set to 0, allowing keyboard/mouse button input at any time. To set ui_transitionkey to 1 you do the following in a script :
setcvar "ui_transitionkey" 1 ;
