AW Interfaces | AW Methods | AW Types and Misc API


Director 6.0/Authorware 4.0 Xtra Development Kit

Authorware Developer's Guide


rev: 3/97

Introduction

The Authorware support API provides ways for Xtras to access the Authorware object model to access icons, call functions, and access variables. Additionally, Authorware Xtras can define and generate specific events to interact with the icons in a presentation, and can store and retrieve themselves when the user pauses and resumes a presentation. Xtras can also subscribe to and be informed of events that occur in Authorware.

Authorware Services

The Authorware service callbacks are a set of interfaces that provide access to objects representing internal data structures of Authorware. Through these interfaces, you can directly manipulate certain features of Authorware pieces.

This discussion begins with an overview of the Authorware object model and how it shapes the interfaces provided by the Authorware services. The overview is followed by a detailed look at the interfaces to the model, describing how to use the Authorware features available through them. Next, there's a discussion of several supporting interfaces provided by the Authorware services API. Finally, there are several examples of accessing and using Authorware services.


The Authorware object model

To allow Xtras to manipulate pieces and their contents, the Authorware service callbacks represent two objects of Authorware's internal model, the player and the piece.

The player can be the Authorware authoring application, a packaged Authorware piece, or Shockwave for Authorware. A player can have one open piece at a time.

Authorware's callback object provides a number of interfaces including standard MOA callbacks. The Authorware callback interfaces include the general interface IMoaMmUtils (described in the Multimedia Developer's Guide).

The callback object also provides the IMoaAwPlayer interface. This interface represents the player at the top of the Authorware object model. To get the IMoaAwPiece interface for a piece object, you call the IMoaAwPlayer::GetPiece() method. The remainder of this chapter describes various techniques for accessing and interacting with these Authorware objects.


Using the Authorware object model

This discussion looks at the two interfaces of the Authorware object model, describing how you acquire these interfaces and detailing the behavior available through each of them.

The IMoaAwPlayer interface

The IMoaAwPlayer interface is provided by Authorware's callback object. Authorware provides an instance of this interface through the callback object. Methods of the player interface let you retrieve the active piece's interface (GetActivePiece()) and close a Windows MCI sound driver (CloseSoundDriver()).

Acquiring IMoaAwPlayer

To get access to the application's single instance of IMoaAwPlayer, you call QueryInterface() on any Xtra object's pCallback instance variable.

The IMoaAwPiece interface

The IMoaAwPiece interface is used to represent presentation objects in the Authorware framework. You can acquire this interface for any active piece, and use the interface to access various features of the piece it represents. This interface supports access to icons, access to palettes, and access to graphics contexts for the presentation window in which the piece is drawn. It also provides scripting support.

Acquiring an IMoaAwPiece interface

The IMoaAwPlayer interface provides the GetActivePiece() method for acquiring the interface of the currently active piece. A sprite asset Xtra can access the piece it belongs to through the IMoaAwSpriteCallback::GetPiece() method.


Icon access

Icons in authorware are accessed by an icon ID, a unique number assigned to the icon when it is added to a piece. Using the API provided by IMoaAwPiece, you can get the unique ID for any icon, then use it to access the media of the icon and to get or set values of any variables in the icon.

The IMoaAwPiece::GetIconId() method returns the icon ID for any named icon. To access the variables in an icon, call the IMoaAwPiece::GetVariable() and IMoaAwPiece::SetVariable() methods, passing the ID to specify the icon. To access the media in a display icon, call the methods IMoaAwPiece::GetMediaBitmap() and IMoaAwPiece::GetMediaImage(). GetMediaBitmap() returns the media of the display icon in bitmap format (as a DIB on Windows or a PICT on the Macintosh). GetMediaImage() returns the media of the display icon in vector format (as a metafile on Windows or a PICT on the Macintosh).

Palette access

You can manipulate a piece's palette with the GetPalette(), SetPalette(), and ResetPalette() methods. GetPalette()returns a handle to the currently active palette. You use SetPalette() to change the palette system colors. ResetPalette() sets the palette back to the default Authorware palette and system color settings.

Imaging support

The IMoaAwPiece interface provides access to the graphics contexts for the presentation window. To get the offscreen drawing buffer, call the IMoaAwPiece::GetPresentationWindowGC() method.

Scripting support

An Xtra can ask Authorware to evaluate any expression or script and get and set variables using the IMoaAwPiece methods EvalExpression(), GetVariable(), and SetVariable() methods. EvalExpression() evaluates an expression or script supplied as a string and returns the result. GetVariable() gets the value of a global variable and SetVariable() sets the value of a global variable.

Event handling

IMoaAwPiece provides the methods SendEvent() and SendEventWithReply() to handle events from an Xtra. These methods are described in the topic "Event sender Xtras".

Asset support API

The Authorware asset callback interface

After a media asset Xtra's IMoaMmXAsset interface is initialized by the host application, its SetCallback() method is called. This method provides an IMoaMmAssetCallback interface to the Xtra. This interface is described in the earlier chapter "Asset Xtras."

In Authorware, the object that provides IMoaMmAssetCallback also implements the IMoaAwAssetCallback interface. To acquire this interface, your asset should call QueryInterface(&IID_IMoaAwAssetCallback, ...) on the callback object passed when the application calls your asset's SetCallback() method. Your Xtra can then call the methods described here to interact with its internal representation within a Authorware piece.

Icon access

IMoaAwAssetCallback allows you to get the identification number of the icon for an asset with the GetIconId() method. You specify the icon's title, then get the identification number.

Scripting support

IMoaAwAssetCallback provides several methods for calling Authorware functions. The GetExpression() method lets you retrieve the text of an expression. You evaluate an expression with EvalExpression(). GetExpressionLength() returns the length in bytes of an expression. StoreExpression() compiles and saves an expression; DeleteExpression() deletes it. You can start and stop a watch on an expression using WatchExpression() and StopWatchExpression().

Sprite asset support API

After a sprite asset Xtra's IMoaMmXSpriteActor interface is initialized by the host application, its SetCallback() method is called. This method provides an IMoaMmSpriteCallback interface to the Xtra. This interface is described in "Asset Xtras."

In Authorware, the object that provides IMoaMmSpriteCallback also implements the IMoaAwSpriteCallback interface. To acquire this interface, the media asset calls QueryInterface(&IID_IMoaAwSpriteCallback, ...) on the callback object passed to your Xtra by the host application in the SetCallback() call to gain access to the IMoaMmSpriteCallback interface. It can then call GetPiece() described here to interact with its Authorware piece.

Acquiring IMoaAwPiece

A sprite can get access to the IMoaAwPiece interface of the piece in which it resides by calling IMoaAwSpriteCallback::GetPiece(). It can then interact with the piece, using the techniques described in "Using the Authorware object model."

Authorware Xtra interfaces

The Authorware support API defines a couple of interfaces that can be implemented by Xtras. You implement the IMoaAwEventSender interface to provide information about events your Xtra can send to Authorware. Implement the IMoaAwSaveState interface to save state information so that a user can pause and resume an Authorware presentation.

Event sender Xtras

An event sender Xtra-one that implements the IMoaAwEventSender interface-can pass information to Authorware and invoke responses defined by the author of a piece. For example, if your Xtra implements a calendar, it could define various events: one that reports when the user selects a new month, another that's triggered when a certain date and time are reached. Within an Authorware piece, the author could define a response-using Authorware functions-that updates another icon in the flowline, or that displays "Times Up!" to the user.

To enable a piece to receive an event, the author adds an interaction icon to the flowline and specifies "Event" as the response type for a branch of the interaction. The author can then select specific events from the Properties: Response dialog. Events are listed in two categories: Icon events, sent by Sprite Xtras, and Xtra events, which can be sent by other types of Xtra. To define events, a Sprite Xtra implements IMoaAwEventSender in the same class that implements IMoaMmXAsset. Other Xtras can implement this interface in any class.

The Authorware event mechanism is asynchronous. Events are placed in a queue, and processed in the order in which they're received. The method an Xtra calls to notify Authorware of an event always returns immediately. Authorware provides a mechanism to notify your Xtra when the event has been processed, and to pass any result data your Xtra needs to proceed.

An Xtra implements IMoaAwEventSender to define its events and to enable Authorware to notify the Xtra when a specific event has been received. The IMoaAwSpriteCallback interface provides methods for a specific sprite Xtra to send events to a response. The IMoaAwPiece interface provides methods for other types of Xtras to send events.

Registering an event sender

Your Xtra should register any classes that implement the IMoaAwEventSender interface. To register an interface, you call IMoaCache::AddRegistryEntry() on the cache passed to your Xtra's IMoaRegister::Register() method.

Retrieving the Xtra name

You implement IMoaAwEventSender::GetSenderXtraName() to return the name of the Xtra to be shown in the list of event senders in Authorware's Properties: Response dialog. A Scripting Xtra should return the name string used in the message table. An Asset Xtra should return its display name string. Return an empty string if you don't want the Xtra to appear in the Response Properties dialog sender list.

Retrieving event descriptions

You implement IMoaAwEventSender::GetXtraEventDescriptions() to return a list of event descriptions that the Xtra sends for all its instances. The events in this list are the events that are common to all instances of the Xtra-events that can be sent by any of its instantiated icons. If you don't want an event to appear in the list of available events in the Authorware Response Properties dialog, precede it with a '/'.

When a sprite asset Xtra implements the IMoaAwEventSender interface, it should implement the GetInstanceEventDescriptions() method to return the list of events sent by a sprite.

Sending Events and Handling Replies

As an event sender Xtra performs in a piece, it will generate events and pass them to Authorware. Authorware provides two ways to send events: one for Sprite Asset Xtras and one for other Xtra types. It also defines two styles of events that an Xtra can send: without reply and with a reply back to the Xtra.

Event TypeWithout reply With reply
Sprite XtrasIMoaAwSpriteCallback::
SendSpriteEvent()
IMoaAwSpriteCallback::
SendSpriteEventWithReply()
Other Xtras IMoaAwPiece::SendEvent() IMoaAwPiece::SendEventWithReply()

When you send an event with a reply, you pass Authorware a pointer to the IMoaAwEventSender interface that will respond to the reply. After the event has been processed, Authorware returns the reply by calling the HandleReply() method of this interface.

Pause and resume in Xtras

Authorware enables the user to stop and resume at any point in a presentation. Xtras can support this feature by implementing the IMoaAwSaveState interface. Authorware calls the methods of this interface at the appropriate times on any instances of IMoaMmXAsset, IMoaMmXSpriteActor, or IMoaDrXLingo whose Xtra has registered this interface. To register this interface, you call IMoaCache::AddRegistryEntry() on the cache passed to the IMoaRegister::Register() method.

The IMoaAwSaveState interface is implemented with three methods: GetStreamOutSaveDataSize(), StreamOutSaveData(), and StreamInSaveData(). These methods are similar to those for streaming media and properties data in an asset Xtra. As with the asset methods, these methods save and retrieve data through an IMoaStream interface. You determine which state your Xtra needs to save to restore itself properly.

Authorware notification clients

Authorware uses the MOA notification interfaces to notify Xtras of specific events of interest. Xtras call the callback interface IMoaNotification to register interest in specific events, and implement the IMoaNotificationClient interface to process the events requested.

Authorware defines the following event notification IDs, which an Xtra uses to indicate the events it's interested in, and which the application uses to indicate the events its sending to the Xtra. For each event type, a specific data type is passed to the IMoaNotification::RegisterNotificationClient() method when registering, and data is received from the application when it calls IMoaNotificationClient::Notify(). The following table lists Authorware event types and the associated Notification IDs and Data:

The Authorware API defines three notification events that any Xtra can respond to by implementing the IMoaNotificationClient interface. These events, defined in awiservc.h, are:

EventNotification ID Data passed to Register() Data received by Notify()
Step frameNID_AwNStep Xtra-specific dataXtra-specific data
Service background processNID_AwNIdle PMoaLong indicating max milliseconds between calls PMoaLong indicating milliseconds since last call
Palette changedNID_AwNPaletteChanged NULLNULL

These events are equivalent to events sent to sprite actors through the IMoaMmSpriteActor::Notify() method. However, any Xtra can implement the IMoaNotificationClient class and subscribe to these events through the host application's IMoaNotification callback interface.


Copyright © 1995-2007 Adobe Macromedia Software LLC, Inc.