Copyright: Copyright ® 1994-96 Electronic Ink


The PrintOMatic Lite Xtra

Version 1.5.1

The PrintOMatic Lite Xtra provides essential printing functionality for Macromedia Director 5.0.

Its main purpose is to add a global print handler to Lingo that will print just about anything. More advanced Lingo users can create an instance of the Xtra for more control over page settings, print preview, and more.

Topics in this section:

PrintOMatic "Heavy": The Full Version

Using PrintOMatic Lite

PrintOMatic Lite Message List

Release Notes


PrintOMatic Heavy: The Full Version
PrintOMatic "Heavy": The Full Version

The PrintOMatic Xtra is the full featured version of PrintOMatic Lite. It is the premier printing tool for Director. PrintOMatic adds a full set of page-layout, text and graphics printing features to Director 4.0 and 5.0 projects on Macintosh and Windows.

PrintOMatic includes commands for accurately specifying the position of any text or graphic element on the page. PrintOMatic documents can contain graphic files from disk, styled text, graphic primitives, cast member bitmaps, and snapshots of the Director stage.

Product Features

-	Generates multi-page layouts with full control over the placement of text and graphic elements on the page.

-	Print styled text: any combination of available fonts, sizes, or styles

-	Print PICT, BMP or EPS files from disk, any portion of the Director stage, or Director cast members.

-	Print object-oriented graphic primitives: lines, boxes, ovals and rounded rectangles.

-	"Master Page" can contain any combination of text or graphic elements

-	Automatic page numbering

-	Customizable and hideable Print Progress dialog

-	Paper-saving Print Preview feature

-	Supports all Macintosh and Windows compatible printers

-	Supports color and landscape-mode printing

-	Fully compatible with MacOS™, Windows™ 3.1 and Windows™ 95

Where to Find PrintOMatic

Unregistered but fully functioning "demonstration" copies of PrintOMatic are distributed as shareware. The latest versions can always be downloaded from the following FTP location:

ftp://ftp.rahul.net/pub/peterv/

Or visit Electronic Ink's Web site:

http://www.rahul.net/peterv/

All documentation, sample code and ordering information for PrintOMatic is included in the downloadable distribution packages at this site.

Purchasing PrintOMatic

The PrintOMatic Xtra is published and distributed worldwide by gray matter design. The registered edition of PrintOMatic is shipped on a cross-platform CD-ROM disc, along with demonstrations, sample code, and other tidbits. To order the PrintOMatic Xtra or to request more information, contact gray matter design:

gray matter design

300 Brannan Street, Suite 210

San Francisco, CA 94107

Tel: (800) 933-6223 or (415) 243-0394

FAX: (415) 243-0396

Email: gmdesign1@aol.com

http://www.gmatter.com/


Using PrintOMatic Lite

The PrintOMatic Lite Xtra can be used in two ways. The first and simplest way to use PrintOMatic Lite is by calling the global print command, passing the Director object(s) you would like to print as parameters:

print member "illustration" of castLib 1

print "Some example text for printing"

print sprite 1, sprite 5

print castLib "documentation"

If all you have to do is print something out quickly and easily, you can stop reading now. That's all there is to it.

Using an Instance of the PrintOMatic Lite Xtra

The second way of using PrintOMatic Lite, which is more powerful and customizable than  simply using the global print command,  is to create an instance of the Xtra using the new command:

set doc = new(xtra "PrintOMatic_Lite")

if not objectP(doc) then exit

An instance of the PrintOMatic Lite Xtra is called a "document object ". Be sure to check the validity of the document object using the objectP() function before continuing.  Once you have created a document object, you can change its attributes, such as the document's name, margins and landscape orientation:

setDocumentName doc, "My Document"

setMargins doc, Rect(36,36,36,36)

setLandscapeMode doc, TRUE

Then, you can add items such as sprites and cast members to the document object using the append command:

append doc, member "title" of castLib 1

append doc, sprite 1

Text field cast members will be printed with all their fonts and styles intact. Rich text cast members' bitmap images will be printed. However, text strings have no inherent style data associated with them. You can use setTextFont, setTextSize and setTextStyle to set the attributes of text strings that you append.

setTextFont doc, "Helvetica"

setTextSize doc, 10

setTextStyle doc, "normal"

append doc, copyrightInfo

When you have appended all the elements you want to print to the document object, show the user the job setup dialog, and print the document if doJobSetup returns TRUE. If you don't want the user to see the job setup dialog, omit the call to doJobSetup.

if doJobSetup(doc) then print doc

Finally, dispose of the document object by setting its value equal to zero. This will release all the memory taken up by the PrintOMatic Lite document.

set doc = 0


PrintOMatic Lite Message List

This is the full list of commands supported by the PrintOMatic Lite Xtra. Click on any of the hypertext links below to jump to a description of the command and how to use it:

-- PrintOMatic Lite Xtra

-- Version 1.5.1

-- Copyright 1994-96 Electronic Ink

--

-- CREATE/DESTROY/RESET A DOCUMENT

new object

forget object

reset object

--

-- DOCUMENT PRINTING SETUP

doPageSetup object

doJobSetup object

setLandscapeMode object, boolean

setMargins object, rect

setDocumentName object, string

--

-- TEXT ATTRIBUTES

setTextFont object, string

setTextSize object, int

setTextStyle object, string

--

-- APPEND TO DOCUMENT

append object, *

--

-- PRINTING

printPreview object

* print *


print

Syntax:	print member whichCastmember [,... ]

print member whichCastmember of castLib whichLib [, ... ]

print castLib whichCast  [, ... ]

print sprite whichSprite  [, ... ]

print string [, ... ]

print list [, ... ]

print documentObject

The print command is an extension to Lingo provided by the PrintOMatic Lite Xtra. This command is used to print one or more items to the currently selected printer. The following Director objects are printable:

type of object	what gets printed

text field cast member	the text of the field, using the specified fonts and styles

rich text cast member	the bitmap image of the cast member, including anti-aliasing

bitmap cast member	the cast member graphic

PICT cast member	the cast member graphic

cast library	all printable cast members in the library, in cast sequence

sprite	the cast member of the sprite

text string	the text string, in the default font (Geneva10pt on Macintosh, Arial 10pt on Windows)

list (linear or property)	the elements in the list

document object	the contents of the PrintOMatic Lite document object

Examples:

You can print a number of objects together with a single call to the print command:

print "Printed Output" & RETURN , member "image" , member "someText"

One of the most powerful uses of the print command is to assemble all the elements of a document into a single cast library, and print the entire cast library with one line of Lingo:

print castLib "document"


new

Syntax:	set doc = new(xtra "PrintOMatic_Lite")

The new command is used to create a new instance of the PrintOMatic Lite  Xtra. The newly created instance is called a document object, since it represents a printable "document": a collection of items that are printed together in a single print job by PrintOMatic Lite.

Once the document object has been created, its settings can be modified, items can be appended to the document, and it can be printed or displayed in a print preview window.

Important Note:

new will return an error code instead of a document object if there is no currently selected printer, or a printing error occurs. Always check the result of new with the objectP() function to make sure you have a valid Xtra instance before continuing!

Example:

The following code example creates a new document, sets the page orientation to landscape mode, appends an image with a caption to the document, and prints the document:

set doc = new(xtra "PrintOMatic_Lite")

if not objectP(doc) then exit

setLandscapeMode doc, TRUE

append doc, member "picture"

append doc, RETURN & "Image printed by the PrintOMatic Lite Xtra."

if doJobSetup (doc) = TRUE then print doc

set doc = 0


forget

You should NEVER call the forget command directly for an instance of a Lingo Xtra. Director automatically calls forget  when an instance of an Xtra needs to be disposed; calling forget yourself can lead to memory leaks or crashing.

 Use the following syntax to explicitly get rid of a PrintOMatic Lite document object when you are done using it:

set doc = 0

Where doc is the PrintOMatic Lite document object you want to dispose of. Explicitly disposing of document objects is optional, since Director will automatically get rid of the object when it's no longer referenced anyway.


reset

Syntax:	reset documentObject

The reset command is used to reset an instance of a PrintOMatic Lite document object. All the contents of the document and any existing pages are deleted. The page settings, such as margins and page orientation, are reset to their default values.


doPageSetup

Syntax:	doPageSetup(documentObject)

Returns:	TRUE if the user clicks "OK" in the page setup dialog

FALSE if the user clicks "Cancel" in the page setup dialog

The doPageSetup function displays the Page Setup dialog for a document object. This function must be called on an empty document, before any elements are appended to it. doPageSetup returns TRUE if the user clicks the "OK" button in the dialog box, or FALSE if the user clicks "Cancel".


doJobSetup

Syntax:	doJobSetup(documentObject)

Returns:	TRUE if the user clicks "Print" in the job setup dialog

FALSE if the user clicks "Cancel" in the job setup dialog

The doJobSetup function displays the job setup dialog for a PrintOMatic Lite document. This function should be called right before printing. If doJobSetup returns TRUE, the user clicked the "Print" button, and printing should proceed. If doJobSetup returns FALSE, the user clicked "Cancel", and you should not print the document. This function cannot be called on an empty document.

Example:

This is the recommended way of calling doJobSetup right before printing a PrintOMatic Lite document object:

if doJobSetup (doc) = TRUE then print doc


setLandscapeMode

Syntax:	setLandscapeMode documentObject, trueOrFalse

This command switches the page orientation of a PrintOMatic Lite document object between landscape and portrait orientation. Since this method changes the whole coordinate system of the document, your document must be empty when you call setLandscapeMode. Call reset on your document beforehand just to make sure.

In Windows, this method works in a very straightforward manner: call it, and the landscape mode changes.

Unfortunately, it's an entirely different story on the Macintosh. The only safe way to change the page orientation on the Mac is by showing the Page Setup dialog and letting the user manually select landscape mode. While showing a Page Setup dialog may be fine for normal software applications such as Word, it's often unacceptable in the context of a multimedia production.

To get around this, PrintOMatic Lite for the Macintosh relies on a "printer database" to store default landscape and portrait page setups for the most common Macintosh printers. This printer database consists of a set of 'PHDL' resources located in the same file as the PrintOMatic Lite Xtra. This database is used by the setLandscapeMode method in the Macintosh version of PrintOMatic Lite.

 If the currently selected printer is not found in the printer database, the user is asked to MANUALLY create default Page Setups for landscape and portrait modes, and those settings are saved and added to the database. This is done through a series of prompt dialogs presented automatically by PrintOMatic when you call setLandscapeMode for an unknown printer.

These user-configured "custom entries" to the printer database are stored in a file called "PrintOMatic Preferences" on the user's hard disk. Subsequent calls to setLandscapeMode on the same computer, with the same printer selected, won't present any annoying dialogs.

What the presence of this "printer database" means is that when you change the landscape mode on the Macintosh, all the other Page Setup settings such as scaling, font substitution, etc., will also revert to those found in the printer database. This is important if the user has changed any of these settings (during a call to doPageSetup) before setLandscapeMode is called.


setMargins

Syntax:	setMargins documentObject, marginRect

This command sets the margins of a PrintOMatic Lite document object. The marginRect parameter is in the form of a Lingo Rect. Values are specified in the format Rect(left, top, right, bottom). The measurements are in points (72 points to the inch). Since this method changes the whole coordinate system of the document, your document must be empty when you call setMargins. Call reset on your document beforehand just to make sure.

Example:

The following example creates a new document and sets the margins to two inches (144 points) on the left, and one inch (72 points) on all other sides.

set doc = new(xtra "PrintOMatic_Lite")

if not objectP(doc) then exit

setMargins doc, Rect(144,72,72,72)


setDocumentName

Syntax:	setDocumentName documentObject, name

This command sets the name of a PrintOMatic Lite document object, which is displayed in the print progress dialog as the document prints. If background printing is enabled, this document name is also displayed by PrintMonitor (Mac) or Print Manager (Windows) as your document prints in the background.


setTextFont

Syntax:	setTextFont documentObject, fontName

This command sets the text font that will be applied to non-styled text data (such as strings) that are subsequently appended to the PrintOMatic Lite document object. If the requested font is not available, the default font (Geneva on the Macintosh, Arial on Windows) is used.


setTextSize

Syntax:	setTextSize documentObject, fontSize

This command sets the text size that will be applied to non-styled text data (such as strings) that are subsequently appended to the PrintOMatic Lite document object.


setTextStyle

Syntax:	setTextStyle documentObject, styleString

This command sets the text style that will be applied to non-styled text data (such as strings) that are subsequently appended to the PrintOMatic Lite document object. The names of the style values correspond exactly to the Director "textStyle" property. Possible values for text styles are:

normal

plain

bold

italic

underline

On the Macintosh, the following additional styles are available:

outline

condense

extend

shadow

All values except normal or plain are added together in a call to setTextStyle, so you can combine a number of styles together in a single call.

Example:

The following example creates a PrintOMatic Lite document object, sets the default font to bold italicized 10 point Helvetica, and prints a short text string:

set doc = new(xtra "PrintOMatic_Lite")

if not objectP(doc) then exit

setTextStyle doc, "bold, italic"

setTextFont doc, "Helvetica"

setTextSize doc, 10

append doc, "Some sample text to print out."

if doJobSetup(doc) then print doc

set doc = 0


append

Syntax:	append documentObject, member whichCastmember [, ... ]

append documentObject, member whichCastmember of castLib whichLib [, ... ]

append documentObject, castLib whichCast [, ... ]

append documentObject, sprite whichSprite [, ... ]

append documentObject, string [, ... ]

append documentObject, list [, ... ]

This command appends one or more items to a PrintOMatic Lite document object.

type of object	what gets printed

text field cast member	the text of the field, using the specified fonts and styles

rich text cast member	the bitmap image of the cast member, including anti-aliasing

bitmap cast member	the cast member graphic

PICT cast member	the cast member graphic

cast library	all printable cast members in the library, in cast sequence

sprite	the cast member of the sprite

text string	the text string, in the default font (Geneva10pt on Macintosh, Arial 10pt on Windows)

list (linear or property)	the elements in the list

Example:

The following example creates a PrintOMatic Lite document object, sets the document name, appends a number of items to the document, and prints it:

set doc = new(xtra "PrintOMatic_Lite")

if not objectP(doc) then exit

setDocumentName doc, "My Example Document"

append doc, sprite 1

append doc, [member "image", member "caption", sprite 5]

append doc, castLib "printout"

if doJobSetup(doc) then print doc

set doc = 0


printPreview

Syntax:	printPreview(documentObject)

Returns:	TRUE if the user previews all the pages in the document

FALSE if the user cancels the print preview

This function displays an on-screen print preview of a PrintOMatic Lite document object. Typing any key or clicking in the preview window advances to the next page; typing command-period (Escape on Windows) cancels the preview without displaying all the pages. When the document can't be displayed on the main screen at 100% size (which is most of the time, unless you have a big monitor), the page is scaled to fit.


PrintOMatic Lite Release Notes

1.5    First public release of the PrintOMatic Lite Xtra.

1.5.1    Fixed a bug in the global print handler that prevented it from working after the first time it was invoked.