Sfairadora

  • Reference Guide

Properties Common to All Dispels

This chapter describes properties common to all dispel classes or to most of them.
Properties in all dispel definition object editors are divided into the display part comprising properties related to the dispel appearance on the screen, the functionality part comprising properties affecting the dispel function, and other specific parts for some dispel classes. The following common parts apply to all dispels:

Control

Item
Description
Tag
Group identifier for the alignment of dispel size or position. Dispels with the same tag will be aligned together. See the chapter on dispel alignment.
On data absence
Appearance of the editor if there is no data for editing (i.e. either the object referenced by the Object name field does not exist, or there is no data item in the object corresponding to the data reference).
gray
the dispel will look like disabled controls under standard Windows settings
hidden
the dispel size will be set to zero so that it will not be displayed at all.
This option is available only in the definition objects of editors.
Forced display
This option allows you to enforce gray appearance (disabled dispel) or hiding (zero size) also in situations other than data absence. The value is combined with the value of the preceding On data absence option and the stronger restriction takes precedence (hidden is stronger than gray).
It makes little sense to specify the value directly as the dispel would then always be either gray or hidden. The option value should be therefore specified by a data-dependent function. The function must return one of the following values:
FORCED_DISPLAY_DEFAULT
normal appearance
FORCED_DISPLAY_GRAY
gray appearance
FORCED_DISPLAY_HIDDEN
hidden dispel
More complex display modifications can be achieved by means of a disp-switch.
Enable write
This option governs whether data in editors can be modified. It is present for dispels that are not editors as well because it applies also to all subordinate dispels. The option has three possible values – enabled (checked), disabled (unchecked), and default. If you select default, the value is inherited from the nearest parent dispel with a non-default value. If all parent dispels are set to default, write is enabled.
If the value is specified by a function, the returned values are:
TRUE
write enabled
FALSE
write disabled
NOT_PRESENT
default
Disable activation
If checked, the dispel cannot be activated even if it normally could (e.g. an editor, button …). Although the dispel cannot be activated, it is still functional – you just cannot control it with the keyboard, but only with the mouse (e.g. a button can be clicked by the mouse).
Disable editing
For text editors: the editor can be activated, but you cannot switch it to the editing regime, that is, to the mode in which you can move within the text with the cursor. Disabled editing is not the same as disabled writing. If write is disabled in the editor, you can still move within the text with the cursor – you just cannot modify the text.

Events

Item
Description
Displaying
Function called upon the display event. The display event refers to the moment when the dispel is inserted into the window that displays it. The function is not called when you change the display mode from “hidden” – see the On data absence and Forced display options above.
The function can be used, for example, to initialize local variables of the presentation. The function should not modify the underlying data of the presentation because you can never be sure how many times and when exactly it would be called. This depends on the presentation structure and on the user – how many times and when he displays it.
The function is specified in the Enki language.
Undisplaying
A complementary function to the Displaying function. It is called when the dispel is being removed from the window that displays it.
The functions is specified in the Enki language.

Help

Item
Description
Tool tip
The tool tip content, displayed when you hover over the dispel with the mouse pointer for a little while. You can choose between rich string (only one line) and rich text (multiple lines); or you can keep the tool tip switched off.
If you specify the text by a function, and the value changes while the tool tip is displayed, the change is continuously reflected in the displayed tool tip.
Context help
Text inserted into the context help window when the dispel is active. (The context help window is opened by the F1 key).
Title
Title displayed in the context help window.
Text
Context help text.
Displayed unfolded
This option determines whether the help in the context help window should be displayed unfolded or folded (i.e. only the title). A button with a plus sign located to the left of the title in the help window allows you to fold or unfold the help. This button in the help window directly changes the value of this option.