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{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}.
  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 the following two
  89 convenience methods, which wrap the canvas into a single page
  90 document.
  91
  92 \begin{methoddesc}{writeEPSfile}{filename, **kwargs}
  93   Writes the canvas to \var{filename} (the extension \texttt{.eps} is
  94   appended automatically, if it is not present). This method
  95   constructs a single page document, passing \var{kwargs} to the
  96   \class{document.page} constructor and the calls the
  97   \method{writeEPSfile} method of this \class{document.document}
  98   instance passing the \var{filename}
  99
 100 \end{methoddesc}
 101
 102 \begin{methoddesc}{writePDFfile}{filename, **kwargs}
 103   Writes the canvas to \var{filename} (the extension \texttt{.pdf} is
 104   appended automatically, if it is not present). This method
 105   constructs a single page document, passing \var{kwargs} to the
 106   \class{document.page} constructor and the calls the
 107   \method{writePDFfile} method of this \class{document.document}
 108   instance passing the \var{filename}
 109 \end{methoddesc}
 110
 111 For more information about the possible arguments of the
 112 \class{document.page} constructor, we refer to Sect.~\ref{document}.
 113
 114 %%% Local Variables:
 115 %%% mode: latex
 116 %%% TeX-master: "manual.tex"
 117 %%% End: