Sfairadora

  • Reference Guide

Disp‑folder

The disp‑folder dispel allows you to gather a larger set of dispels under a single heading so that it can be displayed only when needed. This arrangement makes the presentation easier to read. The disp‑folder covers functionalities that are normally provided by various controls. For example: a button opening a window; a menu item (opening separate menu window); a value selector (“combo box”); or a title with an unfolding button (like in the left pane of the document main window), etc.
For convenience, typical techniques of using the disp‑folder are included in the disp‑folder definition editor. These simplified definition editors are supplied for the following cases:
The General case is explained here. In the general case, there are three types of display:
●
Folded
●
Unfolded
●
External
The folded display is the default appearance of the disp‑folder: the contents are hidden, and only brief summary information is displayed. The folded display may be accompanied, or even entirely replaced, by a title. Typically, the folded display is either a mere title represented by a button, or a title with an unfolding button, or a simple dispel such as a line editor displaying summary information about the edited data. If unfolded display is defined as well, the folded display has an unfolding button on the left. The button is followed by the folded display dispel (provided it is defined) and by a title with an externalizer. If no title is defined, the folded display is reduced to the externalizer only.
The unfolded display is a dispel that replaces the folded display when the users clicks the unfolding button (small plus sign in the box to the left of the folded display). If the disp‑folder is not meant to be unfolded, unfolded display is not defined.
The external display is a dispel displayed in a window when the user clicks the externalizer in the folded display. The externalizer is either the entire title of the folded display or a button with an arrow on the right side of the folded display. The external and unfolded display may be identical and the respective dispel can be then displayed either in a separate window or in the disp‑folder.
You can also assign data to the external and unfolded display, that will be edited by the presentation – then, you have to specify a data reference and an identifier that will provide data to the external and unfolded dispels. If edited data is determined this way, you can have the external display (i.e. open window) edit a copy of the data and save the changes into the physical data item only when the window is closed. If the user closes the window by the Esc key, all changes are canceled and the edited data item remains untouched. This feature, especially when combined with a function verifying the correctness of the entered data, allows you to ensure that incorrect data is not saved (temporary incorrect values are only in the copy of the data and not in the data item itself). The assignment of data to the disp‑folder also enables the user to copy the data. The required settings are explained in the Functionality section below.

Value Setting Function

The disp‑folder can be used to create a window divided into two panes, where the left pane contains a list of elements, and the right pane contains the details of the selected element. To do this, the disp‑folder has the possibility to assign a particular value to a selected data item when activated. (This functionality is similar to that of the radio button). The data item that is being assigned a value is typically a local variable of the presentation (see the data provider), allowing you to pass information about the required presentation between the left and the right pane. Settings determining the value assignment are located in the Functionality section in the Setting value when activated subsection.
This kind of presentation is constructed as follows: The top level contains a data provider defining a local variable. A header provider with heading displayed on the left, containing a list of items, is located under the data provider. The dispel related to the heading contains the details of the selected item. The list of items is a group of disp-folders that may be arranged hierarchically if required (you can create them using the simplified disp-folder editor – the tree editor). Every single disp-folder assigns a unique value to the local variable. The dispel showing the details of the selected item is a disp-switch switching between the actual presentations of individual items according to the value of the local variable.

Folded Display

Item
Description
Title
The title displayed when the disp-folder is folded. It need not be specified – in that case, only the folded display dispel is displayed in the folded state (see the dispel editor below).
Text style
The style applied to the title text. You can choose between basic and heading 1 to 5. Heading 1 is displayed with the biggest font while heading 5 with the smallest.
The basic style corresponds to the Display – button display style or to the Display – labels style if Title style is set to label; individual headings correspond to the Display – heading X styles.
Title style
Title appearance (in most cases the title looks like a button):
simple
a simple button that looks like a plain white rectangle without a frame, containing only the title (appropriate for use in tables and white fields). The actual color may differ depending on Windows settings.
flat in window
the button color is that of the window background and normally there is no frame. The frame is only displayed when touched by the mouse pointer or activated (it is “lifted”). When located in a white field or table, the frame is always displayed.
flat on bar
same as flat in window; appropriate for display in the tool bar.
flat in menu
the button has the same color as the window background and no frame. When activated, the background color changes (standard behavior of menu items).
three-dimensional
common three-dimensional button.
three-dimensional low
three-dimensional button with a thinner frame so that it appears lower.
label
the title is only a label.
auto
the style is determined according to the disp-folder location.
Child position
If you define a dispel (child) for the folded display, this option determines its position with respect to the title:
left
the dispel is to the left of the title.
left, to block
the dispel is to the left of the title. If the disp-folder is wider than its optimal size, the dispel is extended so that it fills the redundant space.
right
the dispel is to the right of the title.
right, to block
the dispel is to the right of the title. If the disp-folder is wider than its optimal size, the dispel is extended so that it fills the redundant space.
below, left
the dispel is below the title and aligned to the left border.
below, left to title
the dispel is below the title and aligned to the left border of the proper title text. That is, if there is an unfolding button in front of the title, the dispel is indented so that it is aligned with the beginning of the title text.
below, centered
the dispel is below the title and centered with respect to the width of the disp-folder.
below, centered to title
the dispel is below the title and centered with respect to the width of the title text. That is, the unfolding button (if there is one) is not taken into account. If the dispel is wider than the title, it is always indented so that it is aligned with the beginning of the title text.
below, right
the dispel is below the title and aligned to the right border.
below, right to title
the dispel is below the title and aligned to the right border. If the dispel is wider than the title, it is always indented so that it is aligned with the beginning of the title text.
below, to block
the dispel is below the title and expanded to have the same width as the title.
below, to block to title
the dispel is below the title and expanded to have the same width as the title. The unfolding button (if there is one) is not taken into account. If the dispel is wider than the title, it is always indented so that it is aligned with the beginning of the title text.
auto
the child position is determined automatically.
Other
Externalizer
The appearance of the symbol informing the user about the possibility to display an external display (i.e. to open another window with extra information). If you explicitly define the externalizer appearance, you should also define the external display because otherwise the disp-folder appearance would be confusing for the user.
disabled
the externalization function is disabled, and clicking the button does not open a window with external display. No symbol indicating possible externalization is displayed.
empty
the externalization function is enabled, but no symbol is displayed.
arrow right
the externalization symbol is a triangular arrow pointing to the right (common for menu items).
arrow down
the externalization symbol is a triangular arrow pointing down (common for droplists in windows).
space for arrow
a space of the same width as the arrows listed above.
ellipsis
the externalization symbol is three dots.
auto
the symbol is determined automatically – if no external display is defined, no symbol is present; otherwise it depends on the disp-folder location.
Icon
Icon displayed by the title. The icon is entered using the icon editor.
Title alignment
If the disp-folder is wider than the title, this option determines the title alignment. The options are: left, center, right, and auto. If the auto option is in place, the alignment depends on the disp-folder location.
Expand button horizontally
If checked, and the disp-folder is wider than the title, and the title is a button, the button is expanded to have the same width as the disp-folder. The title is then aligned within the button area. If unchecked, the entire button including the unfolding button, if present, is aligned.
Expand button vertically
If checked, and the disp-folder is higher than the title, and the title is a button, the button is expanded to have the same height as the disp-folder.
Borders
The spaces left between the title and the button frame.
Disable title activation
If checked, the title (title button) cannot be activated separately. The user will be able to activate only the disp-folder dispel.
Dispel editor
Editor used to define the dispel displayed in the folded state of the disp-folder.

Unfolded Display

Item
Description
Child same as external
If checked, the unfolded display is identical to the external display. The actual display is defined below in the External display section. The dispel can be then displayed either as unfolded or as external (in a window), but not both at the same time.
Child position
See the Child position item in the folded display details above.
Other
Externalizer
Appearance of the externalizer in unfolded display – see the Externalizer item in the folded display details above.
Title same as in folded
If checked, the title for unfolded display is the same as for folded display. Otherwise, the same set of items for title specification, as used in folded display, is displayed so that a specific title can be defined.
Dispel editor
Editor used to define the dispel displayed in the unfolded state of the disp-folder. If the Child same as external option is switched on, the editor is not available.

External Display

Item
Description
Window style
Properties of the window in which the external display is displayed:
normal
normal window
normal volatile
normal window that is automatically closed as soon as the user activates another window or performs an action in it (clicks a button, enters a value, etc.) – that is, the window behaves as a menu window. You can disable the closing of volatile windows for individual editors contained in it by switching on their Disable closing volatile window option.
menu
menu window. The behavior is the same as that of the normal volatile option. The window has no title.
Window title
Title of the external display window.
Dispel editor
Editor used to define the external display. If it is not specified, the external display window cannot be opened.

Other Display Settings

Item
Description
Unfolding button
Toggles the display of the unfolding button. The default setting is neutral – the unfolding button is displayed if unfolded display is defined.
Space for unfolding button
If checked, a space for the unfolding button is left on the left even if the unfolding button is not displayed. This option is useful to align disp-folders with and without unfolding buttons in one group.
Initially unfolded
If checked, the disp-folder is initially unfolded when created. If the instance already exists, toggling this option does not affect anything.
Always create all displays
All dispels are created even if they are not currently displayed (i.e., for example, the external display exists even if it is not displayed in a window). An undisplayed dispel may have data handlers etc.
Leading lines
If there are multiple disp-folders subordinated to another disp-folder, lines are drawn from the parent to the subordinate one. This produces a tree, such as that in the left pane of the document main window.
Drag hover
Determines what happens if the mouse pointer hovers over the disp-folder while dragging data:
no action
nothing happens.
unfold
the same action is performed as the one performed after a mouse click – the display is unfolded or, if it is already unfolded, the external display is opened. The aim is to enable the user to drag the data into a dispel in the unfolded or external display.
set value
the value setting function is executed as described above.
Unfold
Determines how the disp-folder is unfolded: by a single mouse click (by pressing button) or by a double click (by double-clicking button). The auto options determines the appropriate method according to the disp-folder character (e.g. if the disp-folder is meant to set a value and is displayed in a field, the user expects it to unfold after a double click).
Background
Background displayed in the area without element dispels. The options are gray, white, or auto. Actual colors depend on Windows color setting. Gray refers to the window background color whereas white refers to the background of fields (such as table cells, etc.). If the auto option is in place, the background will be white if the group is located in a dispel with white background.

Functionality

Item
Description
Object name
Name of the object where the data is located, that should be attached to the disp-folder. You can select one of the objects provided by parent dispels.
Data reference
Reference to data within the above identified object.
Object name of data for child
The name used to provide the data attached to the disp-folder to the dispels in the unfolded and external display.
Direct data editing
If a data item is attached to the disp-folder by the above settings, and this option is unchecked, the external display (i.e. the window opened by the disp-folder) will edit only a copy of the data. The data will not be saved into the respective data item until the window is closed. Moreover, if the user closes the window by the Esc key, all changes made in the copy will be canceled and the data item will not be changed.
If this option is checked, the data is edited directly.
Confirm removing data
If an optional data item is attached to the disp-folder, its value can be deleted by pressing the Delete key or a corresponding button in the tool bar. This option determines whether a dialog asking for confirmation appears when the user attempts to delete the value.
Disable dragging data by mouse
If a data item is attached to the disp-folder, the value can be copied or moved by mouse-dragging. If you check this option, this feature is disabled.
Disable closing volatile window
Execution of the “value setting function” does not close the volatile window containing the item. (A volatile window is a window that is normally closed when an action in the window is performed – such as a menu window.)
Validator
Function invoked when the external display window is closed. The function may validate data edited by the window. The result represents information about the situation: ok, warning, or error. You can also specify a reference to data related to the error and an error message.
If the result is error, a message is displayed, and the window cannot be closed until the error is corrected. If the result is warning, a message is displayed, and the user may choose either to correct the error or to close the window without correction. If a data reference is specified, and the window is not being closed, editor of the data item identified by the reference is activated.
Function parameter:
err
output parameter of the Error type. The validator function can assign an error message to this parameter (e.g.: err = error("the value of X is too big");) The message should start with a lowercase letter and should not end with a period – errors can be nested, and when they are listed, the first letter is automatically uppercased, and a period is placed at the end.
In addition, you can use the set_data_ref operator to specify reference to data related to the error. For strings you can also specify the line and column where the error occurs. (e.g.: err<-set_data_ref( [Dref]"data.age");)
Result:
one of the following constants:
VLD_OK (0)
everything is ok (the value of the err parameter is ignored).
VLD_WARNING (1)
warning. The user receives the message set in the err parameter. Then, he can choose either to close the window or to correct the error. If he chooses the latter, an editor of the data specified by the err<-set_data_ref operator is activated.
VLD_ERROR (2)
data is incorrectly specified. The user receives the message set in the err parameter. If a data reference is specified by the err<-set_data_ref operator, the respective editor is activated.
(The values of the constants above are included in the parentheses for information. However, the symbolic names should be used rather than their values.)
Example:
if(data.x>1000)
{
err = error("the value of x is higher than 1000");
err<-set_data_ref([Dref]"data.x");
return VLD_ERROR;
};
if(data.y>100)
{
err = error("the value of y is higher than 100");
err<-set_data_ref([Dref]"data.y");
return VLD_WARNING;
};
return VLD_OK;
Setting value when activated
Object name
Name of the object containing the data item that should be assigned a value when the disp-folder is activated/pressed. The action setting the value is specified below by the Set value option. You can select one of the objects provided by parent dispels.
Data reference
Reference to data within the above identified object.
Value
The value that should be set. After you select its type, an editor appears, in which you can specify the value.
Set value
Determines when the above specified value is set:
on activation, delayed
the value is set after the disp-folder activation. However, there is a short delay before the value is set. If, during this delay, the user activates another disp-folder assigning a value to the same item, the value is not set. This option is appropriate if the setting of the value invokes an action that takes a longer time so that the action is performed only if the respective disp-folder is active for a certain period of time. If the user merely runs through a list of disp-folders, the value is not set.
on activation, immediately
the value is set immediately on activation.
when pressed
the value is set when the disp-folder is pressed, but not when it is activated, e.g. by the arrow keys. The disp-folder behavior is then similar to that of a radio button.
Definition type: Disp_folder_def