Zeus Productions Banner

zOpen and zPrint

for Windows v 1.4

User's Guide




Copyright © 1996-1997. Zeus Productions. All Rights Reserved.
Written by Bruce A. Epstein
(This document last revised May 9, 1997)
zOpen and zPrint are trademarks of Zeus Productions

Welcome!


Thank you for your interest in zOpen and zPrint for Windows. zPrint is included as part of zOpen and they are just some 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.

zOpen seamlessly launches external applications from Director to open or print documents. If you need to:

Then zOpen is for you! And it includes zPrint at no extra charge!


If you have purchased zOpen/zPrint for Windows, this package contains everything you need to run them under both Windows 3.1 and Windows 95 using Director 5.0.1. Director 6.0 will be supported when it ships.


If you are using the demonstration version of zOpen for Windows, a warning dialog box will be posted when you call one of its methods. The release version (without the warning dialog) 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 zOpen/zPrint. Note specifically that Run-Time distribution is royalty-free, but limited to five (5) commercial products per copy of zOpen/zPrint. 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.



For Technical Support:



Table of Contents

1. About zOpen/zPrint for Windows

2. zOpen Installation Notes

3. Using zOpen

4. zOpen/zPrint Methods

5. Trouble-Shooting


6. TroubleShooting and Debugging Your Lingo Code



1. zOpen/zPrint for Windows

A. Introduction

zOpen/zPrint will allow you to open external applications and print external documents with Director. zPrint is included within zOpen at no extra charge! Throughout this guide, the term "zOpen" is used, except when something applies excluzively to zPrint.

This User's Guide, the zOpen 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 zOpen/zPrint product 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.

Also note that when viewing this documentation on a Windows 3.1 machine, the enclosed ".html" files may appear with an ".htm" extension. Because the hyperlinks are looking for ".html" files, they won't work. You can access the ".htm" files by opening them manually from within your browser, or double-clicking them in the File Manager (or File Explorer).

B. zOpen/zPrint Product Features

zOpen facilitates launching executables from Director to open or print external documents.

While the launched application is running, zOpen will cover the desktop, similar to a Projector running in "full-screen" mode.

zOpen allows you to use Director as a front end to a software sampler or other executables such as demos, Adobe Acrobat Reader, or a web browser, such as Netscape Navigator or Microsoft Internet Explorer.

zOpen offers a number of advantages over Lingo's "open" command. Most notably, zOpen:
For many more details, consult the zOpen FAQ.



2. zOpen Installation and Usage Notes


The zOpen Xtra comes in two flavors for Windows 3.1 and Windows 95/NT, sold together as one product: zOpen is an Xtra, and must reside in the Xtras folder, but does not require any special installation. It can reside on a CD-ROM or be copied to a hard drive with the Projector.

You can place both the .X16 and .X32 files in the same folder without fear of conflicts, but delete older versions of zOpen, if any. The correct version of the Xtra (16-bit or 32-bit) will automatically be opened depending on the type of projector in use.

zOpen consults both the Registtry and WIN.INI file to determine the executable associated with an extension. Refer to the zFindExe and zOpenExe methods.

A. Authoring Mode Installation

When using zOpen from within Director, the Xtra should be installed in the "Xtras" folder inside Director's installation directory. Place zOpen.X16 in the Xtras folder where the 16-bit version of Director is installed. Place zOpen.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 placing zOpen.X16 and/or zOpen.X32 in your Xtras folder and restarting Director. zOpen will automatically be available for use throughout the Director session. Do not use "openxlib" or "closexlib" to access zOpen.

B. Run-Time Installation

When using zOpen 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 folder(s).

C. Installation and Usage Notes

D. TroubleShooting Your Installation

If zOpen is installed properly, it should be listed along with other installed Xtras when you type "showXlib" in the message window. If zOpen is not listed as an installed Xtra, run the zOpen.DIR movie included with this package to verify that zOpen is properly installed during authoring mode. You can copy the Lingo code from the example's "startMovie" handler into your own movie to perform the startup check from your Projector as well.

If you are still having trouble:


3. Using zOpen and zPrint


Once zOpen is installed, its methods are automatically available via Lingo. Do NOT use the "openXlib" command to open zOpen, nor the "closeXlib" command to close it.

Below we list the appropriate method(s) to accomplish some common tasks:

A. To Locate an Executable:

B. To Open an Executable:

C. To Open a Document:

You must know the location of the document that you wish to open, but you do not necessarily need to know the name or location of the application to open it with. (Although an appropriate application must be installed on the user's system or available on the CD).

D. To Launch a Browser with a URL:

To create an Internet shortcut to a Specific URL:
  1. Create a file and change its name to include a ".URL" extension. This should turn the file into an "Internet Shortcut" automatically.

  2. Select the file in the File Explorer and choose "Properties" from the File Explorer's File menu. Hit the "Internet Shortcut" tab in the Properties dialog box and enter the Target URL, such as http://www.zeusprod.com.

  3. Pass this .URL file to zFindExe to start the user's browser at the given URL

E. To Print a Document:

You must know the location of the document that you wish to print, but you do not necessarily need to know the name or location of the application to print it with. (Although an appropriate application must be installed on the user's system or available on the CD).


4. Calling zOpen/zPrint's Methods


zOpen contains several methods, each performing a different function. Some Xtras require that you first use the new method to instantiate the Xtra before calling other methods; however, the new method is not required to access the other methods in zOpen, which are Global methods. Simply call zOpen's methods as you would any other Lingo command. Refer to the TechNote, "Installing and Using Xtras" for more details.



Housekeeping Methods

The following three methods are provided for administrative purposes and are not required when using the other methods which perform the real work of zOpen/zPrint:

mMessageList

mMessageList returns a list of the other available methods. Use Lingo's "put" command to print out this information in the message window. This method replaces the mDescribe method provided with XObjects in prior versions of Director.


mDescribe

mDescribe prints information about the other available methods in the message window. It is identical to put mMessageList (xtra "zOpen") and is provided as a convenience for those familiar with the mDescribe method provided with XObjects in prior versions of Director.


new

The new method is not required to use zOpen's (Global-level) methods, but is provided to conform to the Xtras standard. Simply use the other methods as you would use any other Lingo command. New can be used for debugging purposes to ensure that zOpen is installed properly..

Methods for Opening and Printing

Note: You do NOT need to instatiate the Xtra using the "new" method in order to use the following methods.


zFindExe

zFindExe locates the application associated with a particular file type or file extension. It is ideal for locating the user's web browser to open HTML files, Adobe Acrobat Reader for PDF files, or a word processor for TXT files.

zFindExe will locate an application based on the association(s) specified in the Windows Registry file and/or WIN.INI file. (Refer to the TechNote, "Windows INI Files" ). These associations are usually set up when an application is installed, but can also be changed by the user. If there is no application associated with the specified file type or file extension, zFindExe will return the EMPTY string. This is useful for determining whether to prompt the user to install an application. If no association is found and the application is located in a known location, such as a CD, use zOpenExe instead of zFindExe.

Syntax:


Examples:
-- Find Adobe Acrobat Reader to open PDF files
set acrobatPath = zFindExe("pdf")

if acrobatPath = EMPTY then put "Acrobat not found"
else zOpenExe (acrobatPath)

-- Find the default Web browser based on file type
set browserPath = zFindExe("htmlfile")

-- Find the default Web browser based on file extension
set browserPath = zFindExe(".htm")

-- Find Word Processor to open a document
set wpPath = zFindExe(the pathname & "myFile.doc")

-- Find Excel to open Spreadsheets
set excelPath = zFindExe("xls")


Refer to the TechNote, "File Types, Creator Codes and Extensions" for information about common file types and their associated applications.


zOpenDoc


zOpenDoc will open or print a document via its associated executable.



Syntax:
zOpenDoc(doc1, mode, wDir1, wState)

where:

doc1 is a string specifying the path to a document. zOpenDoc searches the Windows Registry file and the WIN.INI file for the appropriate application, based on the document's file extension or file type. The specified document will be opened or printed, based on the specified mode (see below). The document path may exclude the drive letter, which defaults to the current drive.

mode is a string specifying either "print" or "open". Use "print" to print the document using the appropriate application for the document type. You can use zPrintDoc to do the same thing. Use "open" to open the document using the appropriate application for the document type.

wDir1 is a string specifying the default working directory to be set for the application. This can be left blank, using either two quotes in succession (""), or the reserved keyword EMPTY.

wState is an integer from 0 to 3 specifying a window's initial state when the application is opened. 0: Normal, 1: Maximized, 2: Minimized, 3: Hidden.

Note: Some applications do not support all options. This parameter only affects the window's initial state when the application is first opened or printed.

Examples:
set path = the pathName
set wDir = the pathName

-- Open a Bitmap in normal window
put zOpenDoc (path & "zlogofin.bmp", "open", wDir, 0)

-- Open a DOC file in normal window
put zOpenDoc (path & "test.doc", "open", wDir, 0)

-- Print a WRI file
put zOpenDoc (path & "readme.wri", "print", wDir, 0)

-- Open PDF in normal window
put zOpenDoc (path & "quickRef.pdf", "open", wDir, 0)

-- Open PDF file in maximized window
put zOpenDoc (path & "quickRef.pdf", "open", wDir, 1)

-- Print a PDF file with hidden window
put zOpenDoc (path & "quickRef.pdf", "print", wDir, 3)

-- Open an HTML file with web browser
put zOpenDoc (path & "index.htm", "open", wDir, 0)

-- Open a URL file with web browser
put zOpenDoc (path & "zeusprod.url", "open", wDir, 0)

zPrintDoc


zPrintDoc will print a document with its associated executable. It is similar to using the zDocOpen method in print mode.


Syntax:
zPrintDoc(doc1, wDir1)

where:

doc1 is a string specifying the path to a document. zPrintDoc searches the Windows Registry file and the WIN.INI file for the appropriate application, based on the document's file extension or file type. The specified document will be printed. The document path may exclude the drive letter, which defaults to the current drive.

wDir1 is a string specifying the default working directory to be set for the application. This can be left blank, using either two quotes in succession (""), or the reserved keyword EMPTY.

Examples:
-- Print a PDF file
if zFindExe ("pdf") <> EMPTY then
zPrintDoc ("zeus.pdf", the pathname)
else
put "Can't print PDF file"
end if


-- Print a text file
zPrintDoc (the pathname & "test.doc", "")


zOpenExe


zOpenExe opens the specified application with optional parameters such as a document name.


Syntax:
zOpenExe(exe1, param1, wDir1, wState)

where:

exe1 is a string specifying the path to an application. You can use the string returned by zFindExe for this purpose.

param1 is a string specifying the parameters to pass to the application, such as a document and optional flags. The complete path to the document must be specified if the path is different than the working directory (see below). The document path may exclude the drive letter, which defaults to the current drive. If this item is blank, the application will be opened without a document.

wDir1 is a string specifying the default working directory to be set for the application. This can be left blank.

wState is an integer from 0 to 3 specifying the window's initial state when the application is opened. 0: Normal, 1: Maximized, 2: Minimized, 3: Hidden.

Note: Some applications do not support all options. This parameter only affects the window's initial state when the application is first opened.

Examples:
-- Find Adobe Acrobat to open PDF files
set acrobatPath = zFindExe("AcroExch.document")

if acrobatPath = EMPTY then
put "Acrobat not found"
else
put zOpenExe(acrobatPath,the pathname & "zeus.pdf","",0)
end if

-- Open Acrobat without a document
set acrobatPath = zFindExe("pdf")
put zOpenExe(acrobatPath,"","",0)

-- Open an html file with a browser full screen
set browserPath = zFindExe("index.htm")
put zOpenExe(browserPath, the pathname & "index.htm","",1)

-- Open word processor
set wpPath = zFindExe ("doc")
put zOpenExe(wpPath,"test.doc", the pathname, 0)

zOpenCover


zOpenCover opens the specified application with optional parameters such as a document name. zOpenCover is similar to zOpenExe, except that it covers the desktop behind the application with a solid-colored window (you can control the color using the red, green and blue parameters). Furthermore, zOpenCover will pause Director while your secondary application runs and resume Director when the applcations finishes. This gives you a certain amount of linear control over the flow of your Director projects.

Syntax:
zOpenCover (exe1, wDir1, red, green, blue)

where:

exe1 is a string specifying the path to an application. You can use zFindExe to determine the path to an unkownn aplication. You can also specify additional parameters to be passed to the executable separated from the application name by a space. For example you can specify a doucment and flags as part of the exe1 parameter.

wDir1 is a string specifying the default working directory to be set for the application. This should not be left blank.

red, green, and blue are integers between 0 and 255 which control the color of the background cover window. For example:

For pure black, use 0, 0, 0
For pure red, use 255, 0, 0
For pure green, use 0, 255, 0
For pure blue, use 0, 0, 255
For pure white, use 255, 255, 255


Examples:
-- Locate the executable associated
-- with "doc" files and run it
-- using a black cover window
set wpPath = zFindExe ("doc")
zOpenCover(wpPath && "test.doc", the pathname, 0,0,0)

-- Open zeus.pdf in Acrobat Reader with blue background window
zOpenCover ("c:\acroread\acroread.exe zeus.pdf", "g:\test\", 0, 0, 255)


5. Trouble-Shooting


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. Refer to the TechNote, "Trouble-Shooting and Debugging" for an overview of the trouble-shooting process.

A. Testing the External Application and Document


Before trying to launch an application with zOpen, you should test it from the Windows Program Manager or File Explorer by double-clicking the application and verifying that it performs as expected.

If the application works, try double-clicking the document, if any, that you are attempting to open via zOpen. Verify that it launches the correct application. Also, try opening the document from within the application using the "File...Open" command.

If the application and document do not work from Windows, they will not work with zOpen. Refer to the TechNote, "Trouble-Shooting Applications" to identify possible sources of errors when working with documents.

If the application and document work successfully, try running them from the Windows "Run" dialog box. This is located under the Windows 3.1 Program Manager menu, or the Windows 95 Start Menu. Specify the command line in the form

applicationPath documentPath

Such as:

c:\acroread\acroread.exe c:\mydoc\test.pdf

B. Verifying the File Paths


If the application and its document work from the Windows desktop, but not with zOpen, 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 Acrobat Reader, try opening it using something like:

open "c:\mydoc\test.pdf" with "c:\acroread\acroread.exe"

If it doesn't work, the most likely source of error is a syntax error or typo in your path specification, or the files do not exist in the specified location.

Refer to the Zeus TechNote, "Path and File Specifications" for details on specifying a Windows file path, and likely sources of error. Note that referring to a shortcut is not supported by zOpen, and Windows 95 long file names should be avoided. Use DOS-style (eight-dot-three) file names and folder names if possible.

C. Verifying your Lingo Code


Once you have verified that the application works from the Windows Run dialog box or with Lingo's open command, you can test it from your Projector. Common sources of error include:



6. TroubleShooting and Debugging Your Lingo Code:


If you are having trouble, please verify the following before contacting technical support.

Check Your Syntax:

Verify the Parameters:

Problem: zOpen is not locating an association between an executable and my application under Windows 3.1 or 3.1.1


A.The prior version of zOpen.X16 did not examine the (rarely used) Windows 3.x Registry File for associations. It only looked in the WIN.INI file, and if the association was not there, it would not be detected. This is fixed in the latest release version of zOpen, although it has yet to tricke down to the demo version.



Q. What if I am still having problems?


A. If you are still having problems: zOpen is a general purpose product. As such, it is impossible to anticipate every conceivable use, or compensate for the behavior of some non-standard applications.

If you feel that you are using it correctly, and still having problems with zOpen, please contact our technical support department. While we ask that you make a good-faith effort to define the problem, please don't wait until you are pulling your hair out to call us. We stand behind our products, and are happy to help you with any implementation questions

You can reach our World-Class technical support at info@zeusprod.com or 1-908-398-1682. We are very helpful. Before calling, please have Director up and running at a PC that you can access while on the phone with technical support.

Good luck in all your multimedia pursuits.

Zeus Productions


Copyright © 1997. Zeus Productions. All rights reserved.
zOpen and zPrint are trademarks of Zeus Productions.

Last Revised: 05/15/97
###