Project members: Constant

With a constant member you can define a global immutable value. You use constants typically to store strings (text) or frequently used configuration parameters like colors, etc. Constant members are represented in Composer by following bricks:

Every constant has an explicitly specified data type (e.g. string, color or bool, ...) and an initialization expression. Because of its nature the expression has to result in an immutable value and it can be determined only at the design time. Constant members can also be localized with several initialization expressions, one for every supported language. This capacitates the constant to automatically offer the value corresponding to the currently selected language.

Please note, a constant member can exist only within a unit member.

Add new constant

First switch to the Composer page for the respective unit member you want to add the new constant member.

Then, in the Gallery window, ensure that the folder Chora is opened.

Look in the folder for the template named Constant.

With the mouse, select the template and drag it into the Composer.

Drop the template within the Composer.

Adding a new constant member.

Name the constant

First ensure, that the constant member is selected.

Press the key F2 or select the menu item EDITRename ....

Enter the new name in the Inspector window.

Constant members have a global character - they can be accessed from everywhere within your project. To address a constant member, you must always use its full name, which is composed of the unit name, the member is defined inside, and the name of the member name itself, both separated by :: (double colon) signs. For example Widgets::LabelColor.

Determine the data type of the constant

Every constant expects the data type to be specified explicitly in its attribute ConstantType. Accordingly, the constant can be initialized with values matching this type declaration only. Please note, new added constants are configured per default with the data type string.

Determine the value of the constant

The value of a constant is determined by the initialization expression specified in its attribute Values. Please note, the resulting data type of the expression must match the type declaration of the constant.

Localize the constant

You can specify several, individual initialization expressions for the Values attribute, one for each language available in your project. The appropriate value is selected dynamically at the runtime when the constant is evaluated within a Chora expression. The selection is controlled by the global variable language.

If you haven't specified any particular language specific value for the constant, the value from the fallback language Default is used automatically.

Duplicate an existing constant

You can create any number of copies of an already existing constant member.

First ensure, that the constant member is selected.

Press the keys CtrlC and CtrlV in succession ...

... or hold the key Ctrl pressed while you drag and drop the selected constant member.

Finally rename the just duplicated constant member.

You can also Drag & Drop a constant member from the Browser into the Composer window and create so a duplicate of the affected member:

First switch to the Composer page for the respective unit member, where you want to add the duplicate of the constant.

Then ensure that the Browser window is visible.

Within the Browser window locate the desired constant member. This can be done easily with Browser's own filter function.

Select this constant member in the Browser window.

Drag and drop the selected constant member into the Composer:

Duplicating a constant by simply Drag & Drop it between the Browser and Composer windows

Finally rename the just duplicated constant member.

Use the constant

Once defined, the name of the constant member can be used within Chora expressions wherever an operand with the data type matching the constant's declaration is expected. At the runtime, the expression evaluates and calculates with the value of the constant. To address a constant, it must be always a full name, composed of the unit name, the constant member is defined inside, and the name of the member itself, both separated by :: (double colon) signs. For example:

// Initialize the local variable with the value of the constant // 'Widgets::LabelColor' var color labelColor = Widgets::LabelColor;

Please note, if the constant is localized for multiple languages, the right value is determined just at the evaluation time of the expression involving the constant. Let's assume, your project contains a constant Widgets::YesText localized for the both languages French and English, then the constant will result in different values depending on the currently selected language:

// Switch to the default (English) language language = Default; var string text1 = Widgets::YesText; // Switch to the French language language = French; var string text2 = Widgets::YesText; trace text1; // "Yes" trace text2; // "Oui"

Derive a variant of a constant

Every constant member can be overridden by one or more constant variant members. Once overridden, the variant member can retrospectively modify the initialization expressions of the original constant member. The derivation of variants provides the fundamental technique to manage several product and design variants within one and the same GUI application. The selection of the appropriate variant occurs automatically depending on the condition specified in the VariantCond attribute of the corresponding variant member.

Control the code generation

With the attribute Generator you can selectively control, whether the constant member should be taken in account during the code generation or not. Configuring this attribute with the value false will exclude the member from your project unless the member name is explicitly involved within a Chora expression.

With the attribute Storage you can selectively specify the location where data belonging to the constant should be stored. The data can be stored directly in the generated code or in a separate so-called Blob file. Unlike the first option, the Blob file can be replaced and so the contents of the constant can be exchanged retrospectively without needing to rebuild the binary.

Delete a constant

First ensure, that the constant member is selected.

Press the key DEL or select the menu item EDITDelete.

Attributes of a constant

The following table shows the complete list of attributes provided by the constant member:

Attribute name

Short description

Brick

Determines the position and the size of a constant member brick within the Composer window.

ConstantType

Determines the data type of a constant member.

Description

Contains the description for the constant member.

Generator

Controls the code generation for the affected constant member.

Storage

Controls the storage location for data belonging to the constant

when generating code.

Values

Determines the values for a constant member.

Chora syntax of a constant

This section describes the Chora syntax of how constants are stored inside Embedded Wizard project files. The knowledge about the syntax can be helpful when you plan to process the project contents by third party tools. In particular, the general purpose Export and Import functionality introduced in version 14 requires a good understanding of how project members are represented in Chora syntax to correctly interpret the exported members and synthesize the Chora code for members to import. Please note, Embedded Wizard project files (and thus Chora code) are encoded as text in UTF-8 format.

In Chora syntax, constant definition is always introduced with the keyword const, followed by the data type, the name and the value of the constant. The name and the value are separated by an assignment operator = and the complete constant definition terminates with ; semicolon sign. Wherever necessary, the tokens are separated by whitespace signs. Being a constant, the specified value has to be immutable and it has to match the data type of the constant. The data type corresponds to the value of the attribute ConstantType. The value corresponds to the content of the attribute Values.

A constant may be localized for multiple languages. It this case the constant contains multiple values, each composed of a language name and the corresponding value. Each language name and the corresponding value are separated by an assignment operator = and terminated with ; semicolon sign. All language specific values are enclosed between a pair of parenthesis (..). Please note that every language-dependent constant must contain a value for the Default language.

The definition of a constant can be initiated by a comment block providing optional description for the constant. The content of this comment corresponds to the value of the constant's attribute Description. Furthermore the directives $rect, $output and $storage can be specified providing values for the corresponding attributes Brick, Generator and Storage. The following examples demonstrate the described syntax:

// This is a non-language-dependent constant containing a 'color' value. // // $rect determines the position of the brick inside Composer window. // $output imposes the code generation of the constant regardless of its \ // usage inside the project. $rect <10,10,210,50> $output true const color DefaultBackgroundColor = #FF0000FF; // This constant contains 'strings' localized for the language 'German' \ // and 'Spanish'. The language 'Default' represents the value for all other \ // languages. // // $rect determines the position of the brick inside Composer window. // $storage indicates the content of the constant to be stored in a Blob file. $rect <10,10,210,50> $storage Blob const string LocalizedConstant = ( Default = "Video Settings"; German = "Bildeinstellungen"; Spanish = "Configuración de vídeo"; );

Each Chora file (or text exchanged with an external Export and/or Import tool) can be (or even should be) prefixed with $version directive. This directive determines the version number of the included Chora code. For details concerning the syntax of the version please see the chapter $version macro. Furthermore, the code can include a $scope directive followed by a path to a project member acting as the original owner of the corresponding code. That means the members described by the Chora code existed inside the member specified in $scope. In case of a constant, $scope would specify the name of the unit the constant belongs to.