Project members: Array

The member array is intended to store state information within a component, similarly to a variable, but unlike variables, one array can manage multiple values (items) at the same time. Every array has an explicitly specified data type (e.g. string, color, bool, ...) determining the possible content of the array and optional expressions to individually initialize the array items. Arrays are represented in Composer usually by following bricks:

An array can be defined within a class or class variant only. If one class is derived from another class, all arrays defined in the ancestor classes are inherited implicitly. In the derived class the inherited arrays can be overridden individually with new initialization expressions for their items.

In order to preserve the clarity, all arrays inherited from a base class but not overridden in the actual class are not shown as bricks in the Composer. The Inspector, in turn, shows always the complete list including all inherited members. If you are looking for a particular inherited array, use the Inspector for this purpose. Please note, inherited but not overridden arrays are shown in Inspector with gray thin font:

Inherited but not overridden arrays appear only in the Inspector window. They are shown with thin gray font.

If an inherited array has been overridden, Inspector shows it with dark gray font. Additionally, overridden arrays appear as bricks in the Composer window. You can distinguish easily, whether an array is overridden or whether it is new by considering the font color in its brick. New arrays are shown with black font. Overridden arrays, in turn, with gray font:

Overridden arrays appear in Inspector with dark gray font. They are also shown as bricks in Composer, again with gray font.

Arrays are ideal to store runtime state information. If there are several instances of one and the same class existing, every instance will manage its own copy of arrays. In object-oriented sense, arrays are the attributes or the fields of an object.

Add new array

First switch to the Composer page for the respective class or class variant definition, where you want to add the new array.

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

Look in the folder for the template named Array.

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

Drop the template within the Composer.

Adding a new array member.

Name the array

First ensure, that the array member is selected.

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

Enter the new name in the Inspector window.

Arrays have a local character - they can be accessed only in context of an instance of the class, in which they are defined. To address an array, you use its name. Please note, the name of an inherited array can't be changed retrospectively in the derived class.

Determine the data type of the array

Every array expects the data type to be specified explicitly in its attribute Type. Accordingly, the array items can store values matching this type declaration only. Please note, new added arrays are configured per default with the data type string. Moreover, the data type of an inherited array can't be changed retrospectively in the derived class.

Determine the size of the array

Every array expects the size (the capacity) to be specified explicitly in its attribute Dimension. The size determines how many items the array can store. Please note, new added arrays are configured per default with 4 items. Moreover, the size of an inherited array can't be changed retrospectively in the derived class.

Determine the initialization values for array items

With the attribute Items you can specify expressions to initialize the items of an array - individually for every item. If an expressions is omitted, the corresponding item will retain its original value. This means in particular for new added arrays, that the item retains a zero value corresponding to the data type of the array (an empty string, a transparent color, boolean value false, ...). Please note, the resulting data type of an expression must match the type declaration of the array.

Control the initialization order

At the runtime, when new instance of a class is created, all items of arrays defined within the class are initialized automatically with their corresponding initialization expressions. This initialization is performed strictly in the order in which the members are defined within the class, starting with the back most member (the member with the lowest order number).

The actual order of a member can be verified in the members area of the Inspector window. To change the initialization order you need to explicitly restack the member. This, however, is necessary only in cases, when one array item is initialized with expression containing as operand another member. This 'operand' member, in such case, has to be initialized first.

Localization

With the attribute MultiLingual you can configure a class to handle as far as possible the language selection by itself. If this attribute is true, Embedded Wizard will automatically re-evaluate all initialization expressions, which involve multi-lingual operands. For example, if an array item is initialized with a localized constant, the initialization expression is re-evaluated and the resulting, eventually different constant value is re-asigned to the array item automatically.

Duplicate an existing array

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

First ensure, that the array member is selected.

Press the keys CtrlC and CtrlV in succession ...

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

Finally rename the just duplicated array member.

Override an inherited array

When an item of an inherited array is modified, the array will automatically become overridden causing its brick to appear in Composer. The Inspector shows overridden arrays with dark gray instead of thin font as explained above. You override an array if you want the array items to be initialized with expressions different to those specified in its inherited version.

Revert to inherited array value

If you want to revert an overridden array to its original inherited state, delete it simply. Thereupon, its brick disappears from the Composer and the Inspector shows the variable name with thin font again. In turn, to revert a single item to its inherited value, select the item and press the keys CtrlR.

Use the array

The array items can be evaluated within Chora expressions wherever an operand with the data type matching the array's declaration is expected. Similarly, the items can modified individually in assignment operations. To address an item, you use the name of the array followed by the index of the desired item.

In case of one-dimensional arrays, the index must be an expression resulting in an unsigned integer value and it must be enclosed between a pair of [...] (squared brackets). Arrays are always used in scope of the object, the array belongs to. If no scope is specified, the operation is considered as being performed in context of this object. For example:

var int32 inx;

// Increment all items within the array 'numbers' of 'this' object
for ( inx = 0; inx < numbers.size; inx = inx + 1 )
  numbers[ inx ] = numbers[ inx ] + 1;

// Increment all items within the array 'numbers' of a foreign object
for ( inx = 0; inx < someObject.numbers.size; inx = inx + 1 )
  someObject.numbers[ inx ] = someObject.numbers[ inx ] + 1;

In case of a multidimensional array, the index must be a , (comma) separated list of unsigned integer expressions enclosed between a pair of [...] (squared brackets). The number of expressions must correspond to the specified dimension of the array. For example:

var int32 col;
var int32 row;

// Assuming, there is a two-dimension array 'tiles' defined with
// its Dimension configured as '10, 20', then the following loop
// will iterate through all items of the array and initialize
// them with random values:
for ( row = 0; row < 10; row = row + 1 )
  for ( col = 0; col < 20; col = col + 1 )
    tiles[ row, col ] = math_rand( 0, 100 );

Please note, to obtain the size of an array, you can use the size instant property.

Control the code generation

With the attribute Generator you can selectively control, whether the array 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 an array

First ensure, that the array member is selected.

Press the key DEL or select the menu item EDITDelete.

Please note, inherited arrays can't be deleted. However, if an array is overridden you can delete this overriding.

Attributes of an array

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

Attribute name

Short description

Brick

Determines the position and the size of an array member brick within the Composer window.

Description

Contains the description for the array member.

Dimension

Determines the number of items within an array member. Please note, this attribute can't be modified if the array is inherited.

Generator

Controls the code generation for the affected array member.

Items

Determines the initial values for array items.

Type

Determines the data type of an array member. Please note, this attribute can't be modified if the array is inherited.