Declaring a configurable text file

!text

Declare a configurable text file

Syntax

!text textfile_id “filename”

Declare a file of configurable text for the program.

textfile_id

The identifier by which the text is to be referenced within the program.

“filename”

This must be a language file located in the $SCULPTOR/text directory. The extension (.eng, .esp) should not be included in the filename.

The use of configurable text files enables quoted text within the program to be obtained from a specified file, rather than being hard-coded. This is particularly valuable for the purpose of enabling the same program to be run in different national languages without the need to amend the program code. All headings, messages and on-screen help can be made to appear in the chosen language.

The use of configurable text files is however by no means restricted to language translation. The system may be used in any circumstances where it is desirable to vary the contents of quoted strings within a program.

Several text files may be declared within a program, each of which must be given a textfile_id unique within the program.

The text files are located in the directory $SCULPTOR/text. Frequently they provide different language translations of the same text. A group of related text files bears the same name, with only the extension differing. The extensions indicate the language or other nature of the text file. Configurable text files for the Sculptor program designer spd might be:

spd.eng

English text

spd.esp

Spanish text

spd.fra

French text

The text file extension - SCTEXT

The extension is determined at run time. Normally it is set to the value of the environment variable SCTEXT. When a program loads, the current value of SCTEXT is stored in the system variable sys.Text.

If SCTEXT has not been set, or if the specified filename does not exist with the extension represented by SCTEXT, then the default extension .eng is used. If the default file does not exist, then the program cannot be run.

Accessing text from within a file

An item from a text configuration file may be used anywhere in the program where a string within quotes would be legal. The syntax to call an item is:

textfile_id[integer]

textfile_id is the identifier of a configurable text file that has been declared in the program, and integer specifies the text item required from within that file. textfile_id[integer] is replaced by the string defined as string integer in the configuration file. If the text item does not exist, a blank string is returned.

NOTES

  • Only one text file extension may be in force at any one time. The exception to this occurs when an extension other than .eng is being used, and not all the files declared exist with that extension, causing the standard English defaults to be used.

  • The name of the file specified in a ![o]file or !text declaration may not be configurable text, but must be hard-coded. These are exceptions to the rule that wherever quoted text is valid in a program’s code, configurable text may be used.

  • For clarity it is recommended that !define be used to attach meaningful names to text subscripts, as is shown in the example below.

EXAMPLE

!text Sculptor "sculptor"
!text MyText "mytext"

!define PLEASE_TYPE_YOUR_NAME 1
!define PLEASE_TYPE_YOUR_AGE 2

     +textbox NameBox at 20,20 {
          caption = MyText[PLEASE_TYPE_YOUR_NAME]
          ...
     }

RELATED TOPICS

The configurable text editor sctextw

sys.Text