doc/parts/extensions/Shapes-Graphics-shapesarrow.sxml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <?xml-stylesheet type="text/xsl" href="formats/html.xsl"?>
   3
   4 <!-- This file is part of Shapes.                                           -->
   5 <!--                                                                        -->
   6 <!-- Shapes is free software: you can redistribute it and/or modify         -->
   7 <!-- it under the terms of the GNU General Public License as published by   -->
   8 <!-- the Free Software Foundation, either version 3 of the License, or      -->
   9 <!-- any later version.                                                     -->
  10 <!--                                                                        -->
  11 <!-- Shapes is distributed in the hope that it will be useful,              -->
  12 <!-- but WITHOUT ANY WARRANTY; without even the implied warranty of         -->
  13 <!-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          -->
  14 <!-- GNU General Public License for more details.                           -->
  15 <!--                                                                        -->
  16 <!-- You should have received a copy of the GNU General Public License      -->
  17 <!-- along with Shapes.  If not, see <http://www.gnu.org/licenses/>.        -->
  18 <!--                                                                        -->
  19 <!-- Copyright 2009, 2014, 2015 Henrik Tidefelt                             -->
  20
  21
  22 <book>
  23   <namespace>..Shapes..Graphics</namespace>
  24   <extension>shapesarrow</extension>
  25   <description>
  26     <p>A <str-Shapes /> alternative to the <str-MetaPost /> arrowhead.</p>
  27   </description>
  28   <prelude />
  29   <needs></needs>
  30
  31   <title><self /></title>
  32   <meta-selflink><self-href /></meta-selflink>
  33   <up-link><parent-namespace /></up-link>
  34   <base href=<!--#expand-next-string-->"$(BASE)" />
  35   <examples-home href=<!--#expand-next-string-->"$(EXAMPLES)" />
  36   <shapes-version number=<!--#expand-next-string-->"$(SHAPES_VERSION)" />
  37   <external>
  38     <!--#include virtual="^/toc.xml" -->
  39   </external>
  40
  41   <top>
  42     <alphabetical-index/>
  43     <p>Please refer to <extension path="..Shapes..Graphics/arrowheads" /> for an introduction to arrowheads.</p>
  44   </top>
  45
  46   <body>
  47
  48     <system-binding name="ShapesArrow">
  49       <function>
  50         <case>
  51           <arguments>
  52             <arg identifier="p">
  53               <type><named-type name="Path" /></type>
  54             </arg>
  55             <arg identifier="width">
  56               <type>
  57                 <union-type>
  58                   <named-type name="Length" />
  59                   <named-type name="Float" />
  60                 </union-type>
  61                 </type>
  62               <default><eq>3</eq></default>
  63             </arg>
  64             <arg identifier="frontAngle">
  65               <type><named-type name="Float" /></type>
  66               <default><eq>40°</eq></default>
  67             </arg>
  68             <arg identifier="rearAngle">
  69               <type><named-type name="Float" /></type>
  70               <default><eq>150°</eq></default>
  71             </arg>
  72             <arg identifier="fillAsStroking">
  73               <type><named-type name="Boolean" /></type>
  74               <default><eq><const-true /></eq></default>
  75             </arg>
  76           </arguments>
  77           <result>
  78             <type>
  79               <structure-type>
  80                 <field name="picture"><type><named-type name="Drawable" /></type></field>
  81                 <field name="cut"><type><named-type name="Length" /></type></field>
  82               </structure-type>
  83             </type>
  84           </result>
  85           <dynamic-references>Whole graphics state</dynamic-references>
  86           <description>
  87             <p>This arrowhead does not inherit the parameterization from <value name="MetaPostArrow" />, although <arg name="frontAngle" /> corresponds to <inline>ahAngle</inline>.  Instead of <inline>ahLength</inline>, there is <arg name="width"/>, and there is the additional parameter <arg name="rearAngle" />.</p>
  88             <p>If <arg name="width" /> is a <named-type name="Float" />, it is implicitly multiplied by <dynamic namespace="..Shapes..Traits" name="width" />, but truncated at <physical><scalar>3</scalar><unit>bp</unit></physical> from below.  Widths smaller than <physical><scalar>3</scalar><unit>bp</unit></physical> can still be obtained by specifying the width directly as a <named-type name="Length" />.  By defining an arrowhead as a dynamic variable, it is even possible to make the width your own function of <dynamic namespace="..Shapes..Traits" name="width" />, like so:
  89 <pre>
  90 <![CDATA[dynamic @myHead identity dynamic [ShapesArrow width:@width*(1.5+4.5bp/(1bp+@width)) ...]]]>
  91 </pre>
  92 </p>
  93             <p>An example is included to illustrate how the shape of the arrowhead is determined.</p>
  94 <example-with-output title="Geometry of the ShapesArrow" internal-id="shapesarrow:illustration">
  95 <image pdf="features/shapesarrow-parameters_3.pdf" jpg="features/shapesarrow-parameters_70%.jpg" />
  96 <source file="features/shapesarrow-parameters.shape">
  97 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)features/shapesarrow-parameters.shape" -->]]>
  98 </source>
  99 <caption>
 100   <p>The shape of the <value name="ShapesArrow" /> arrowhead on a bent path is defined by generalization of how the arrowhead is defined for straight paths.  Looking at the arrowhead on the straight path, the shape of each triangular hook is determined by the length <eq>w</eq> and the angles <eq>α</eq> and <eq>β</eq>.  From the triangle, the distances <eq>r</eq>, <eq>h</eq>, and <eq>l</eq> are determined.  From the red point at the rear of the arrowhead, the tangent direction at that point, the angle <eq>β</eq>, and the distance <eq>r</eq>, the outer red points are determined.  The outer blue paths are then obtained by scaling and rotation of the central blue path of length <eq>h</eq>, so that they join the front red point with the corresponding outer red point.  The outer red points are connected with straight lines to the rear red point.</p>
 101   <p>Note that the construction of the arrowhead does not (unless the path is straight) result in an angle of exactly <arg name="frontAngle" /> at the front, and that the two tangents at the front may not be symmetric with respect to the tangent direction of the underlying path.  However, as the illustration shows, the deviations may hardly be noticeable.</p>
 102 </caption>
 103 </example-with-output>
 104           </description>
 105         </case>
 106       </function>
 107     </system-binding>
 108
 109   </body>
 110
 111 </book>