  |
GoFiler Legato Script Reference
Legato v 1.5d Application v 5.25a
|
| Table of Contents | < < Previous | Next >> |
Chapter Four — Flow Control (continued)
Directives tell the script processor to perform certain tasks during the initial preprocess parse process. This is similar to preprocess directives in C/C++. Directives are useful in a number of important areas to allow aliases to be defined, include other sections of programs and to direct certain sections of the program to be included or not included in the final executable portion of the script.
Like many other programming languages, Legato uses the ‘#’ character before a statement to indicate that it is a directive. The # must be the first item on the line and the statement encompasses the complete text line. Directives are not actually “run” or “executed”. Rather, they tell the script engine do things like pretend the string IDCANCEL is really the number 2. Directives are all processed by the script engine in the first stage of program execution known as the preprocess phase.
It is important to note that directives work on keywords and defined data. They cannot employ variables since the script is not actually running while they are being processed.
The #include directive allows a program to be assembled from a series of files. This makes organizing a program much simpler by allowing resources, defines and even various sections of a program to be broken into separate files. This can also allow for subroutines to be placed in discrete files allowing for use in multiple separate script programs.
The format is as follows:
#include "filename"
#include <filename>
Where
filename
If in quotes, specifies a relative filename or an absolute filename. This cannot be a variable and must be in double quotes. If in angle brackets, the file is expected to be located in the application program path at “Script\Include\”. Note that this is not a preprocessed string literal and therefore does not process backslashes as escape characters.
For the sake of conditional directives, a pseudo definition will appear only in included files called “_INCLUDE_FILE”. This can be used specify whether code should included on a conditional basis.
The #define statement allows the programmer to create substitutions for certain types of text. For example (expressed in various places in the script):
#define MY_NAME 201 ... (in resource) ... CONTROL "", MY_NAME, "edit", ES_LEFT|WS_CHILD|WS_VISIBLE|WS_BORDER|WS_TABSTOP, 53, 15, 119, 12, 0 ... (in procedure) ... name = EditGetText(MY_NAME);
At every point that MY_NAME appears, the value 201 will be substituted. This is useful in that a named value can be used in both a resource definition for a dialog and within the procedures to reference the dialog control. While during the development process numbers could be used, defined terms are useful in creating easily organized and readable code.
The format is as follows:
#define name replacement_text
Where:
name
The name or text of the item to be replaced. The name must follow the variable naming rules and cannot contain spaces, operators or other information.
replacement text
The text to replace the name with. The text can be a complex series of data containing variables, expressions and any data desired by the programmer. The name may also contain other references to defined terms.
Note that the define directive does not support complex macros with parameters.
While the text of a define can be upper and lower case, it is general practice to use all capitals to help differentiate from other variables and information.
A define statement can be repeated so long as the replacement text is the same. Defines can also be used in resource editors. The define directive supports recursive replacements within replacements. The replacements are performed repetitively until all terms have been resolved.
Improperly defined defines will result in errors at the point of definition, for example, redefining a term. Syntax errors within the defined text will be displayed at the point of parsing where the term was replaced.
Note that “_INCLUDE_FILE” is a pseudo definition tested only with #ifdef and #ifndef.
By default a series of terms is defined in the SDK for both script and resource statements. These definitions support common Windows values (e.g., error codes and window messages), common language items (logical ‘TRUE’ and ‘true’ as ‘1’) and specific function value definitions.
The standard SDK include is provided in the Template\Script folder in the application’s folder. Programmers can use this file as a basis to create or modify the standard definitions. Do not alter this specific file, it is not directly included during the preprocess phase but rather built into the script language. The standard items can be ‘undefined’ or the SDK copied and modified.
All API function names are defined as part of the default definitions. As such, language such as:
#ifdef StatusBarMessage
StatusBarMessage(0x00C00000, "<B>string Cube: Testing Diag</B>");
#endif
Can be used for scripts that might operate in various environments such as within a full application or within Legato Basic. Since Legato Basic does not have an application frame, there are no status bar API functions.
The #ifdef directive controls conditional paring of the source file by checking the specified name. If the name has been defined by using a #define directive, #ifdef directs the compiler to continue with the statement immediately after the #ifdef directive. If the name has not been defined, #ifdef directs the parser to skip all statements up to the next #endif directive.
Form:
#ifdef name
Where:
name
A defined name.
The #ifdef must be ended or closed with a #endif or #else or #elif.
The #ifndef directive controls conditional paring of the resource file by checking the specified name. If the name has not been defined or if its definition has been removed by using the #undef directive, #ifndef directs the compiler to continue processing statements up to the next #endif, #else, or #elif directive and then skip to the statement after the #endif directive. If the name is defined, #ifndef directs the parser to skip to the next #endif, #else, or #elif directive.
Form:
#ifndef name
Where:
name
A defined name.
The #ifndef must be ended or closed with a #endif or #else or #elif.
The #elseif directive marks a section to parse if the #ifdef or #ifndef fails.
Form:
#elseif
Where:
(no parameters)
The #elif directive is provided for compatibility and operates the same as the #elseif directive .
The #endif directive closes a #ifdef, #ifndef, #elseif or #elif directive. This must be the last directive in the sequence.
4.16.10 The #resource Directive
The #resource directive indicates that the following text is part of a resource, such as a dialog box, and should not be included in the script code but rather as part of the script resources. The #resource must be closed with an #endresource directive.
Resources may be included directly at any place within the script as directly using directives or by including the resources as a .rc file type. The #resource direct should not be used in an .rc file.
An example of an inline resource:
#resource
ProgressDlg DIALOGEX 0, 0, 220, 60
STYLE DS_3DLOOK | DS_CONTEXTHELP | WS_POPUP | WS_VISIBLE | WS_CAPTION
CAPTION ""
FONT 8, "MS Sans Serif"
{
CONTROL "Next >>", IDOK, "BUTTON", BS_PUSHBUTTON | BS_CENTER | WS_CHILD | \
WS_VISIBLE | WS_TABSTOP, 173, 44, 40, 12
CONTROL "", IS_PROGRESS_BAR, "msctls_progress32", WS_CHILD | WS_VISIBLE | \
WS_BORDER, 8, 4, 204, 10, 0
CONTROL "", IS_TEXT_A, "static", SS_LEFT | WS_CHILD | WS_VISIBLE, 7, 18, 160, 8, 0
CONTROL "", IS_TEXT_B, "static", SS_LEFT | WS_CHILD | WS_VISIBLE, 7, 28, 160, 8, 0
CONTROL "Help", IDHELP, "BUTTON", BS_PUSHBUTTON | BS_CENTER | WS_CHILD | \
WS_VISIBLE | WS_TABSTOP, 6, 44, 40, 12
CONTROL "Cancel", IDCANCEL, "BUTTON", BS_PUSHBUTTON | BS_CENTER | WS_CHILD |\
WS_VISIBLE | WS_TABSTOP, 125, 44, 40, 12
}
#endresource
Resources are all compiled as part of the preprocess during script startup. They can be spread anywhere within the source code and can be mixed with include files.
4.16.11 The #endresource Directive
The #endresource directive indicates the end of resources and tells the script engine to consider the code that follows as part of general script code.
Pragma (or from “pragmatic”) is a directive that tells the script engine to process or not process certain events, error or in a certain environment.
Form:
#pragma directive [options]
Where:
directive
Specifies a predefined action.
options
Optional string parameter which may or may not be required depending on the directive.
The actions types are as follows (they are case-insensitive):
AllowBreak
Allows the script to be broken with the Pause/Break key. When running in IDE mode, this is the default.
AppVersion version
Checks the ‘version’ string against the application. On failure, a message box is displayed and forces the script to exit. The version is in the form ‘0.0a’ or major version number, minor version number and release letter. This is one of only a few directives or functions that will result in an uncommanded message box on error:
C
Specifies a pragma comment. Pragma comments survive code crunching to allow non-program data to be included in the source file.
DebugTrace
When present, a debug trace file is created. If no additional parameter is provided, the debug trace file will be placed into the “LegatoLog” folder for the vendor in the application data folder (“%appdata%”). If a name is provided without qualified path, the path is added to the LegatoLog folder. If a full path is provided, the trace file is created at the specified location see Section 2.8 Debugging Tools for more information. Adding “Robust” prior to the filename will cause the file to be flushed on each log entry. This is useful if the application is crashing but it does significantly slow processing.
Disable
When present, the script will exit as if an “exit” statement was processed. This is useful to quickly disable a script.
NoSDK
Directs the script engine to dump the predefined terms with the SDK. If for some reason a developer decided that the SDK defaults were not appropriate, using this pragma resets the predefined values. Note that since this action resets the defined terms in the preprocessor, no defines can be placed prior to this directive. This directive does not remove the predefined data for resources.
ScriptVersion version
Checks the ‘version’ string against the script engine. On failure, a message box is displayed and forces the script to exit. The version is in the form ‘0.0a’ or major version number, minor version number and release letter. This is one of only a few directives or functions that will result in an uncommanded message box on error:
| Table of Contents | < < Previous | Next >> |
© 2012-2024 Novaworks, LLC. All rights reserved worldwide. Unauthorized use, duplication or transmission prohibited by law. Portions of the software are protected by US Patents 10,095,672, 10,706,221 and 11,210,456. GoFiler™ and Legato™ are trademarks of Novaworks, LLC. EDGAR® is a federally registered trademark of the U.S. Securities and Exchange Commission. Novaworks is not affiliated with or approved by the U.S. Securities and Exchange Commission. All other trademarks are property of their respective owners. Use of the features specified in this language are subject to terms, conditions and limitations of the Software License Agreement.