'\"
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH Tk_CanvasPs 3 4.0 Tk "Tk Library Procedures"
.so man.macros
.BS
.SH NAME
Tk_CanvasPsY, Tk_CanvasPsBitmap, Tk_CanvasPsColor, Tk_CanvasPsFont, Tk_CanvasPsPath, Tk_CanvasPsStipple \- utility procedures for generating Postscript for canvases
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
double
\fBTk_CanvasPsY\fR(\fIcanvas, canvasY\fR)
.sp
int
\fBTk_CanvasPsBitmap\fR(\fIinterp, canvas, bitmap, x, y, width, height\fR)
.sp
int
\fBTk_CanvasPsColor\fR(\fIinterp, canvas, colorPtr\fR)
.sp
int
\fBTk_CanvasPsFont\fR(\fIinterp, canvas, tkFont\fR)
.sp
\fBTk_CanvasPsPath\fR(\fIinterp, canvas, coordPtr, numPoints\fR)
.sp
int
\fBTk_CanvasPsStipple\fR(\fIinterp, canvas, bitmap\fR)
.fi
.SH ARGUMENTS
.AS Tcl_Size "numPoints"
.AP Tk_Canvas canvas in
A token that identifies a canvas widget for which Postscript is
being generated.
.AP double canvasY in
Y-coordinate in the space of the canvas.
.AP Tcl_Interp *interp in/out
A Tcl interpreter;  Postscript is appended to its result, or the
result may be replaced with an error message.
.AP Pixmap bitmap in
Bitmap to use for generating Postscript.
.AP int x in
X-coordinate within \fIbitmap\fR of left edge of region to output.
.AP int y in
Y-coordinate within \fIbitmap\fR of top edge of region to output.
.AP "int" width in
Width of region of bitmap to output, in pixels.
.AP "int" height in
Height of region of bitmap to output, in pixels.
.AP XColor *colorPtr in
Information about color value to set in Postscript.
.AP Tk_Font tkFont in
Font for which Postscript is to be generated.
.AP double *coordPtr in
Pointer to an array of coordinates for one or more
points specified in canvas coordinates.
The order of values in \fIcoordPtr\fR is x1, y1, x2, y2, x3, y3,
and so on.
.AP Tcl_Size numPoints in
Number of points at \fIcoordPtr\fR.
.BE
.SH DESCRIPTION
.PP
These procedures are called by canvas type managers to carry out
common functions related to generating Postscript.
Most of the procedures take a \fIcanvas\fR argument, which
refers to a canvas widget for which Postscript is being
generated.
.PP
\fBTk_CanvasPsY\fR takes as argument a y-coordinate in the space of
a canvas and returns the value that should be used for that point
in the Postscript currently being generated for \fIcanvas\fR.
Y coordinates require transformation because Postscript uses an
origin at the lower-left corner whereas X uses an origin at the
upper-left corner.
Canvas x coordinates can be used directly in Postscript without
transformation.
.PP
\fBTk_CanvasPsBitmap\fR generates Postscript to describe a region
of a bitmap.
The Postscript is generated in proper image data format for Postscript,
i.e., as data between angle brackets, one bit per pixel.
The Postscript is appended to the result of interpreter \fIinterp\fR
and \fBTCL_OK\fR is returned unless an error occurs, in which case
\fBTCL_ERROR\fR is returned and the interpreter result is overwritten
with an error message.
.PP
\fBTk_CanvasPsColor\fR generates Postscript to set the current color
to correspond to its \fIcolorPtr\fR argument, taking into account any
color map specified in the \fBpostscript\fR command.
It appends the Postscript to the interpreter \fIinterp\fR's result and returns
\fBTCL_OK\fR unless an error occurs, in which case \fBTCL_ERROR\fR is
returned and the interpreter's result is overwritten with an error message.
.PP
\fBTk_CanvasPsFont\fR generates Postscript that sets the current font
to match \fItkFont\fR as closely as possible.
\fBTk_CanvasPsFont\fR takes into account any font map specified
in the \fBpostscript\fR command, and it does
the best it can at mapping X fonts to Postscript fonts.
It appends the Postscript to interpreter \fIinterp\fR's result and
returns \fBTCL_OK\fR unless an error occurs, in which case
\fBTCL_ERROR\fR is returned and the interpreter's result is
overwritten with an error message.
.PP
\fBTk_CanvasPsPath\fR generates Postscript to set the current path
to the set of points given by \fIcoordPtr\fR and \fInumPoints\fR.
It appends the resulting Postscript to the result of interpreter \fIinterp\fR.
.PP
\fBTk_CanvasPsStipple\fR generates Postscript that will fill the
current path in stippled fashion.
It uses \fIbitmap\fR as the stipple pattern and the current Postscript
color;  ones in the stipple bitmap are drawn in the current color, and
zeroes are not drawn at all.
The Postscript is appended to interpreter \fIinterp\fR's result and
\fBTCL_OK\fR is returned, unless an error occurs, in which case
\fBTCL_ERROR\fR is returned and the interpreter's result is
overwritten with an error message.
.SH KEYWORDS
bitmap, canvas, color, font, path, Postscript, stipple