Zeus Tech Note
Installing and Using Xtras

(This document last revised August 26, 1997)

Copyright © 1996-1997. Zeus Productions. All Rights Reserved.
Written by Bruce A. Epstein

This TechNote explains how to install and use Xtras. You should first read the Xtras FAQ for answers to the most common questions about Xtras, including what versions are used under the different operating systems.

There are four distinct types of Xtras supported by Director, Lingo Xtras, Sprite Xtras, Tool Xtras and Transition Xtras. Regardless of the type of Xtra, they are all installed in the same location. The type of Xtra determines where they show up in Director once they are installed. Other Xtras may be used by Director but not show up anywhere in the interface. (Input Filters show up in the Import Dialog Box?) Others are used only during playback (?) such as the streaming Shockwave audio Xtras.

Xtra Versions

The Macintosh and Windows platforms require different versions of an Xtra. Furthermore, the different type of Macintosh models, and different versions of Windows may require more than one version of an Xtra.

Macintosh Xtras

The type of Xtra required on the Macintosh depends on the processor type (68K or PowerPC) and not the type of Projector (true?). The Mac OS will automatically look for the correct type of Xtra for the processor installed. The easiest course is to use both a Fat Binary Projector, and a Fat Xtra which is a single Xtra that will work with all types of Macintoshes.

PowerMacs require a PowerMac or Fat Xtra. PowerMacs will not work with a 68K-only Xtra even if you run a Standard Macintosh (68K) projector (true?)
68K (Standard) Macs require a 68K or Fat Xtra, and will not work with PowerMac only Xtras, such as QD3D.

Windows Xtras

The type of Xtra required under Windows depends on the processor type, not the operating system. The Xtra must always match the projector, so 16-bit Xtras are used with 16-bit Projectors and 32-bit Xtras are used with 32-bit Projectors. Generally 16-bit Xtras have an .X16 extension and are used under Windows 3.1 and 32-bit Xtras have an .X32 extension and are used under Windows 95/NT.

Windows 3.1 - Windows 3.1 supports only 16-bit projectors, so you should always use 16-bit Xtras under Windows 3.1.
Windows 95 - A 16-bit projector running under Windows 95 requires a 16-bit Xtra. A 32-bit projector running under Windows 95 requires a 32-bit Xtra.
Windows NT - Windows NT does not support 16-bit projectors so it requires 32-bit projectors and 32-bit Xtras. Not all Xtras, even 32-bit Xtras, work under any or all versions of Windows NT.

Installation

Under Windows, you can place both the .X16 and .X32 files in the same folder without fear of conflicts. The correct version of the Xtra will automatically be opened depending on the type of projector (16-bit or 32-bit) in use.

On the Macintosh, you ordinarily just include a FAT version of the Xtra, which will work with any type of Macintosh projector. It is possible to have separate 68K and PowerPC versions of an Xtra, but this is less common.

Director looks for Xtras in certain valid folders (see below). Xtras can be nested up to five folders deep, so it is possible to get your Xtras organized somewhat. By placing Xtras in the proper Xtras folder, they will be opened and closed automatically. Do not use the openXlib and closeXlib commands to open and close the Xtras, as you would with XObjects. Some problems have been reported when using openXLib and closeXLib with Xtras, and Macromedia strongly recommends putting the Xtras in the "Xtras" folder instead of using openXlib and

closeXlib.

A projector will open all Xtras in the "Xtras" folder when it starts up. Unless you have very many Xtras, loading the Xtras should not require much time.

Xtras can contain version numbers, and theoretically, if you include multiple versions of the same Xtra, Director will select the newest one. In practice, many Xtra developers omit version information. It is best to delete old versions of Xtras and only include the current version in your Xtras folder.

Authoring Mode Xtras

During authoring, Xtras should be installed in the "Xtras" folder inside Director's installation directory:

Macintosh - place all Xtras in the Xtras folder where Director is installed. You can also place Xtras within the Macromedia Xtras folder in the System Folder (?)
Windows - place any 16-bitXtra (.X16) in the Xtras folder where the 16-bit version of Director is installed. Place any 32-bitXtra (.X32) in the Xtras folder where the 32-version of Director is installed.

When using Director 5.0.1, you can also place these Xtras within the C:\WINDOWS\MACROMED\XTRAS folder. Consult the Director manuals for more information.

After installing new Xtras be sure to restart Director. The Xtras will automatically be available for use throughout the Director session. Do not use "openxlib" or "closexlib" to access Xtras.

Run-Time Xtras

When using an Xtra from within a Projector, the Xtra(s) must be placed in a folder call "Xtras" within the same folder as the projector. Projectors will not access Xtras installed in the Authoring Mode Xtras folders.

TroubleShooting Your Installation

If a Lingo Xtra is installed properly, it should be listed along with other installed Xtras when you type "showXlib" in the message window. Tool Xtras should appear either under the Xtras menu. Transition Xtras should appear the transition dialog box. Sprite Xtras should appear under the list of available castmember types.

If you are having trouble:

Ensure that the Xtra is located in a folder called "XTRAS" in one of the valid locations (see above)
If Director reports a conflict with other Xtras, or the current version does not seem available, remove any older or duplicate versions of the Xtras, including ones in other folders.
Ensure that the Xtra is not in a folder that is nested more than five levels deep within the Xtras folder.
Delete the Director preferences file ("C:\WINDOWS\Director.prf" or "System Folder:Preferences:Director 5.0 Preferences"). You will need to reset any preferences manually.
Delete the Xtras Cache file ("D50Xtra.MCH" or "System Folder:Preferences:Director 5.0 Xtra Cache") from the folder where Director is installed (both the 16-bit and 32-bit versions under Windows)
Restart Director for the newly installed Xtras to take effect.
Refer to the Xtras FAQ.
Temporarily remove other Xtras to reduce the liklihood of conflicts.
Contact the vendor for tech support and to ensure that you have the latest version of the Xtra. Macromedia distributes an updated version of the FileIO Xtra. The one that shipped with Director 5.0 was buggy. You should be using FileIO Xtra version 1.0.1 or higher.
Test on a different machine to see if the error is machine-specific

Macintosh Specific Trouble-shooting:

Mac sure the Xtra has the proper Type (Xtra) and Creator Code (Xown), or it won't be recognized.
Mac sure that the Xtra's resource fork is intact. It could be damaged or discarded by copying the file via a Windows machine or Windows-format disk. Start with a fresh copy of the Xtra.
Test the Xtra on both a 68K Mac and a PowerMac. You must ensure that the Xtra supports the platform on which you are testing. Some Xtras, such as the QD3D Xtras, support PowerPCs only.
Restart with minimal extensions to reduce the liklihood of conflicts.

Windows-specific trouble-shooting

Test under a different version of the OS (Windows 3,.1 or Windows 95) to determine if the problem is related to the particular version of the Xtra
Test the 16-bit and 32-bit versions under Windows with 16-bit and 32-bit projectors respectively. 16-bit Xtras have an ".X16" extension, and 32-bit Xtras have an ".X32" extension.

Using Xtras

Lingo Xtras are called from Lingo, as you would use other Lingo commands, functions or subroutines. They are similar to child objects in many respects. To see which Lingo Xtras are installed, you can use showXlib or you can use Lingo to examine the available Xtras. Refer to the number of Xtras command.
Transition Xtras - Transitions appear in the list of Transitions that comes up when you attempt to add a transition in the transition channel. Transition Xtras appear alongside the built-in transitions that come with Director or Authorware. Simply use them as you would any other Transition
Sprite Xtras - allow you to add new types of castmembers. They show up in the ??. When you add a new castmember it can be placed on the stage like any other sprite. The control and properties of the castmember depend on the implementation of the Sprite Xtra itself.
Tool Xtras - these Xtras are added automatically to Director's Xtras menu, and are accessible only during authoring mode. They may perform a single function, but most often have their own window that stays active until you close it.

Using Lingo Xtras

Of all the Xtra types, only Lingo Xtras require you to write additional Lingo code. Within a Lingo Xtra there are one or more "methods" that perform various functions. Some methods, such as mMessageList and new are standard to all Xtras, but most methods are unique to a particular Xtra. There are three types of Lingo methods:

Global methods - these methods are indicated by the an asterisk "*" next to their name in the method listing, and provide additional Lingo functions without requiring you to instantiate the Xtra. Simply use them as you would other Lingo. For example, the FileIO Xtra includes the "getOSDirectory" method, that can be called as follows (the parentheses are mandatory)

set systemDir = getOSDirectory()Not that Global methods perform a single operation and do not have any "state" which is saved.
Xtra-level methods - these methods pertain to the Xtra itself, often provide information about the Xtra, and require an Xtra reference such as Xtra "FileIO" or Xtra 1. The most important Xtra-level method is the standard newmethod, which is used to instantiate an Xtra, such as:

set myObj = new (Xtra "FileIO")

The standard mMessageList method, used to list other supported methods, is another important Xtra-level method:

put mMessageList (Xtra "FileIO")
Other Xtra-level methods are (sometimes) indicated by a plus sign "+" next to their name in the method listing

FileIO's version method returns the Xtras current version.

put version (Xtra "FileIO") -- "FileIO 1.0.1 May 31 1996"
Instance-level methods - these methods pertain to an instance of the Xtra, and require that you first instantiate the Xtra using the new method. A single Xtra can be used to control, say, multiple files, with each instance referring to a different file. The value returned by new is used to call instance-level methods, as shown below.

Standard Lingo Xtra Methods

All Lingo Xtras support certain standard methods:

mMessageList - this method returns a list of other supported methods. Syntax:

put mMessageList (xtra "FileIO")
new - this method creates an instance of (i.e. "instantiates") the Xtra. Once you have instantiated the Xtra, you can use the other supported methods, such as:

global gFileObj

set gFileObj = new (xtra "FileIO")

if not objectP (gFileObj) then

alert "something didn't work"

else

gFileObj (createFile, the pathname & "junk.txt")

end if

Programming with Xtras

For those of you familiar with XObjects, there are several major differences when programming with Xtras:

Macromedia strongly recommends putting the Xtras in the "Xtras" folder instead of using openXlib and closeXlibBy placing Xtras in the proper Xtras folder, they will be opened and closed automatically. Do not use the openXlib and closeXlib commands to open and close the Xtras, as you would with XObjects. Some problems have been reported when using openXLib and closeXLib with Xtras.

A projector will open all Xtras in the "Xtras" folder when it starts up. Unless you have very many Xtras, loading the Xtras should not require much time.
The mDescribe method used by XObjects is no longer supported. Use mMessageList instead, and note the difference syntax. Instead of:

FileIO (mDescribe)

use:

put mMessageList (xtra "FileIO")
The mNew method used by XObjects is no longer supported. Use new instead, and note the difference syntax. Instead of:

set myObj = FileIO (mNew)

use:

set myObj = new (xtra "FileIO")
Do not use the mDispose or forget method to dispose of an Xtra instance, as these can lead to a crash. Director will clean up the instance at its leisure when the instance is no longer being used. To free up an instance, set it equal to zero, such as:
set tempObj = new (xtra "FileIO") -- Instantiate Xtra set tempObj = 0 -- Dispose of instance

Each time an Xtra is instantiated and disposed, some memory is consumed, and it takes a while for Director to reclaim the memory. Instantiating an Xtra thousands of times is usually wasteful and can lead to a crash. Use a single Xtra instance throughout your project by assigning it to a global variable, rather than repeatedly instantiating the Xtra.

...much more to come, including:

Xtras in Shockwave, and new information about Xtras in Director 6

Zeus Tech Note Installing and Using Xtras