Sfairadora

  • Reference Guide

Check Box

The check box allows the user to choose between two possible states to a data item. One state is “option checked” and the other “option unchecked”. You can also permit a third state – “option undefined”. It is assumed that the underlying data item is either of the Bool type or of a numeric type. Unchecked option represents 0 (FALSE), checked option represents 1 (TRUE), and undefined option represents a missing value (the data item must be optional). Should you require a different representation, you must specify the getter and setter functions.
The check box looks either like a box that can contain a check mark or like a button that is either pressed or not pressed. The neutral state is graphically distinguished only for the flat in window style, provided that no icon is specified.
If you need to enable selection from more than two values, then it is more appropriate to use a radio button, a value selector, or a disp‑folder containing a value selector.

Display

Item
Description
Title
Text displayed on the check box.
Other
Style
Check box appearance:
flat in window
the usual appearance with the check box on the left. If you specify an icon, a button with the icon is displayed instead; this button can be pressed down.
flat on bar
in the unchecked state it looks like a simple text without a frame; when touched by the mouse pointer or activated, a frame appears (the button is “lifted”). In the checked state it looks like a pressed button.
flat in menu
text with either the specified icon or a check mark on the left. When activated, the background color changes (standard behavior of menu items). The mark or icon on the left is present/pressed when checked state is in place.
three-dimensional
common three-dimensional button that is pressed in the checked state.
three-dimensional low
three-dimensional button with a thinner frame so that it appears lower. It is pressed in the checked state
auto
the style is determined according to the check box location.
Icon
Icon displayed to the left of the title according to the selected style. The icon is entered using the icon editor.
Hide title
If checked, the title is not displayed on the check box, and only the icon is displayed. Title text is displayed in the tool tip.
Borders
The spaces left between the check box frame and the title. Values for all directions can be specified individually. If no value is specified, appropriate borders are determined automatically according to the title text.

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 of a numeric type or of a type that allows type conversion to a number. If this is not the case, the getter and setter functions must be specified.
Three states
Permits the neutral state.
Other
Data type
The data type that is to be stored into the respective data object by the check box. Usually, it need not be specified – it is determined automatically from the actual type of the edited data. However, if the type of the edited data is Union, it may be necessary to specify the actual value to be stored by the check box.
Getter function
This function is used to determine the check box state from the edited data. If no function is present, standard type conversion is used.
The function is specified in the Enki language.
Function parameter:
val
the current value of the data item determining the check box state. Its type corresponds to the edited data item type. If data is absent, NONE value is passed.
Result type: Bool|None.
Result values:
FALSE
check box is unchecked
TRUE
check box is checked
NONE
neutral state (only when permitted by the Three states option). Return of the NOT_PRESENT value has the same effect.
Examples are included under this table.
Setter function
This function is used to insert a value into the edited data item when the check box state is changed. If no function is present, standard type conversion is used.
The function is specified in the Enki language.
Function parameter:
val
either TRUE or FALSE value depending on the check box state (Bool type). Three-state check boxes can also pass the NONE value (None type). The NONE value should be first tested in the function by the === (is identical) operator (using the if(val===NONE) command), in order to prevent type errors in subsequent code expecting a Bool type value while the actual value type was None.
Result:
the value that will 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.
Disable closing volatile window
If the check box is in a volatile window – that is, in a window that is automatically closed when an action in the window is performed (such as the menu window – see the Disp‑folder), then, when this option is checked, the window will not be closed by pressing the check box.
Definition type: Check_box_def
Example 1: a check box switching the value of a string data item between "Important" (the check box is checked) and "" (empty string – the check box is unchecked).
Getter function:
if(val=="Important")
return TRUE;
return FALSE;
Note: the getter function sets the check box to unchecked state for any value other than "Important".
Setter functions:
if(val)
return "Important"
else
return "";
Example 2: a three-state check box switching an optional numeric item between 100 (the check box is checked), 0 (the check box is not checked), and not-present (the neutral state).
Getter function:
if(val===NONE)
return NONE;
if(val==100)
return TRUE;
return FALSE;
Note: the NONE value is tested first to be excluded at the beginning so that the rest of the function could count on the val value being a number. The NONE value is tested by the === operator (three equal signs) to prevent any type conversion, to make sure the comparison is successful only for this one value.
Setter function:
if(val===NONE)
return NONE;
if(val)
return 100
else
return 0;