doc/parts/namespace/Shapes-Traits.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 2015 Henrik Tidefelt                                         -->
  20
  21
  22 <book>
  23   <namespace>..Shapes..Traits</namespace>
  24   <description>
  25     <p>Traits of graphical elements, such as color, reflection properties, and stroke width.</p>
  26   </description>
  27
  28   <title><self /></title>
  29   <up-link><parent-namespace /></up-link>
  30   <base href=<!--#expand-next-string-->"$(BASE)" />
  31   <examples-home href=<!--#expand-next-string-->"$(EXAMPLES)" />
  32   <shapes-version number=<!--#expand-next-string-->"$(SHAPES_VERSION)" />
  33   <external>
  34     <!--#include virtual="^/toc.xml" -->
  35   </external>
  36
  37   <top>
  38     <alphabetical-index/>
  39     <p>The <self /> namespace is organized with basic and general things directly at the top, while constants are grouped inside nested namespaces.  There is also the <namespace relative="Light" /> namespace that gathers the more advanced features of light and reflections.</p>
  40
  41     <p>The bindings in this namespace are closely related to the <em>graphics state parameters</em> in <str-PDF />.</p>
  42     <p>Many of these dynamic variables can be set to a <named-type name="Void" /> value, which means that painted objects do not specify the property for themselves, but inherit the property from the context where they appear.  This feature is a low-level <str-PDF /> trick, and the effects may be (or at least seem) unpredictable.</p>
  43   </top>
  44
  45   <body>
  46
  47   <section id="namespace/shapes/traits/strokes">
  48     <title>Strokes</title>
  49     <body>
  50
  51 <dynamic-variable name="width">
  52   <type><union-type><named-type name="Length" /> <named-type name="Void" /></union-type></type>
  53   <default><physical><scalar>1</scalar><unit>bp</unit></physical></default>
  54   <constraint><self /> ≥ <physical><scalar>0</scalar><unit>bp</unit></physical></constraint>
  55   <description>
  56     <p>Intended to be used as the width when paths are stroked.  A value of <physical><scalar>0</scalar><unit>bp</unit></physical> has a special meaning in <str-PDF />, being that the stroke shall be as thin as possible without dissappearing on the rendering device.  On high resolution printers, this may result in a line which is very hard to read, while such a line shall allways be clearly visible on a computer screen.</p>
  57     <p>Note that if the width is inherited from the context, it will not be possible to compute a correct bounding box of a stroked object.</p>
  58   </description>
  59 </dynamic-variable>
  60
  61 <dynamic-variable name="stroking">
  62   <type><union-type><named-type name="Color" /> <named-type name="Void" /></union-type></type>
  63   <default><value namespace="..Shapes..Traits..BW" name="BLACK" /></default>
  64   <description>
  65     <p>Color used when paths are stroked.</p>
  66   </description>
  67   <see-also>
  68     <dynamic name="strokingalpha" />
  69   </see-also>
  70 </dynamic-variable>
  71
  72 <dynamic-variable name="cap">
  73   <type><union-type><named-type name="CapStyle" /> <named-type name="Void" /></union-type></type>
  74   <default><value namespace="..Shapes..Traits..Cap" name="BUTT" /></default>
  75   <description>
  76     <p>Line cap style.</p>
  77   </description>
  78 </dynamic-variable>
  79
  80 <dynamic-variable name="join">
  81   <type><union-type><named-type name="JoinStyle" /> <named-type name="Void" /></union-type></type>
  82   <default><value namespace="..Shapes..Traits..Join" name="MITER" /></default>
  83   <description>
  84     <p>Line join style.</p>
  85   </description>
  86   <see-also>
  87     <dynamic name="miterlimit" />
  88   </see-also>
  89 </dynamic-variable>
  90
  91 <dynamic-variable name="miterlimit">
  92   <type><union-type><named-type name="Float" /> <named-type name="Void" /></union-type></type>
  93   <default><eq>10</eq></default>
  94   <constraint><self /> ≥ <eq>1</eq></constraint>
  95   <description>
  96     <p>Miter limit value to use when <dynamic name="join" /> is <value namespace="..Shapes..Traits..Join" name="MITER" />.</p>
  97   </description>
  98 </dynamic-variable>
  99
 100 <dynamic-variable name="dash">
 101   <type><union-type><named-type name="Dash" /> <named-type name="Void" /></union-type></type>
 102   <default><inline>[dashpattern]</inline></default>
 103   <description>
 104     <p>Dash pattern to use for strokes.  (The default value gives solid lines.)</p>
 105   </description>
 106   <see-also>
 107     <value name="dashpattern" />
 108   </see-also>
 109 </dynamic-variable>
 110
 111 <system-binding name="dashpattern">
 112   <function>
 113     <case constructor-of="Dash">
 114       <arguments>
 115         <sink>
 116           <type><named-type name="Length" /></type>
 117         </sink>
 118       </arguments>
 119       <dynamic-references></dynamic-references>
 120       <description>
 121         <p>Creates a dash pattern from a sequence of lengths, to be used with <dynamic name="dash" />.</p>
 122         <p>If called with no arguments, the constructed pattern gives a solid line.  Otherwise, the lengths determine where along a stroked line the pen shall be switched between on and off, with the pen initially being on.</p>
 123         <p>Note that a dash pattern can be scaled and shifted by means of operators, see <named-type name="Dash" />.</p>
 124       </description>
 125     </case>
 126   </function>
 127 </system-binding>
 128
 129 <dynamic-variable name="strokingalpha">
 130   <type><union-type><named-type name="Alpha" /> <named-type name="Void" /></union-type></type>
 131   <default><inline>[shape 1]</inline></default>
 132   <description>
 133     <p>Alpha settings for stroking operations.</p>
 134   </description>
 135   <see-also>
 136     <value name="alphashape" /> <value name="alphaopacity" /> <dynamic name="stroking" />
 137   </see-also>
 138 </dynamic-variable>
 139
 140     </body>
 141   </section><!-- End of namespace/shapes/traits/strokes -->
 142
 143
 144   <section id="namespace/shapes/traits/fills">
 145     <title>Fills</title>
 146     <body>
 147
 148 <dynamic-variable name="nonstroking">
 149   <type><union-type><named-type name="Color" /> <named-type name="Void" /></union-type></type>
 150   <default><value namespace="..Shapes..Traits..BW" name="BLACK" /></default>
 151   <description>
 152     <p>Color used when paths are filled (or, more generally, anything but stroked).  (The name is inherited from <str-PDF />.)</p>
 153   </description>
 154   <see-also>
 155     <dynamic name="nonstrokingalpha" />
 156   </see-also>
 157 </dynamic-variable>
 158
 159 <dynamic-variable name="nonstrokingalpha">
 160   <type><union-type><named-type name="Alpha" /> <named-type name="Void" /></union-type></type>
 161   <default><inline>[shape 1]</inline></default>
 162   <description>
 163     <p>Alpha settings for nonstroking operations.</p>
 164   </description>
 165   <see-also>
 166     <value name="alphashape" /> <value name="alphaopacity" /> <dynamic name="nonstroking" />
 167   </see-also>
 168 </dynamic-variable>
 169
 170     </body>
 171   </section><!-- End of namespace/shapes/traits/fills -->
 172
 173
 174   <section id="namespace/shapes/traits/color">
 175     <title>Color and transparency</title>
 176     <body>
 177
 178 <dynamic-variable name="blend">
 179   <type><union-type><named-type name="BlendMode" /> <named-type name="Void" /></union-type></type>
 180   <default><value namespace="..Shapes..Traits..Blend" name="NORMAL" /></default>
 181   <description>
 182     <p>Blend mode.</p>
 183   </description>
 184 </dynamic-variable>
 185
 186 <dynamic-variable name="blendspace">
 187   <type><named-type name="ColorSpace" /></type>
 188   <default><em>(inherited)</em></default>
 189   <description>
 190     <p>Color space for blending.</p>
 191   </description>
 192 </dynamic-variable>
 193
 194 <system-binding name="alphashape">
 195   <function>
 196     <case constructor-of="Alpha">
 197       <arguments>
 198         <arg>
 199           <type><named-type name="Float" /></type>
 200         </arg>
 201       </arguments>
 202       <dynamic-references></dynamic-references>
 203       <description>
 204         <p>Creates a <em>shape alpha</em> value (refer to the <str-PDF /> reference for details), to be used with <dynamic name="alpha" />.</p>
 205       </description>
 206       <see-also>
 207         <value name="alphaopacity" /> <value name="alphamask" /> <value name="clip" />
 208       </see-also>
 209     </case>
 210   </function>
 211 </system-binding>
 212
 213 <system-binding name="alphaopacity">
 214   <function>
 215     <case constructor-of="Alpha">
 216       <arguments>
 217         <arg>
 218           <type><named-type name="Float" /></type>
 219         </arg>
 220       </arguments>
 221       <dynamic-references></dynamic-references>
 222       <description>
 223         <p>Creates an <em>opacity alpha</em> value (refer to the <str-PDF /> reference for details), to be used with <dynamic name="alpha" />.</p>
 224       </description>
 225       <see-also>
 226         <value name="alphashape" /> <value name="alphamask" /> <value name="clip" />
 227       </see-also>
 228     </case>
 229   </function>
 230 </system-binding>
 231
 232 <system-binding name="newColorInterpolator">
 233   <hot>
 234     <constructor-of><named-statetype name="ColorInterpolator" /></constructor-of>
 235     <description></description>
 236   </hot>
 237 </system-binding>
 238
 239     </body>
 240   </section><!-- End of namespace/shapes/traits/color -->
 241
 242
 243   <section id="namespace/shapes/traits/misc">
 244     <title>Miscellaneous</title>
 245     <body>
 246
 247 <system-binding name="NO_MASK">
 248   <simple-value>
 249     <type><named-type name="SoftMask" /></type>
 250     <description>
 251       <p>Value for <dynamic name="alpha" /> and <dynamic name="luminosity" /> that indicates that the transparent imaging shall not be used.</p>
 252     </description>
 253   </simple-value>
 254 </system-binding>
 255
 256     </body>
 257   </section><!-- End of namespace/shapes/traits/misc -->
 258
 259
 260   </body>
 261
 262 </book>