8
.. sectionauthor:: Jörg Lehmann <joergl@users.sourceforge.net>
11
One of the central modules for the PostScript access in PyX is named ``canvas``.
12
Besides providing the class ``canvas``, which presents a collection of visual
13
elements like paths, other canvases, TeX or LaTeX elements, it contains the
14
class ``canvas.clip`` which allows clipping of the output.
16
A canvas may also be embedded in another one using its ``insert`` method. This
17
may be useful when you want to apply a transformation on a whole set of
24
This is the basic class of the canvas module, which serves to collect various
25
graphical and text elements you want to write eventually to an (E)PS file.
28
.. class:: canvas(attrs=[], texrunner=None)
30
Construct a new canvas, applying the given *attrs*, which can be instances of
31
:class:`trafo.trafo`, :class:`canvas.clip`, :class:`style.strokestyle` or
32
:class:`style.fillstyle`. The *texrunner* argument can be used to specify the
33
texrunner instance used for the :meth:`text` method of the canvas. If not
34
specified, it defaults to *text.defaulttexrunner*.
36
Paths can be drawn on the canvas using one of the following methods:
39
.. method:: canvas.draw(path, attrs)
41
Draws *path* on the canvas applying the given *attrs*.
44
.. method:: canvas.fill(path, attrs=[])
46
Fills the given *path* on the canvas applying the given *attrs*.
49
.. method:: canvas.stroke(path, attrs=[])
51
Strokes the given *path* on the canvas applying the given *attrs*.
53
Arbitrary allowed elements like other :class:`canvas` instances can be inserted
57
.. method:: canvas.insert(item, attrs=[])
59
Inserts an instance of :class:`base.canvasitem` into the canvas. If *attrs* are
60
present, *item* is inserted into a new :class:`canvas`\ instance with *attrs* as
61
arguments passed to its constructor is created. Then this :class:`canvas`
62
instance is inserted itself into the canvas.
64
Text output on the canvas is possible using
67
.. method:: canvas.text(x, y, text, attrs=[])
69
Inserts *text* at position (*x*, *y*) into the canvas applying *attrs*. This is
70
a shortcut for ``insert(texrunner.text(x, y, text, attrs))``).
72
The :class:`canvas` class provides access to the total geometrical size of its
76
.. method:: canvas.bbox()
78
Returns the bounding box enclosing all elements of the canvas.
80
A canvas also allows one to set its TeX runner:
83
.. method:: canvas.settexrunner(texrunner)
85
Sets a new *texrunner* for the canvas.
87
The contents of the canvas can be written using the following two convenience
88
methods, which wrap the canvas into a single page document.
91
.. method:: canvas.writeEPSfile(file, *args, **kwargs)
93
Writes the canvas to *file* using the EPS format. *file* either has to provide a
94
write method or it is used as a string containing the filename (the extension
95
``.eps`` is appended automatically, if it is not present). This method
96
constructs a single page document, passing *args* and *kwargs* to the
97
:class:`document.page` constructor and the calls the :meth:`writeEPSfile` method
98
of this :class:`document.document` instance passing the *file*.
101
.. method:: canvas.writePSfile(file, *args, **kwargs)
103
Similar to :meth:`writeEPSfile` but using the PS format.
106
.. method:: canvas.writePDFfile(file, *args, **kwargs)
108
Similar to :meth:`writeEPSfile` but using the PDF format.
111
.. method:: canvas.writetofile(filename, *args, **kwargs)
113
Determine the file type (EPS, PS, or PDF) from the file extension of *filename*
114
and call the corresponding write method with the given arguments *arg* and
118
.. method:: canvas.pipeGS(filename="-", device=None, resolution=100, gscommand="gs", gsoptions="", textalphabits=4, graphicsalphabits=4, ciecolor=False, input="eps", **kwargs)
120
This method pipes the content of a canvas to the ghostscript interpreter
121
directly to generate other output formats. At least *filename* or *device* must
122
be set. *filename* specifies the name of the output file. No file extension will
123
be added to that name in any case. When no *filename* is specified, the output
124
is written to stdout. *device* specifies a ghostscript output device by a
125
string. Depending on your ghostscript configuration ``"png16"``, ``"png16m"``,
126
``"png256"``, ``"png48"``, ``"pngalpha"``, ``"pnggray"``, ``"pngmono"``,
127
``"jpeg"``, and ``"jpeggray"`` might be available among others. See the output
128
of ``gs --help`` and the ghostscript documentation for more information. When
129
*filename* is specified but the device is not set, ``"png16m"`` is used when the
130
filename ends in ``.png`` and ``"jpeg"`` is used when the filename ends in
133
*resolution* specifies the resolution in dpi (dots per inch). *gscmd* is the
134
command to be used to invoke ghostscript. *gsoptions* are an option string
135
passed to the ghostscript interpreter. *textalphabits* are *graphicsalphabits*
136
are conventient parameters to set the ``TextAlphaBits`` and
137
``GraphicsAlphaBits`` options of ghostscript. You can skip the addition of those
138
option by set their value to ``None``. *ciecolor* adds the ``-dUseCIEColor``
139
flag to improve the CMYK to RGB color conversion. *input* can be either
140
``"eps"`` or ``"pdf"`` to select the input type to be passed to ghostscript
141
(note slightly different features available in the different input types).
143
*kwargs* are passed to the :meth:`writeEPSfile` method (not counting the *file*
144
parameter), which is used to generate the input for ghostscript. By that you
145
gain access to the :class:`document.page` constructor arguments.
147
For more information about the possible arguments of the :class:`document.page`
148
constructor, we refer to Sect. :mod:`document`.
added
removed
manual/canvas.rst
