1 \section{Module
\module{canvas
}}
4 \sectionauthor{J\"org Lehmann
}{joergl@users.sourceforge.net
}
6 One of the central modules for the PostScript access in
\PyX{} is
7 named
\verb|canvas|. Besides providing the class
\verb|canvas|, which
8 presents a collection of visual elements like paths, other canvases,
9 \TeX{} or
\LaTeX{} elements, it contains the class
10 \texttt{canvas.clip
} which allows clipping of the output.
12 A canvas may also be embedded in another one using its
\texttt{insert
}
13 method. This may be useful when you want to apply a transformation on
14 a whole set of operations..
16 \declaremodule{}{canvas
}
18 \subsection{Class
\class{canvas
}}
20 This is the basic class of the canvas module, which serves to collect
21 various graphical and text elements you want to write eventually to an
24 \begin{classdesc
}{canvas
}{attrs=
[], texrunner=None
}
25 Construct a new canvas, applying the given
\var{attrs
}, which can be
26 instances of
\class{trafo.trafo
},
\class{canvas.clip
},
27 \class{style.strokestyle
} or
\class{style.fillstyle
}. The
28 \var{texrunner
} argument can be used to specify the texrunner
29 instance used for the
\method{text()
} method of the canvas. If not
30 specified, it defaults to
\var{text.defaulttexrunner
}.
34 Paths can be drawn on the canvas using one of the following methods:
36 \begin{methoddesc
}{draw
}{path, attrs
}
37 Draws
\var{path
} on the canvas applying the given
\var{attrs
}.
40 \begin{methoddesc
}{fill
}{path, attrs=
[]}
41 Fills the given
\var{path
} on the canvas applying the given
45 \begin{methoddesc
}{stroke
}{path, attrs=
[]}
46 Strokes the given
\var{path
} on the canvas applying the given
50 Arbitrary allowed elements like other
\class{canvas
} instances can
51 be inserted in the canvas using
53 \begin{methoddesc
}{insert
}{item, attrs=
[]}
54 Inserts an instance of
\class{base.canvasitem
} into the canvas. If
55 \var{attrs
} are present,
\var{item
} is inserted into a new
56 \class{canvas
}instance with
\var{attrs
} as arguments passed to its
57 constructor is created. Then this
\class{canvas
} instance is
58 inserted itself into the canvas.
61 Text output on the canvas is possible using
63 \begin{methoddesc
}{text
}{x, y, text, attrs=
[]}
64 Inserts
\var{text
} at position (
\var{x
},
\var{y
}) into the
65 canvas applying
\var{attrs
}. This is a shortcut for
66 \texttt{insert(texrunner.text(x, y, text, attrs))
}).
69 The
\class{canvas
} class provides access to the total geometrical size
72 \begin{methoddesc
}{bbox
}{}
73 Returns the bounding box enclosing all elements of the canvas.
76 A canvas also allows one to set its TeX runner:
78 \begin{methoddesc
}{settexrunner
}{texrunner
}
79 Sets a new
\var{texrunner
} for the canvas.
82 The contents of the canvas can be written using the following two
83 convenience methods, which wrap the canvas into a single page
86 \begin{methoddesc
}{writeEPSfile
}{file, *args, **kwargs
}
87 Writes the canvas to
\var{file
} using the EPS format.
\var{file
}
88 either has to provide a write method or it is used as a string
89 containing the filename (the extension
\texttt{.eps
} is appended
90 automatically, if it is not present). This method constructs a
91 single page
document, passing
\var{args
} and
\var{kwargs
} to the
92 \class{document.page
} constructor and the calls the
93 \method{writeEPSfile
} method of this
\class{document.
document}
94 instance passing the
\var{file
}.
97 \begin{methoddesc
}{writePSfile
}{file, *args, **kwargs
}
98 Similar to
\method{writeEPSfile
} but using the PS format.
101 \begin{methoddesc
}{writePDFfile
}{file, *args, **kwargs
}
102 Similar to
\method{writeEPSfile
} but using the PDF format.
105 \begin{methoddesc
}{writetofile
}{filename, *args, **kwargs
}
106 Determine the file type (EPS, PS, or PDF) from the file extension
107 of
\var{filename
} and call the corresponding write method with
108 the given arguments
\var{arg
} and
\var{kwargs
}.
111 \begin{methoddesc
}{pipeGS
}{filename="-", device=None, resolution=
100,
112 gscommand="gs", gsoptions="",
113 textalphabits=
4, graphicsalphabits=
4,
114 ciecolor=False, input="eps", **kwargs
}
115 This method pipes the content of a canvas to the ghostscript
116 interpreter directly to generate other output formats. At least
117 \var{filename
} or
\var{device
} must be set.
\var{filename
} specifies
118 the name of the output file. No file extension will be added to that
119 name in any case. When no
\var{filename
} is specified, the output is
120 written to stdout.
\var{device
} specifies a ghostscript output
121 device by a string. Depending on your ghostscript configuration
122 \code{"png16"
},
\code{"png16m"
},
\code{"png256"
},
\code{"png48"
},
123 \code{"pngalpha"
},
\code{"pnggray"
},
\code{"pngmono"
},
124 \code{"jpeg"
}, and
\code{"jpeggray"
} might be available among
125 others. See the output of
\texttt{gs --help
} and the ghostscript
126 documentation for more information. When
\var{filename
} is specified
127 but the device is not set,
\code{"png16m"
} is used when the filename
128 ends in
\texttt{.png
} and
\code{"jpeg"
} is used when the filename
129 ends in
\texttt{.jpg
}.
131 \var{resolution
} specifies the resolution in dpi (dots per inch).
132 \var{gscmd
} is the command to be used to invoke ghostscript.
133 \var{gsoptions
} are an option string passed to the ghostscript
134 interpreter.
\var{textalphabits
} are
\var{graphicsalphabits
} are
135 conventient parameters to set the
\texttt{TextAlphaBits
} and
136 \texttt{GraphicsAlphaBits
} options of ghostscript. You can skip
137 the addition of those option by set their value to
\code{None
}.
138 \var{ciecolor
} adds the
\texttt{-dUseCIEColor
} flag to improve
139 the CMYK to RGB
color conversion.
\var{input
} can be either
140 \code{"eps"
} or
\code{"pdf"
} to select the input type to be passed
141 to ghostscript (note slightly different features available in the
142 different input types).
144 \var{kwargs
} are passed to the
\method{writeEPSfile
} method (not
145 counting the
\var{file
} parameter), which is used to generate the
146 input for ghostscript. By that you gain access to the
147 \class{document.page
} constructor arguments.
150 For more information about the possible arguments of the
151 \class{document.page
} constructor, we refer to Sect.~
\ref{document}.
155 %%% TeX-master: "manual.tex"