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.

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.

Values

Determines the values for a constant member.