NAME

maccarbonprint - namespace that contains commands specific for the MacCarbonPrint package. This describes version 0.2.

SYNOPSIS

package require MacCarbonPrint ?version?

DESCRIPTION

The MacCarbonPrint package creates the ::maccarbonprint:: namespace with commands. It gives an Tcl interface to Apple's Carbon Printing Manager. There are two dialog windows that control how printing is made, the page setup dialog, and the print dialog. The rest of the commands control the printing loop, opens a print document, makes a print window (page) for drawing, ejects the drawed page, and eventually, closes the print document. Note that these four commands must always be called in matching pairs, after a print page has been created it must also be closed when finished drawing.

Presently, the drawing commands are identical to the canvas create commands with one exception; there is no create window command. All options are identical.

By default, the printers resolution is the same as the screens resolution, typically 72 dpi. This means that a one pixel wide line is drawn with the corresponding width on paper which may look to bold. A page format object may therefore be configured with a higher resolution than 72 dpi to obtain finer lines. However, in order for the printed image not to shrink, the corresponding print window must also be scaled using the same factor. Special considerations are need to display text as the font size must also be properly scaled.

The print loop is controlled by the (close|open)(doc|page) commands. The close/open commands must be called in matching pairs. You should not display any error messages while inside the printing loop, since the printing system may already have taken care of this. A typical example without any error checking is shown below:

set res [::maccarbonprint::print]
if {[llength $res] > 0} {
    set printObj [lindex $res 1]
    ::maccarbonprint::opendoc $printObj 1 1
    set win [::maccarbonprint::openpage $printObj]

    # Drawing.
    $win create image 320 40 -anchor nw -image $anImage
    ...

    # Close down.
    ::maccarbonprint::closepage $printObj
    ::maccarbonprint::closedoc $printObj
}

The only information you should preserve each time the user prints the document should be that obtained via the Page Setup dialog. The information supplied by the user through the Print dialog should pertain to the document only while the document prints, and you should not re-use this information if the user prints the document again.

COMMANDS

maccarbonprint::close printObject
Closes the printing loop, and releases all resources associated with the printObject.

maccarbonprint::closedoc printObject
Closes the printing loop, and releases all resources associated with the printObject. Must be called after a maccarbonprint::opendoc command, and after a maccarbonprint::closepage command.

maccarbonprint::closepage printObject
Closes the printing page, and deletes the corresponding print window (canvas). Must be called after a maccarbonprint::openpage command.

maccarbonprint::getdocumentformats
Returns a list of the the spool file formats that can be generated for the specified printing session. Typically application/pdf, and may also include postscript if supported.

maccarbonprint::getprinternames
Returns a list of the the printers currently available. The returned printer names can be used in the -printer option of the ::maccarbonprint::print command.

maccarbonprint::loadpageformat path
Restores the pageformat object stored in a file with the given path.
Returns the token for the restored pageformat object.

maccarbonprint::loadprintsettings path ?-key value ...?
Restores the printsettings stored in a file with the given path and creates a printObject for them. The following key-value pairs are allowed:

-copies integer
Sets the number of copies.

-firstpage integer
Sets the first page to print.

-lastpage integer
Sets the last page to print.

-pageformat pageformattoken
Uses the given page format for this print object.

-pagerange {minPage maxPage}

Returns a two element list: {type printObject}, where type is any of the buttons: printer, file, fax, preview, or unknown.

maccarbonprint::opendoc printObject firstPage lastPage ?-documentformat format?
Initiates the printing loop. The firstPage and lastPage are used for the progress window. If the format option is postscript you must use the maccarbonprint::postscript to provide the drawing commands.

maccarbonprint::openpage printObject ?-offsetx x -offsety y -scale factor?
Makes a new fresh printing page and associated print window for drawings. Print window command is returned. This token is a command that can be used exactly as a canvasPath create item command with the exception for the window item which is lacking.

-offsetx x
(Default = 0) Sets the x origin of the print canvas.

-offsety y
(Default = 0) Sets the y origin of the print canvas.

-scale factor
(Default = 1.0) Sets scale of the print canvas. Typically used when changing the resolution of the page format.

maccarbonprint::pageformatconfigure pageformattoken ?-key value ...?
If no options given, it returns a list of -key value describing the features of the page format pageformattoken that is returned from the maccarbonprint::pagesetup command. The keys are -adjustedpaperrect, -adjustedpagerect, -unadjustedpaperrect, -unadjustedpagerect, -resolution, -orientation, -scale. The following option may be used:

-resolution list
Sets the printers resolution which is typically 72 dpi as default. The list can either be a single floating point value describing both the horizonthal and vertical resolutions, or be a two element list decribing horizonthal and vertical resolutions separately.

maccarbonprint::pagesetup ?-key value ...?
Displays a page setup dialog. If the user presses the OK button it returns a pageformat token, which can be used in the maccarbonprint::pageformatconfigure and maccarbonprint::print commands. The following options may be used:

-dialog boolean
(Default = true) The dialog is displayed by default, but a page format object may be created with default settings without showing the dialog. This page format object may be used in the maccarbonprint::print command.

-pageformat pageformattoken
Makes the settings from any previous page setup dialog to be used with this dialog.

-parent toplevelPath
Instead of displaying a standalone toplevel dialog window, a so called sheet window is displayed, which slides down from the given toplevel window's name list.

maccarbonprint::postscript printObject psdata
Sends psdata to the printer. Must be called between an maccarbonprint::openpage and a maccarbonprint::closepage command. Two conditions must be fulfilled; postscript must be a supported ducument format (and returned by the maccarbonprint::getdocumentformats command), and postscript format must have been set as the document format in the maccarbonprint::opendoc call.

maccarbonprint::print ?-key value ...?
Displays a print dialog, and returns empty if the cancel button was pressed. It starts the print session unless the cancel button is pressed. The print session must be closed with either a maccarbonprint::closedoc or a maccarbonprint::close command in order to release the resources associated with the printObject. If any other button is pressed it returns a two element list: {type printObject}, where type is any of the buttons: printer, file, fax, preview, or unknown. The printObject is the print token used in many of the commands, and defines the settings used when printing. The following options may be used:

-printobject printobjecttoken
Lets you use the settings from a previously created printObject for your dialog. All other options (see below) will override these settings.

-printer string
Specifies a printer name to use as default printer.

-copies integer
Sets the number of copies.

-firstpage integer
Sets the first page to print.

-lastpage integer
Sets the last page to print.

-pageformat pageformattoken
Makes the settings from any previous page setup dialog to be used in this print session.

-pagerange {minPage maxPage}

-parent toplevelPath
Instead of displaying a standalone toplevel dialog window, a so called sheet window is displayed, which slides down from the given toplevel window's name list.

maccarbonprint::printcanvas canvasPath printObject
High level command to handle the complete printing loop (opendoc to closedoc) when printing a canvas widget. The printObject is returned from the maccarbonprint::print command.

maccarbonprint::printconfigure printObject
Returns a list of -key value options for a print settings object. The keys are any of -copies, -documentformattypes, -firstpage, -lastpage, -pagerange, and all the options returned by the maccarbonprint::pageformatconfigure command.

maccarbonprint::printtext textPath printObject
High level command to handle the complete printing loop (opendoc to closedoc) when printing a text widget. The printObject is returned from the maccarbonprint::print command. Very primitive!

maccarbonprint::savepageformat pageformattoken path
Stores the settings in the given pageformat object in a file with the given path.
Returns an empty string.

maccarbonprint::saveprintsettings printObject path
Stores the settings in the given print object in a file with the given path.
Returns an empty string.

KEYWORDS

Print, Mac OS X, and MacCarbonPrint