The PrintOMatic Xtra can be used in two ways. The first and simplest way to use PrintOMatic is by calling the global print
command, passing the Director object(s) you would like to print as parameters:
member "illustration" of castLib 1 print "Some example text for printing" print sprite 1, sprite 5 print castLib "documentation"
If all you need to do is print something out quickly and easily, you can stop reading now; that's all there is to it.
Creating an Instance of the PrintOMatic Xtra
The second way of using PrintOMatic, which is much 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")
if not objectP(doc) then exit
An instance of the PrintOMatic Xtra is called a "document object ", also referred to in this documentation as a "document". Be sure to check the validity of the document object using the objectP()
function after creating it (shown in the example above). Once you have created a document, 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
Page 0 (zero) of a document is the document's "master page". The contents of the master page are drawn on every body page of the document, beneath the body page's contents. When you create a new document, the master page is the default page until you create a new page (see Adding Pages, below.) All items added before the first newPage
command will appear on the document's master page.
A common item to place on the master page is a page number. Use the setPageNumSymbol
command in combination with a text item on the master page to place a page number on every page of your document:
-- place a page number at the bottom right of the page
set pgNumSym = numToChar(166) -- paragraph symbol on mac
setPageNumSymbol doc, pgNumSym
setTextJust doc, "right"
drawText doc, Point(getPageWidth(doc),getPageHeight(doc)), "page"&&pgNumSym
For a document object to be printable, it must contain at least one page. Add new pages to a document using the newPage
command. A page added using newPage
becomes the "current page", where all new graphic elements, "frames", and other items are placed. To make a previously added page (including the master page) the "current page", use the setPage
command.
newPage
doc -- add a new page setPage doc, 0 -- return to the master page
PrintOMatic uses the same coordinate system as the Director stage, which places (0,0) at the top-left corner. Coordinate values increase towards the bottom and right sides of the page. All drawing coordinates are specified in points, with 72 points to the inch.
All drawing coordinates for objects in PrintOMatic are relative to the page margins, which are set using the setMargins
command. The drawing area defined by the margins applies to the entire document.
Calling pageSetup
or setLandscapeMode
may change the size of the page, thereby changing the coordinate system, as well as the values returned by getPageWidth
and getPageHeight
. If you store these values in Lingo variables, be sure to retrieve them again after calling pageSetup
or setLandscapeMode
.
The most common method of placing text or graphics on a PrintOMatic page is to create one or more rectangular "frames" on the page, then append contents to these frames. The contents of multiple "linked" frames will flow from one frame to the next.
For example, to create a two-column layout, create two frames side by side on the page, and link them together so the text and graphics flow from one frame to the next:
-- create a new document
set doc = new(xtra "PrintOMatic")
-- get width and height
set w = getPageWidth(doc)
set h = getPageHeight(doc)
-- create a new page
newPage doc
-- create the first column
newFrame doc, Rect(0,0,(w/2)-18,h), FALSE
-- create the second column, linked to the first
newFrame doc, Rect((w/2)+18,0,w,h), TRUE
The last parameter in the newFrame
command specifies whether or not the new frame is linked to the previous frame.
Once you have created one or more "frames" to append to, you can add items such as sprites and cast members to the document using the append
and appendFile
commands:
append
doc, member "title" of castLib 1, TRUE append doc, sprite 1, TRUE appendFile doc, the pathName&"myFile.eps", FALSE
The last “autoAppend” parameter of append
and appendFile
calls specifies whether pages are automatically added to the document as content is inserted. Please see the append
command for a detailed description of the "autoAppend" feature of PrintOMatic.
IMPORTANT NOTE: Text field cast members will be printed with all their fonts and styles intact. However, Rich Text cast members will only be printed as bitmaps, because of the way Director stores their data..
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
A second way of placing items on a PrintOMatic page is to explicitly position them as graphic elements in the exact location you want them to appear. You can place pictures, single lines of text, rectangles, rounded rectangles, lines and ovals on the page in this manner. Many of the graphic element drawing routines take a Lingo Rect
as the second parameter, to specify their position and size. The last parameter to thse calls designates whether the object is filled (TRUE
) or stroked (FALSE
):
drawRect
doc, Rect(0,0,50,50), TRUE drawRoundRect doc, Rect(0,0,50,50), 25, FALSE drawOval doc, Rect(100,100,500,500), TRUE
The drawLine
routine takes a starting Point
and ending Point
as its parameters:
drawLine
doc, Point(0,0), Point(500,0)
The drawPicture
routine can position a bitmapped image on the page using a Point
or a Rect
to specify size and location. If you use a Point
, the image will be positioned at its normal size (72 dpi for cast members) with its top left corner at the specified point:
drawPicture
doc, member "illustration", Point(0,100)
If you specify the image location using a Rect
, the image will be scaled to fit at the largest possible size within the Rect
without distorting the image. Unless the provided Rect
has the exact same proportions as the image, the entire Rect
may not be filled with the image data:
drawPicture
doc, member "illustration", Rect(0,0,500,300)
Drawing the Contents of the Stage
The contents of the Director stage can be placed on a PrintOMatic page using the drawStagePicture
routine. The size and positioning rules for drawStagePicture
are the same as for drawPicture
: if a Point
is specified, the top left corner of the Stage picture will be placed there; if a Rect
is specified, the stage image will be scaled to fit within the Rect
without distortion.
drawStagePicture
doc, Point(0,0) drawStagePicture doc, Rect(0,0,the width of the stage, the height of the stage)
The drawStagePicture
routine can print a cropped portion of the stage by specifying the area you want to capture after specifying the image's position on the page:
drawStagePicture
doc, Rect(0,0,100,100), Rect(50,50,150,150)
Finally, you can capture the stage picture from Director's off-screen buffer by adding a TRUE
to the end of any of the above specified forms of drawStagePicture
. Capturing from the offscreen buffer will prevent the contents of any windows or MIAWs in front of the Stage from being captured along with the stage image.
drawStagePicture
doc, Point(0,0), Rect(50,50,100,100), TRUE
When you have appended all the elements you want to print to the document, 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 by setting its value equal to zero. This will release all the memory taken up by the document object.
set doc = 0
PrintOMatic contains a number of other routines that are not described in the sections above. Please consult the full message list for a complete listing of all the commands supported by the PrintOMatic Xtra.