Sfairadora

  • Reference Guide

Line Editor

The line editor is used to enter values represented by a single line text. It is typically used for strings and numbers, but it can edit values of any other type. A standard type conversion mechanism is used to convert a general type into the displayed string and vice versa. Should this standard solution be inappropriate in a particular situation, you can specify a setter and getter function as explained further on. The setter function may also be employed to check the validity of the entered value.
The use of the line editor is explained in a separate chapter.

Display

Item
Description
Alignment
Alignment of the content if the editor is wider than its content. The options are: left, center, and right, or you can leave the auto option in place.
Auto alignment adopts the alignment assigned to the table column if the editor is in a table. If alignment cannot be determined this way, then it depends on the data type. Numeric types are right-aligned whereas all other types are left-aligned.
Number precision
Determines the number of displayed decimal places when a real number is being edited. For time (Time) values, this setting determines whether seconds and minutes are displayed and their precision. The setting is ignored for all other types.
Group digits
If checked, numbers are displayed with digits divided into groups per three. The thousand separator symbol specified in the Symbols section of the document settings is used to delimit the digit groups.
Spin buttons
If checked, two buttons are displayed on the right side of the line editor with an upward and downward arrow respectively. If the line editor edits a number, the buttons can be used to increase and decrease its value.
Spin expression
This field is available if the Spin buttons option is checked. It allows you to specify an Enki language function used to increase or decrease the value when the spin buttons are clicked.
If no spin expression is specified, the spin buttons can be used only for numbers. Then, one click produces an increase or decrease by 1. If you need a different functionality, you have to specify a function.
Function parameters:
val
present value in the editor. The value type is the same as the type of the edited data.
increase
a Bool type value. If TRUE, the edited value is to be increased; otherwise it is to be decreased.
count
number of repeated calls of the spin function during a single click on the spin button. This value can be used to accelerate increasing/decreasing of the value if the spin button is held down for a longer time. The default behavior is first to increase/decrease by 1, and after twenty steps by 5.
Example: Suppose you have a line editor editing a real number (Real type). You want the spin buttons to change the value by 0.01 and, after some time, to accelerate the increment to 0.05. To do so, set the spin expression to:
var Real step = if(count<20) 0.01 else 0.05;
if(increase)
val + step
else
val – step
Other
Frame Style
Appearance of the editor frame:
none
no frame
simple
simple line (usually black; the color depends on Windows settings).
deep
three-dimensional frame that appears sunken (the standard appearance of a field for editing in Windows).
auto
the frame depends on the editor location.
Borders
The spaces left between the frame and the editor content. Values for all directions can be specified individually. If no value is specified, borders are determined automatically according to the editor location.
Background
Background color. You can choose between white and gray. However, the actual colors depend on Windows settings. If you leave the auto option in place, editors with disabled editing will be gray while the usual case will be white.

Functionality

Item
Description
Object name
Name of the object where the edited data is located. You can select one of the objects provided by parent dispels.
Data reference
Reference to a data item within the above identified object.
The identified data must be scalar, or else the editor displays an error. The line editor may in principle edit non-scalar data as well, but this is usually impractical. Moreover, there is a danger that the text representation of the data will be too long, and data display will take an inadequate amount of time. If you need to edit non-scalar data, you must specify a getter function as described below, e.g. as [String]val (that is, as an explicit type conversion of the value into a string).
Other
Data type
The data type that should be saved by the editor into the respective data item. Usually, it need not be specified – it is determined automatically from the actual type of the edited data item. However, if the type of the edited data item is Union, it may be necessary to specify the value type to be saved by the editor.
Getter function
This function is used to convert edited data to a string that is to be displayed in the editor and edited. If no function is present, standard type conversion is used.
The function is specified in the Enki language.
Function parameters:
val
the value to be edited. Its type corresponds to the edited data item type. If data is absent, the NONE value is passed.
precision
an integer number – editing precision of the number. The value is received from the setting described above. Often, it is insignificant for the function and can be ignored.
Result type: String or Rich_string, depending on the setting of the Non-formatted text option described below.
Setter function
This function is used to convert the edited string to a value that is to be saved into the edited data item. If no function is present, standard type conversion is used.
The function is specified in the Enki language.
Function parameters:
val
value of the String or Rich_string type, depending on the setting of the Non-formatted text option described below. The content of the line editor that should be saved.
precision
see the getter function.
Result: the value to be saved into the data item. If the result type fails to match the type of the data item in which it should be stored, a type conversion is performed. If the function returns the NONE or NOT_PRESENT constant, and the edited data item is optional, its value is removed. If the function returns the Error type, the error message contained in the error is displayed. The editing does not end until the user corrects the error. This feature can be used to test validity of the entered value.
Example: suppose you wish to create an editor of a real number whose value should be between 0 and 100. Create the following Enki language setter function:
var Real r = [Real]val;
if(r<0)
error("the value must not be lower than 0");
if(r>100)
error("the value must not be higher than 100");
return r
Storing value
This option determines when the data edited by the editor is saved into the data item.
on end of editing
the value is saved when editing ends.
by spin button
the value is saved when editing ends and every time the user clicks a spin button.
on every change
the value is saved upon every modification. However, if an error occurs during saving (e.g. a setter function error), the value is not saved, and the error message is not displayed until the user attempts to end the editing.
Non-formatted text
If checked, only plain text (String type) is edited, that is, its formatting cannot be changed. If unchecked, formatted text (Rich_string) is edited. If neutral, the editing mode depends on the edited data – formatted text is used for the Rich_string type, and unformatted text for all other types.
Maximum number of characters
The maximum number of characters that can be typed into the editor.
Trim spaces
If checked, all leading and trailing blanks are removed before the string is saved or passed to the setter function.
Find text for value
This option is significant only if the line editor is immediately included in a disp‑folder whose external presentation (menu) contains a value selector. In this situation, the string is first looked up in the value selector titles before it is converted to a value by means of a standard conversion. This process assigns a value to the text. In other words: if there is a menu in the line editor for value selection, the value can be either selected from the menu or specified by entering the value title.
If the option is checked, the lookup works also the other way round – the value is looked up in the value selector and the respective title is returned and displayed instead of the value.
Enable value without text
This option is available only if Find text for value is checked. Checking this option allows the user to enter values other than the titles existing in the respective value selector.
Disable closing volatile window
If the editor is in a menu window or in another volatile window, and the option is checked, the window is not closed when editing ends (normally, it is closed).
Definition type: Line_editor_def