manual/pattern.rst

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