doc/parts/state-types/containers.sxml

   1 <section id="state-types/containers">
   2 <title>Containers</title>
   3 <top>
   4         <p>States of types in this section are used to produce containers with objects in.</p>
   5 </top>
   6
   7   <core-state-type name="Group">
   8     <abstraction>
   9       <p>States of type <self /> are used to fill containers of type <named-type name="Group" />.</p>
  10     </abstraction>
  11     <construction>
  12                         <binding name="newGroup" />
  13     </construction>
  14                 <mutator op="tack-on">
  15                         <function>
  16                                 <case>
  17                                         <arguments>
  18                                                 <arg>
  19                                                         <type><named-type name="Drawable" /></type>
  20                                                 </arg>
  21                                         </arguments>
  22                                         <dynamic-references><dynvar name="blend" /></dynamic-references>
  23                                         <side-effect>
  24                                                 <p>Put element on top of pile.</p>
  25                                         </side-effect>
  26                                 </case>
  27                         </function>
  28                 </mutator>
  29                 <mutator op="peek">
  30                         <function>
  31                                 <case>
  32                                         <result>
  33                                                 <type><named-type name="Group" /></type>
  34                                         </result>
  35                                         <dynamic-references></dynamic-references>
  36                                         <description>
  37                                                 <p>Get current pile.</p>
  38                                         </description>
  39                                 </case>
  40                         </function>
  41                 </mutator>
  42                 <mutator op="freeze">
  43                         <function>
  44                                 <case>
  45                                         <result>
  46                                                 <type><named-type name="Group" /></type>
  47                                         </result>
  48                                         <dynamic-references></dynamic-references>
  49                                         <description>
  50                                                 <p>Get current pile.</p>
  51                                         </description>
  52                                 </case>
  53                         </function>
  54                 </mutator>
  55                 <mutator identifier="erase">
  56                         <function>
  57                                 <case>
  58                                         <arguments>
  59                                         </arguments>
  60                                         <dynamic-references></dynamic-references>
  61                                         <side-effect>
  62                                                 <p>Erase contents.</p>
  63                                         </side-effect>
  64                                         <description>
  65                                                 <p>A common application of this is when <state name="page" /> has been used to define the contents of the pages in <state name="catalog" />.  Then, when <state name="catalog" /> is non-empty at the end of the program, it is an error if <state name="page" /> is also non-tmpty.  All you have to do then is to write
  66 <pre>
  67 •page.[erase]
  68 </pre>
  69 at the end of the program.</p>
  70                                         </description>
  71                                 </case>
  72                         </function>
  73                 </mutator>
  74                 <mutator identifier="remove">
  75                         <function>
  76                                 <case>
  77                                         <arguments>
  78                                                 <arg identifier="key">
  79                                                         <type><named-type name="Symbol" /></type>
  80                                                 </arg>
  81                                         </arguments>
  82                                         <dynamic-references></dynamic-references>
  83                                         <side-effect>
  84                                                 <p>Remove <em>shallow</em> tagged objects with the key <arg name="key" />.</p>
  85                                         </side-effect>
  86                                         <description>
  87                                                 <p>Here, <em>shallow</em> refers to objects that were tacked on directly to the state.  For instance,
  88 <pre>
  89 •page &lt;&lt; [shift (1cm,0cm)] [] [tag 'a [stroke (0cm,0cm)--(1cm,1cm)]]
  90 •page.[remove 'a]
  91 </pre>
  92 will <em>not</em> remove the stroke from the page, since the value being tacked on to the state is transformed.  To make it work, apply the transform to the object being tagged:
  93 <pre>
  94 •page &lt;&lt; [tag 'a  [[shift (1cm,0cm)] [stroke (0cm,0cm)--(1cm,1cm)]]]
  95 </pre>
  96 </p>
  97                                         </description>
  98                                         <see-also>
  99                                                 <binding name="tag" />
 100                                         </see-also>
 101                                 </case>
 102                         </function>
 103                 </mutator>
 104   </core-state-type>
 105
 106   <core-state-type name="Group3D">
 107     <abstraction>
 108       <p>States of type <self /> are used to fill containers of type <named-type name="Group3D" />.</p>
 109     </abstraction>
 110     <construction>
 111                         <binding name="newGroup3D" />
 112     </construction>
 113                 <mutator op="tack-on">
 114                         <function>
 115                                 <case>
 116                                         <arguments>
 117                                                 <arg>
 118                                                         <type><named-type name="Drawable3D" /></type>
 119                                                 </arg>
 120                                         </arguments>
 121                                         <dynamic-references><dynvar name="blend" /></dynamic-references>
 122                                         <side-effect>
 123                                                 <p>Put element on top of pile.</p>
 124                                         </side-effect>
 125                                 </case>
 126                         </function>
 127                 </mutator>
 128                 <mutator op="peek">
 129                         <function>
 130                                 <case>
 131                                         <result>
 132                                                 <type><named-type name="Group3D" /></type>
 133                                         </result>
 134                                         <dynamic-references></dynamic-references>
 135                                         <description>
 136                                                 <p>Get current pile.</p>
 137                                         </description>
 138                                 </case>
 139                         </function>
 140                 </mutator>
 141                 <mutator op="freeze">
 142                         <function>
 143                                 <case>
 144                                         <result>
 145                                                 <type><named-type name="Group3D" /></type>
 146                                         </result>
 147                                         <dynamic-references></dynamic-references>
 148                                         <description>
 149                                                 <p>Get current pile.</p>
 150                                         </description>
 151                                 </case>
 152                         </function>
 153                 </mutator>
 154                 <mutator identifier="erase">
 155                         <function>
 156                                 <case>
 157                                         <arguments>
 158                                         </arguments>
 159                                         <dynamic-references></dynamic-references>
 160                                         <side-effect>
 161                                                 <p>Erase contents.</p>
 162                                         </side-effect>
 163                                         <description>
 164                                                 <p>Analogous to <mutator type="Group" mutator="erase" />.</p>
 165                                         </description>
 166                                 </case>
 167                         </function>
 168                 </mutator>
 169                 <mutator identifier="remove">
 170                         <function>
 171                                 <case>
 172                                         <arguments>
 173                                                 <arg identifier="key">
 174                                                         <type><named-type name="Symbol" /></type>
 175                                                 </arg>
 176                                         </arguments>
 177                                         <dynamic-references></dynamic-references>
 178                                         <side-effect>
 179                                                 <p>Remove <em>shallow</em> tagged objects with the key <arg name="key" />.</p>
 180                                         </side-effect>
 181                                         <description>
 182                                                 <p>Analogous to <mutator type="Group" mutator="remove" />.</p>
 183                                         </description>
 184                                 </case>
 185                         </function>
 186                 </mutator>
 187   </core-state-type>
 188
 189   <core-state-type name="Catalog">
 190     <abstraction>
 191       <p>States of type <self /> are used to construct documents with many pages, page labels, cross references, and so on.</p>
 192     </abstraction>
 193     <construction>
 194                         <state name="catalog" />
 195     </construction>
 196                 <description>
 197                         <p>There is currently no way a user can create their own <named-state-type name="Catalog" /> states; only the global <state name="catalog" /> may be accessed.  It is directly associated with the program output, so instead of peeking or freezing the state, the program is terminated, at which point the contents of the state is used.</p>
 198                 </description>
 199                 <see-also>
 200                         <state name="catalog" />
 201                 </see-also>
 202                 <mutator op="tack-on">
 203                         <function>
 204                                 <case>
 205                                         <arguments>
 206                                                 <arg>
 207                                                         <type><named-type name="Drawable" /></type>
 208                                                 </arg>
 209                                         </arguments>
 210                                         <dynamic-references><dynvar name="eyez" /></dynamic-references>
 211                                         <side-effect>
 212                                                 <p>Add graphics as page att the end of the catalog.</p>
 213                                                 <p>Note that a <named-type name="Drawable" /> value can contain objects that have special meaning when appearing on a page out output.  Below, functions that construct such objects are listed.</p>
 214                                                 <p>Don't expect the lista of dynamic references to be complete, and don't expect any of the listed references to actually be used.</p>
 215                                         </side-effect>
 216                                         <see-also>
 217                                                 <binding name="destination" />
 218                                                 <binding name="site" />
 219                                                 <binding name="annotationText" />
 220                                                 <binding name="annotationLaunch" />
 221                                                 <binding name="annotationLink" />
 222                                         </see-also>
 223                                 </case>
 224                         </function>
 225                 </mutator>
 226                 <mutator identifier="setbboxgroup">
 227                         <function>
 228                                 <case>
 229                                         <arguments>
 230                                                 <arg identifier="key">
 231                                                         <type><named-type name="Symbol" /></type>
 232                                                 </arg>
 233                                         </arguments>
 234                                         <dynamic-references></dynamic-references>
 235                                         <side-effect>
 236                                                 <p>Define the bounding box key to be used for pages subsequently tacked on to the catalog.  These pages will get equal media boxes in the end, being the smallest that contains all the bounding boxes of the pages in the group.</p>
 237                                         </side-effect>
 238                                 </case>
 239                                 <case>
 240                                         <arguments>
 241                                         </arguments>
 242                                         <dynamic-references></dynamic-references>
 243                                         <side-effect>
 244                                                 <p>Clear the bounding box key to be used for pages subsequently tacked on to the catalog.  Pages will get a media box equal to their own bounding box.</p>
 245                                         </side-effect>
 246                                 </case>
 247                         </function>
 248                 </mutator>
 249                 <mutator identifier="setpagelabel">
 250                         <function>
 251                                 <case>
 252                                         <arguments>
 253                                                 <arg identifier="prefix">
 254                                                         <type><named-type name="String" /></type>
 255                                                 </arg>
 256                                                 <arg identifier="style">
 257                                                         <type><named-type name="Symbol" /></type>
 258                                                 </arg>
 259                                                 <arg identifier="number">
 260                                                         <type><named-type name="Integer" /></type>
 261                                                 </arg>
 262                                         </arguments>
 263                                         <dynamic-references></dynamic-references>
 264                                         <side-effect>
 265                                                 <p>Change the page labeling properties to use for future pages being added to the state.</p>
 266                                         </side-effect>
 267                                         <description>
 268                                                 <p>All arguments may be omitted, and their names explain their meanings.  If omitted, the corresponding property is not changed by the mutator.</p>
 269                                                 <p>The parameter <arg name="style" /> can be any of <inline>'none</inline>, <inline>'decimal</inline>, <inline>'ROMAN</inline>, <inline>'roman</inline>, <inline>'ALPHABET</inline>, or <inline>'alphabet</inline>.</p>
 270                                         </description>
 271                                 </case>
 272                         </function>
 273                 </mutator>
 274                 <mutator identifier="nextpagelabel">
 275                         <function>
 276                                 <case>
 277                                         <arguments>
 278                                         </arguments>
 279                                         <result>
 280                                                 <type><named-type name="String" /></type>
 281                                         </result>
 282                                         <dynamic-references></dynamic-references>
 283                                         <side-effect>
 284                                                 <p>None.</p>
 285                                         </side-effect>
 286                                         <description>
 287                                                 <p>Returns the string that would be used as page label for the next page being added to the state.</p>
 288                                         </description>
 289                                 </case>
 290                         </function>
 291                 </mutator>
 292                 <mutator identifier="nextpagenumber">
 293                         <function>
 294                                 <case>
 295                                         <arguments>
 296                                         </arguments>
 297                                         <result>
 298                                                 <type><named-type name="Integer" /></type>
 299                                         </result>
 300                                         <dynamic-references></dynamic-references>
 301                                         <side-effect>
 302                                                 <p>None.</p>
 303                                         </side-effect>
 304                                         <description>
 305                                                 <p>Returns the document page number (as opposed to logic page number) for the next page being added to the state.</p>
 306                                         </description>
 307                                 </case>
 308                         </function>
 309                 </mutator>
 310   </core-state-type>
 311
 312
 313   <core-state-type name="Text">
 314     <abstraction>
 315       <p>States of type <self /> are used to combine font properties with strings to paint text.</p>
 316     </abstraction>
 317     <construction>
 318                         <state name="newText" />
 319     </construction>
 320                 <mutator op="tack-on">
 321                         <function>
 322                                 <case>
 323                                         <arguments>
 324                                                 <arg>
 325                                                         <type><named-type name="TextOperation" /></type>
 326                                                 </arg>
 327                                         </arguments>
 328                                         <dynamic-references></dynamic-references>
 329                                         <side-effect>
 330                                                 <p>Append operation.</p>
 331                                         </side-effect>
 332                                 </case>
 333                                 <case>
 334                                         <arguments>
 335                                                 <arg>
 336                                                         <type><named-type name="String" /></type>
 337                                                 </arg>
 338                                         </arguments>
 339                                         <dynamic-references>
 340                                                 <dynvar name="text_font" />
 341                                                 <dynvar name="text_characterspacing" />
 342                                                 <dynvar name="text_wordspacing" />
 343                                                 <dynvar name="text_horizontalscaling" />
 344                                                 <dynvar name="text_leading" />
 345                                                 <dynvar name="text_font" />
 346                                                 <dynvar name="text_size" />
 347                                                 <dynvar name="text_rendering" />
 348                                                 <dynvar name="text_rise" />
 349                                                 <dynvar name="text_knockout" />
 350                                         </dynamic-references>
 351                                         <side-effect>
 352                                                 <p>Append text without kerning.</p>
 353                                         </side-effect>
 354                                 </case>
 355                                 <case>
 356                                         <arguments>
 357                                                 <arg>
 358                                                         <type><named-type name="Transform" /></type>
 359                                                 </arg>
 360                                         </arguments>
 361                                         <dynamic-references></dynamic-references>
 362                                         <side-effect>
 363                                                 <p>Append <em>move to</em> command.</p>
 364                                         </side-effect>
 365                                 </case>
 366                                 <case>
 367                                         <arguments>
 368                                                 <arg>
 369                                                         <type><named-type name="Coords" /></type>
 370                                                 </arg>
 371                                         </arguments>
 372                                         <dynamic-references></dynamic-references>
 373                                         <side-effect>
 374                                                 <p>Append <em>newline</em> command followed by relative move.</p>
 375                                         </side-effect>
 376                                 </case>
 377                                 <case>
 378                                         <arguments>
 379                                                 <arg>
 380                                                         <type><named-type name="FloatPair" /></type>
 381                                                 </arg>
 382                                         </arguments>
 383                                         <dynamic-references>
 384                                                 <dynvar name="text_size" />
 385                                         </dynamic-references>
 386                                         <side-effect>
 387                                                 <p>Append <em>newline</em> command followed by relative move, interpreting the move in units of <dynvar name="text_size" />.</p>
 388                                         </side-effect>
 389                                 </case>
 390                         </function>
 391                 </mutator>
 392                 <mutator op="freeze">
 393                         <function>
 394                                 <case>
 395                                         <result>
 396                                                 <type><named-type name="Drawable" /></type>
 397                                         </result>
 398                                         <dynamic-references><dynstate name="graphics" /> <dynstate name="text" /></dynamic-references>
 399                                         <description>
 400                                                 <p>Produce graphic representation of entered objects.</p>
 401                                         </description>
 402                                 </case>
 403                         </function>
 404                 </mutator>
 405                 <freeze>
 406                         <type><named-type name="Drawable" /></type>
 407                 </freeze>
 408   </core-state-type>
 409
 410 </section>