Types

All data - in particular properties and functions' parameters - need to be of a certain type. Essentially, this is a convention you know from everyday's life. There are some information which are always a number - e.g. the phone number. Then there are other information which are always words, e.g. a person's name.

Furthermore, there are some sub-types. E.g. a phone number will always follow a specific pattern (per country), a zip code - which in many countries is also a number - will follow another pattern. If you, by accident, dialed a person's zip code instead of their phone number, most likely you will get no connection (which at least gives you immediate feedback that something is wrong), but in rare cases you might even get connected. But most likely not to the person you intended to speak to. Hence, the most important lesson is: types matter. Passing the wrong type of a parameter to a function will lead to wrong results, and most likely to errors (in which case usually the macro does nothing).

And: there are more complex types as well. Imagine the data type 'address'. An address in real life comprises of a street name, a house number, a zip code, a city, and maybe a few more details. in general, such complex data types are refered to as objects or structures, and it is important to know the details of how they are composed.

Here, we only very briefly try to explain the various types you might come across when writing macros. Please feel free to refer to countless programming literature if you are interested in more details.

As types are that important to adhere to, and as functions are very picky about what they want to get as input and what they maybe return, there are means to convert data from one type to another. This is called type casting. While this is a good thing in order to provide the correct data type, this invokes the next challenge: conversion rules. Some are easy to understand, e.g. casting an integer value to a float. Others aren't: what rule would you suggest to cast the string “Moving Light” into an integer value? But usually you shouldn't need to bother. Just use the appropriate casting function, e.g. in the example Chase - Change a chaser's overlap.

Another example about when and when not to reference types: http://forum.avolites.com/viewtopic.php?f=20&t=5766#p20783

The ActionScript.SetProperty function can be used to set a value of any type, as the parameter type Object is the root class for all types including non-reference types (e.g. integers, floats). The ActionScript.SetProperty.Integer function only accepts an integer as the second parameter which can have the advantage when parsing input this can be assumed and so the correct type is chosen (particularly in WebAPI). However you can force a conversion by using casts which can work where automatic conversion is not possible for example:

ActionScript.SetProperty("Windows.Playbacks.FixedColumns", int:"5")

will work where

ActionScript.SetProperty.Integer("Windows.Playbacks.FixedColumns", "5")

will not.

The ActionScript.SetProperty.Enum function takes a string as the value parameter and internally converts that string to the correct enumeration type based on the current value of the property being set. WebAPI does something similar when initially parsing values but uses the function parameter type to determine this however as there are many enumeration types there is not a SetProperty function for each one as this would be impractical. You could do the following:

ActionScript.SetProperty("Windows.Playbacks.ButtonSize", 
  Math.ToEnum(
    "Avolites.Titan.Controllers", 
    "Avolites.Titan.Controllers.HandleButtonSize", 
    "Fixed")
  )

but that is very long-winded in comparison to the ActionScript.SetProperty.Enum function.

And another hint: casting doesn't work inside code blocks, see http://forum.avolites.com/viewtopic.php?f=20&t=5783:

It appears that you cannot use the cast operator within a statement block. It tries to get the function being called but cannot find it inside the statement block.

Here is a list of the primitive types covered in this wiki: