GUI Scripting: SliderDef
This page is part of a series. See GUI Scripting Language for overview.
Introduction
A sliderDef is a menu component that allows the user to select the value of a particular attribute by moving the "thumb" (i.e., movable element) of a slider. The sliderDef is only responsible for drawing the thumb. The other visual aspects of the slider - span and tic marks - are provided by a separate windowDef drawn behind the sliderDef. Similarly, the text prompt is separate.
To select a sliderDef of interest, first hover over it, which will brighten the thumb. Then use left mouse button (LMB) to select it, which will further highlight the thumb and - given the click location - jump the thumb to a valid location. You can also drag the thumb with the LMB to a new location.
Alternatively, use the left/right arrow keys, or the keypad left/right arrows. Each press will move the slider one "step". (Since TDM uses only horizontal sliders, this is fine. If you were to implement a vertical slider, the same keys are used, so apply less obviously. Also, RMB clicks can be used to step the TDM slider, but buggy code moves the thumb in just one direction.)
In TDM practice, the changed value takes effect immediately. This change will propagate to a designated cvar, followed by invocation of an appropriate engine command if needed. This cvar, like all cvars, can be manipulated in the console and is persisted to Darkmod.cfg.
Of the Properties in common, a sliderDef routinely sets rect and matcolor. Further, forecolor can filter the color tint of the slider thumb when not in active use; it is overwritten by hovercolor.
User variables were not seen in practice.
SliderDefs can take event handlers, in cases where just changing a cvar is not enough. For examples, see the "sliderDef objectivesSize" in mainmenu_settings_guisize.gui, as well as mainmenu_settings_video.gui's various sliderDefs.
Tool tips (implemented by event handlers) are provided for a number of choiceDefs and sliderDefs. See GUI Scripting:Tooltip Macro for more.
Additional Properties of SliderDefs
® = A property known as a "register", that can be altered at runtime by binding it to a GUI:: parameter, or in a "set" or "transition" script command. Other properties cannot be so altered, nor appear within event handlers.
Defining a Horizontal Slider and its Cvar
Cvar "cvar_name" ®
Defines the cvar that the sliderDef is bound to. A valid value of the cvar determines the initial slider position, and subsequent slider changes propagate to the cvar.
High float
The upper boundary for the slider and its cvar value. Default: 100
Low float
The lower boundary for a slider and its cvar value. Default: 0
Step float, or Stepsize float
The interval that the slider will move. In particular, the amount to change when the arrow keys are used. Default: 1
Thumbshader "path_to_mtr"
Material to use for the slider's thumb element (the part that moves).
Other Slider Def Properties
Liveupdate bool
This Property also available for editDefs and choiceDefs. If set to 1, the cvar is changed as the text is changed, and the text changes as the cvar changes. Otherwise only changes when "cvar read group_name" or "cvar write group_name" is sent. This is always initialized to 1 (true) in TDM's classes for choiceDef, editDef, and sliderDef, and never seen to be changed explicitly thereafter in any GUIs. Speculatively, if you wanted to design menus that used that had "Done" and "Cancel" buttons, you might use:
liveupdate 0
Scrollbar bool
Is this slider used as a scroll bar? Default is 0 (false). Not currently used in TDM core GUIs.
scrollbar 1
Vertical bool
Should the slider go up and down instead of left and right? Default is 0 (false). Not currently used in TDM core GUIs.
vertical 1
Verticalflip bool
Presumably, for a vertical slider, puts the high value at bottom and low value at top.
Cvargroup "group_name"
Makes this sliderDef part of a named group of controls that can be updated by a single read or write command. Within the GUI, editDefs and choiceDefs may also be part of the group. Note that for choiceDefs, that assignment is done with updategroup "group_name".
(This tagging is presumably designed to be used with controls for which liveupdate is false. While a number of TDM main menu controls are tagged with groupname "render", these same controls all have liveupdate of true. Thus it's likely that the tagging is leftover and unused. For more, see the updategroup description under GUI Scripting: ChoiceDef.)
Audio Volume Example
This is a fragment from mainmenu_settings_audio.gui, related to the slider for audio volume. The windowDef draws the background panel, and the sliderDef atop it gets the user's setting, from -40 to 0. That value is passed on to the particular cvar to which the slider is bound (namely, "s_volume_dB"). Any value change is handled by the cvar processing.
...
windowDef VolumeSlider
{
rect SETTINGS_X_OFFSET, 40+TT_OFFSET_Y, 128, MM_SLIDER_H
background "guis/assets/mainmenu/buttons_settingsmenu/slider_bg"
matcolor 0, 0, 0, 1
noevents 1
}
sliderDef Volume
{
rect SETTINGS_X_OFFSET, 40+TT_OFFSET_Y, 71, 8
forecolor 0.8, 1, 1, 1
matcolor 1, 1, 1, 1
low -40
high 0
step 1
thumbShader "guis/assets/mainmenu/buttons_settingsmenu/slider_bar1"
cvar "s_volume_dB"
}
...
