Personal tools

Scripting Events

From RadiWiki

Jump to: navigation, search

This is the starting point for learning about scripting in Radi.

Writing scripts in Radi requires a basic understanding of JavaScript, the web's standard programming language. There is a tremendous amount of JavaScript learning resources on the web, so this document won't attempt to cover the whole language here. Even if you're a complete beginner at programming, you can get started with simple commands now and move on to more advanced topics later.

Radi is a great place to start learning some JavaScript because you don't have to write a whole web application in JavaScript; there's a lot you can do by attaching small bits of JavaScript code to specific events like mouse moves and clicks. This lets you accomplish essential interactive features like "when the user moves the mouse over a particular element, pause the animation; if the user clicks the mouse button, move to a specific frame and start playing again".

What you'll find below are mostly "scripting recipes". Instead of an trying to cover all the topics from fundamentals on up, this document will demonstrate some essential techniques using practical examples.

Do you have a topic in mind that really ought to be covered here? Please send email to pauli (at) lacquer (dot) fi, and I'll do my best to answer.


Contents

How scripts relate to events

Most interaction in Radi is based on the concept of event scripts (sometimes called event handlers). These are pieces of JavaScript code that get executed once the event in question takes place. For example, when a "click" event script is attached to a Canvas element, the event script will run whenever the user clicks on the element.

There are two places where event scripts can be attached in Radi:

Top-level elements. Any top-level element (Canvas, Video, Block, etc.) can contain scripts to handle interactive events like user mouse clicks.

Timeline events. These are events that occur on the timeline. You can create any number of them as needed. A timeline event is always associated with a specific frame, and the event script is called when playback enters that frame.

This illustration shows where these event scripts can be edited in the user interface.

Radi event script types.png


Redirecting to another website

One of the most common things to do on a click is to redirect to another web page. This is simple to achieve using a standard JavaScript property called window.location:

Interactive-click-window-location.png


The window object always represents the current browser window in JavaScript. Setting its location property to a new URL will redirect the web browser to that URL.


Pausing the timeline

Scripts can access the current Radi document to control its playback and access its content, for example layer data. This access is provided to event scripts using an object called simply 'radi', which has a number of methods that event scripts can call.

The 'radi' object is provided to element event scripts as a property of the event object, i.e. event.radi. To stop playback, you would call the stop method like this:

Radi-clickevent-stop.png


To resume playback, you would similarly call: event.radi.play()


Moving to a different frame

Scripts can jump to a different frame on the timeline. A common use for this feature is to place independent animation sequences on the same timeline. When one sequence ends, it will pause the timeline and wait for some user input. An event script will then jump to a different frame and restart playback.

Jumping to another frame works very similarly to the stop/play example given above: event.radi.goToFrame(frameNumber)

The following is a slightly more complex example of an event script. The timeline is moved to a different frame depending on whether the user clicks on the left or right side of a canvas element. This is accomplished by checking the event.offsetX property, which gives the horizontal mouse position (X coordinate) within the element. There is naturally also an event.offsetY property that you can use to read the vertical position.

Because this script is longer than one line, we should place it in the scene root object rather than putting it directly in the Inspector. This is good practice because it ensures that all your longer scripts can be found in one place. The scene root is an object that you can access everywhere in your Radi document via env.scene and it's designed for storing custom scripts only. The event script will simply call the method in the scene root:

Radi-clickevent-canvasclicked.png


The method looks like this -- the use of event.offsetX to determine where the user has clicked:

Radi-clickevent-canvasclicked-sceneroot.png


The name of our custom method is canvasClicked. This could be anything. In a real application you'd probably want to use some more descriptive name that relates to your content.

Note how in the event script, we wrote env.scene.canvasClicked() to call this method, but in the Script Editor the name of the method is given as this.canvasClicked(). The different format because JavaScript's this object is special: it always refers to the current object, whatever that may be. In Radi, it's standard practice that your scripts are associated with this so that Radi is free to work out where the scripts are eventually placed when published.

In the Script Editor it's easy to tell what the this object refers to: it's written just above the editing area ("Displaying script for...").