KEYWORDS
maccarbonprint - namespace that contains commands specific for
the MacCarbonPrint package. This describes version 0.2.
package require MacCarbonPrint ?version?
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.
- 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.
Print, Mac OS X, and MacCarbonPrint
Copyright © 2003 Mats Bengtsson
Copyright © 2003 ElectronicFarm