MOA Developer's Guide
MOA Interfaces | MOA Methods | MOA Types and Misc API

Director Xtra Development Kit: MOA Developer's Guide

MOA Technical Concepts


The MOA object model

This section covers the main conceptual points of the MOA object model, beginning with the central mechanism of MOA, the interface. It then goes on to describe the conceptual relationship among MOA objects, classes, and interfaces.


Interfaces and interaction

MOA is built on the fundamental concept of interface, one of the foundations of COM. Interfaces are the basic mechanism by which an application and an external code module--an Xtra--interact.

An interface can be thought of as a template that specifies how independent code modules interact.




For two modules to interact through an interface, each plays a specific role: either providing or using the interface. A provider is a module that implements the interface by providing specific behavior that conforms to the template.


A user is a module that relies on the behavior specified by the interface.


When a provider and user of the interface come together, they can interact through the template of the interface.


Interfaces can be defined independently of both providers and users: one programmer or organization may define an interface, while others implement or use it. This separation makes the MOA object model well-suited to defining and implementing Xtras.

For two independent modules to interact, each must provide an interface to the other, and use an interface provided by another.


Interfaces define self-contained units of behavior. Each interface has a specific, coherent purpose. For complex behaviors, a single module provides more than one interface, and uses more than one interface in other modules.


A Macromedia application may provide a number of interfaces to its Xtras. It may also define several interfaces intended to be provided by Xtras.


Defining interfaces

In C-language terms, an interface is a set of prototypes--names, argument types, and return types--for a set of related functions. These function prototypes are referred to as methods. Because an interface declares only the external signature of its methods, it can be declared independently of both its providers and users.

For example, consider an interface named Shape. This interface specifies standard behavior for rendering 2D graphic shapes. In this simple example, the Shape interface specifies just one method: Draw. An application may use the Shape interface by calling the Draw method.


An Xtra that provides the Shape interface includes code for the Draw method. For example, a rectangle Xtra would include code to render a rectangle.



Objects and interfaces

Traditionally, a program consists of two types of entities: data and procedures. Data represents things such as names, addresses, or the position and size of a graphic shape. Procedures operate on data--for example, by adding two numbers and returning the result, sorting a list of names, and so on. Frequently, programmers develop suites of functions to operate on specific types of data.

Object-oriented programming formalizes and extends this approach to programming. Data and procedures are combined in a single unit, the object. Generally, the data of an object can only be accessed and manipulated through procedures belonging to the object. This is referred to as encapsulation.


Encapsulation helps ensure data integrity. Since the data is controlled by the object, the user is less likely to make inadvertent changes than with traditional data structures. Encapsulation also facilitates code maintenance, because objects are manipulated solely through procedures. The structure of an object's data can be designed and modified to suit its own needs, without affecting the users.

Because interfaces represent units of behavior agreed on by separate code modules, they're well suited to object-oriented programming. By providing one or more interfaces, a MOA object provides a specific set of behavior to its users, while keeping its data encapsulated.


In addition to encapsulation, interfaces enable different types of objects to respond to the same procedures in their own way. In object-oriented terms, this is referred to as polymorphism. Because of polymorphism, a user can interact with objects of many types without knowing about the internal details of those objects.


The benefits of polymorphism and encapsulation can be demonstrated by the Shape interface. You can imagine many types of object that provide this interface: circles, rectangles, line segments, and so on. Each of these object types may implement the Draw method in its own way. For example, the rectangle implements Draw to render a rectangle, while the circle implements Draw to render a circle.


Each of these shapes can use the most appropriate type of data to define what to draw. The rectangle would probably use two control points to define its drawing area, while the circle might use a center point and radius. Encapsulation keeps this implementation detail hidden from users of the Shape interface.


An application that uses the Shape interface could call the Draw method on a rectangle Xtra, a circle Xtra, or any other Xtra that implements the Shape interface, and reliably get a rendering of the appropriate shape.


Objects and classes

The previous section referred to a type of object, such as a rectangle object. For a given Xtra, you may want to create any number of objects. For example, an animation program may use several rectangles, each independent of the other. This means you need a way to define the behavior of a rectangle Xtra once, then allow the application to recreate that behavior any number of times. To define a specific type of Xtra object, you define a class. Objects of a specific class are referred to as instances of that class.

A MOA class implements an interface by providing a method implementation for each method. It's possible for any number of instances to be created from the class, each responding to the methods in its interfaces. The class also defines data, or instance variables, and each instance has its own set of these variables.


Instance variables are private, accessible only within the method implementations. The terms object and instance are often used interchangeably throughout this document.

In practice, some classes are only instantiated once. For example, you may only need one instance of a particular sound filter in SoundEdit. In any case, classes provide a modular way to implement the specific interaction described by an interface.


MOA application architecture

Using interfaces, classes, and objects, the MOA object model provides a modular way to specify interaction between a Macromedia application and an Xtra. This section explores the general relationship between applications and Xtras.


Applications, Xtras, and interfaces

All interfaces used between applications and Xtras are defined by Macromedia. In a sense, the application forms the base or foundation for the Xtra, the interfaces serve as an intermediate layer, and Xtras are supported by the application and its interfaces.



Xtra and callback Interfaces
Some MOA interfaces are intended to be implemented by classes in an application, others by classes in an Xtra. The interfaces implemented by an application are referred to as callback interfaces. Those implemented by Xtras are called Xtra interfaces.




Callback interfaces are implemented by classes in an application and provided for use by its Xtras. When implementing an Xtra, you are given access to the callback interfaces to get information from the application. Some callback interfaces are general purpose; others are provided for the specific purposes of a particular application. Each application defines and instantiates the classes that implement its callback interfaces.

Xtra interfaces are intended to be implemented by classes in the Xtra and used by the application. The application creates instances of the classes in the Xtra and uses them to perform behavior specified by the Xtra interface.


Lifetime of an Xtra

The lifetime of an Xtra object is controlled in part by MOA and in part by the specific application it is interacting with. There are five general phases in the lifecycle of a MOA Xtra: startup, registration, instantiation, activation, and release. This section explores these phases in sequence.


Startup
When an application starts up, it checks for Xtras in a couple of standard directories. The precise path to these directories is platform dependent, as listed in the following table:



Macintosh

<Application folder>:Xtras

Windows NT/Windows 95

<Application dir>\Xtras

In all cases, MOA applications search this directory to a depth of five subdirectories. When it encounters a new Xtra (one that wasn't registered the last time the application started), MOA attempts to register the Xtra.


Registration
When an application finds an Xtra for the first time, it registers it. Registration is provided through a standard Xtra interface, IMoaRegister, with one method, Register(). The purpose of this interface is to enable an application to determine the classes and interfaces implemented by your Xtra. Each Xtra includes this information in its implementation of the IMoaRegister interface. In addition, all MOA applications define specific keys and values to be added to the cache through the IMoaRegister interface. This enables the application to determine what functionality your Xtra provides--and thus, where in its user interface to make your Xtra available to the user.


Instantiation
Once an Xtra has been registered, the application automatically makes it available to the user at appropriate times. Instances of your Xtra classes are often created as the result of the user selecting an item from a menu or manipulating some other user interface feature. For example, in SoundEdit, Xtra objects are created when the user selects their behavior from the menu, and disposed of after the user finishes using them (usually by closing their dialog box).

In other cases, one Xtra object may create instances of other classes defined by the same Xtra. In Director, for example, a media asset object is created when the user adds a media asset Xtra to the cast. The media asset object, in turn, creates an instance of an associated sprite actor class when the media asset is added to the score.

Whenever an Xtra object is instantiated, MOA automatically initializes a couple of instance variables belonging to all MOA objects: pCalloc and pCallback. These are set to some standard interfaces within the application. The next section describes in greater detail how an Xtra uses these instance variables.
Activation
A Macromedia application invokes the behavior of your Xtra by calling methods in the Xtra interfaces you've implemented. Some Xtra interface methods may be called by an application as the result of user action. Other methods are called as the internal code of the application performs some behavior in which your Xtra interacts, for example, the animation or event-handling loops.
Release
As the application uses Xtra objects, it requests interfaces from them, calls methods in those interfaces, then releases them. MOA uses reference counting to determine when an object is in use and when it can be purged from memory. Each time an interface is requested from an object, the reference count for that interface is incremented. Each time an interface is released, the reference count is decremented. When all references to all interfaces of an object have been released, the reference count drops to 0 and the object becomes a target for purging from memory. Note that the object may not be purged immediately--the application will determine when it needs additional memory and purge any unreferenced objects at the appropriate time.


Accessing callback and Xtra Interfaces

To complete the picture of how applications and Xtras interact through MOA interfaces, this discussion details the ways applications provide interfaces to Xtras and Xtras provide interfaces to applications.
Standard MOA interfaces
There are a number of standard interfaces defined by MOA. Among these are several standard callback interfaces intended to be provided by an application for the use of its Xtras. These callback interfaces are:

Interface Purpose

IMoaCalloc Standard memory allocation and release

IMoaCallback General access to an application

IMoaHandle Handle-based memory allocation

IMoaProgressBox User notification for longer processes

IMoaStream Access to file and memory buffers

IMoaPixelAccess Access to bitmap pixel information

In addition, MOA defines a standard Xtra interface, IMoaRegister. This interface defines a way for Xtras to describe their capabilities to an application, including the classes and interfaces they implement.
The callback object
Each MOA-capable application defines a class that represents the top-level access to its capabilities. One instance of this class is created when the application starts; this instance is referred to as the callback object. The callback object is the main way all Xtras get access to the capabilities of an application. The callback object is accessed through the standard MOA instance variable pCallback.
Access to callback interfaces from an Xtra
An application makes its capabilities available to an Xtra through various callback interfaces. Some of these are provided by the callback object, others are provided by objects of other classes.

The diagram below shows a number of callback interfaces provided by an application to an Xtra. Some of these are standard interfaces defined by MOA. Some are standard interfaces defined by the application. Others are optional interfaces, supplied by either MOA or the application.


This diagram illustrates three ways interfaces are provided by an application for use by an Xtra. From top to bottom, these are:
Using instance variables
Each Xtra object has two instance variables provided by MOA that point to interfaces within an application, pCalloc and pCallback.

The pCalloc instance variable provides the application's IMoaCalloc interface. This interface is used by the Xtra to allocate small chunks of non-relocatable memory, such as those required by its instance variables.

The pCallback instance variable provides the IMoaCallback interface of the application's callback object. This interface can be considered the main entry point to the application. Through it, the Xtra acquires access to all other interfaces and objects provided by the application.
Calling the QueryInterface() method
To use other interfaces provided by an application, an Xtra often acquires them from the application's callback object. To do so, it calls the QueryInterface() method on the interface provided by pCallback. QueryInterface() is a standard method of all MOA interfaces, used to acquire other interfaces provided by the same object. Through this method, the Xtra gets access to the application's IMoaHandle interface, used for allocating larger chunks of relocatable memory. The Xtra can also use QueryInterface() to access the "top-level" interface for application-specific functionality. Other general-purpose interfaces provided by calling QueryInterface() on pCallback may include IMoaProgressBox, IMoaStream, and utility interfaces provided by the application.
Calling methods in a callback interface
The third general way an Xtra acquires interfaces and objects from an application is by calling methods in one of the callback interfaces provided through pCallback. For example, the application's top-level interface may provide methods that return interfaces to other objects--referred to in the diagram as "model objects"--within the application. One example would be an object representing an open document in an application. The interfaces of these model objects in turn may include methods for accessing the interfaces of other objects representing internal details of the application.


Access to Xtra interfaces
A MOA application can get the use of interfaces provided by an Xtra in a couple of ways, as shown in the following diagram. The diagram also illustrates how methods of an Xtra interface may be used to provide callback interfaces from the application to the Xtra.


Calling Register()
Before it accesses any other classes or interfaces provided by an Xtra, an application needs to learn the capabilities of the Xtra. The standard Xtra interface IMoaRegister provides the mechanism for this. This interface consists of one method, Register(), invoked by the application's registration process the first time it detects your Xtra. The registry calls your Xtra's Register() method to get some standard information and some application-specific information. Standard information provided by every Xtra includes the classes and interfaces it provides. Application-specific information provided by an Xtra helps the application determine where your Xtra should appear in its menus. When it calls this method, the application provides the callback interfaces IMoaCache and IMoaDict to the Xtra for storing registration information.

Note that MOA creates an instance of an Xtra object before calling Register() on it. It only does this the first time it encounters the Xtra in the standard Xtras folders. The object is only created so the application can register it; it is usually purged from memory immediately. Subsequently, MOA and the application can use information in the cache to create "real" instances of the Xtra for use within the context of the application.
Calling Xtra interface methods
After registration, the application knows the classes and interfaces your Xtra provides. It can then create an instance of the class and access the Xtra interfaces it provides. Certain methods in the interface you implement may be passed additional callback interfaces from the application. For example, the hypothetical Xtra interface IMoaHello could include a Hello() method for your object to pass its greeting. One parameter of this method may be an instance of IMoaStream, a MOA callback interface for writing data to streams. Your implementation of Hello() calls methods in IMoaStream to write a greeting from the Xtra to the application.

The next chapter shows how an Xtra would implement this hypothetical IMoaHello interface, using the various mechanisms described above to provide interfaces to the application and to access interfaces provided by the application.

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