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

Director Xtra Development Kit: Multimedia Developer's Guide

Tool Xtras

Introduction

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.

Implementing a Tool Xtra

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 implementIMoaMmInterrogate and IMoaMmTerminator to perform application startup and shutdown allocation and resource access. The tool class may implement IMoaInitFromDict to perform custom initialization.

Creating and disposing of tool Xtras

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.

Registering a tool Xtra

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.

Keys for Tool Xtras

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.

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