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.

Properties Shared with All GuiDef Types

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

Video Brightness Example - of a Numeric CVar, Shared with a Slider

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