Sfairadora

  • Reference Guide

Dispels

This subsection allows you to create your own named dispels. You can use them later as named dispels when creating presentations. You can also assign a type to a dispel created this way so that it is used automatically by the universal dispel whenever you need to edit the respective type. Consequently, if you create a new data type in the Data Types subsection, you can create a corresponding dispel here, and it will be automatically used by Sfairadora for editing of the new type.
A table is displayed for this subsection in the right pane of the document main window, where every row corresponds to one defined dispel. Every dispel must be assigned a name (must be an identifier) identifying the dispel; then there is a button opening the dispel definition editor and a details button opening a window, in which you can specify the properties of the defined dispel.

Properties of Defined Dispels

Item
Description
Name
The name under which the dispel is stored in the document. The name must be an identifier. This item edits the same piece of information as the name field in the table of defined dispels described above.
Dispel
Button opening the dispel definition editor. Identical to the button in the table of defined dispels described above.
Names of edited data objects
When used, the defined dispel must be linked to particular data that is to be edited by the dispel. This field specifies a name of this data, which can be used by subordinate dispels used in the definition. Usually there is only one piece of such data, however, an editor may in general edit multiple pieces of data located in different places. The name must be an identifier.
Example: suppose you wish to create an editor for the Address data type (a structure containing the first name, last name, street … elements). Enter an Object name, for example adr, representing the edited address. The defined editor will contain, among others, line editors editing individual elements of the address. The Object name of these elements will be adr and their data reference will be first_name for the first element, last_name for the second one, etc.
Parameters
Allows you to enter the type of a value that is passed whenever the defined dispel is used in order to set some properties of the dispel. It is strongly recommended to use structure as the parameter type because then you can add new values to the parameter if necessary.
Example: Suppose you are creating a dispel intended to specify length. Its parameter can be a structure with the following elements:
String
name of the unit of measure in which the value should be entered.
Real number
coefficient used to convert the entered unit into meters.
Integer number
number of decimals to be specified in the value.
Name of parameters
Object name of objects passed as parameters, which can be used by dispels included in the definition to reference this data. The default is param, but you can choose any other name. The name must be an identifier.
Default value
Parameter value specified by the universal dispel when it uses the defined dispel. If the value is not specified, default value of the parameter data type is used.
Edited types
A list of data types that can be edited by the defined dispel. This list is used by the universal dispel. If a presentation of a type listed here is to be created, this dispel is used.
Maximum recursion depth
The defined dispel may contain a named dispel whose name recursively references the name of the defined dispel. Consequently, the defined dispel can be used several times in itself. This is not necessarily an error – if, for example, you create a dispel displaying the contents a folder on the disk, it contains an instance of itself repeatedly for every subordinate folder. However, it is necessary to prevent an infinite recursion – the application would end up in an infinite loop. Therefore you can specify the maximum number of times the dispel may be recursively nested in itself. The number of occurrences “side by side” does not count, only the depth of nesting “inside each other”.
Should the maximum recursion depth be exceeded during usage, the instance of the defined dispel is no longer created on the level where the excess occurs, but a message appears announcing that the maximum allowed dispel recursion depth has been exceeded, and the infinite loop ends.
If no value is specified, the default is 20.
In table
Information for the named dispel – whether the defined dispel is intended for use inside a table or outside a table.
If the box is checked, the dispel is used only inside a table. If not, it is used only outside a table. If the box is in the neutral state (no value specified), the dispel is used in both cases without any difference.
Help
You can define a help message, which is displayed when the defined dispel is used in a named dispel.