Geep: Add category tag

2022-11-04T17:42:13Z

Add category tag

← Older revision		Revision as of 17:42, 4 November 2022
Line 146:		Line 146:
	* Up arrow: Move cursor vertically up in text:		* Up arrow: Move cursor vertically up in text:
	* Ctrl+up arrow: Scroll up		* Ctrl+up arrow: Scroll up

			{{GUI}}

Geep: /* Additional Properties of EditDefs */

2022-10-14T16:01:03Z

Additional Properties of EditDefs

← Older revision		Revision as of 16:01, 14 October 2022
Line 31:		Line 31:

	==Additional Properties of EditDefs==		==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.		® = 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===		===EditDef Properties – Used in TDM Core===

Geep: /* Introduction */

2022-08-10T20:39:55Z

Introduction

← Older revision		Revision as of 20:39, 10 August 2022
Line 3:		Line 3:
	An editDef provides a data-entry field. Three use cases are prominent.		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 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.		* '''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?		* '''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?

Geep: create this article

2022-08-10T20:37:53Z

create this article

New page

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.
* '''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 [[GUI Scripting: Properties in Common | Properties in common]] for placement and to style the presentation of its text. [[GUI Scripting: User Variables | 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.

===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

GUI Scripting: EditDef - Revision history

Geep: Add category tag

Geep: /* Additional Properties of EditDefs */

Geep: /* Introduction */

Geep: create this article