skip the third part of a pfb in pdf when possible; improved pfb EOF check in pdf
[PyX/mjg.git] / manual / canvas.tex
blobd0dc7940c4ed84d274abe8aef1b2f4e6f7131bea
1 \section{Module \module{canvas}}
2 \label{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
22 (E)PS file.
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{stlye.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}.
31 \end{classdesc}
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}.
38 \end{methoddesc}
40 \begin{methoddesc}{fill}{path, attrs=[]}
41 Fills the given \var{path} on the canvas applying the given
42 \var{attrs}.
43 \end{methoddesc}
45 \begin{methoddesc}{stroke}{path, attrs=[]}
46 Strokes the given \var{path} on the canvas applying the given
47 \var{attrs}.
48 \end{methoddesc}
50 Arbitrary allowed elements like other \class{canvas} instances can
51 be inserted in the canvas using
53 \begin{methoddesc}{insert}{PSOp, attrs=[]}
54 Inserts an instance of \class{base.PSOp} into the canvas. If
55 \var{attrs} are present, PSOp 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. Returns \var{PSOp}.
59 \end{methoddesc}
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))}).
67 \end{methoddesc}
69 The \class{canvas} class provides access to the total geometrical size
70 of its element:
72 \begin{methoddesc}{bbox}{}
73 Returns the bounding box enclosing all elements of the canvas.
74 \end{methoddesc}
76 A canvas also allows one to set global options:
78 \begin{methoddesc}{set}{styles}
79 Sets the given \var{styles} (instances of \class{style.fillstyle} or
80 \class{style.strokestyle} or subclasses thereof). for the rest of
81 the canvas.
82 \end{methoddesc}
84 \begin{methoddesc}{settexrunner}{texrunner}
85 Sets a new \var{texrunner} for the canvas.
86 \end{methoddesc}
88 The contents of the canvas can be written using:
90 \begin{methoddesc}{writeEPSfile}{filename, paperformat=None,
91 rotated=0, fittosize=0, margin="1 t cm", bbox=None, bboxenlarge="1
92 t pt"}
93 Writes the canvas to \var{filename} (the extension \texttt{.eps} is
94 appended automatically). Optionally, a \var{paperformat} can be
95 specified, in which case the output will be centered with respect to
96 the corresponding size using the given \var{margin}. See
97 \var{canvas.\_paperformats} for a list of known paper formats . Use
98 \var{rotated}, if you want to center on a $90^\circ$ rotated version
99 of the respective paper format. If \var{fittosize} is set, the
100 output is additionally scaled to the maximal possible size.
101 Normally, the bounding box of the canvas is calculated automatically
102 from the bounding box of its elements. Alternatively, you may
103 specify the \var{bbox} manually. In any case, the bounding box
104 becomes enlarged on all side by \var{bboxenlarge}. This may be used
105 to compensate for the inability of \PyX{} to take the linewidths
106 into account for the calculation of the bounding box.
107 \end{methoddesc}
109 \subsection{Patterns}
111 The \class{pattern} class allows the definition of PostScript Tiling
112 patterns (cf.\ Sect.~4.9 of the PostScript Language Reference Manual)
113 which may then be used to fill paths. The classes \class{pattern} and
114 \class{canvas} differ only in their constructor and in the absence of
115 a \method{writeEPSfile()} method in the former. The \class{pattern}
116 constructor accepts the following keyword arguments:
118 \medskip
119 \begin{tabularx}{\linewidth}{l>{\raggedright\arraybackslash}X}
120 keyword&description\\
121 \hline
122 \texttt{painttype}&\texttt{1} (default) for coloured patterns or
123 \texttt{2} for uncoloured patterns\\
124 \texttt{tilingtype}&\texttt{1} (default) for constant spacing tilings
125 (patterns are spaced constantly by a multiple of a device pixel),
126 \texttt{2} for undistored pattern cell, whereby the spacing may vary
127 by as much as one device pixel, or \texttt{3} for constant spacing and
128 faster tiling which behaves as tiling type \texttt{1} but with
129 additional distortion allowed to permit a more efficient
130 implementation.\\
131 \texttt{xstep}&desired horizontal spacing between pattern cells, use
132 \texttt{None} (default) for automatic calculation from pattern
133 bounding box.\\
134 \texttt{ystep}&desired vertical spacing between pattern cells, use
135 \texttt{None} (default) for automatic calculation from pattern
136 bounding box.\\
137 \texttt{bbox}&bounding box of pattern. Use \texttt{None} for an
138 automatical determination of the bounding box (including an
139 enlargement by $5$ pts on each side.)\\
140 \texttt{trafo}&additional transformation applied to pattern or
141 \texttt{None} (default). This may be used to rotate the pattern or to
142 shift its phase (by a translation).
143 \end{tabularx}
144 \medskip
146 After you have created a pattern instance, you define the pattern
147 shape by drawing in it like in an ordinary canvas. To use the pattern,
148 you simply pass the pattern instance to a \method{stroke()},
149 \method{fill()}, \method{draw()} or \method{set()} method of the
150 canvas, just like you would do with a colour, etc.
154 %%% Local Variables:
155 %%% mode: latex
156 %%% TeX-master: "manual.tex"
157 %%% End: