manual/canvas.tex

   1 \section{Module \module{canvas}}
   2 \label{canvas}
   3
   4 \sectionauthor{J\"org Lehmann}{joergl@users.sourceforge.net}
   5
   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.
  11
  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..
  15
  16 \declaremodule{}{canvas}
  17
  18 \subsection{Class \class{canvas}}
  19
  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.
  23
  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}
  32
  33
  34 Paths can be drawn on the canvas using one of the following methods:
  35
  36 \begin{methoddesc}{draw}{path, attrs}
  37   Draws \var{path} on the canvas applying the given \var{attrs}.
  38 \end{methoddesc}
  39
  40 \begin{methoddesc}{fill}{path, attrs=[]}
  41   Fills the given \var{path} on the canvas applying the given
  42   \var{attrs}.
  43 \end{methoddesc}
  44
  45 \begin{methoddesc}{stroke}{path, attrs=[]}
  46   Strokes the given \var{path} on the canvas applying the given
  47   \var{attrs}.
  48 \end{methoddesc}
  49
  50 Arbitrary allowed elements like other \class{canvas} instances can
  51 be inserted in the canvas using
  52
  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. Returns \var{item}.
  59 \end{methoddesc}
  60
  61 Text output on the canvas is possible using
  62
  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}
  68
  69 The \class{canvas} class provides access to the total geometrical size
  70 of its element:
  71
  72 \begin{methoddesc}{bbox}{}
  73   Returns the bounding box enclosing all elements of the canvas.
  74 \end{methoddesc}
  75
  76 A canvas also allows one to set global options:
  77
  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}
  83
  84 \begin{methoddesc}{settexrunner}{texrunner}
  85   Sets a new \var{texrunner} for the canvas.
  86 \end{methoddesc}
  87
  88 The contents of the canvas can be written using:
  89
  90 \begin{methoddesc}{writeEPSfile}{filename, paperformat=None,
  91     rotated=0, fittosize=0, margin=1*unit.t_cm, bbox=None,
  92     bboxenlarge=1*unit.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}
 108
 109 \subsection{Patterns}
 110
 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:
 117
 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
 145
 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.
 151
 152
 153
 154 %%% Local Variables:
 155 %%% mode: latex
 156 %%% TeX-master: "manual.tex"
 157 %%% End: