Sfairadora

  • Reference Guide

File Manipulator

File manipulators are tools allowing you to open files other than standard documents (files with the .s‑d extension) in Sfairadora. A file manipulator can be also regarded as a document template that loads data from the required file when opened. The built-in file manipulators for the opening of text files and for the opening of files in RTF format are a good example. File manipulators are stored in a specific folder (by default Documents:Sfairadora\File Manipulators – the actual path can be ascertained from the system information window).

Using a File Manipulator

All created file manipulators are available in the File|New menu. You can use the menu to create a new file whose type corresponds to the file manipulator. If you save a document created this way, the new file is not a standard Sfairadora document, but rather a file of the type corresponding to the used file manipulator (e.g. if you use the text file manipulator and save the created document as usual, you will create a new text document with the .txt extension). All file manipulators are also available in the open file window (File|Open File menu command). All file types corresponding to available file manipulators are listed in this window at the end of the Files of type listbox. Consequently, if a text file manipulator is available, the listbox of file types in the file open window will contain, among others, the “Text (*.txt)” option.

Creating a File Manipulator

The first step towards the creation of a file manipulator is switching the document type to file manipulator. This is done in the Settings section using the Document type listbox. If the document has already been saved to disk, it is automatically moved to the file manipulators folder. The standard extension of a file manipulator file is .s‑d‑fman.
When you switch a file to the file manipulator type, the following items specific for file manipulators appear in the Settings section:
Item
Description
Manipulator name
The name that will be displayed in the File|New menu and in the Files of type listbox in the open file window.
Current manipulator
This field is read-only and is filled out in documents opened by means of the file manipulator. It contains the full name of the file manipulator file that has been used to open the document.
Current format
Similar to the Current manipulator field; it contains the extension of the file opened by the file manipulator.
File formats
Table containing file formats managed by the file manipulator. It may be useful to include multiple formats if a single logical data type tends to be stored in different formats (e.g. images can be in JPEG, PNG, etc.). If the different formats lack a common uniting substance, you should create multiple file manipulators.
If multiple formats are defined, then it is entirely up to the creator of the file manipulator whether and how potential format conversions or other operations will be performed. Information about the current format is available in the Enki language through the following item:
document.settings.file_manipulator_info.current_format
See the file_manipulator_info item in the document.settings.
Name
Format name displayed to the user.
Main
If multiple file manipulators are associated with a particular extension, preference is given to the one that has this option checked. If there is more than one, the selection is random. The Main option should be used only with those file manipulators that process the respective format in an exhaustive manner in some sense.
File extensions
A list of extensions associated with the format. The column contains a list, therefore you have to enter one extension without the initial dot per row. You should enter multiple extensions if the given format occurs with multiple extensions (such as the JPEG format, which occurs with the jpg, jpe, and jpeg extensions). If the formats are not identical, you have to fill in multiple rows with formats rather than just multiple extensions.
File open function
An Enki language function executed when the file is loaded. The function is specified in the function editor. The parameter of the function is the file_name string containing the full path to the file that is being opened. You must use Enki language functions for file manipulation to open and load a file.
File save functions
Analogical to the file open function.
New document initialization
An Enki language function executed when a new file is created by means of a file manipulator (from the File|New menu). This function may perform a necessary initialization of the document. If no initialization is necessary, the function is not needed.
‍
Before you can create functions for opening and saving data from a file, you first have to create corresponding data structures in the Data document section where the data will be stored. Second, you will probably have to create a presentation allowing you to edit the data. Before saving a file manipulator, it is recommended to open the respective presentation in a window, switch off the closing main window closes document option in the Settings section, and close the main window because a document opened by means of the file manipulator looks like the file manipulator did when it was saved. You can also switch on the Closing window closes document option in the Presentation definition section for the presentation created to edit the data; consequently, the window containing the defined presentation will assume the role of the document main window. Besides this main presentation, you can define additional presentations as needed, which will be available from the Presentation or tools menu.