Sfairadora

  • Reference Guide

R-D/C Presentation Model

The Recursive Data-Control model (R-D/C model) is a means developed to facilitate construction of data presentation in Sfairadora. The model is used to create user-defined presentations in the Presentation document section as well as to modify presentations created automatically in the Data or View section. The strength of the R-D/C model features is proven by the fact that Sfairadora entire user interface has been developed by means of this model – the same model that is available to the users.

The Concept of Dispel

The cornerstone concept of the R-D/C model is a control also referred to as a dispel (an acronym of display and element). Dispels are either simple – such as editors and buttons, or compound – containing other dispels, such as tables. Compound dispels determine the layout of subordinate dispels on the screen – e.g. a group, arranging dispels side by side or under each other; they also allow you to organize presentations dynamically – e.g. a disp-switch.

Size and Position

A particular presentation therefore consists of dispels arranged into a hierarchy or tree. This tree arrangement determines the optimal position of dispels on the screen and their size. The size of individual dispels may dynamically change in reaction to the changes of data edited by the dispels. Dimensions may also change in reaction to changes of the display styles, defining the formats of texts included in presentations. In addition to this basic dimension-controlling mechanisms, a group of dispels can be aligned with respect to their size or position.

Relation Between Presentation and Data

Data edited by individual dispels (editors) is not contained within the dispels, but stored in data structures separated from the presentation itself. This organization corresponds to the fundamental segmentation of Sfairadora into the data, view, and presentation level. (There is no difference between data and view with respect to the presentation design – both levels represent data). This arrangement is sometimes referred to as the data-control model (or data-view, where the view term denotes a presentation and not a view in the sense used in Sfairadora).
Consequently, you need to specify a name of the object in which the data is stored and a reference to data within the object, for every editor. For example, if a table data item is stored in the Data document section, the object name should be set to document and the data reference to data.table. Details on the document data model are explained in the Document Data Type chapter.
The situation can be interpreted that certain data is provided to the presentation and certain dispels accept the data. Sfairadora further enhances this arrangement into a recursive model, where dispels are not just data acceptors, but also data providers. A data object provided by a dispel is then available to all subordinate dispels in the presentation definition hierarchy. The document main window provides the document data object (denoting the entire document to which the presentation belongs – its type is described in the Document Data Type chapter) and the system data object (the system document, whose type is described in the System Document Data Type chapter). Subordinate dispels can reference data in these objects. Some dispels can provide additional data. For example, a table provides a cell_data data object (the name can be changed in the table definition) to the dispel in every cell. This data object represents data of the particular cell (is cell-specific). The data provider dispel is very important in this respect – it allows you to create local variables storing the presentation state. Another useful feature is the possibility to define local variables as computed items, whose value is automatically updated according to the value of other data.
Sfairadora automatically updates editor content if the underlying data is changed. Consequently, if there are two editors for a single data item, changes made in one editor are immediately reflected in the other, too. The particular moment when the change is applied depends on when the editor actually writes data into the data object. For example, the line editor allows you to choose whether data should be saved whenever you type a character or only at the end of editing.

Universality of the R-D/C Model and Presentation Perceived as a Program

The possibility of using local variables in presentations is as significant as it is in programs. In general, a presentation defined by means of the R-D/C model can be regarded as an analogy to a program – while the run of a program is distributed in time, presentation realization is distributed in space on the screen. This analogy between presentations and programs guarantees that the R-D/C model can be used to design any conceivable presentation without any limits. The following analogies can be identified between basic programming languages constructs and the R-D/C model elements:
● local definition (variable, function …)
● condition
● function call
● pointer to function, virtual function
● numeric calculations
computed local variables in data provider

Commands

Dispels provide commands in addition to data. A dispel command is available to all subordinate dispels just like the data. For example, a document window provides a command to save the document etc. A command can be executed either by means of a button dispel or from any other dispel by means of the execute_command function of the Enki language. All available commands are described in the Command List chapter.

State Data, Tools, and Second-Level Dispels

This arrangement of dispels both receiving and providing data presents an elegant solution for the operation of tools. Tools are dispels whose functions do not directly apply to data, but to the currently active dispel instead. Tools can be therefore regarded as second-level dispels. The typical tools include dispels for menu, tool bar, and specific tool windows (such as character format).
The main issue in designing tools is their interaction with the currently active dispel. In Sfairadora, this is solved by the data externalization mechanism. Data externalization is a mechanism that gathers all data available to the currently active dispel and provides these data to all tools (i.e. second-level dispels – menus, tool bar elements, and tool windows), as if the tools were subordinate to the currently active dispel (even though they are not). Commands are, of course, externalized just like data.
Most editors create and provide a state data object for the interaction with tools. This object continuously reflects the editor state – for example, the cursor position, currently used character format, etc. Also this object is externalized to tools. Consequently, the tools can both display the editor state and affect the editor operation through changes of the state object data. Names and types of state objects are described in the State Objects chapter.

Dispel Definition Object and Attributes Entered Through Expressions

Every dispel is defined by its definition object. A definition object is a data object just like any other data object in Sfairadora, and can be treated accordingly. Presentation is therefore defined by creating a definition object and setting required attributes. Dispel definition objects are created and edited by the dispel definition object editor. Its function in relation to different dispel classes is described further on in the respective chapters.
A dispel definition object is not the same as the dispel itself – the dispel is only based on it. A single definition object may have multiple dispels (such as the sequence editor possessing only one definition object for its items, but as many dispels as there are elements of the sequence) or no dispels at all.
There is one definition object type for every dispel class. The definition object type contains data items representing all attributes of a dispel belonging to that class. Each attribute can be specified either directly by a particular value or indirectly by an Enki language function. The latter is done in the definition object editors by clicking the fn button ( ) in front of the respective value. If you specify the attribute by means of a data-dependent function, the function is re-evaluated whenever the data is changed. The attribute value is thus always up‑to‑date with the data.

Dispel Appearance

The criterion for dispel classification is their function, not their appearance. For example, a check box may look like a button, but it is still a check box because it is used to set a data value; not a button, which would be used to perform an action when clicked.
In relation to this forementioned principle, some attributes of the dispel appearance need not be defined – and typically should not be defined – as they are determined automatically according to the dispel location. The following locations are distinguished based on the traditional dispel appearance:
●
in window
●
in field (e.g. in a table; in general, anywhere in the window where the background is white and not gray)
●
in tool bar
●
in menu window
●
in status line
For example, a button located in a window is normally three-dimensional; a button located in a tool bar is flat, but it is lifted when touched by the mouse pointer; and a button located in a menu looks like a menu item that changes background color when touched by the mouse pointer.

Errors in Dispel

Since dispel attributes may be defined by functions, run-time errors may occur during their evaluation. To facilitate debugging, errors information is stored by the dispels where they occurred. If an error occurs in a particular dispel, you will see a small red square in the upper left corner of the dispel . The dispel context menu will then contain an Errors item listing the description of all errors related to the dispel. Since one error may produce another error on a higher level, the errors are threaded by causality. The last error is on the top position in the menu followed by the chain of causes back to the error origin. If the error is linked to a particular place in the document (e.g. to a position in the function source text or to a data item), you can display the respective place in the document by clicking on the selected error.