APIs available from Shockwave

Scripting languages differ, but the methods and properties that Shockwave makes available to them are identical. The following sections describe:

  • The methods and properties that the scripting environment can send to a Shockwave movie

  • The externalEvent Lingo command, which allows the movie to send messages to the browser

 
Lingo that communicates with the browser

Use the externalEvent command from within a movie to control external objects in the browser, including other Shockwave movies. This command has the form:

externalEvent "string"

Where string represents the browser instructions that the Shockwave movie sends.

This command doesn't return a value.

How the scripting environment interprets the string included with the externalEvent command depends on the scripting environment.

 
Using externalEvent in LiveConnect

In LiveConnect, the string is evaluated as a function call. For JavaScript, simply define a function called whatever you choose in the HTML header. In the movie, the chosen function name and parameters should be passed as the string parameter to externalEvent. Because the browser must interpret parameters as strings, you must enclose them in single quotation marks.

In HTML, use a statement similar to the following:

function AnyFunctionName(parm1, parm2) {
// script here
}

In the movie, use a statement similar to the following: 

externalEvent "AnyFunctionName('parm1', 'parm2')"
 
Using externalEvent in ActiveX

ActiveX handles externalEvent as an event. You can process this event and its string parameter the same as other events, such as an onClick event in a button object. Use a statement similar to the following:

externalEvent ("string")
In HTML, you can define a function to receive the event in the HTML header. Use a statement similar to this example in VBScript: 

Sub
    MovieName_ExternalEvent (aString)
    REM process the string
End Sub
 
Commands a browser can send to a Shockwave movie

 
Play()

This command starts the movie if it is stopped. When the movie starts, its on prepareMovie handler runs first.

This command has no effect on a movie that is already playing. For example, it doesn't restart a movie or run its on prepareMovie handler.

 
Stop()

This command completely stops the movie. However, the movie still redraws the Stage if another window passes over the movie.

Except for Rewind(), GotoFrame(), and GetCurrentFrame(), the movie doesn't generate or respond to events in this state until the movie receives the Play() command from the scripting environment.

This command runs the movie's on stopMovie handler when the movie stops. Lingo globals aren't preserved.

 
Rewind()

This command rewinds the movie.

  • If the AutoStart property is true, the movie then plays.

  • If the AutoStart property is false, the movie remains stopped.

 
GetCurrentFrame()

This command returns the number of the current frame. It works whether or not the movie is stopped.

 
GotoFrame(frameNumber)

This command instructs the movie to go to the specified frame. It works whether or not the movie is stopped.

 
GotoMovie(movieURL)

This command instructs the movie to go the specified URL, which may be relative. It doesn't work if the movie is stopped.

 
EvalScript(string)

This command calls an on EvalScript handler in the movie, which must be present for EvalScript() to work.

The on EvalScript handler can process the parameter string however you choose to specify it. If the movie does not contain an on EvalScript handler, the error string "handler not defined" is generated and returned to the calling browser script. No dialog box appears.

Specify return values by placing a return string statement at the end of the on EvalScript handler or executing a Lingo statement that returns a value.

 
Properties a browser can set in a Shockwave movie

 
AutoStart

This property determines whether or not a movie starts automatically when it loads on the web page and when Rewind() is called. Set the AutoStart property in the EMBED or OBJECT tag as an attribute; possible values are true or false.

  • If AutoStart is true, movies play immediately upon loading. This is the default for tags that do not specify this attribute.

  • If AutoStart is false, movies load and then stop.

    This property can also be set after the movie has been loaded on the page.

At the time this book was printed, the AutoStart property gives valid results for the following:

  • Netscape Navigator 3.0 and Internet Explorer 3.0 in Windows 95 or Windows NT 4

  • Netscape Navigator 3.0 on the Macintosh Power PC

  • Any other browser that supports the same functionality as Netscape Navigator 3.0 or Internet Explorer 3.0

On Windows 3.1 and standard Macintosh computers, the AutoStart property is always true, even if the EMBED tag attempts to set AutoStart to false.

Casa de Bender