Array

Author
Status	Released
Release Date	2006
Last Updated
Available for
Supported Runtimes
License	Free
Attributes	{{{Attributes}}}
Download
Includes Examples	Yes
Includes Help Files	Yes
Links	Included by default.
Alternates	INI Object Associative Array Binary Array ByteArray INI++ Object Dynamic Array MagicDeque

The Array object provides a convenient way to store a lot of data. It consists basically of a big array of value (or strings), and you can access each value or string individually with the actions and expressions in the event editor.

The Array object is a hidden object: it is not displayed on the screen. But when the application runs it is resident in memory and provides the user with loads of data storage.

The Array itself is a multi-dimensional array: it can count up to 3 dimensions (X, Y, and Z), being strings of integer values. The number of elements in each dimension is not limited. The only limit is the memory of your computer. Warning, a three-dimensional array can take a lot of space very quickly.

To insert an Array object in the application, simply use the Insert object dialog box, and choose Array Object. Drop it anywhere you like in the playfield: as the object is not visible, it will not change anything. We simply recommend for a better display of your application in the frame editor, to drop it out of the play area.

Properties

When you drop an Array object on the frame, or when you select it, the property toolbar displays its properties.

Dimensions

You can specify the size of each array dimension (dimension size should be greater than 0). These dimensions are similar to columns or row in a table. As you increase a dimension's size, more slots are created where data can be stored. Currently, only three array dimensions are supported. Since arrays are loaded in memory, having exceedingly large arrays (arrays with huge dimensional sizes) will generate a warning during edit time. Unused dimensions should have a size of 1.

X Dimension.

This numeric value defines the number of elements contained in the first dimension of the array. If you want to create a single dimension array, set the Y and Z dimensions to 1, and only change the X dimension.

Y Dimension.

This numeric value contains the number of elements contained in the second dimension of the array. If you want to create a two dimension array, set the Z dimension to 1, and change the value of the X and Y dimensions.

Z Dimension.

This numeric value contains the number of elements contained in the third dimension of the array.

Numeric or Text?

This property specifies what kind of data the array will hold during runtime. Numeric arrays hold only numbers (integers and floats) while text arrays hold only text.

Type of array.

Indicates whether the array consists of numbers (Integer numbers, stored on 4 bytes) or of strings (unlimited length). If you choose one type of array, you will not be able to change it during the application runtime. If you need both numbers and strings, simply drop two Array objects on the frame.

Options

Base 1 Index

Base 1 index. This property is quite important: if tells the array object if the first element of the array is referred to by 0 or by 1. For example, imagine a three dimension array, if Base 1 Index is selected, the first element will be the one at coordinates ( 1, 1, 1 ). If it is not selected, it will be ( 0, 0, 0 ). Programmers usually prefer a 0-based index.
By default, the first index (slot) of a dimension starts at 0. If you wanted to reference the first element in a one-dimensional array, the index would be 0. Checking this option makes the first index 1. It is recommend against checking this option for consistency within Fusion.

Global Array

This very powerful property allows you to make the array global to the entire application. Values or strings will be transferred from one frame to another. You can have several global arrays in your application, just use different names. The content of the array will be transferred only to arrays with the same name and with the "Global Array" property checked.
By default, data within an array is discarded after the array is destroyed (such as when a frame ends). When checked, the data within an array is saved across all frames of the application. Other Array Objects with the same name can access this global data. You may have multiple global arrays within an application.

Conditions

The Array object contains conditions to test the value of the internal indexes: you can know if the index has reached the limit of its dimension.

Is the index to the dimension X at end?

This condition is true when the internal X index has reached the end of the elements of the X dimension. Example, if your dimension contains 10 elements, this condition will be true when the value reaches 10 (for zero-based indexes).

Is the index to the dimension Y at end?

Same as before, but for the Y index and the Y dimension.

Is the index to the dimension Z at end?

Same as before, but for the Z index and the Z dimension.

Actions

The Array object contains a lot of actions for you to set or change the values contained in the object.

Clear array.

This action erases the content of the array. If the array contains numbers, they are all set to zero. If it contains strings, the memory used by the strings is freed, and the array only contains empty strings "".

Write

Write value to X.

This action is to be used with arrays defined with one dimension only (X). This action asks for the value to write and the X index where to write the value. It modifies the value at the given index.

Write value to XY.

This action is to be used with two dimensions arrays. It asks for the value to write and the X and Y indexes where to write the value. It modifies the value at the current indexes.

Write value to XYZ.

This action is to be used with three dimensions arrays. It asks for the value to write and the X, Y and Z indexes. It modifies the value at the current indexes.

• Note: the three previous actions only work with arrays containing numbers.

Write string to X.

This action only works with one dimension arrays. It asks for the string to write and the X index. It writes the string at the given position.

Write string to XY.

This action only works with two dimensions arrays. It asks for the string to write and the X and Y indexes. It writes the string at the given position.

Write string to XYZ.

This action only works with three dimensions arrays. It asks for the string to write and the X, Y and Z indexes. It writes the string at the given position. Note: the three previous actions only work with arrays containing strings.

Write value to current position.

The array object contains internal indexes that you can modify with actions listed below this paragraph. This action writes a value at the position defined by the internal indexes.

Write string to current position.

Same action, but for strings: it writes the string at the position defined by the internal indexes.

Change current position

As said before, the Array object contains internal indexes that you can use to store data with. Use the two previous actions to do so. This submenu contains actions to change the value of the current position indexes.

Set X dimension index to...

Changes the value of the internal X index.

Set Y dimension index to...

Changes the value of the internal Y index.

Set Z dimension index to...

Changes the value of the internal Z index.

Add 1 to X dimension index.

Adds one to the X index. Very useful if you are making a loop to explore all the elements of the dimension.

Add 1 to Y dimension index.

Adds one to the Y index.

Add 1 to Z dimension index.

Adds one to the Z index.

Files

The files submenu contains actions that allow you to save and load the content of the array.

Load array from file.

This action asks for one parameter: the filename of the file to load. You can use the file selector or enter an expression. It loads into the array a file previously saved by it. Each dimension is resized to match the dimensions of the array in the file, and all the elements are replaced by the new ones. Load an array from file via a file selector. This action will open a file selector at runtime, asking for the name of the file to load. As for the previous action, it has to be a file previously saved by the object.

Save array to file.

This action asks for a filename parameter. It saves the complete content of the array, each value, each string is saved. Use the previous actions to reload the array.

Save array to file via a file selector.

This action opens a file selector at runtime, asking for the name of the file to create.

Expressions

The Array object contains a lot of expressions to retrieve the data contained in the array.

Current position of the X index.

index x( "Array" )

Returns the value of the internal X index.

Current position of the Y index.

index y( "Array" )

Returns the value of the internal Y index.

Current position of the Z index.

index z( "Array" )

Returns the value of the internal Z index.

X Dimension.

DimX( "Array" )

Returns the size (number of elements) of the X dimension.

Y Dimension.

DimY( "Array" )

Returns the size of the Y dimension.

Z Dimension.

DimZ( "Array" )

Returns the size of the Z dimension.

Read value from X position.

ValueAtX( "Array", >Enter X offset< )

This expression returns the number value contained at a specific position in a one dimension array. It asks for the index in the X dimension.

Read value from XY position.

ValueAtXY( "Array", >Enter X offset<, >Enter Y offset< )

This expression returns the number value contained at a specific location in a two dimensions array. It asks for two parameters : the index in the X and Y dimensions.

Read value from XYZ position.

ValueAtXYZ( "Array", >Enter X offset<, >Enter Y offset<, >Enter Z offset< )

This expression returns the number value contained at a specific location in a three dimensions array. It asks for three parameters: the index in the X, Y and Z dimensions.

Read string from X position.

StrAtX( "Array", >Enter X offset< )

This expression returns the string contained at a specific location in a one dimension array. It asks for one parameter: the index in the X dimension.

Read string from XY position.

StrAtXY( "Array", >Enter X offset<, >Enter Y offset< )

Returns the string contained at a specific location in a two dimensions array. It asks for two parameters: the indexes in the X and Y dimensions.

Read string from XYZ position.

ValueAtXYZ( "Array", >Enter X offset<, >Enter Y offset<, >Enter Z offset< )

Returns the string contained at a specific location in a three dimensions array. It asks for three parameters: the indexes in the X, Y and Z dimensions.

Read value from current position.

current value( "Array" )

Returns the value contained at the position referred to by the internal indexes of the object.

Read string from current position.

current str$( "Array" )

Returns the string contained at the position referred to by the internal indexes of the object.

Advantages

• Saves and loads data faster than the INI Object
• Difficult to externally manipulate array files
• Extremely easy to find each data element in an array
• Array can be global across frames
• Overall smaller disk size
• Array exist in internal memory rather than just a local file
• All array operations executed on data in memory
• Easy to iterate through the array

Disadvantages

• No way to explicitly decrease size of array during runtime through actions
• Concept of arrays difficult to grasp for newcomers and those unfamiliar
• Large arrays can take up increasingly huge amounts memory (can cause entire applications to crash)
• Indices are only addressable by numbers (not so much of a disadvantage, but takes time to get used to)

Tips & Tricks

• If your array can store something other than numbers, use a text array instead of a numeric array. You can always use Val(<MyStringHere>) to convert numbers within string into a numerical value.

Further Reading

Here are some links around the web:

• The Basics of Saving Data in Multimedia Fusion 2 and Clickteam Fusion - Xable

Contributors to this page

Advaith (60.2%), Lh37 (4.0%), ProdigyXable (35.8%)