Zeus Productions Banner

zOpen™ and zPrint™

for Windows v 2.0

User's Guide




Copyright © 1996-1997. Zeus Productions. All Rights Reserved.
Written by Bruce A. Epstein
(This document last revised November 5, 1997)

If you are reading this document off-line, the latest version of this User's Guide
can be found on our web site at http://www.zeusprod.com/doc/zowguide.html.

Refer to the Tech Alerts at http://www.zeusprod.com/products/alert.html for late-breaking solutions/updates involving zOpen and other Zeus Products.



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 6.0 (Director version 5.0.1 is also fully supported).


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 exclusively 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 Registry and WIN.INI files to determine the executable associated with an extension. Refer to the zFindExe and zOpenExe methods.

A. Authoring Mode Installation

zOpen supports Director 6, as well as Director 5. When using zOpen while authoring within Director, the zOpen should be installed in the "Xtras" folder inside Director's installation directory. Place zOpen.X32 in the Xtras folder where your 32-bit version of Director is installed.

If using the 16-bit version of Director 5.0.1, place zOpen.X16 in the Xtras folder where the 16-bit version of Director is installed.

After placing zOpen.X16 and/or zOpen.X32 in your Xtras folder(s) and restarting Director, zOpen will automatically be available for use throughout the Director session. Type "showXlib" in the Message Window or run the example DIR file to verify installation. Do not use "openXlib" or "closeXlib" to access or close the zOpen Xtra.

B. Run-Time Installation

When using zOpen from within a Projector, the Xtra(s) must be placed in a folder call "Xtras" one level down from the Projector. Projectors will not access Xtras installed in the Authoring Mode Xtras folder(s) described above.

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.

Methods for Opening and Printing

Note: You do NOT need to instantiate 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
	-- This example uses zFindExe for error checking
	-- before attempting to run an application

	set acrobatPath = zFindExe(".pdf") 

	if acrobatPath = EMPTY then
	  alert "Acrobat not found" 

	else
	  zOpenExe (acrobatPath)
	end if

	-- 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
	-- Here, a document is used to located the Word Processor,
	-- but you could just as easily have used only the "doc"
	-- extension for the search.
	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. In most cases, this should be the folder containing the document to be opened, but some applications may require a specific working directory, such as the folder in which they are installed. Failure to set this properly may prevent zOpen from properly opening your application and/or document.

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: (it is assumed that the file to open is located in the same folder as the Director movie, as indicated by the pathname, which is also used as the working directory.) 
	-- Open a Bitmap in normal window 
	-- This example demonstrates uses zFindExe for error checking
	-- before attempting to open the document
	set appPath = zFindExe(".bmp") 
	if appPath = EMPTY then
	  alert "Bitmap editor not found" 
	else
	  zOpenDoc (the pathName & "zlogofin.bmp", "open", the pathName, 0) 
	end if

	-- Open a DOC file in a normal window 
	zOpenDoc (the pathName & "test.doc", "open", the pathName, 0) 

	-- Print a WRI file 
	zOpenDoc (the pathName & "readme.wri", "print", the pathName, 0) 


	-- Open PDF in a normal window 
	zOpenDoc (the pathName & "quickRef.pdf", "open", the pathName, 0) 

	-- Open PDF file in a maximized (full-screen) window 
	zOpenDoc (the pathName & "quickRef.pdf", "open", the pathName, 1) 

	-- Print a PDF file with hidden window 
	zOpenDoc (the pathName & "quickRef.pdf", "print", the pathName, 3) 

	-- Open an HTML file with web browser 
	zOpenDoc (the pathName & "index.htm", "open", the pathName, 0) 

	-- Open a URL file with web browser 
	zOpenDoc (the pathName & "zeusprod.url", "open", the pathName, 0)

zPrintDoc


zPrintDoc will print a document with its associated executable. It is similar to using the zOpenDoc 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. In most cases, this should be the folder containing the document to be printed, but some applications may require a specific working directory, such as the folder in which they are installed. Failure to set this properly may prevent the application from properly printing your document.

Examples: 
	-- Print a PDF file 
	if zFindExe (".pdf") <> EMPTY then 
	  zPrintDoc ("zeusprod.pdf", the pathname) 

	else 
	  alert "Can't find application to print a 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. In most cases, this should not be left blank, but should be the folder containing the document to be opened. If you are not opening a document, you should set the working directory to the folder containing the application, or the folder containing the Projector (as indicated by the pathname). Failure to set this properly may prevent zOpen from properly opening your application and/or document.

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 
	-- This example demonstrates uses zFindExe to locate Acrobat
	-- before attempting to open Acrobat

	set acrobatPath = zFindExe(".pdf")

	if acrobatPath = EMPTY then 
	  alert "Acrobat not found" 

	else
	  zOpenExe(acrobatPath, the pathname & "zeusprod.pdf", "", 0) 

	end if 


	-- Open Acrobat without a document and supressed the splash screen
	set acrobatPath = zFindExe(".pdf") 
	zOpenExe(acrobatPath, "/s", "", 0) 


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


	-- Open a word processor 
	set wpPath = zFindExe (".doc") 
	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 application 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 unknown application. 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 document 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. In most cases, this must be the folder containing the document to be opened. If you are not opening a document, you should set the working directory to the folder containing the application, or the folder containing the Projector (as indicated by the pathname). Failure to set this properly may prevent zOpen from properly opening your application and/or document.

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)


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.

Syntax: 
	put mMessageList (Xtra "zOpen")

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.

Syntax: 
	mDescribe (Xtra "zOpen")

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.

Syntax: 
	set instance = new (Xtra "zOpen")
Example: 
	set myInstance = new (Xtra "zOpen")



	-- check for success
	if objectP(myInstance) then

	  put "zOpen instantiated successfully"

	  -- Dispose of the instance
	  set myInstance = 0
	else
	  put "Failure instantiating zOpen. Error:" && myInstance
	end if


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 extenal applications and documents.

If the application and document work successfully from the Windows desktop, 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:

Below are listed some common problems, and their most likely solutions:

Refer to the Tech Alerts for late-breaking solutions/updates involving Zeus Products.

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.

Problem: When I return from my external application, my Director presentation has stopped.

A.This is the normal and expected operation under the Director development environment. This is not an issue when running from a Projector. If you want your Projector to continue to animate while another application is running, use the "Animate in Background" option when creating your Projector. If you want Director to pause while the external application is running, turn off the "Animate in Background" option when creating your Projector.


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-732-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: 11/05/97
###