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.
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.
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.
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.
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.
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 canvasPathcreateitem
command with the exception for the window item which is lacking.
-offsetxx
(Default = 0) Sets the x origin of the print canvas.
-offsetyy
(Default = 0) Sets the y origin of the print canvas.
-scalefactor
(Default = 1.0) Sets scale of the print canvas. Typically used when changing the
resolution of the page format.
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:
-resolutionlist
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.
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:
-dialogboolean
(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.
-pageformatpageformattoken
Makes the settings from any previous page setup dialog to be used
with this dialog.
-parenttoplevelPath
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.
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.
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:
-printobjectprintobjecttoken
Lets you use the settings from a previously created printObject
for your dialog. All other options (see below) will override these settings.
-printerstring
Specifies a printer name to use as default printer.
-copiesinteger
Sets the number of copies.
-firstpageinteger
Sets the first page to print.
-lastpageinteger
Sets the last page to print.
-pageformatpageformattoken
Makes the settings from any previous page setup dialog to be used in
this print session.
-pagerange{minPage maxPage}
-parenttoplevelPath
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.
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.
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.
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!