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