Events, parameters, properties and actions
<<< previous section: IntroductionEvents
Programming in the mediascape toolkit is 'event based'. This means any code you write will be triggered by a particular event. All mediascape objects have associated event tabs displayed in the Script window. So for example the top level Mediascape object has an 'Onloaded' and 'OnUnloading' event; an audio file has an 'OnStarted' and 'OnFinished' event; a region has an 'OnEnter' and 'OnExit' event and so on. Select the appropriate tab and add your code in the script window and it will be run when the event occurs. The event names should be fairly self-explanatory; so whenever you add an object to your mediascape it's a good idea to look at the associated event tabs to get a better understanding of the actions that can be taken with it. Events will be the starting point of any interaction and therefore any programming you do.
Parameters, Properties and Actions
Parameters
Each event has associated 'parameters' which can be viewed by opening the 'Parameters Window' (click the toggle button to open this). Some parameters are specific to a type of event - for instance the GPS 'OnLocation' event has an x and y parameter which can be used to access the updated x and y coordinates of the user. However, for the most part the only parameter available is 'me', which is basically a short cut to accessing the object that triggered the event. To test this out type 'me' into the script window and follow this with a full stop. A pop-up window will appear with a list of words. Now delete 'me.' and try typing the name of the object the event belongs to followed by a full stop. So if you originally typed 'me.' into the OnEnter event of a region called 'myRegion' try typing 'myRegion' followed by a full stop. You should see the same pop-up window with the same list of words. Finally go to an event that does not belong to 'myRegion', let's say the OnStarted event of an Audio track. Type 'myRegion' followed by a full stop - you'll again see the same pop-up. Now try 'me' followed by a full stop - this time the list will be different. So what is this pop-up list about?Properties and Actions
As well as associated events, each object you add to your mediascape may have associated properties or actions. To make things easy for you the mscape toolkit lists those available for a particular object whenever you type its name (or 'me'), followed by a full stop, in the script window. You can then use the mouse or cursor to select from the list, or start typing the name of a property or action. You'll notice that when you select from the list another pop-up will appear with a description of the currently selected item. This tells you whether it is a property or an action and gives you further information and an example of it in use. If you hit return (or double-click) the property or action code will automatically be added into the script window using the correct syntax.| The complete list of properties and actions for an Audio object:  |
The icons to the left represent the type:  |
Actions are things you can do with an object: for example you can play, stop or pause an audio track. Notice that when you add an action from the pop-up it is always followed by curved brackets: (). When looking through your code you can use this convention to distinguish between object properties and actions. You should hopefully have realised that some events will only ever be triggered if a certain action is carried out first. For instance the OnFinished event of an audio will only ever happen if the audio is first played.
One final point to notice here is the distinction between using 'me' and an object name. 'me' is convenient if you're accessing the object that triggered an event, but you'll often want to start an action on another unrelated object, in which case you need to use that object's full name. A good example is playing an audio when someone enters a region: in the region's OnEnter event you type the name of the audio followed by the 'Play' action: myAudio.Play();.
Variable and property types
Properties belong to specific objects, but there are times when you might want to store a value independently of an object. This is where variables come into play. One important factor you will notice on reading the linked page is the issue of the type of variable you use. As with variables, properties come in different types and it's important to know what type you're dealing with: if you need to store it in a variable you need to use a matching type and type is also important when comparing properties and variables.Next section: Reading parameters, properties and variables >>>
