Thank you for your interest in zLaunch
for Macintosh, one of the many utilities for Macromedia Director available
from Zeus Productions. Please visit our
web site for more information on our products
for both Mac and Windows and custom
development services.
zLaunch seamlessly launches other applications from Director:
open
command...
Then zLaunch is for you! If you are not sure if zLaunch
is appropriate for you, consult our Needs
Analysis FAQ.
If you have purchased zLaunch for Macintosh, this package contains everything
you need to run zLaunch on both standard (680x0) Macs and PowerMacs, using
Director 6.0 (Director 4.0.4 and 5.0.1 are also supported).
zLaunch is also available in a Windows
3.1/95 version, sold separately. The zLaunch
for Windows User's Guide is included in this package as well.
zLaunch for Macintosh can be obtained by contacting
Zeus Productions Sales at:
Be sure to download
the latest End-User and Run-Time licensing agreements, as you are bound
by these agreements if you use zLaunch. Note specifically that Run-Time
distribution is royalty-free, but limited to five (5) commercial products
per copy of zLaunch. Also note that you must include the Zeus logo and copyright
information in your product(s). Refer to the licensing information included
with this package, or licensing
information on our web site for complete details.
We know that zLaunch will help you to use external applications with
Director and we hope that you find zLaunch easy to use.
This User's Guide, the zLaunch FAQs
and the example Director movie have been heavily revised. Even if you
are familiar previous versions, you will benefit from numerous additional
tips and trouble-shooting hints provided throughout this
guide. The latest versions of the Zeus
TechNotes cited throughout this publication are available on our web site where you'll also find the latest zLaunch information.
When viewing the latest
version of this User's Guide on our web site, all hyperlinks will access
the latest information. When viewing this HTML file locally on your machine,
some hyperlinks will not work. For example, the links to glossary
terms are only available on our web site.
zLaunch facilitates launching executables from Director. It allows you
to quit Director, so you can launch demos even in low RAM situations, and
then restart Director when the launched executable completes.
While the launched application is running, zLaunch's desktop cover remains
in effect, similar to a Projector running in "full-screen" mode.
zLaunch allows you to use Director as a front end to a software sampler
or other executables such as demos, ReadMe files, Acrobat PDF files, or
a web browser.
zLaunch is truly amazing, and is available for both Macintosh and Windows (sold separately).
zLaunch for the Macintosh now offers:
"zLaunch" is a single Fat Binary executable, which means it runs
on all types of Macs, and runs natively
on PowerMacs. You can use it with any Macintosh Director projector: "Standard
Macintosh" (680x0), "Power Macintosh Only" (PowerMac native),
or "All Macintosh Models" (Fat Binary).
zLaunch does not require a formal installation procedure. Simply include
zLaunch and one or more external configuration files in the same folder
as your Director movie and/or Projector from which it is called. zLaunch
can reside in any folder, but it is easiest if it is in the same folder
with the Director movie during development or your Projector during run-time.
zLaunch can run from either a hard drive or a CD. There is no
need to copy it into the System Folder, or similar requirement.
Include your zLaunch configuration file in the same folder
with zLaunch, unless you are creating your configuration file
dynamically.
As stated above, there is a single Fat Binary version of zLaunch for
all Macs.
Naturally, you cannot run a PowerMac-only projector on a 680x0 Mac, nor
can zLaunch launch a PowerMac-only application on a 680x0 Mac.
You must either create a 680x0-compatible or Fat Binary version of the projector.
You must launch a 680x0-compatible or Fat Binary version of the external
executables, or, warn the user if the application only works on PowerMacs.
If you build a Fat projector, the process name when it is run on a Standard Macintosh will always be "Projector". The internal name "Projector" does not change even when you change the Projector's file name. The best solution is the leave the Projector named "Projector", and refer to this name on lines 1, 2 and 5 of your configuration file (see below). You can create an alias to your projector and give the alias the name you want your users to see.
As stated above, there is a single Fat Binary version of zLaunch for
all Macs.
PowerMacs can run any type of Macintosh-compatible application, and zLaunch
can launch either native or non-native applications.
For optimal performance one would either run a Fat Binary or PowerMac version
of the executable(s) but you can also run a Standard (680x0) Mac executable.
Due to differences between the two operating systems, the zLaunch calling
sequence is different under the two platforms. Be sure to consult the example
Director movie, and the zLaunch
for Windows user's guide separately for details.
Due to differences between the two operating systems, there are some notable
differences between zLaunch for Macintosh and zLaunch for Windows. Be sure
to consult the example Director movie, and the zLaunch
for Windows user's guide separately for details. Please note:
quit command, whereas zLaunch for Macintosh will quit
your projector for you (refer to the parameter specified on Line 1).
You can use zLaunch with Director 4, Director 5, or Director 6. When you create your projector, you must use the "Animate in Background" option, accessible via the "Options..." button in the "Create Projector" dialog box. Failure to do so will prevent zLaunch from being able to quit your projector.
When using Director 4.0, upgrade to Director 4.0.4, which fixes numerous
bugs and allows you to build Fat Binary Projectors. Be sure to complete
the update properly, as an improper updating of resource files can lead
to faulty projectors.
Refer to the Zeus
TechNote, "Creating Director
Projectors for Macintosh and Windows", for details on the different
projector types, and how to cover the Macintosh Desktop from within a projector.
When using Director 5.0, upgrade to Director 5.0.1, which fixes some
bugs in Director 5.0. Be sure to complete the update properly, as an improper
updating of resource files can lead to faulty projectors. If using FileIO,
obtain the latest version of the FileIO Xtra, as the one that shipped with
Director 5.0 was a beta version and had numerous bugs.
Refer to the Zeus
TechNote, "Creating Director
Projectors for Macintosh and Windows", for complete details on
projector options.
Zeus Productions has made every effort to test zLaunch with Director
6.0, although it is always possible that new issues arise with the new version
of Director. If you are aware of any such issues, please send
e-mail to Zeus.
Refer to the Zeus
TechNote, "Creating Director
Projectors for Macintosh and Windows", for complete details on
projector options.
A "Stub Projector" is a small projector that references external
assets, including external DIR or DXR files. Stub Projectors are STRONGLY
recommended. Refer to the Zeus
TechNote, "Creating and Using Stub
Projectors", for complete details on creating stub projectors.
To control zLaunch on the Macintosh, you must specify a configuration file
(described below) that contains the parameters needed to launch your particular
application.
This configuration file is an ASCII text file, created in SimpleText. You
must create a separate configuration file for each different application
you launch with zLaunch. (zLaunch for Windows allows multiple sets of
parameters in a single INI file)
NOTE: Due to differences in the operating systems, zLaunch for Macintosh
uses a different method than zLaunch for Windows to specify its parameters.
The format of the Macintosh configuration file is different than the format
of the Windows configuration (INI) file. Refer to the zLaunch
for Windows User's Guide.
Furthermore, you can not use the parameterList method (available in zLaunch
for Windows) with zLaunch for the Macintosh. Refer to the TechNote "Creating Files Dynamically"
for more information on dynamically setting the parameters. This is demostrated
fully in the example DIR file.
To initiate zLaunch, use Lingo's "open...with"
statement, of the form:
open the pathName & "configFile" with the pathName & "zLaunch"
Where configFile is the name of the configuration file described
in detail below.
Once you have created a configuration file, you can run zLaunch using the
following Lingo syntax:
open the pathName & "myConfigFile" with the pathName & "zLaunch"
NOTE: You must substitute in the name of your configuration file in place
of "myConfigFile". This example assumes that the
configuration file and zLaunch are in the same folder as your Director movie,
as indicated by the Lingo property "the pathName".
When the user clicks a button to launch an external application, you would
ordinarily do the following:
For a full-blown example, refer to the ZLAUNCH.DIR example Director file.
Once zLaunch is started using Lingo's "open"
command, you should wait in the next frame for zLaunch to kill the projector.
You must NOT wait in a tight repeat loop. Wait in a frame using
"go the frame" instead:
on exitFramego the frameend
The configuration must contain exactly seven line, with the parameters as follows:
Several example files are provided in the Example Config Files folder.
A typical file may look like this:
MyProjector
MyProjector
HD:Desktop Folder:launchTest:SimpleText
SimpleText
HD:Desktop Folder:launchTest:MyProjector
WAIT
2
Here is a line-by-line explanation of this sample configuration file
Line 1 - Kills the process called "MyProjector"
(this is your Projector without any path)
Line 2 - Waits for process called "MyProjector"
(i.e. the projector named above) to die
Line 3 - Starts up SimpleText, located
at:
"HD:Desktop Folder:launchTest:SimpleText"
Line 4 - Waits until SimpleText is
terminated (presumably by the user).
Line 5 - Re-launches the projector located at
:
"HD:Desktop Folder:launchTest:MyProjector"
Line 6 - Waits for that projector to indicate
that it is started up
Line 7 - Waits an additional two seconds before
dismissing the black window that covers the desktop, and killing zLaunch.
Each line in the configuration file corresponds to a parameter to be passed to zLaunch. Below is a detailed explanation of each line of the configuration file.
The parameter on line 1 allows zLaunch to cover the desktop before killing
the projector in order to prevent the flash of the desktop. Line 1 should
contain the name of your projector that zLaunch should kill.
Technically, this is the task name or "process name" which zLaunch
should kill. This should be the name of your Projector as shown by its Finder
icon, excluding the path name. Do NOT include the file path to the projector
on this line. Use the projector's name, and NOT the name of the current
Director movie.
If you build a Fat projector, the process name when it is run on a
Standard Macintosh will always be "Projector". The internal name
"Projector" does not change even when you change the Projector's
file name. The best solution is the leave the Projector named "Projector",
and refer to this name on lines 1, 2 and 5 of your configuration file (see
below). You can create an alias to your projector and give the alias the
name you want your users to see.
Specify the special word NONE if you do not want zLaunch to kill
the projector (i.e. to leave the projector running). In this case, you may
want to quit the projector via Lingo manually, or not at all.
This is also useful for debugging when you are testing zLaunch from the
Finder. Refer to the debugging section below.
You should NOT quit the projector via Lingo if you are specifying that zLaunch
should kill it for you. Otherwise, the desktop may flash.
Do NOT allow any extraneous spaces on the line, as zLaunch is "whitespace-sensitive".
Do not use quotes around the text. "NONE" should be in all capital
letters, but the projector name is not case-sensitive.
Once zLaunch attempts to kill your projector, it may take several seconds
before the projector actually dies. Line 2 ensures that the projector has
died before zLaunch launches the secondary application, such as a demo.
This option gives the Projector a chance to quit in order that it frees
up RAM and releases system resources such as control over the palette.
Line 2 should contain the name of the process which zLaunch should wait
for to die.
This should ordinarily be the same as line 1, the name of the Projector,
excluding the path (process names don't include the path). Do NOT include
the file path to the projector on this line. Use the projector's name,
and NOT the name of the current Director movie.
If you build a Fat projector, the process name when it is run on a
Standard Macintosh will always be "Projector". The internal name
"Projector" does not change even when you change the Projector's
file name. The best solution is the leave the Projector named "Projector",
and refer to this name on lines 1, 2 and 5 of your configuration file. You
can create an alias to your projector and give the alias the name you want
your users to see.
If for some reason, you want to launch the secondary executable immediately,
specify NONE. This will prevent zLaunch from explicitly waiting for
the projector to die (although line 1 can still specify the projector to
be killed). In that case, the RAM in use by Director may not yet be available
to your executable.
Do NOT allow any extraneous spaces on the line, as zLaunch is "whitespace-sensitive".
Do not use quotes around the text. "NONE" should be in all capital
letters, but the projector name is not case-sensitive.
Line 3 specifies the application for zLaunch to launch, plus an optional document name. The proper format for this line depends on what parameters you want to pass to zLaunch. There are three possible formats for this line, depending on whether you need to launch:
To launch an application in a known location without a document, simply
specify the full path to the application to be launched.
The general syntax is:
applicationPath:applicationName
The following example would run the application "MyDemo"
located in the "MyFolder" folder on the disk named
"MyCD":
MyCD:MyFolder:MyDemo
Refer to the example configuration file "Netscape No Doc" which
launches Netscape, as found by the complete path specification, without
a document.
(This option is supported as of version 1.12 )
To launch an application in a known location with a document from a known
location, use the keyword OPEN, followed by the full path to the
application to be launched, followed by the full path to the document
to be opened. Separate the parameters with forward slashes ("/").
The general syntax is:
OPEN/applicationPath:applicationName/documentPath:documentName
The following example would open the document "ReadMe"
located in the "MyDocs" folder on the disk named "MyCD"
with the application "SimpleText" located in the
"MyApps" folder on the disk named "MyCD":
OPEN/MyCD:MyApps:SimpleText/MyCD:MyDocs:ReadMe
Slashes are used to separate the parameters because spaces, colons and commas
can be part of a Macintosh file names or path. Do NOT allow any extraneous
spaces at the beginning or end of the line, nor between the parameters or
adjacent to the slashes. Do not use quotes around the parameters. "OPEN"
should be in all capital letters, but the application and document paths
are not case-sensitive. Be sure to include any special characters, such
as the trademark symbol (tm) from the application's path or name.
Refer to the example configuration file "Netscape by path w/Doc"
which launches Netscape, as found by the complete path specification, and
a document, also specified by its complete path.
Using "OPen" (last two letters lowercase) instead of "OPEN"
will cause zLaunch not to hide the menu bar, if applicable.
(This option is supported as of version 1.12 )
On the Macintosh, each file contains a unique, hidden Creator
Code or "signature". zLaunch can use this Creator Code to
locate the application and launch it. Refer to the Zeus
TechNote, "File Types, Creator
Codes and Extensions"
To launch an application from an unknown location with a document from a
known location, use the keyword OPSG (OPen SiGnature)
followed by the Creator Code of the application to be launched, followed
by the full path to the document to be opened. Separate the parameters
with forward slashes ("/").
The general syntax is:
OPEN/creatorCode/documentPath:documentName
The following example would open the document "ReadMe"
located in the "MyDocs" folder on the disk named
"MyCD" with the application whose Creator code is
"ttxt" (in this case SimpleText):
OPSG/ttxt/MyCD:MyDocs:ReadMe
Slashes are used to separate the parameters because spaces, colons and commas
can be part of a Macintosh file names or path. Do NOT allow any extraneous
spaces at the beginning or end of the line, nor between the parameters or
adjacent to the slashes. Do not use quotes around the parameters. "OPSG"
should be in all capital letters, and the Creator Code is case-sensitive.
The document path is not case-sensitive.
Not also that Creator Codes are always exactly four characters. Some
Creator Codes may be three letters followed by a space, which is mandatory.
Using "OPsg" (last two letters lowercase) instead of "OPSG"
will cause zLaunch not to hide the menu bar, if applicable.
Refer to the example configuration file "Netscape by Sig (Creator)
w/Doc" which launches Netscape Navigator, by it's Creator Code ("Signature
Code"), which happens to be "MOSS", with a document, specified
by its complete path.
Note:
Once zLaunch launches your executable, you want it to wait for that process
to terminate.
Line 4 specifies the name of the launched executable that zLaunch should
wait for before relaunching the projector, allowing the user to interact
with the launched application at their leisure.
zLaunch simply waits in the background while this process is still active.
Once the specified process terminates, zLaunch will attempt to relaunch
the projector specified in line 5.
Technically, this is the task name or "process" name for which
zLaunch should wait. Typically the user must terminate the launched application,
although some applications may terminate automatically.
This is ordinarily the name of the launched application that was specified
in Line 3, excluding the path (process names don't include the path).
If for some reason, you do not want zLaunch to wait while the secondary
executable is active, specify NONE. This will prevent zLaunch from
explicitly waiting for the application. In that case, the RAM in use by
the application may not yet be available to relaunch your projector.
Do NOT allow any extraneous spaces on the line, as zLaunch is "whitespace-sensitive".
Do not use quotes around the text. "NONE" should be in all capital
letters, but the application name is not case-sensitive. Be sure to include
any special characters, such as the trademark symbol (tm) from the application's
name.
Note: You need to know the name of the executable, even if you launched
it using its Creator Code on Line 3.
Line 5 specifies the name of the projector, including the path, to re-launch
when the launched application is exited by the user. (NOTE: This can be
different from the original projector, but is usually the same as lines
1 and 2, with the addition of the full path specification).
If for some reason, you do not want zLaunch to re-launch the projector,
specify NONE. In that case, zLaunch will simply terminate to the
Finder.
Do NOT allow any extraneous spaces on the line, as zLaunch is "whitespace-sensitive".
Do not use quotes around the text. "NONE" should be in all capital
letters, but the projector path is not case-sensitive. Be sure to include
any special characters, such as the trademark symbol (tm) from the projector's
name.
Refer to the Zeus
TechNote, "Path and File Specifications"
for details on specifying a Macintosh file path.
Line 6 controls whether zLaunch waits for the re-launched Projector to
start up again. This parameter is used ensure that the projector specified
in Line 5 has started before zLaunch kills itself.
Because applications may take a few seconds to start up, this parameter
helps prevent zLaunch from dismissing the desktop-covering black window
too early.
If you specify the keyword WAIT, zLaunch waits until the application
specified on Line 5 has started. If you specify the keyword NOWAIT,
zLaunch continues immediately once it relaunches the projector. Refer to
the parameter for Line 7 below.
Line 7 specifies the time delay (in seconds) to wait AFTER re-launching
the projector (as specified in Line 5) before zLaunch kills itself and its
desktop-covering black window.
Some applications do not take control of the screen as soon as they start.
In the case of Director, it does not cover the desktop immediately.
This parameter prevents zLaunch from dismissing the desktop-covering black
window before the projector opens a window to cover the desktop.
Start with a time delay of 2 (seconds), and adjust it as necessary.
The first step towards fixing a problem is to determine its exact nature.
To say "it doesn't work" is not very helpful. Try to narrow down
the problem by determining what does work, which will leave you with
a better understanding of where the problem lies.
Before trying to launch an application from zLaunch, you should test
it from the Finder by double-clicking the application and verifying that
it performs as expected.
If the application does not work in the Finder, it will not work with zLaunch.
You may not be able to launch an application because:
If the application works, also try double-clicking the document, if any,
that you are attempting to open via zLaunch. Verify that it launches the
correct application. Also, try opening the document from the application
using the "File...Open" command. Lastly, try dragging and dropping
the document onto the application in the Finder.
If the document does not work from the Finder, it will not work with zLaunch.
You may not be able to open a document because:
If the application and its document work from the Finder, try starting
them from Director's message window using Lingo's "open"
or "open...with" command. (Note that the document
name precedes the application name when using the "open...with"
command, ).
For example, to verify that you have the correct path to SimpleText, try
launching it using something like:
open "HD:docs:ReadMe" with "HD:Applications:SimpleText"
Likely sources of error include:
Refer to the Zeus TechNote, "Path and File Specifications" for details on specifying a Macintosh file path.
If you have determined the correct path to the application and the document,
you are ready to verify its operation with zLaunch.
First, verify that zLaunch itself is working by double-clicking the zLaunch
executable in the Finder. It should black out the entire screen, and the
screen should stay black until you hit Command-Q to quit zLaunch. If this
does not work, refer to the list of possible sources of error in section
A, "Testing the External Application and Document",
above. The most likely source of error is a file that was corrupted during
the download or while copying it from another machine over a network.
If both zLaunch and your external application appear functional, you
should test your configuration file in isolation of your Director Projector.
First, quit all other applications. Then, drag and drop your configuration
file onto the zLaunch icon. (The configuration file must have a file Type
of "TEXT". Refer to the Zeus
TechNote, "File Types, Creator
Codes and Extensions".) If you can't drag and drop the configuration
file onto zLaunch, make sure that the configuration file was created in
SimpleText. Also try rebooting and rebuilding your desktop.
zLaunch should attempt to launch the application specified in line 3 of
your configuration file. It should then wait for that application to run,
as specified by line 4 of your configuration file.
zLaunch may not work with aliases or with hidden files. If you are using
an alias or a hidden file, test it first with a normal file.
Most of the example configuration files use "NONE" as the projector
name, so that you can debug the launching of the application without repeatedly
running your projector.
Once you can successfully use zLaunch from the Finder, add your projector
name to the configuration file. Refer to the discussion of Lines 1, 2 and
5 of the configuration file for details.
If Lines 3, 4, 5, 6 and 7 of your configuration file are correct, from the
Finder, zLaunch should launch the specified application, wait for it to
terminate, and then re-launch the projector.
Once you have verified that lines 3 through 7 of your configuration file
are correct. You can test zLaunch from your Projector. Common sources of
error include:
Below are listed some common problems, and their most likely solutions.
You may be running the wrong executable, or
there may have been a problem with the download. Make sure that you have
the latest version of zLaunch and download it again if necessary.
Test your project using the debug version
of zLaunch. It uses a "Zeus" wallpaper pattern to cover the desktop,
which makes it obvious when zLaunch is active and/or in the foreground.
If zLaunch does not launch your application,
there are several distinct possibilities:
The problem is either a syntax error in your
configuration file, a problem with you Lingo technique, or a problem with
the way you built the projector.
The likely cause is that you are not properly
waiting for the projector to die before launching the application. This
is controlled via Line 2 of the configuration file. This line tells zLaunch
to wait until the projector has died before proceeding. Line 2 of the configuration
file should ordinarily be the same as line 1 of the configuration file.
For some reason, zLaunch is not waiting
for the launched application to terminate as you would expect.
Be sure that all of the components for the
application are present and in the required folder(s). Some applications
require hidden files which you may have accidentally omitted, or require
files to be in a certain location. Test the application separately from
zLaunch to verify its operation.
zLaunch is probably having trouble finding
the document:
A projector can only start at its beginning,
but you can simulate a restart using the sample Lingo code in the ZLAUNCH.DIR
example movie. It records the frame and movie name in a small text file,
and restores the projector's position the next time it is run. You can
use the savePosition() handler to store the projector position,
and the restorePosition() handler to restore it.
If your application does not have any menu resources, the Macintosh
menu bar may flash when switching between applications. Use a resource
editor, such as ResEdit, to copy
the "mctb" resources from
zLaunch's resource fork
into the resource fork of your application. Be sure to make a backup copy
of both zLaunch and your application first.
The color in palette position 120 is used
to draw a thin outline around the stage. If this color is bright, it will
be readily visible.
There are a few possibilities:
The OPSG command works only with a file.
If you do not want to open a file, don't use the OPEN command. Just specify
the application name alone on line 3 of the configuration file.
Create a dummy resource-only file using ResEdit.
Set the Creator Code to match your application that you are launching.
If you are still having problems:
Good luck in all your multimedia pursuits.
Zeus Productions
Last Updated 09/01/97
Copyright © 1996-1997. Zeus Productions. All Rights Reserved.
###