doc/parts/extensions/Shapes-Layout-shiftoff.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 2008, 2014 Henrik Tidefelt                                   -->
  20
  21
  22 <book>
  23         <title>shiftoff</title>
  24         <description>
  25                 <p>Very basic layout tools that mimic <str-MetaPost /> suffix placement syntax.</p>
  26         </description>
  27         <meta-selflink><self-href /></meta-selflink>
  28         <base href=<!--#expand-next-string-->"$(BASE)" />
  29         <examples-home href=<!--#expand-next-string-->"$(EXAMPLES)" />
  30         <shapes-version number=<!--#expand-next-string-->"$(SHAPES_VERSION)" />
  31         <up-link><parent-namespace /></up-link>
  32         <needs>
  33                 <a extension="basic-layout" />
  34         </needs>
  35         <public-namespace>Shapes..Layout</public-namespace>
  36   <external>
  37     <!--#include virtual="^/toc.xml" -->
  38   </external>
  39         <top>
  40                 <alphabetical-index/>
  41                 <p>The name of this extension includes the mysterious <em>wfo</em>.  It stands for <em>waiting for objects</em>, and refers to the wish to deal with elements of block diagrams using objects of user-defined types rather than just relying on <named-type name="Drawable" />.  However, by relying on <named-type name="Drawable" /> as the representation, this extension is much more generally useful than it would otherwise be.</p>
  42         </top>
  43
  44         <section id="extensions/shiftoff/constants">
  45                 <title>Constants</title>
  46                 <body>
  47                         <p>The constants defined here give numeric values to directions.  This is preferred over using symbols, since a miss-spelled symbol won't be detected by static analysis of the program.  Note, though, that the numeric values should never be used as such; they could equally well have been defined as unique symbols.</p>
  48
  49                         <system-binding identifier="to_lft">
  50                                 <simple-value>
  51                                         <type><named-type name="Float" /></type>
  52                                         <description>
  53                                                 <p>Constant for the direction <em>left</em>.</p>
  54                                         </description>
  55                                 </simple-value>
  56                         </system-binding>
  57                         <system-binding identifier="to_llft">
  58                                 <simple-value>
  59                                         <type><named-type name="Float" /></type>
  60                                         <description>
  61                                                 <p>Constant for the direction <em>down and left</em> (“lower left”).</p>
  62                                         </description>
  63                                 </simple-value>
  64                         </system-binding>
  65                         <system-binding identifier="to_bot">
  66                                 <simple-value>
  67                                         <type><named-type name="Float" /></type>
  68                                         <description>
  69                                                 <p>Constant for the direction <em>down</em> (“bottom”).</p>
  70                                         </description>
  71                                 </simple-value>
  72                         </system-binding>
  73                         <system-binding identifier="to_lrt">
  74                                 <simple-value>
  75                                         <type><named-type name="Float" /></type>
  76                                         <description>
  77                                                 <p>Constant for the direction <em>down and right</em> (“lower right”).</p>
  78                                         </description>
  79                                 </simple-value>
  80                         </system-binding>
  81                         <system-binding identifier="to_rt">
  82                                 <simple-value>
  83                                         <type><named-type name="Float" /></type>
  84                                         <description>
  85                                                 <p>Constant for the direction <em>right</em>.</p>
  86                                         </description>
  87                                 </simple-value>
  88                         </system-binding>
  89                         <system-binding identifier="to_urt">
  90                                 <simple-value>
  91                                         <type><named-type name="Float" /></type>
  92                                         <description>
  93                                                 <p>Constant for the direction <em>up and right</em> (“upper right“).</p>
  94                                         </description>
  95                                 </simple-value>
  96                         </system-binding>
  97                         <system-binding identifier="to_top">
  98                                 <simple-value>
  99                                         <type><named-type name="Float" /></type>
 100                                         <description>
 101                                                 <p>Constant for the direction <em>up</em> (“top”).</p>
 102                                         </description>
 103                                 </simple-value>
 104                         </system-binding>
 105                         <system-binding identifier="to_ulft">
 106                                 <simple-value>
 107                                         <type><named-type name="Float" /></type>
 108                                         <description>
 109                                                 <p>Constant for the direction <em>up ad left</em> (“upper left”).</p>
 110                                         </description>
 111                                 </simple-value>
 112                         </system-binding>
 113                         <system-binding identifier="to_center">
 114                                 <simple-value>
 115                                         <type><named-type name="Float" /></type>
 116                                         <description>
 117                                                 <p>Constant for centered placement.</p>
 118                                         </description>
 119                                 </simple-value>
 120                         </system-binding>
 121                 </body>
 122         </section>
 123
 124         <section id="extensions/shiftoff/functions">
 125                 <title>Functions</title>
 126                 <body>
 127                         <p>Functions for working with directions in terms of the constants defined by this extension.</p>
 128
 129                         <system-binding identifier="dirtopoint">
 130                                 <function>
 131                                         <case>
 132                                                 <arguments>
 133                                                         <arg identifier="d">
 134                                                                 <type><named-type name="Float" /></type>
 135                                                         </arg>
 136                                                 </arguments>
 137                                                 <result>
 138                                                         <type><named-type name="FloatPair" /></type>
 139                                                 </result>
 140                                                 <dynamic-references></dynamic-references>
 141                                                 <description>
 142                                                         <p>Converts a direction constant (which must have one of the values held by the constants defined by this extension) to a relative point to center at.  The returned value can be used with <binding extension="basic-layout" name="center" />.</p>
 143                                                 </description>
 144                                         </case>
 145                                         <see-also><binding extension="shiftoff" name="to_dir" /></see-also>
 146                                 </function>
 147                         </system-binding>
 148
 149                         <system-binding identifier="to_dir">
 150                                 <function>
 151                                         <case>
 152                                                 <arguments>
 153                                                         <arg identifier="z">
 154                                                                 <type><named-type name="FloatPair" /></type>
 155                                                         </arg>
 156                                                 </arguments>
 157                                                 <result>
 158                                                         <type><named-type name="Float" /></type>
 159                                                 </result>
 160                                                 <dynamic-references></dynamic-references>
 161                                                 <description>
 162                                                         <p>This generalizes the inverse of <binding extension="shiftoff" name="dirtopoint" />.  It converts any relative point (see <binding extension="basic-layout" name="center" />) to the closest direction constant defined by this extension.  It always returns a directional value, never <binding extension="shiftoff" name="to_center" />.</p>
 163                                                 </description>
 164                                         </case>
 165                                 </function>
 166                         </system-binding>
 167
 168                         <system-binding identifier="dir_to">
 169                                 <function>
 170                                         <case>
 171                                                 <arguments>
 172                                                         <arg identifier="d">
 173                                                                 <type><named-type name="Float" /></type>
 174                                                         </arg>
 175                                                 </arguments>
 176                                                 <result>
 177                                                         <type><named-type name="FloatPair" /></type>
 178                                                 </result>
 179                                                 <dynamic-references></dynamic-references>
 180                                                 <description>
 181                                                         <p><b>This function might be removed in the future!</b></p>
 182                                                         <p>This generalizes <binding extension="shiftoff" name="dirtopoint" /> by being applicable to any float value.  This makes ugly use of the numerical values held by the constants defined by this extension.</p>
 183                                                 </description>
 184                                         </case>
 185                                 </function>
 186                         </system-binding>
 187
 188                         <system-binding identifier="shiftoff">
 189                                 <function>
 190                                         <case>
 191                                                 <arguments>
 192                                                         <arg identifier="obj">
 193                                                                 <type><named-type name="Drawable2D" /></type>
 194                                                         </arg>
 195                                                         <arg identifier="d">
 196                                                                 <type><named-type name="Float" /></type>
 197                                                         </arg>
 198                                                 </arguments>
 199                                                 <result>
 200                                                         <type><named-type name="Drawable2D" /></type>
 201                                                 </result>
 202                                                 <dynamic-references></dynamic-references>
 203                                                 <description>
 204                                                         <p>Provides <str-MetaPost />-like layout.</p>
 205                                                         <p>For instance, to place a label below a point, say <inline>lblPoint</inline>, one may write:
 206 <pre>
 207 •page &lt;&lt; [shift lblPoint] [] [shiftoff (TeX `$x_{1}$´) to_bot]
 208 </pre></p>
 209                                                 </description>
 210                                         </case>
 211                                         <see-also><binding extension="shiftoff" name="shiftoffwlm" /></see-also>
 212                                 </function>
 213                         </system-binding>
 214
 215                         <system-binding identifier="shiftoffwlm">
 216                                 <function>
 217                                         <case>
 218                                                 <arguments>
 219                                                         <arg identifier="obj">
 220                                                                 <type><named-type name="Drawable2D" /></type>
 221                                                         </arg>
 222                                                         <arg identifier="d">
 223                                                                 <type><named-type name="Float" /></type>
 224                                                         </arg>
 225                                                 </arguments>
 226                                                 <result>
 227                                                         <type><named-type name="Drawable2D" /></type>
 228                                                 </result>
 229                                                 <dynamic-references><dynvar extension="basic-layout" name="labelmargin" /></dynamic-references>
 230                                                 <description>
 231                                                         <p>Provides <str-MetaPost />-like layout.</p>
 232                                                         <p>This function is like <binding extension="shiftoff" name="shiftoff" />, but treats the obeject as if it was slightly bigger than it really is.  The implementation uses <binding extension="basic-layout" name="centerat_wlm" /> instead of <binding extension="basic-layout" name="center" />.</p>
 233                                                 </description>
 234                                         </case>
 235                                 </function>
 236                         </system-binding>
 237
 238                 </body>
 239         </section>
 240 </book>