• Reference Guide

Tools Document Section

A tool is a set of controls allowing you to perform additional operations with the currently active control. An example of a built-in tool is the window used to modify text formatting in a text editor. Users can define their own tools in this section.
Tools defined in the document are available in the Tools menu. If you need to create a tool available to all documents, you can either save it to the system document or create a document of a special type serving this purpose – a tool set. The latter option is more appropriate because the tool is saved to a separate file and is therefore easier to manipulate with (transfer to another computer, backup …).
In principle, tools resemble presentations, but the difference is that presentations are firmly attached to their data whereas tools manipulate with the data of the currently active editor. Consequently, tools are second-level presentations above ordinary presentations – if you activate a tool, the previous active editor is not deactivated, but its activity is retained and the tool is related to it. Tools are always displayed in a separate window, which is not located inside the application main window (among other document windows), but directly on Windows desktop. Tool windows are normally displayed in front of all other Sfairadora windows.

Data Available to Tools

In order to successfully create a tool, you will need to know what kind of data is provided by different editors. This data is stored in so-called state objects. The actual operation of a tool is realized through manipulation with this data. In addition, you can access data provided by a sequence editor, table, disp‑folder, and especially by a data provider. Furthermore, data of the active document (under the document object name) and of the system document (under the system object name) is available. If the tool is defined in terms of a tool set, the document to which the tool relates is available under the master object name (the document name refers to the actual tool set document). You can change this object name in the Settings document section of the tool set in the Name of master document data field.

Tool Properties

The following information about tools is displayed in the right pane of the document main window for items in the Tools section:
The name under which the tool is stored in the document. The name must be an identifier.
Window title
Title of the tool window. The tool is listed in the Tools section under this title as well.
The box is checked if the tool is displayed. When you check the box, the tool is displayed, and vice versa.
Window style
Determines the appearance and behavior of the window:
looks like an ordinary window, which can be hidden behind Sfairadora main window or minimized.
Tool window
has a thinner title, is located in front of all Sfairadora windows, and cannot be minimized.
Window state
The following items reflect the current state of the window if the tool is displayed. Changes of the window state (e.g. its relocation ore resizing) by the mouse are mirrored by these values and vice versa – changes of these values immediately relocate or resize the window. If the window is not displayed, the values indicate how it will be displayed when opened.
Window position
Current position of the tool window. If no value is present, Sfairadora determines the optimal position for displaying the window itself.
Window size
Current size of the tool window. If no value is present, the window is in the dynamic mode adjusting the window size according to its contents. Entering a value is equivalent to fixing the window size with the mouse. See also the explanation of the window size management.
Minimized window position
Position of the window when minimized. This option is available only when the window style is set to “normal”.
Tool guard data
This field allows you to enter a reference to the data whose presence is necessary for the tool to be displayed. In other words: the tool is displayed only when this data is available. If the data is unavailable, the tool window shrinks to title only. This option enables you to create a tool that will be available only in a particular situation. If these items are not specified and data necessary for the tool is still unavailable, most likely only labels of the entered data will be displayed; this is not a functional problem, but it does not look nice.
Example: Suppose you need to create a tool available only if an editor providing information on paragraph formatting is active (i.e. a rich text editor). Use the following setting:
Object name = editor_state
Data reference = rich_pformat_info
Object name
Name of the object in which data should be possibly present. See the chapter on object names. Object names of data supplied by individual editors are explained in the State Objects chapter.
The field contains a listbox of available data names. However, it is usually of no use in this particular situation because the context in which the tool would be used is not known. Therefore you will usually need to enter the object name manually.
Reference to data
Reference to specific data within the object identified by the Object name field. See the Identifiers and References chapter and the description of individual state object types.
Edit presentation
This button opens the dispel definition editor to edit the appearance of the tool. The process of creating presentations by means of the R-D/C model is explained in the R-D/C Presentation Model chapter.