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.
  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 its TeX runner:
  77
  78 \begin{methoddesc}{settexrunner}{texrunner}
  79   Sets a new \var{texrunner} for the canvas.
  80 \end{methoddesc}
  81
  82 The contents of the canvas can be written using the following two
  83 convenience methods, which wrap the canvas into a single page
  84 document.
  85
  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}.
  95 \end{methoddesc}
  96
  97 \begin{methoddesc}{writePSfile}{file, *args, **kwargs}
  98   Similar to \method{writeEPSfile} but using the PS format.
  99 \end{methoddesc}
 100
 101 \begin{methoddesc}{writePDFfile}{file, *args, **kwargs}
 102   Similar to \method{writeEPSfile} but using the PDF format.
 103 \end{methoddesc}
 104
 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}.
 109 \end{methoddesc}
 110
 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}.
 130
 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).
 143
 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.
 148 \end{methoddesc}
 149
 150 For more information about the possible arguments of the
 151 \class{document.page} constructor, we refer to Sect.~\ref{document}.
 152
 153 %%% Local Variables:
 154 %%% mode: latex
 155 %%% TeX-master: "manual.tex"
 156 %%% End: