manual/canvas.rst

   1
   2 .. module:: canvas
   3
   4 ====================
   5 Module :mod:`canvas`
   6 ====================
   7
   8 .. sectionauthor:: Jörg Lehmann <joergl@users.sourceforge.net>
   9
  10
  11 In addition it
  12 contains the class ``canvas.clip`` which allows clipping of the output.
  13
  14
  15 Class :class:`canvas`
  16 ---------------------
  17
  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.
  22
  23 .. class:: canvas(attrs=[], texrunner=None)
  24
  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*.
  30
  31 Paths can be drawn on the canvas using one of the following methods:
  32
  33
  34 .. method:: canvas.draw(path, attrs)
  35
  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.
  40
  41
  42 .. method:: canvas.fill(path, attrs=[])
  43
  44    Fills the given *path* on the canvas applying the given *attrs*.
  45
  46
  47 .. method:: canvas.stroke(path, attrs=[])
  48
  49    Strokes the given *path* on the canvas applying the given *attrs*.
  50
  51 Arbitrary allowed elements like other :class:`canvas` instances can be inserted
  52 in the canvas using
  53
  54
  55 .. method:: canvas.insert(item, attrs=[])
  56
  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.
  61
  62 Text output on the canvas is possible using
  63
  64
  65 .. method:: canvas.text(x, y, text, attrs=[])
  66
  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))``.
  69
  70 The :class:`canvas` class provides access to the total geometrical size of its
  71 element:
  72
  73
  74 .. method:: canvas.bbox()
  75
  76    Returns the bounding box enclosing all elements of the canvas (see Sect. :ref:`bbox_module`).
  77
  78 A canvas also allows to set its TeX runner:
  79
  80
  81 .. method:: canvas.settexrunner(texrunner)
  82
  83    Sets a new *texrunner* for the canvas.
  84
  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.
  87
  88
  89 .. method:: canvas.writeEPSfile(file, *args, **kwargs)
  90
  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*.
  97
  98
  99 .. method:: canvas.writePSfile(file, *args, **kwargs)
 100
 101    Similar to :meth:`writeEPSfile` but using the PS format.
 102
 103
 104 .. method:: canvas.writePDFfile(file, *args, **kwargs)
 105
 106    Similar to :meth:`writeEPSfile` but using the PDF format.
 107
 108
 109 .. method:: canvas.writetofile(filename, *args, **kwargs)
 110
 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
 113    *kwargs*.
 114
 115
 116 .. method:: canvas.pipeGS(filename="-", device=None, resolution=100, gscommand="gs", gsoptions="", textalphabits=4, graphicsalphabits=4, ciecolor=False, input="eps", **kwargs)
 117
 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
 129    ``.jpg``.
 130
 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).
 141
 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.
 145
 146 For more information about the possible arguments of the :class:`document.page`
 147 constructor, we refer to Sect. :mod:`document`.
 148
 149
 150 Class :class:`clip`
 151 ---------------------
 152
 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.