8 .. sectionauthor:: Jörg Lehmann <joergl@users.sourceforge.net>
12 contains the class ``canvas.clip`` which allows clipping of the output.
18 This is the basic class of the canvas module. Instances of this class collect
19 visual elements like paths, other canvases, TeX or LaTeX elements. A canvas may
20 also be embedded in another one using its ``insert`` method. This may be useful
21 when you want to apply a transformation on a whole set of operations.
23 .. class:: canvas(attrs=[], texrunner=None)
25 Construct a new canvas, applying the given *attrs*, which can be instances of
26 :class:`trafo.trafo`, :class:`canvas.clip`, :class:`style.strokestyle` or
27 :class:`style.fillstyle`. The *texrunner* argument can be used to specify the
28 texrunner instance used for the :meth:`text` method of the canvas. If not
29 specified, it defaults to *text.defaulttexrunner*.
31 Paths can be drawn on the canvas using one of the following methods:
34 .. method:: canvas.draw(path, attrs)
36 Draws *path* on the canvas applying the given *attrs*. Depending on the
37 *attrs* the path will be filled, stroked, ornamented, or a combination
38 thereof. For the common first two cases the following two convenience
39 functions are provided.
42 .. method:: canvas.fill(path, attrs=[])
44 Fills the given *path* on the canvas applying the given *attrs*.
47 .. method:: canvas.stroke(path, attrs=[])
49 Strokes the given *path* on the canvas applying the given *attrs*.
51 Arbitrary allowed elements like other :class:`canvas` instances can be inserted
55 .. method:: canvas.insert(item, attrs=[])
57 Inserts an instance of :class:`base.canvasitem` into the canvas. If *attrs* are
58 present, *item* is inserted into a new :class:`canvas` instance with *attrs*
59 as arguments passed to its constructor. Then this :class:`canvas` instance
60 is inserted itself into the canvas.
62 Text output on the canvas is possible using
65 .. method:: canvas.text(x, y, text, attrs=[])
67 Inserts *text* at position (*x*, *y*) into the canvas applying *attrs*. This is
68 a shortcut for ``insert(texrunner.text(x, y, text, attrs))``.
70 The :class:`canvas` class provides access to the total geometrical size of its
74 .. method:: canvas.bbox()
76 Returns the bounding box enclosing all elements of the canvas (see Sect. :ref:`bbox_module`).
78 A canvas also allows to set its TeX runner:
81 .. method:: canvas.settexrunner(texrunner)
83 Sets a new *texrunner* for the canvas.
85 The contents of the canvas can be written to a file using the following
86 convenience methods, which wrap the canvas into a single page document.
89 .. method:: canvas.writeEPSfile(file, *args, **kwargs)
91 Writes the canvas to *file* using the EPS format. *file* either has to provide a
92 write method or it is used as a string containing the filename (the extension
93 ``.eps`` is appended automatically, if it is not present). This method
94 constructs a single page document, passing *args* and *kwargs* to the
95 :class:`document.page` constructor and calls the :meth:`writeEPSfile` method
96 of this :class:`document.document` instance passing the *file*.
99 .. method:: canvas.writePSfile(file, *args, **kwargs)
101 Similar to :meth:`writeEPSfile` but using the PS format.
104 .. method:: canvas.writePDFfile(file, *args, **kwargs)
106 Similar to :meth:`writeEPSfile` but using the PDF format.
109 .. method:: canvas.writetofile(filename, *args, **kwargs)
111 Determine the file type (EPS, PS, or PDF) from the file extension of *filename*
112 and call the corresponding write method with the given arguments *arg* and
116 .. method:: canvas.pipeGS(filename="-", device=None, resolution=100, gscommand="gs", gsoptions="", textalphabits=4, graphicsalphabits=4, ciecolor=False, input="eps", **kwargs)
118 This method pipes the content of a canvas to the ghostscript interpreter
119 to generate other output formats. At least *filename* or *device* must
120 be set. *filename* specifies the name of the output file. No file extension will
121 be added to that name. When no *filename* is specified, the output
122 is written to stdout. *device* specifies a ghostscript output device by a
123 string. Depending on the ghostscript configuration ``"png16"``, ``"png16m"``,
124 ``"png256"``, ``"png48"``, ``"pngalpha"``, ``"pnggray"``, ``"pngmono"``,
125 ``"jpeg"``, and ``"jpeggray"`` might be available among others. See the output
126 of ``gs --help`` and the ghostscript documentation for more information. When
127 *filename* is specified but the device is not set, ``"png16m"`` is used when the
128 filename ends in ``.png`` and ``"jpeg"`` is used when the filename ends in
131 *resolution* specifies the resolution in dpi (dots per inch). *gscmd* is the
132 command to be used to invoke ghostscript. *gsoptions* is an option string
133 passed to the ghostscript interpreter. *textalphabits* and *graphicsalphabits*
134 are convenient parameters to set the ``TextAlphaBits`` and
135 ``GraphicsAlphaBits`` options of ghostscript. The addition of these options
136 can be skipped by setting their values to ``None``. *ciecolor* adds the
137 ``-dUseCIEColor`` flag to improve the CMYK to RGB color conversion. *input*
138 can be either ``"eps"`` or ``"pdf"`` to select the input type to be passed
139 to ghostscript (note slightly different features available in the different
140 input types regarding e.g. :mod:`epsfile` inclusion and transparency).
142 *kwargs* are passed to the :meth:`writeEPSfile` method (not counting the *file*
143 parameter), which is used to generate the input for ghostscript. By that you
144 gain access to the :class:`document.page` constructor arguments.
146 For more information about the possible arguments of the :class:`document.page`
147 constructor, we refer to Sect. :mod:`document`.
151 ---------------------
153 In addition the canvas module contains the class ``canvas.clip`` which allows for
154 clipping of the output by passing a clipping instance to the attrs parameter of
155 the canvas constructor.