AW Interfaces | AW Methods | AW Types and Misc API
rev: 3/97
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.
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.
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.
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 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()
).
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 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.
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.
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).
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.
The IMoaAwPiece
interface
provides access to the graphics contexts for the presentation
window. To get the offscreen drawing buffer, call the IMoaAwPiece::GetPresentationWindowGC()
method.
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.
IMoaAwPiece
provides the methods SendEvent()
and SendEventWithReply()
to handle events from an
Xtra. These methods are described in the topic "Event sender Xtras".
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.
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.
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()
.
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.
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."
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.
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.
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.
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.
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.
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 Type | Without reply | With reply |
Sprite Xtras | IMoaAwSpriteCallback::
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.
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 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:
Event | Notification ID | Data passed to Register() |
Data received by Notify() |
Step frame | NID_AwNStep
| Xtra-specific data | Xtra-specific data |
Service background process | NID_AwNIdle
| PMoaLong indicating max milliseconds between calls
| PMoaLong indicating milliseconds since last call
|
Palette changed | NID_AwNPaletteChanged
| NULL | NULL |
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.