GUI Scripting: EditDef
This page is part of a series. See GUI Scripting Language for overview.
Introduction
An editDef provides a data-entry field. Three use cases are prominent.
- For a Single-Line String Value. TDM uses this to get a new name when saving a game (in mainmenu_loadsave.gui). In this case, the editDef uses the "maxChars" property to limit the string length, and an onEnter event handler to save the game under the entered name.
- For a Numeric CVar, Shared with a Slider. Under Settings/Video, there are four sliders. Moving any of these sliders will change the numeric value shown to its left, in a central column. Conversely, since that value is shown with an editDef, you can edit the value and the change affects the slider. Both the editDef and sliderDef use the "cvar" property, to specify the CVar through which value synchronization occurs. This is discussed further in the Example below.
- For General, Multiline Text. There is a capability to do general text editing of a word-wrapped field with scroll bar. TDM does not use this; perhaps Doom3 multiplayer chat did?
After you set your focus into the editDef field, the usual text-editing keystroke handling is supported. Among notable features:
- Backspace and (Linux-friendly) Ctrl+h: Delete a character to the left of the cursor
- Insert key: Toggles character overwrite mode, with the cursor changed to a vertical bar.
- Ctrl+leftArrow: Skip left to previous word as delimited by spaces.
Other editing keys as routinely expected:
- Left arrow: Move left
- Right arrow: Move right
- Home key: Move to start of line
- End key: Move to end of line
For editing keys related to multiline editing, see "Additional Notes" below.
Many keys will invoke the editDef's event handlers (if defined):
- Any key press that changes the actual displayed text: onAction.
- Any key release (including cursor-movement keys): onActionRelease.
- Enter key, or Keypad Enter
- if wrap not enabled: onEnter (as well as onAction).
- if wrap enabled for multiline: treated as line break.
- Escape key: onEsc.
A editDef will make use of Properties in common for placement and to style the presentation of its text. User variables were not seen in practice. Event handlers were mentioned above.
Additional Properties of EditDefs
® = 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.
EditDef Properties – Used in TDM Core
Cvar "name" ®
Defines the editDef's bound Cvar, whose value should be numeric.
cvar "r_postprocess_brightness"
Maxchars number
Maximum number of characters that can be typed.
maxchars 32 // As used in mainmenu_loadsave.gui to limit name of saved game.
EditDef Properties – Not Used in TDM Core
Cvargroup "group_name"
Makes this editDef part of a named group of controls that can be updated by a single read or write command. Within the GUI, sliderDefs 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, which is never the case in TDM 2.10. For more, see the updategroup description under GUI Scripting: ChoiceDef.)
Forcescroll bool
If 1 (true), forces the control to scroll to the bottom when first drawn. Default: 0 (false).
forcescroll 1
Liveupdate bool
This Property is also available for choiceDefs and sliderDefs. 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 had "Done" and "Cancel" buttons, you might use:
liveupdate 0
Numeric bool
If 1 (true), this control only accepts numbers. Specifically only digits 0..9 and ‘.' are acceptable. Does not support negative numbers. Default: 0 (false).
numeric 1
Password bool
If 1 (true), the control displays asterisks (***) rather than the text. Default: 0 (false).
Readonly bool
If 1 (true), text is non-editable. Default: 0 (false).
readonly 1
Source "file_path"
File to read the initial text from.
Wrap bool
If 1 (true), text larger than the width of the control is wrapped, and a scroll bar (slider) is created if the text goes beyond the height. For multi-line text. Default: 0 (false).
wrap 1
On the Settings/Video/General page, there are four rows with sliders and associated displays of their values using editDefs. For these cases, the CVar binding alone was sufficient; no event handlers (associated with editDef value changes) were deployed. Note that the CVar must be a float (not excluding negative values), and will itself reject an attempt at alpha character entry.
Let's take "Brightness" as a representative row. This GUI snippet involves a single row with 3 columns:
- Column 1: A prompt for the field name, in a windowDef
- Column 2 (but the last guiDef in our code here): An editDef "Brightness Value" with the numeric value, held in a cvar, "r_postprocess_brightness".
- Column 3: A slider that can also be used to manipulate the cvar, and composed of:
- a windowDef with the slider's background (range-bar and tic-marks);
- the sliderDef itself.
The CVar binding alone was sufficient in these cases; no event handlers were deployed. Note that the CVar must be a float (including negative), and will itself reject an attempt at alpha character entry.
Assume that common macros like SETTINGS_FONT are already defined. Then, within a parent windowDef for the whole page, the relevant Brightness snippet is:
...
windowDef SettingGeneralVideoText6
{
rect TEXT_X_OFFSET, 102, 230, MM_LINE_H
text "#str_02155" // Brightness
SETTINGS_TEXT
}
...
windowDef BrightnessSlider
{
rect SETTINGS_X_OFFSET-1, 108, 128, MM_SLIDER_H
background "guis/assets/mainmenu/buttons_settingsmenu/slider_bg"
matcolor 0, 0, 0, 1
noevents 1
}
sliderDef Brightness
{
rect SETTINGS_X_OFFSET-1, 109, 71, 8
forecolor 0.8, 1, 1, 1
matcolor 1, 1, 1, 1
low 0.5
high 2.0
step 0.1
thumbShader "guis/assets/mainmenu/buttons_settingsmenu/slider_bar1"
cvar "r_postprocess_brightness"
// Not shown in this example: onMouseEnter & onMouseExit event handling for secondary window & tooltip
}
editDef BrightnessValue
{
rect SETTINGS_X_OFFSET-71, 102, 71, MM_LINE_H
forecolor SETTINGS_FONT_COLOUR
cvar "r_postprocess_brightness"
font SETTINGS_FONT
textaligny 2
textscale SETTINGS_FONT_SCALE_SLIDER
}
...
Additional Notes
Implementation Oddities
From a usability perspective, the coupling between a sliderDef, editDef, and Cvar could be improved. For example, it would be desirable to enforce, at the Cvar itself, a minimum, maximum, and step value, all floats, and have that propagated to sliderDef and editDef behavior. That would solve problems with entering (in the console or the editDef) a value that exceeds the slider bounds. And would fix the problem with mouse sliding causing ugly spurious-precision values.
The keypad is generally ignored as a source of edit keystrokes. And odd to have skip-word leftwards and not skip-word rightwards.
Another Single-Line String Example
The TDM code contains one other example of a single-line entry form, leftover from Doom 3 multiplayer, to solicit a server password from the player. As background, Doom 3 developed its own OS-independent form of message box, with layout defined in msg.gui. The message box can be drawn in various enumerated styles, many of which TDM uses. The MSG_PROMPT style is the one that employs an editDef to get a password. Since TDM is single-player, the code that invokes this is unused.
Additional Editing Keys for Multiline Text
Besides what was mentioned in the Introduction, multiline text can use these additional editing keys:
- Ctrl+Home: Move to start of text
- Ctrl+End: Move to end of text
- Down arrow: Move cursor vertically down in text
- Ctrl+down arrow: Scroll down
- Up arrow: Move cursor vertically up in text:
- Ctrl+up arrow: Scroll up
