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.

Features Shared with All GuiDef Types

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"
}
...