doc/parts/extensions/Shapes-Layout-basic-layout.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   <within-namespace>..Shapes..Layout</within-namespace>
  24   <extension>basic-layout</extension>
  25   <description>
  26     <p>Elementary layout using bounding boxes.</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>The functions in this extension provide the basic means for layout.</p>
  44   </top>
  45
  46         <section id="extensions/basic-layout/path-max">
  47                 <title>Extreme coordinates on paths</title>
  48                 <body>
  49                         <p>These functions optimize along paths in one of the four principal directions, returning the coordinate of the optimum.</p>
  50
  51                         <system-binding identifier="xmax">
  52                                 <function>
  53                                         <case>
  54                                                 <arguments>
  55                                                         <arg identifier="p">
  56                                                                 <type><named-type name="Path" /></type>
  57                                                         </arg>
  58                                                 </arguments>
  59                                                 <result>
  60                                                         <type><named-type name="Length" /></type>
  61                                                 </result>
  62                                                 <dynamic-references></dynamic-references>
  63                                                 <description>
  64                                                         <p>Rightmost coordinate along <arg name="p" />.</p>
  65                                                 </description>
  66                                         </case>
  67                                 </function>
  68                         </system-binding>
  69
  70                         <system-binding identifier="xmin">
  71                                 <function>
  72                                         <case>
  73                                                 <arguments>
  74                                                         <arg identifier="p">
  75                                                                 <type><named-type name="Path" /></type>
  76                                                         </arg>
  77                                                 </arguments>
  78                                                 <result>
  79                                                         <type><named-type name="Length" /></type>
  80                                                 </result>
  81                                                 <dynamic-references></dynamic-references>
  82                                                 <description>
  83                                                         <p>Leftmost coordinate along <arg name="p" />.</p>
  84                                                 </description>
  85                                         </case>
  86                                 </function>
  87                         </system-binding>
  88
  89                         <system-binding identifier="ymax">
  90                                 <function>
  91                                         <case>
  92                                                 <arguments>
  93                                                         <arg identifier="p">
  94                                                                 <type><named-type name="Path" /></type>
  95                                                         </arg>
  96                                                 </arguments>
  97                                                 <result>
  98                                                         <type><named-type name="Length" /></type>
  99                                                 </result>
 100                                                 <dynamic-references></dynamic-references>
 101                                                 <description>
 102                                                         <p>Topmost coordinate along <arg name="p" />.</p>
 103                                                 </description>
 104                                         </case>
 105                                 </function>
 106                         </system-binding>
 107
 108                         <system-binding identifier="ymin">
 109                                 <function>
 110                                         <case>
 111                                                 <arguments>
 112                                                         <arg identifier="p">
 113                                                                 <type><named-type name="Path" /></type>
 114                                                         </arg>
 115                                                 </arguments>
 116                                                 <result>
 117                                                         <type><named-type name="Length" /></type>
 118                                                 </result>
 119                                                 <dynamic-references></dynamic-references>
 120                                                 <description>
 121                                                         <p>Bottommost coordinate along <arg name="p" />.</p>
 122                                                 </description>
 123                                         </case>
 124                                 </function>
 125                         </system-binding>
 126
 127                 </body>
 128         </section>
 129
 130         <section id="extensions/basic-layout/basic">
 131                 <title>Basic positioning operations</title>
 132                 <body>
 133
 134                         <system-binding identifier="center">
 135                                 <function>
 136                                         <case constructor-of="Drawable">
 137                                                 <arguments>
 138                                                         <arg identifier="obj">
 139                                                                 <type><named-type name="Drawable" /></type>
 140                                                         </arg>
 141                                                         <arg identifier="z">
 142                                                                 <type><named-type name="FloatPair" /></type>
 143                                                                 <default><eq>(0,0)</eq></default>
 144                                                         </arg>
 145                                                 </arguments>
 146                                                 <dynamic-references></dynamic-references>
 147                                                 <description>
 148                                                         <p>The argument <arg name="z" /> is interpreted as a point in the bounding box of <arg name="obj" />, with (-1,-1) being the lower left corner, and (1,1) being the upper right corner.  <arg name="obj" /> is then shifted so that this point ends up at the origin.</p>
 149                                                 </description>
 150                                         </case>
 151                                 </function>
 152                         </system-binding>
 153
 154                         <system-binding identifier="center_x">
 155                                 <function>
 156                                         <case constructor-of="Drawable">
 157                                                 <arguments>
 158                                                         <arg identifier="obj">
 159                                                                 <type><named-type name="Drawable" /></type>
 160                                                         </arg>
 161                                                         <arg identifier="x">
 162                                                                 <type><named-type name="Float" /></type>
 163                                                                 <default><eq>0</eq></default>
 164                                                         </arg>
 165                                                 </arguments>
 166                                                 <dynamic-references></dynamic-references>
 167                                                 <description>
 168                                                         <p>Like <value name="..Shapes..Layout..center" />, but operates only along the <eq>x</eq> axis.</p>
 169                                                 </description>
 170                                         </case>
 171                                 </function>
 172                         </system-binding>
 173
 174                         <system-binding identifier="center_y">
 175                                 <function>
 176                                         <case constructor-of="Drawable">
 177                                                 <arguments>
 178                                                         <arg identifier="obj">
 179                                                                 <type><named-type name="Drawable" /></type>
 180                                                         </arg>
 181                                                         <arg identifier="y">
 182                                                                 <type><named-type name="Float" /></type>
 183                                                                 <default><eq>0</eq></default>
 184                                                         </arg>
 185                                                 </arguments>
 186                                                 <dynamic-references></dynamic-references>
 187                                                 <description>
 188                                                         <p>Like <value name="..Shapes..Layout..center" />, but operates only along the <eq>y</eq> axis.</p>
 189                                                 </description>
 190                                         </case>
 191                                 </function>
 192                         </system-binding>
 193
 194                         <system-binding identifier="centerof">
 195                                 <function>
 196                                         <case constructor-of="Coords">
 197                                                 <arguments>
 198                                                         <arg identifier="obj">
 199                                                                 <type><named-type name="Drawable" /></type>
 200                                                         </arg>
 201                                                 </arguments>
 202                                                 <dynamic-references></dynamic-references>
 203                                                 <description>
 204                                                         <p>Returns the point which is mid-way between the extreme points of the bounding box in the <eq>x</eq> and <eq>y</eq> direction, respectively.</p>
 205                                                 </description>
 206                                         </case>
 207                                 </function>
 208                         </system-binding>
 209
 210                 </body>
 211         </section>
 212
 213         <section id="extensions/basic-layout/labelmargin">
 214                 <title>Label margin</title>
 215                 <body>
 216                         <p>When positioning text relative to other elements, it often looks good if labels appear at a certain distance from the objects they label.  This idea is implemented as functions using a common dynamic variable.</p>
 217
 218                         <dynamic-variable identifier="labelmargin">
 219                                 <default><physical><scalar>1</scalar><unit>mm</unit></physical></default>
 220                                 <type><named-type name="Length" /></type>
 221                                 <description>
 222                                         <p>Distance to be used when placing labels relative to the point they label.</p>
 223                                 </description>
 224                         </dynamic-variable>
 225
 226                         <system-binding identifier="center_wlm">
 227                                 <function>
 228                                         <case constructor-of="Drawable">
 229                                                 <arguments>
 230                                                         <arg identifier="obj">
 231                                                                 <type><named-type name="Drawable" /></type>
 232                                                         </arg>
 233                                                         <arg identifier="z">
 234                                                                 <type><named-type name="FloatPair" /></type>
 235                                                         </arg>
 236                                                 </arguments>
 237                                                 <dynamic-references><dynvar extension="basic-layout" name="labelmargin" /></dynamic-references>
 238                                                 <description>
 239                                                         <p>The argument <arg name="z" /> is interpreted as a point in the bounding box of <arg name="obj" />, with (-1,-1) being the lower left corner, and (1,1) being the upper right corner.  <arg name="obj" /> is then shifted so that this point ends up at the origin.</p>
 240                                                 </description>
 241                                         </case>
 242                                 </function>
 243                         </system-binding>
 244
 245                 </body>
 246         </section>
 247
 248         <section id="extensions/basic-layout/mediation">
 249                 <title>Mediation</title>
 250                 <body>
 251                         <p>By <em>mediation</em> we refer to the specification of a value relative to a lower and upper bound.  The bounds can either be very general, or the beginning and end of a path.</p>
 252
 253                         <system-binding identifier="mediate">
 254                                 <function>
 255                                         <case>
 256                                                 <type-templates>
 257                                                         <template name="L">
 258                                                                 <description>
 259                                                                         <p>Elements constitute a linear space, that is, they can be added and multiplied by scalars.</p>
 260                                                                 </description>
 261                                                         </template>
 262                                                 </type-templates>
 263                                                 <result>
 264                                                         <type><template-type name="L" /></type>
 265                                                 </result>
 266                                                 <arguments>
 267                                                         <arg identifier="r">
 268                                                                 <type><named-type name="Float" /></type>
 269                                                         </arg>
 270                                                         <arg identifier="x1">
 271                                                                 <type><template-type name="L" /></type>
 272                                                         </arg>
 273                                                         <arg identifier="x2">
 274                                                                 <type><template-type name="L" /></type>
 275                                                         </arg>
 276                                                 </arguments>
 277                                                 <dynamic-references></dynamic-references>
 278                                                 <description>
 279                                                         <p>Simply computes (1-<arg name="r" />)*<arg name="x1" /> + <arg name="r" />*<arg name="x2" />.</p>
 280                                                 </description>
 281                                         </case>
 282                                 </function>
 283                         </system-binding>
 284
 285                         <system-binding identifier="mspoint">
 286                                 <function>
 287                                         <case constructor-of="Coords">
 288                                                 <arguments>
 289                                                         <arg identifier="pth">
 290                                                                 <type><named-type name="Path" /></type>
 291                                                         </arg>
 292                                                         <arg identifier="mediation">
 293                                                                 <type><named-type name="Float" /></type>
 294                                                         </arg>
 295                                                         <arg identifier="slide">
 296                                                                 <type><named-type name="Length" /></type>
 297                                                                 <default><physical><scalar>0</scalar><unit>cm</unit></physical></default>
 298                                                         </arg>
 299                                                 </arguments>
 300                                                 <dynamic-references></dynamic-references>
 301                                                 <description>
 302                                                         <p>Interprets <arg name="mediation" /> as a length relative the total length of <arg name="pth" />, then adds <arg name="slide" /> to this length, and finds the coordinates at the computed arc time.</p>
 303                                                         <p>For instance, the geometric midpoint of a path <inline>myPath</inline> is obtained as <inline>[mspoint myPath 0.5]</inline>.</p>
 304                                                 </description>
 305                                         </case>
 306                                 </function>
 307                         </system-binding>
 308                 </body>
 309         </section>
 310
 311         <section id="extensions/basic-layout/boxes">
 312                 <title>Boxes</title>
 313                 <body>
 314                         <p>It is sometime useful to control the layout of an object by altering one or several of its boxes.  At the moment, there are just two boxes, the <em>bounding box</em> and the <em>bleed box</em>, and for historical reasons, the short <em>bbox</em> refers to the <em>bounding box</em>.</p>
 315
 316                         <system-binding identifier="bboxed_sym">
 317                                 <function>
 318                                         <case>
 319                                                 <arguments>
 320                                                         <arg identifier="obj">
 321                                                                 <type><named-type name="Drawable" /></type>
 322                                                         </arg>
 323                                                 </arguments>
 324                                                 <result>
 325                                                                 <type><named-type name="Drawable" /></type>
 326                                                 </result>
 327                                                 <dynamic-references></dynamic-references>
 328                                                 <description>
 329                                                         <p>Enlarges the bounding box to a rectangle just big enough to obtain the center of the bounding box at the origin.</p>
 330                                                 </description>
 331                                         </case>
 332                                 </function>
 333                         </system-binding>
 334
 335                         <system-binding identifier="bboxed_sym_y">
 336                                 <function>
 337                                         <case>
 338                                                 <arguments>
 339                                                         <arg identifier="obj">
 340                                                                 <type><named-type name="Drawable" /></type>
 341                                                         </arg>
 342                                                 </arguments>
 343                                                 <result>
 344                                                                 <type><named-type name="Drawable" /></type>
 345                                                 </result>
 346                                                 <dynamic-references></dynamic-references>
 347                                                 <description>
 348                                                         <p>Enlarges the bounding box to a rectangle just big enough to obtain the center of the bounding box at the <eq>y</eq> coordinate zero.</p>
 349                                                 </description>
 350                                         </case>
 351                                 </function>
 352                         </system-binding>
 353
 354                         <system-binding identifier="bboxed_sym_x">
 355                                 <function>
 356                                         <case>
 357                                                 <arguments>
 358                                                         <arg identifier="obj">
 359                                                                 <type><named-type name="Drawable" /></type>
 360                                                         </arg>
 361                                                 </arguments>
 362                                                 <result>
 363                                                                 <type><named-type name="Drawable" /></type>
 364                                                 </result>
 365                                                 <dynamic-references></dynamic-references>
 366                                                 <description>
 367                                                         <p>Enlarges the bounding box to a rectangle just big enough to obtain the center of the bounding box at the <eq>x</eq> coordinate zero.</p>
 368                                                 </description>
 369                                         </case>
 370                                 </function>
 371                         </system-binding>
 372
 373                         <system-binding identifier="bboxed_enlarge">
 374                                 <function>
 375                                         <case>
 376                                                 <arguments>
 377                                                         <arg identifier="obj">
 378                                                                 <type><named-type name="Drawable" /></type>
 379                                                         </arg>
 380                                                         <arg identifier="z">
 381                                                                 <type><named-type name="Coords" /></type>
 382                                                         </arg>
 383                                                 </arguments>
 384                                                 <result>
 385                                                                 <type><named-type name="Drawable" /></type>
 386                                                 </result>
 387                                                 <dynamic-references></dynamic-references>
 388                                                 <description>
 389                                                         <p>Enlarges the bounding box in all four principal direction to a rectangle, the horizontal and vertical enlargements given by the corresponding coordinates of <arg name="z" />.</p>
 390                                                 </description>
 391                                         </case>
 392                                 </function>
 393                         </system-binding>
 394
 395                         <system-binding identifier="enlarge_bleedbox">
 396                                 <function>
 397                                         <case>
 398                                                 <arguments>
 399                                                         <arg identifier="obj">
 400                                                                 <type><named-type name="Drawable" /></type>
 401                                                         </arg>
 402                                                         <arg identifier="z">
 403                                                                 <type><named-type name="Coords" /></type>
 404                                                         </arg>
 405                                                 </arguments>
 406                                                 <result>
 407                                                                 <type><named-type name="Drawable" /></type>
 408                                                 </result>
 409                                                 <dynamic-references></dynamic-references>
 410                                                 <description>
 411                                                         <p>Like <value name="..Shapes..Layout..bboxed_enlarge" />, but acting on the bleed box instead of the bounding box.</p>
 412                                                 </description>
 413                                         </case>
 414                                 </function>
 415                         </system-binding>
 416
 417                 </body>
 418         </section>
 419
 420 </book>