manual/pattern.rst

   1
   2 .. module:: pattern
   3
   4 *********************
   5 Module :mod:`pattern`
   6 *********************
   7
   8 .. sectionauthor:: Jörg Lehmann <joergl@users.sourceforge.net>
   9
  10
  11 This module contains the :class:`pattern.pattern` class, whichs allows the definition of
  12 PostScript Tiling patterns (cf. Sect. 4.9 of the PostScript Language Reference
  13 Manual) which may then be used to fill paths. In addition, a number of
  14 predefined hatch patterns are included.
  15
  16
  17 Class :class:`pattern`
  18 ======================
  19
  20 The classes :class:`pattern.pattern` and :class:`canvas.canvas` differ only in their
  21 constructor and in the absence of a :meth:`writeEPSfile` method in the former.
  22 The :class:`pattern` constructor accepts the following keyword arguments:
  23
  24 +-----------------+-----------------------------------------------+
  25 | keyword         | description                                   |
  26 +=================+===============================================+
  27 | ``painttype``   | ``1`` (default) for coloured patterns or      |
  28 |                 | ``2`` for uncoloured patterns                 |
  29 +-----------------+-----------------------------------------------+
  30 | ``tilingtype``  | ``1`` (default) for constant spacing tilings  |
  31 |                 | (patterns are spaced constantly by a multiple |
  32 |                 | of a device pixel), ``2`` for undistorted     |
  33 |                 | pattern cell, whereby the spacing may vary by |
  34 |                 | as much as one device pixel, or ``3`` for     |
  35 |                 | constant spacing and faster tiling which      |
  36 |                 | behaves as tiling type ``1`` but with         |
  37 |                 | additional distortion allowed to permit a     |
  38 |                 | more efficient implementation.                |
  39 +-----------------+-----------------------------------------------+
  40 | ``xstep``       | desired horizontal spacing between pattern    |
  41 |                 | cells, use ``None`` (default) for automatic   |
  42 |                 | calculation from pattern bounding box.        |
  43 +-----------------+-----------------------------------------------+
  44 | ``ystep``       | desired vertical spacing between pattern      |
  45 |                 | cells, use ``None`` (default) for automatic   |
  46 |                 | calculation from pattern bounding box.        |
  47 +-----------------+-----------------------------------------------+
  48 | ``bbox``        | bounding box of pattern. Use ``None`` for an  |
  49 |                 | automatic determination of the bounding box   |
  50 |                 | (including an enlargement by ``bboxenlarge``  |
  51 |                 | pts on each side.)                            |
  52 +-----------------+-----------------------------------------------+
  53 | ``trafo``       | additional transformation applied to pattern  |
  54 |                 | or ``None`` (default). This may be used to    |
  55 |                 | rotate the pattern or to shift its phase (by  |
  56 |                 | a translation).                               |
  57 +-----------------+-----------------------------------------------+
  58 | ``bboxenlarge`` | enlargement when using the automatic bounding |
  59 |                 | box determination; default is 5 pts.          |
  60 +-----------------+-----------------------------------------------+
  61
  62 After you have created a pattern instance, you define the pattern shape by
  63 drawing in it like in an ordinary canvas. To use the pattern, you simply pass
  64 the pattern instance to a :meth:`stroke`, :meth:`fill`, :meth:`draw` or
  65 :meth:`set` method of the canvas, just like you would do with a colour, etc.
  66