Office of Digital Humanities

DigHT 310
Printing in LiveCode

As you might expect, LiveCode provides ways to output the content of your stack to a printer. Let's look at the LiveCode language elements that enable you to control printer output.

Printing Cards—the print Command

The most basic capability is to print a card or cards from your stack, relying on the layout of your cards to determine the layout of the printed page. You could, of course, simply use the Print Card... item from the File menu. But often you want more control over the final appearance of the printed product. The print command gives you the capability to initiate a print card job from any handler. There are several forms of the command:

print card --print the designated card

print card 1

print card from topLeft to rightBottom --print the rectangular area from the designated card

print card 1 from 100,50 to 500,450

print stack -- print all the cards in the designated stack

print stack "myStack"
print all cards --these two commands are equivalent

print number cards -- print the given number of cards, starting from the current card.

print 20 cards

print marked cards -- print all cards in the stack for which the marked property is true

print card into pageRectangle -- print the card into a rectangle that you define

print card 1 into 72,100,450,400 -- the four values indicate the left, top, right, bottom edges of the printing rectangle, in point from the edge of the paper. (1 inch = 72 points)

print break -- forces a page break

If you specify a form that includes more than one card (such as print stack), the cards may be printed more than one to a page, depending on the size of the cards and on whether you specify a pageRect.

Printing Properties

There are several properties that allow you to control the appearance of the printed product. Here are some of them:

TERM	TYPE	Description
availablePrinters	property	Use the availablePrinters to retrieve a return-delimited list of all available system printers. These names can be used to select the active printer by using the printerName property.
printerName	property	Use the printerName to get and set the currently active system printer. Setting the printerName causes the specified printer to be chosen and the print properties will be updated to reflect the defaults for the printer. Setting the printerName to empty causes the default system printer to be set as active. If the specified name is not a known printer, the result is set to "unknown printer" and nothing changes.
printerSettings	property	Use the printerSettings to get and set the active system printer and default settings. The settings string is a binary string encoding printer driver specific options together with paper and job settings. Setting the printerSettings will attempt to change the default system printer to the one encoded in the settings string, upon failure "unknown printer" will be returned. Setting the printerSettings to empty causes the default system printer to be set as active.
printerFeatures	property	Use the printerFeatures to determine what features the printer supports. This property is a comma-delimited list of features from the following list: collate : the printer supports collation copies : the printer supports printing multiple copies color : the printer supports printing in color duplex : the printer can print in duplex mode
printerOutput	property	Use the printerOutput to get and set the output mode for the active printer. The value "device" means printer output will be sent the physical printer. The value "preview" means printer output will be sent to a preview window (OS X only). The value "file:filepath" means printer output will be sent to the file specified in filepath. (On OS X, the output format is PDF, on Windows it is platform-specific, on Linux it is PostScript) The value "system" means printer output is system defined and not understood by LiveCode but will be preserved in the printerSettings string (read-only)
printTitle	property	Use the printTitle to get and set the name of the next document to be printed. This is passed to the OS and will be displayed in the printer queue. If the printTitle is empty, the title of the defaultStack at the time of the 'open printing' command is used.
printScale	property	Specifies how much cards are shrunk or expanded when printing. The default value is 1. The printScale specifies the ratio between the number of pixels in the card and the number of points on the printed page. A ratio of 1 means the printed and screen card should be the same size, if the screen's resolution is 72 pixels per inch. For example, if a card is 360 pixels wide and you want its printed image to be 4 inches (288 points) across, set the printScale to 0.8 (288 pixels divided by 360 points). Examples: set the printScale to 2 -- prints double size set the printScale to .25 -- prints one quarter size
printMargins	property	Specifies the width of the page margins when printing cards. The margins are in the order left, top, right, bottom. The default is 72,72,72,72 (72 points = 1 inch) Examples: set the printMargins to 72,144,72,72 -- 2" margin on top, 1" on the other sides.
printGutters	property	When more than one card is printed per page, specifies how much blank space is used to separate printed cards on the page. There are two parameters, for the vertical and horizontal separation. (72 points = 1 inch.) Examples: set the printGutters to 18,36 -- 1/4" vertical separation, 1/2" horizontal separation.
printPaperSize	property	Specifies the dimensions of the paper used for printing. This is the size of the physical paper before any scaling or rotation is applied. The printPaperSize consists of two non-negative integers, separated by a comma. By default, the printPaperSize is the pixel size set by the print driver. On Mac OS and OS X systems, this is set in the Page Setup dialog box; on Windows systems, it is set in the printing options dialog box. Example: set the printPaperSize to 612,792 -- 8.5x11 inches, US Letter size
printPaperOrientation	property	Specifies whether LiveCode prints in landscape mode or portrait mode. Possible values are: portrait: rotated 0 degrees landscape: rotated 90 degrees clockwise reverse portrait: rotated 180 degrees clockwise reverse landscape: rotated 270 degrees clockwise (Reverse options not supported on Windows.) Example: set the printPaperOrientation to "landscape" -- prints the document rotated 90 degrees clockwise
printPaperCopies	property	Use the printCopies to get and set the number of times the next document should be printed.
printCollate	property	Use the printCollate to get and set the current collation mode of the printer. If the printCollate is true and more than one copy is printed, individual copies will be ordered correctly.
printDuplex	property	Use the printDuplex to get and set the current duplex mode of the printer. The value "none" means that the printer should print single-sided. The value "long edge" means that the printer should print double-sided without reflecting the back page The value "short edge" means that the printer should print double-sided and reflect the back page
printRanges	property	Use the printRanges to specify what pages should be printed in the current job. This value can be: "all" to indicate all pages should be printed "current" to indicate that the application's current page should be printed "selection" to indicate that the current selection should be printed a comma-separated list of integers, or integer ranges in the form "n-m" specifying the pages, e.g. "1-10,20-45,50" During the printing loop, if the printRanges is a list of ranges then LiveCode will automatically skip pages that are not within any ranges. If the printRanges is not such a list, then the application must determine what should be printed itself.
printPageNumber	property	Use the printPageNumber to determine the index of the page currently being printed in the current printing loop. This property is empty when a printing loop is not in effect.
formatForPrinting	property	***Windows only!*** Specifies whether font layout is done using printer fonts or screen fonts. Windows systems may use different font versions for printing and for screen display, and the spacing of the print version may differ from the spacing of the screen version. This can result in layouts and line breaks differing between the screen display and the printed result. For the best appearance of printed cards in a stack, make sure the stack is closed (and not in memory), then set the stack's formatForPrinting property to true before opening the stack to print it. Important! Do not edit field text in a stack whose formatForPrinting is true. Doing so can cause display anomalies. Set the formatForPrinting property to false before you make changes to text in fields. The spacing of printer font versions usually results in a difficult-to-read display when these fonts are used for screen viewing. To avoid display problems, set the formatForPrinting property to true only when printing. To let the user preview the appearance of the printed output, set the formatForPrinting property to true before opening the stack.

Displaying the Print Dialog

There is a command that lets you display a print dialog before starting the print job:

answer printer - Displays a platform-appropriate printer setup dialog. If the user does not cancel the dialog, upon return the various printer setting properties will be updated to reflect their choices.

answer page setup - Opens a dialog that lets you set standard printing options, like paper size and page orientation, before printing. These choices also affect the various printer setting properties.

Printing Text from Fields

In addition to printing entire cards you may also send formatted or unformatted text to the printer by using special commands:

revPrintField field descriptor - Prints the text in the field using the field's text properties.

revPrintText text,header text,footer text,fieldTemplate - Prints any text. Also allows you to set a header and footer. If the text being printed is plain text, and a fieldTemplate is specified, the text is printed with that field's textFont, textSize, and textStyle

revShowPrintDialog showPageSetup,showPrintDialog - Lets you display the standard print dialog for the user before printing The two arguments—showPageSetup and showPrintDialog— should be set to either true or false.

More on Printing Multiple Cards

You can print batches of cards in a single job by using:

open printing [with dialog] -- The with dialog option displays the standard print dialog on Macintosh systems. On Windows and Unix systems, this option is ignored. Instead, use the answer printer command, above.

close printing

Between the open and close statements you can issue one or more print card commands. Cards printed in conjunction with this structure will print to a single page (assuming they are sized to do so.) For example, the following button handler will print all the cards in the stack, four to a page:

  on mouseUp 
	 set the printRotated to true
	 open printing with dialog
	 if the result is "Cancel" then exit mouseUp
	 set the printScale to .4
	 set the printMargins to 36,36,36,36 --1/2 inch margins
	 set the printGutters to 18,18 --1/4 inch gutters
	 repeat with i = 1 to number of cards
	   print card i
	 end repeat 
	 close printing -- sends job to printer
  end mouseUp

You can use a print break command within the open printing structure to force a page break.