manual/canvas.rst

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