manual/connector.rst

   1
   2 .. module:: connector
   3
   4 ***********************
   5 Module :mod:`connector`
   6 ***********************
   7
   8 This module provides classes for connecting two :class:`box`\ -instances with
   9 lines, arcs or curves. All constructors of the following connector-classes take
  10 two :class:`box`\ -instances as the two first arguments. They return a
  11 connecting path from the first to the second box. The overall geometry of the
  12 path is such that is starts/ends at the boxes' centers. It is then cut by the
  13 boxes' outlines. The resulting :class:`connector` will additionally be shortened
  14 by lengths given in the *boxdists* (a list of two lengths,
  15 default ``[0,0]``).
  16
  17 Angle keywords can be either absolute or relative. The absolute angles refer to
  18 the angle between x-axis and the running tangent of the connector, while the
  19 relative angles are between the direct connecting line of the box-centers and
  20 the running tangent (see figure. :ref:`fig_connector`).
  21
  22 The bulge-keywords parameterize the deviation of the connector from the
  23 connecting line. It has different meanings for different connectors (see figure.
  24 :ref:`fig_connector`).
  25
  26
  27 Class :class:`line`
  28 ===================
  29
  30 The constructor of the :class:`line` class accepts only boxes and the
  31 *boxdists*.
  32
  33
  34 Class :class:`arc`
  35 ==================
  36
  37 The constructor takes either the *relangle* or a combination
  38 of *relbulge* and *absbulge*. The "bulge" is meant to be a
  39 hint for the greatest distance between the connecting arc and the straight
  40 connection between the box-centers. (Default: ``relangle=45``,
  41 ``relbulge=None``, ``absbulge=None``)
  42
  43 Note that the bulge-keywords override the angle-keyword.
  44
  45 If both *relbulge* and *absbulge* are given, they will be
  46 added.
  47
  48
  49 Class :class:`curve`
  50 ====================
  51
  52 The constructor takes both angle- and bulge-keywords. Here, the bulges are used
  53 as distances between the control points of the cubic Beziér-curve. For the signs
  54 of the angle- and bulge-keywords refer to figure :ref:`fig_connector`.
  55
  56 *absangle1* or *relangle1* ---  *absangle2* or
  57 *relangle2*, where the absolute angle overrides the relative if both
  58 are given. (Default: ``relangle1=45``, ``relangle2=45``, ``absangle1=None``,
  59 ``absangle2=None``)
  60
  61 *absbulge* and *relbulge*, where they will be added if both
  62 are given. ---  (Default: ``absbulge=None``, ``relbulge=0.39``; these default
  63 values produce output similar to the defaults of :class:`arc`.)
  64
  65 .. _fig_connector:
  66 .. figure:: connector.*
  67    :align:  center
  68
  69    The angle-parameters of the connector.arc (left panel) and the connector.curve (right panel) classes.
  70
  71
  72 Class :class:`twolines`
  73 =======================
  74
  75 This class returns two connected straight lines. There is a vast variety of
  76 combinations for angle- and length-keywords. The user has to make sure to
  77 provide a non-ambiguous set of keywords:
  78
  79 *absangle1* or *relangle1* for the first angle, ---
  80 *relangleM* for the middle angle and ---  *absangle2* or
  81 *relangle2* for the ending angle. Again, the absolute angle overrides
  82 the relative if both are given. (Default: all five angles are ``None``)
  83
  84 *length1* and *length2* for the lengths of the connecting
  85 lines. (Default: ``None``)
  86