MM Developer's Guide
MM Interfaces | MM Methods
| MM Types and Misc API
A multimedia Tool Xtra provides authors with additional functionality
in a multimedia authoring application such as Director or Authorware.
A Tool Xtra registers a display name which appears in the application's
Xtras menu. When the user selects the item, the Tool Xtra is notified
and can perform a useful operation, bring up a user dialog, and
so on.
Tools have full access to all the callbacks offered by an application.
In Director, this includes access to all cast member and score
data, as well as the current cast and score selections in the
authoring environment. This allows Xtra writers to create tools
that operate on the current selection. For example, one tool might
create an optimized palette for all of the currently selected
cast members in the active cast.
Tools (and other Xtras, for that matter), are free to create new
modal or modeless windows which may appear in the authoring environment.
Tools can use the MUI Xtra API
to present custom dialogs, alerts, file open and save dialogs,
and other user interface features (see the MUI documentation for
information on which application's support the MUI Xtra API).
Note: Multimedia tool Xtras replace the Director-specific
tool Xtras supported in the previous release.
Tool Xtras are very simple. They should be created with two MOA
classes, each supporting one of the following interfaces:
Class | Interface | Behavior |
Registration class | IMoaRegister |
Standard MOA registration interface |
Tool class | IMoaMmXTool |
Tool Xtra interface |
As is true with all Xtras, the Tool Xtra may additionally implement
several other interfaces. The registration class may implement
IMoaMmInterrogate
and IMoaMmTerminator
to perform application startup and shutdown allocation and resource
access. The tool class may implement IMoaInitFromDict
to perform custom initialization.
The host application creates an instance of your class supporting
IMoaMmXTool
the first time it is needed, either to call its Invoke()
method or its GetEnabled()
method. Only a single instance for each tool is created; after
creation, the instance will persist as long as the host app is
running, and will be released at application shut-down.
If you specify your tool as "alwaysEnabled" (see below),
your code will not be loaded (and instance created) unless the
item is selected by the user. Otherwise, your instance may be
created sooner if the application needs to enable/disable your
item in the user interface.
Although there's only one instance of your tool xtra class per
Xtra menu item, this doesn't mean you're limited to a single window
for your user interface. This instance is simply used to handle
selection of your tool. Your tool xtra can choose to create additional
objects (such as windows) each time it is selected, if you wish.
Typically, however, tool xtras should either use a modal dialog
or have a single modeless window which is brought forward when
the item is selected. Alternatively, the tool xtra can immediately
execute some function without displaying any UI, if appropriate.
In the Register()
method of your IMoaRegister
implementation, you register the display name and category for
your Xtra. These registry keys are the same ones used for Sprite
and Transition Xtras. In addition, you can register a third bit
of data under the "alwaysEnabled" key. This will indicate
to the host application that your tool is always enabled as long
as the application is running; in this case, your GetEnabled()
method will never get called, and the host application won't have
to load your code unless your item is selected. Otherwise, your
code will need to be loaded and your GetEnabled()
method called whenever the app needs to determine whether or not
your item needs to be enabled in the user interface.
kMoaMmDictKey_DisplayNameString
| This key is used to register the name of your Tool as you'd like it to appear in the host application UI. This should be a localized, human-readable C string. |
kMoaMmDictKey_DisplayCategoryString
| This key registers the category of your Tool as you'd like it to appear in the host application UI. This should be a localized, human-readable C string. |
kMoaDrDictKey_AlwaysEnabled
| This key registers whether this tool is always enabled. This should be a MoaLong: FALSE (0) if the tool needs to be enabled & disabled dynamically; TRUE (1) if the tool should always be enabled in the UI. If TRUE, your IMoaMmXTool::GetEnabled() method will not be called. |