examples/drawing/arrow.txt

   1 Adding an arrow when stroking a path
   2
   3 The example shows how to use an arrow decorator instance to add an arrow to a
   4 path when it is stroked. Instead of using a default arrow instance we're about
   5 to create a highly customized arrow head. ...
   6
   7 !! The arrow head is a so-called ornament. Beside attaching stroke and fill
   8 styles during the process of converting a path into a decorated path, any
   9 number of ornaments can be added to the decorated path. When adding ornaments,
  10 parts of the path can also be marked as not-to-be-stroked. While this is taken
  11 into account in a final stroke operation, different decorators do not see this
  12 information such that decorators always commute.
  13
  14 Apart from setting arrow specific features like the arrow size, a list of
  15 styles and decorators can be passed to the arrow. In this example the arrow is
  16 stroked in red with round corners where the pathitems join. In addition, the arrow
  17 is filled in green.
  18
  19 ! Note that style properties are inherited from the outer towards the inner
  20 decorators. In this example, the linewidth is also used when stroking the arrow
  21 head. We could for example also skip the color.rgb.green value in the
  22 `deco.filled` decorator and the arrow would be filled in blue.
  23
  24 !! To continue removing the deco.filled features, it is equivalent to write
  25 `deco.filled([])`, `deco.filled()` and `deco.filled`. This is due to the fact that
  26 `deco.filled` already is an instance, which can be ''modified by call''. An empty
  27 list does not really modify it. But you could even skip `deco.filled` completely
  28 and the arrow would still be filled with blue color. The reason is, that the
  29 arrow is implemented in a way that it always ''merges'' the `filled` decorator. This
  30 step in the evaluation of the attributes is transparent to other settings: if
  31 we would replace the `deco.filled([color.rgb.green])` by `color.rgb.green`, we
  32 would still get a filled green arrow. You could then remove the `color.rgb.red`
  33 in `deco.stroked` inside of the arrow instance and the line would become green as
  34 well. Note that the order of the attributes is not important for this style
  35 delegation feature.
  36
  37 !! As we're learned that the arrow decorators always fill the arrow head by
  38 default, the question is, whether and how such a feature can be removed. This
  39 is done by ''clear'' instances available as a `clear` class attribute. Hence in case
  40 of `deco.filled` it is available as `deco.filled.clear`. When you add this
  41 attribute to the earrow call, the arrowhead will not be filled anymore and you
  42 will notice that the blue line is not stroked inside the arrowhead.
  43
  44 !! You might also have noticed, that the dashed linestyle is not used when
  45 stroking the arrowhead. This is similar to the default `filled` feature of the
  46 arrowhead: The arrowhead merges a `style.linestyle.normal` to ensure a solid
  47 line. Instead of manually setting `style.linestyle.dashed` in the arrowhead you
  48 could use `style.linestyle.clear` to restore the linestyle setting of the path.