. DirectXtras Home
        Home

DirectCommunication Xtra
DirectConnection Xtra
DirectControl Xtra
Documentation
License Agreement
Licensing Fees
Order Form
DirectEmail Xtra
DirectFTP Xtra
DirectImage Xtra
DirectInteraction Xtra
DirectOS Xtra
DirectSMS Xtra
DirectSound Xtra
DirectTransition Xtra
DirectTransition3D Xtra Set I
DirectTransition3D Xtra Set II
DirectTransition3D Xtra Set III
DirectTTS Xtra
XtrAgent
DirectXport Xtra

SpeechPlugin

Special Discounted Bundles

The Gallery
How To Order
Order Form
Check for Upgrades

Sign in
Change Your Profile

Contact Us
















    .
DirectXtras
Xtra Power for Director & Authorware



DirectControl Xtra
 The only way to hook up a joystick to Director & Authorware and start blasting.

Authorware 4.x Compatible Authorware 5.x CompatibleAuthorware 6.x CompatibleAuthorware 7.x CompatibleDirector 5.x Compatible Director 6.x CompatibleDirector 7.x Compatible Director 8.x CompatibleDirector MX CompatibleDirector MX 2004 Compatible Director Shockwave Compatible and Safe     MacOS 8.x and 9.x CompatibleWindows Compatible   


DirectControl Xtra™ Version 2.0 Documentation

Developed by Tomer Berda, DirectXtras Inc.
(C) Copyright 1996-2004.
Last updated: August 20th, 2004.

Introduction

DirectControl Xtra is a cross platform, easy to use Scripting Xtra for Macromedia Director, Authorware, and Shockwave, that provides fast and consistent access to analog and digital joysticks.

DirectControl Xtra also applies to other ancillary input devices that track positions within an absolute coordinate system, such as a touch screen, digitizing tablet and light pen. 

Each device can use up to six axes of movement, a point-of-view hat, and 32 buttons.

Applications can use DirectControl Xtra to determine the capabilities of attached joysticks and query for their axes position and buttons information. 

DirectControl Xtra is available for Director 5 and above, Authorware 4 and above, and is compatible with Windows 9X and newer (including 2000, ME, NT, XP) as well as MacOS 8 and 9.

DirectControl Xtra is Shockwave safe, so it can also be used with Shockwave 7 or later and when safety features in Director are turned on.

An auto downloadable Shockwave safe package of DirectControl Xtra is also available. It is a compressed, small sized (about 20K) version of the Xtra, that can be downloaded automatically from a web site to the user's local machine whenever needed, and once installed provides Shockwave applications on the web with access to joysticks.

Installation

Registration

System Requirements

Functions Reference

Child Functions:

New()
Forget()

joySelect()

joyGetName()

joyGetNumButtons()

joyGetNumAxes()

joyGetPos()

joyButtonDown()

joyGetPOV()

joyGetCaps()

Global Function:

joyGetNumAttachedDevs()

Installation

DirectControl Xtra has an authoring version, a run time version, a Shockwave version, and an auto downloadable Shockwave safe package. The trial version only includes the authoring version.

The authoring version should be placed in your Director and/or
Authorware "Xtras" folder. It will be used by Director and/or Authorware
when creating and testing your movie/presentation. 

The run time version should be placed in a folder named "Xtras" that is
inside the folder that contains the host projector/package. Alternatively, you
can bundle it in your projectors/packages. It is used when running your movie/presentation as a stand-alone application.

The Shockwave safe version can be used with Shockwave for Director or Authorware, and should be placed in the appropriate Shockwave 'Xtras' folder.


The auto downloadable Shockwave safe package should be
uploaded to your server. It is used when running your movie in a web
browser via Shockwave for Director 7 or above. 

Once you have decided the location on your server where the auto
downloadable packages will be placed, you should modify the "xtrainfo.txt"
file in the Director 7 or above folder accordingly. For example if you uploaded
the downloadable package to "http://www.myserver.com/packs" you
should add the following lines to "xtrainfo.txt". 

[#namePPC:"DirectControl", #nameW32:"DireCtrl.x32",
#package:"http://www.myserver.com/packs/DirectControl"] 


Finally, add a reference to the auto downloadable package in your movie.
Open a movie that uses the DirectControl Xtra. From the
Modify->Movie->Xtras dialog in Director, select the DirectControl Xtra in the list of Xtras. The "Download if needed" check box should now be enabled. (If it's not enabled, make sure the filename in "xtrainfo.txt" matches the actual
filename of the Xtra.) Click on the check box and Director will load information
from the package file for each platform and add it to the current movie. 

IMPORTANT: The authoring, run time and Shockwave versions can not
coexist in the same "Xtras" folder, so be sure to place the appropriate version
in the appropriate folder. 

 

Registration

DirectControl Xtra is a commercial product. 

Basically, there are 3 types of licenses: Single, Site and Corporate.

Single License: Entitles an organization to receive one copy of the licensed
Xtra(s) which can only be used by a single developer on a single computer at
any one time.

Site License: Entitles an organization to receive one copy of the licensed
Xtra(s) which can be used by any number of developers on any number of
workstations within one site.

Corporate License: Entitles an organization to receive one copy of the
licensed Xtra(s) which can be used by any number of developers on any
number of workstations within the entire corporation (multiple sites).

Important Notes:

  • A copy of the licensed Xtra includes the Authoring and freely distributable Runtime versions.
  • If you intend to distribute your application on both platforms (Windows and MacOS), or if you author your application on one platform and intend to deliver it on the other platform, you'd have to license both the Windows and MacOS versions of the Xtra.
  • Qualification for free and discounted upgrades and updates will be provided based on the registered e-mail address.
  • All licenses now include the Shockwave safe version of the Xtra along with an auto-downloadable Shockwave safe package which can be used with Shockwave movies on the web.
  • Single and Site licenses include free future upgrades and updates for minor revisions of the licensed Xtra(s), while Corporate license includes free future upgrades and updates for both major and minor revisions of the licensed Xtra(s).

Once you have licensed DirectControl Xtra, you will be given a serial number that should be passed to the New() function when creating the DirectControl Xtra instance in order to unlock the Xtra. Once the Xtra is unlocked,
trial warnings will no longer be presented, there will be no other limitations and the run-time and Shockwave versions of the Xtra will become activated.

Be sure to protect the call to New() so that the serial number does not become exposed. This method should be called before any other methods are called. 

You can freely distribute the run time version and Shockwave safe package of DirectControl Xtra with any application developed by you, and you alone. You can not redistribute the authoring version. Please refer to the license agreement for further information.

Note that if your Shockwave movie needs to run on both Windows and MacOS, you'd need to obtain a license for both the Windows and MacOS versions of the Xtra, in order to obtain both the Windows and MacOS Shockwave safe versions and their auto-downloadable Shockwave safe packages, along with serial numbers to activate them.

 

System Requirements

At least one joystick has to be connected to the system for the Xtra to be of any use. Applications can call the global function joyGetNumAttachedDevs() to find out how many joysticks, if at all, are connected to the system.

DirectControl Xtra can access any joystick that is installed and recognized by the operating system control panel.

On Windows, no special drivers are needed for the Xtra to work properly.

On MacOS, the Xtra requires that InputSprocket extension will be installed and activated. If it is not, Director and Authorware will not load the Xtra. Therefore, it is important to check whether the Xtra was loaded properly prior to using it, in order to avoid script errors. This can be done by going through the list of installed Xtras and checking whether an Xtra named "DirectControl" exists there. Please refer to the sample Director movie for a sample code that demonstrates how to check whether the Xtra was loaded properly.

 

Functions Reference

 

Lingo Sample Code for Director: New ( Xtra "DirectControl", integer SerialNumber )

Sample Code for Authorware: NewObject ("DirectControl", integer SerialNumber)

Lingo Sample Code for Director: new xtra("DirectControl", integer SerialNumber )

Creates a new DirectControl Xtra instance and assigns it the first connected joystick.

The returned value is a new instance of DirectControl Xtra.

Parameter :

SerialNumber : DirectControl Xtra Serial Number. If you are using the trial version, pass the number 0.

Returns : DirectControl instance.

 

Lingo Sample Code for Director: Forget ( object me )

Sample Code for Authorware: DeleteObject ( object me )

JavaScript Sample Code for Director: object me=0

Deletes a DirectControl Xtra instance.

Parameter :

object me : DirectControl Instance.

Returns : None.

In Director, you can also delete the DirectControl Xtra instance by setting it to zero.

 

joySelect ( object me, integer JoystickID )

Associates one of the joysticks that are attached to the system to the DirectControl Xtra instance

Parameters :

object me : DirectControl Instance.

JoystickID : The ID of the joystick to associate with the DirectControl instance. Can be any number between 1 to the total number of joysticks that are attached to the system, as returned by joyGetNumAttachedDevs().

Returns : Error Code.

Remarks : DirectControl Xtra attempts to select joystick # 1 by default when the DirectControl Xtra instance is being created, if at least one joystick is attached to the system.

 

joyGetName ( object me )

Returns the joystick's product name. 

Parameter :

object me : DirectControl Instance.

Returns : A string representing the joystick's product name. 

 

joyGetNumButtons ( object me )

Returns the number of buttons available on the joystick. 

Parameter :

object me : DirectControl Instance.

Returns : The number of buttons available on the joystick. 

 

joyGetNumAxes ( object me )

Returns the number of axes currently in use by the joystick. 

Parameter :

object me : DirectControl Instance.

Returns : The number of axes currently in use by the joystick. 

 

joyGetPos ( object me, integer Axis )

Returns the current position of the specified axis.

Parameters :

object me : DirectControl Instance.

Axis : Can be a number between 1 to the number of axes currently in use by the joystick, as returned by joyGetNumAxes(), representing the number of axis to query :

1: Current X-coordinate.
2: Current Y-coordinate.
3: Current Z-coordinate.
4: Current position of the rudder or fourth joystick axis.
5: Current 5th axis position.
6: Current 6th axis position. 

Returns : A number between 0 (minimum position) and 100,000 (maximum position) indicating the current axis position. If an error occurs, the returned value is -1.

 

joyButtonDown ( object me, integer Button )

Returns 1 if the specified joystick button is down, and 0 otherwise.

Parameters :

object me : DirectControl Instance.

Button : A number between 1 to the number of buttons available on the joystick, as returned by joyGetNumButtons(), representing the number of the button to query. 

Returns : 1 if the specified joystick button is down, and 0 otherwise. If an error occurs, the returned value is -1.

 

joyGetPOV( object me )

Returns the current position of the point-of-view control.

Parameters :

object me : DirectControl Instance.

Returns : Returns the current position of the point-of-view control. The returned values are in the range 0 to 35,900. These values represent the angle, in degrees, of each view multiplied by 100.

Devices with a point-of-view control typically have these five positions :

-1 : Point-of-view hat is in the neutral position. The value -1 means the point-of-view hat has no angle to report.

0 : Point-of-view hat is pressed forward. The value 0 represents an orientation of 0.00 degrees (straight ahead).

9,000 : Point-of-view hat is pressed to the right. The value 9,000 represents an orientation of 90.00 degrees (to the right).

18,000 : Point-of-view hat is pressed backward. The value 18,000 represents an orientation of 180.00 degrees (to the rear).

27,000 : Point-of-view hat is being pressed to the left. The value 27,000 represents an orientation of 270.00 degrees (90.00 degrees to the left).

 

joyGetCaps ( object me, integer Caps )

Queries a joystick to determine its capabilities

Parameters :

object me : DirectControl Instance.

Caps : Joystick capability to query. Can be one of the following values:

1: Joystick has z-coordinate information.
2: Joystick has rudder (fourth axis) information.
3: Joystick has u-coordinate (fifth axis) information.
4: Joystick has v-coordinate (sixth axis) information.
5: Joystick has point-of-view information.

Returns : True if the joystick has the specified capability and false otherwise.

 

joyGetNumAttachedDevs ( )

Returns the number of joysticks attached to the system. 

Returns : The number of joysticks attached to the system, or 0 (zero) if no joysticks are connected.

 

Error Codes

 

0: Success (no error).

167: The specified joystick is unplugged.
168:
Invalid axis was specified.
169:
Invalid button was specified.

The DirectControl Xtra functions might return additional platform specific error codes that are not listed above.



DirectXtras Inc.
P.O Box 2645, Menlo Park, CA, 94026, U.S.A
Voice: +1-415-5058249, Fax: +1-801-8585841
Toll Free: 1-800-4453093
E-mail General Information: info@directxtras.com
E-mail Technical Support: support@directxtras.com

Copyright © 1996-2004 DirectXtras Inc. All Rights Reserved.
WebMaster: tamar@directxtras.com
Last Updated: 9/18/2004 8:36:38 AM.