| blob | 4e6cf5ad6d7931fced610f95ec711c8830ff78f8 |
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 Henrik Tidefelt -->
22 <book>
24 <description>
26 </description>
32 <needs>
35 </needs>
36 <top>
37 <alphabetical-index/>
41 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)showcase/blockdrawdemo.shape" -->]]>
42 </source>
43 <caption>
44 <p>An application of the <a extension="blockdraw" /> extension. This example contains some non-standard solutions, showing how the functions of this extension can be combined with standard <str-Shapes /> operations.</p>
45 </caption>
46 </example-with-output>
47 <p>The original implementation of this concept was for <str-MetaPost/> (it is available from <a href="http://tug.ctan.org/tex-archive/graphics/metapost/contrib/macros/blockdraw_mp/">CTAN</a>, and part of some <str-LaTeX /> distributions). It was then translated into an early version of <str-Shapes />, and it was believed that it would become much cleaner if a user-defined type would be used to represent the blocks. At that time, the name of the extension was <filename>blockdraw_wfo</filename>, where the <filename>wfo</filename> stands for <em>Waiting For Objects</em>. However, it has turned out that by <em>not</em> using a user-defined type, but relying simply on <named-type name="Drawable" /> values instead to represent blocks, the applicability of this extension has become much wider than expected. Hence, the <filename>_wfo</filename> tag has been removed, and there are currently no plans for changing the representation of blocks.</p>
48 </top>
52 <body>
53 <p>Before going into the detailed description of the bindings introduced by this extension, this tutorial will serve as a quick start for them who just want to see what the source code for some examples could look like. This tutorial is really not much more than that; a sequence of increasingly complex examples.</p>
58 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/blockdraw-tutorial-hello.shape" -->]]>
59 </source>
60 <caption>
61 <p>The simplest of all examples. This is simply a label placed in a rectangular block of standard size. Have a look at the source code right away!</p>
62 </caption>
63 </example-with-output>
66 <image pdf="doc/blockdraw-tutorial-relative_3.pdf" jpg="doc/blockdraw-tutorial-relative_70%.jpg" />
68 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/blockdraw-tutorial-relative.shape" -->]]>
69 </source>
70 <caption>
71 <p>Several functions are provided to put a block at a predefined distance apart from a given block. They are non-pure functions that both add the positioned object to a destination state and return it so that it can be used for future reference. See <a id="extensions/blockdraw/layout" ><title /></a> for a complete list of layout functions.</p>
72 <p>The reason why <binding extension="blockdraw" name="sumpicture" /> is a function rather than a <named-type name="Drawable" /> is that the result is a function of the dynamic environment; both the radius size of the block, the width of the line, and the size of the summation sign, depend on dynamic bindings.</p>
73 </caption>
74 </example-with-output>
77 <image pdf="doc/blockdraw-tutorial-conpoint_3.pdf" jpg="doc/blockdraw-tutorial-conpoint_70%.jpg" />
79 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/blockdraw-tutorial-conpoint.shape" -->]]>
80 </source>
81 <caption>
82 <p>A connection point function is used to find an appropriate connection point of a block with two inputs. Exactly how this point is pointed out using a connection arrow from nowhere is not important here.</p>
83 </caption>
84 </example-with-output>
89 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/blockdraw-tutorial-labels.shape" -->]]>
90 </source>
91 <caption>
92 <p>Depending on the relative layout of blocks, a varying degree of manual effort is needed to get the connecting paths right. In this example, all paths but the feed-back path can be deduced automatically using <binding extension="blockdraw" name="connect" />. The constructed path is both painted and returned. Most of the time the return value is ignored (by means of <binding name="ignore" />), but it is useful when we want to place a label along the path. See <a id="extensions/blockdraw/connections" /> for the complete set of functions for the purpose of making connections.</p>
93 <p>Putting a label along the connection is easy. To make the source code readable, it is a good idea to bind the connection path to a variable, and then use this variable when placing the label. Special purpose functions are provided to ensure a consistent layout of labels; the user need only select a point on the path (preferably using <binding extension="basic-layout" name="mspoint" />) and a side of that point (by using the “<inline>putlabel</inline>-function” named accordingly), and how the label should be aligned.</p>
94 <p>Putting a label at a terminal point is similar to labeling a connection, the only difference is how the point to be labeled is selected. Note that for a <binding name="pointpicture" />, all connection point functions will return the same point.</p>
95 <p>This example also shows how to place signs at connection points, and how to indicate a point where a signal splits by a small dot.</p>
96 <p>This is a comparatively simple figure, containing three different kinds of objects: blocks, connections and annotations along the connections. This example also follows the good habit to let preferences that might be shared by several figures be extracted into a separate file (<a href=<!--#expand-next-string-->"$(BASE)$(EXAMPLES)doc/blockdraw-tutorial-tut-prefs.shext">link</a>).</p>
97 </caption>
98 </example-with-output>
103 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/blockdraw-tutorial-layout.shape" -->]]>
104 </source>
105 <caption>
106 <p>Laying out the blocks of a slightly more complicated diagram, and constructing a nice path to be dashed.</p>
107 <p>The art of making nice block diagrams using this extension turns out to be a matter of having an idea for how to select from the predefined distances. Here are a few guidelines from the author:</p>
108 <ul>
109 <li><p>Use <em>Far</em> between terminals and the closest <em>block</em> they connect to.</p></li>
111 <li><p>Use <em>Near</em> between horizontally aligned blocks when there shall be <em>no</em> label on the connection.</p></li>
112 <li><p>Use <em>Far</em> between horizontally aligned blocks when there <em>shall be</em> a label on the connection.</p></li>
114 </ul>
115 <p>Note how the dashed line was handled similarly to a label when selecting the distance after the middle summation.</p>
116 <p>There are many situations when simple guidelines like the ones above cannot be applied successfully, and one will have to improvise. For example, the shorter distances may be preferred if the graphics becomes too wide, although an alternative solution to this is to change the values of the predefined lengths instead, see <a id="extensions/blockdraw/settings" />.</p>
117 </caption>
118 </example-with-output>
120 <p>OK, this is the end of the tutorial. Hopefully you didn't find the examples too difficult to follow — did you even get interested to learn more about the range of functions provided?</p>
121 </body>
122 </section>
126 <top>
127 <p>This extension introduces a large number of dynamic variables to control various aspects of the appearance. The variables fall naturally into different categories, and are presented accordingly below.</p>
128 </top>
131 <body>
132 <dynamic-variable-table>
136 <description>
138 </description>
139 </dynamic-variable>
143 <description>
145 </description>
146 </dynamic-variable>
150 <description>
152 </description>
153 </dynamic-variable>
157 <description>
158 <p>Half the height of blocks which are meant to have enough vertical space for a standing fraction in the label.</p>
159 </description>
160 </dynamic-variable>
161 </dynamic-variable-table>
162 </body>
163 </section>
167 <body>
168 <dynamic-variable-table>
172 <description>
174 </description>
175 </dynamic-variable>
179 <description>
181 </description>
182 </dynamic-variable>
183 </dynamic-variable-table>
184 </body>
185 </section>
189 <body>
190 <dynamic-variable-table>
194 <description>
196 </description>
197 </dynamic-variable>
201 <description>
203 </description>
204 </dynamic-variable>
208 <description>
210 </description>
211 </dynamic-variable>
215 <description>
217 </description>
218 </dynamic-variable>
222 <description>
224 </description>
225 </dynamic-variable>
226 </dynamic-variable-table>
227 </body>
228 </section>
232 <body>
233 <dynamic-variable-table>
237 <description>
239 </description>
240 </dynamic-variable>
244 <description>
246 </description>
247 </dynamic-variable>
251 <description>
252 <p>A distance that may be used when there should be enough space for a small label between the blocks.</p>
253 </description>
254 </dynamic-variable>
258 <description>
260 </description>
261 </dynamic-variable>
265 <description>
267 </description>
268 </dynamic-variable>
269 </dynamic-variable-table>
270 </body>
271 </section>
275 <body>
278 <type>
279 <function-type>
280 <arguments>
282 </arguments>
283 <result>
285 </result>
286 </function-type>
287 </type>
288 <description>
289 <p>Transform that is applied to anything which is thought to be a label. Useful to scale down labels to allow smaller diagrams.</p>
290 <p>An alternative could be to produce big diagrams, and then scale the result at the end, but this is a mess compared to always producing graphics in the true scale.</p>
291 </description>
292 </dynamic-variable>
296 <type>
297 <function-type>
298 <arguments>
300 </arguments>
301 <result>
303 </result>
304 </function-type>
305 </type>
306 <description>
308 <p>When called from within this extension, <dynvar name="width" /> will always be set to <dynvar extension="blockdraw" name="connectionlw" />. Hence, users who call <dynvar extension="blockdraw" name="connectpainter" /> directly should consider using this line width as well.</p>
309 </description>
310 </dynamic-variable>
311 </body>
312 </section>
314 </section>
318 <body>
319 <p>These functions return plain <named-type name="Drawable" /> objects — they are dumb in this sense. A more accurate way of modelling things would at least include information about connection points with each block, while we <em>compute</em> connection points assuming that the blocks are rectangular, see <a id="extensions/blockdraw/con-points" />.</p>
324 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/blockdraw-blocks.shape" -->]]>
325 </source>
326 <caption>
328 </caption>
329 </example-with-output>
332 <function>
333 <case>
334 <arguments>
337 </arg>
340 </arg>
343 </arg>
344 </arguments>
345 <result>
347 </result>
348 <dynamic-references><dynvar extension="blockdraw" name="textscaling" /> <dynvar extension="blockdraw" name="blocklw" /></dynamic-references>
349 <description>
350 <p>This function is considered low-level and should not be used directly in standard applications.</p>
352 </description>
353 <see-also>
359 </see-also>
360 </case>
361 </function>
362 </system-binding>
365 <function>
366 <case>
367 <arguments>
370 </arg>
371 </arguments>
372 <result>
374 </result>
375 <dynamic-references><dynvar extension="blockdraw" name="longblockrx" /> <dynvar extension="blockdraw" name="longblockry" /></dynamic-references>
376 <description>
378 <p>Calls <binding extension="blockdraw" name="sizedblock" /> internally, which uses additional dynamic variables.</p>
379 </description>
380 <see-also>
382 </see-also>
383 </case>
384 </function>
385 </system-binding>
388 <function>
389 <case>
390 <arguments>
393 </arg>
394 </arguments>
395 <result>
397 </result>
399 <description>
401 <p>Calls <binding extension="blockdraw" name="sizedblock" /> internally, which uses additional dynamic variables.</p>
402 </description>
403 <see-also>
405 </see-also>
406 </case>
407 </function>
408 </system-binding>
411 <function>
412 <case>
413 <arguments>
416 </arg>
417 </arguments>
418 <result>
420 </result>
421 <dynamic-references><dynvar extension="blockdraw" name="longblockrx" /> <dynvar extension="blockdraw" name="fracblockry" /></dynamic-references>
422 <description>
423 <p>Constructs a long rectangular block of standardized size, tall enough to accommodate a standing fraction in the label.</p>
424 <p>Calls <binding extension="blockdraw" name="sizedblock" /> internally, which uses additional dynamic variables.</p>
425 </description>
426 <see-also>
428 </see-also>
429 </case>
430 </function>
431 </system-binding>
434 <function>
435 <case>
436 <arguments>
439 </arg>
440 </arguments>
441 <result>
443 </result>
444 <dynamic-references><dynvar extension="blockdraw" name="longblockrx" /> <dynvar extension="blockdraw" name="longblockry" /></dynamic-references>
445 <description>
446 <p>Like <binding extension="blockdraw" name="longblock" />, but makes the block wider if required to accommodate the label.</p>
447 </description>
448 </case>
449 </function>
450 </system-binding>
453 <function>
454 <case>
455 <arguments>
458 </arg>
459 </arguments>
460 <result>
462 </result>
463 <dynamic-references><dynvar extension="blockdraw" name="longblockrx" /> <dynvar extension="blockdraw" name="fracblockry" /></dynamic-references>
464 <description>
465 <p>Like <binding extension="blockdraw" name="fracblock" />, but makes the block wider if required to accommodate the label.</p>
466 </description>
467 </case>
468 </function>
469 </system-binding>
472 <function>
473 <case>
474 <arguments>
477 </arg>
478 </arguments>
479 <result>
481 </result>
482 <dynamic-references><dynvar extension="blockdraw" name="textscaling" /> <dynvar extension="blockdraw" name="smallblockr" /> <dynvar extension="blockdraw" name="blocklw" /></dynamic-references>
483 <description>
485 </description>
486 </case>
487 </function>
488 </system-binding>
491 <function>
492 <case>
493 <arguments>
494 </arguments>
495 <result>
497 </result>
498 <description>
499 <p>Returns a small circular summation block. Note that this must be a function since the result shall depend on dynamic bindings!</p>
500 <p>Calls <binding extension="blockdraw" name="roundblock" /> internally, which uses additional dynamic variables.</p>
501 </description>
502 </case>
503 </function>
504 </system-binding>
507 <function>
508 <case>
509 <arguments>
510 </arguments>
511 <result>
513 </result>
514 <dynamic-references><dynvar name="stroking" /> <dynvar extension="blockdraw" name="connectionlw" /></dynamic-references>
515 <description>
516 <p>Returns a small circular dot to use where a signal splits. The size is chosen relative to the width of the connection strokes. Note that this must be a function since the result shall depend on dynamic bindings!</p>
517 </description>
518 </case>
519 </function>
520 </system-binding>
523 <function>
524 <case>
525 <arguments>
526 </arguments>
527 <result>
529 </result>
531 <description>
532 <p>Returns a small circle that can be used if a signal terminal is to be emphasized. The size is chosen relative to the width of the connection strokes. Note that this must be a function since the result shall depend on dynamic bindings!</p>
533 </description>
534 </case>
535 </function>
536 </system-binding>
538 </body>
539 </section>
543 <body>
544 <p>The functions are non-pure, as they have the bad (?) habit of tacking on their return value to a <named-state-type name="Group" />. The reason is that it is almost always convenient to bind a block to a variable so that it can be referred to, and there is seldom reason not to draw it as soon as it is laid out. If one does not want the object to be drawn to any state, one may simply pass <state name="ignore" /> as the destination.</p>
545 <p>The number of functions in this section may seem overwhelming, but the reason for this is to hide degrees of freedom in order to gain in consistency of the spacing between blocks in the diagram. Except <binding extension="blockdraw" name="putblockOrigin" />, uses typically select among function being named after two axes for the user to choose from; one distance axis (<em>VeryNear</em>, <em>Near</em>, <em>LabelSpace</em>, <em>Far</em>, <em>VeryFar</em>), and one direction axis (<em>Left</em>, <em>Right</em>, <em>Below</em>, <em>Above</em>). This explains 20 of the functions here. In addition, there are some low-level functions, and another four where the point on the distance axis is <em>LabelMargin</em> (here, the distance depends on the direction, but users typically don't use these functions anyway).</p>
550 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/blockdraw-layout.shape" -->]]>
551 </source>
552 <caption>
553 <p>A selection of the layout functions. The name of the functions reflect which dynamic variable is used to determine the distance between the objects, in the direction also given by the name of the function. Note that all these functions are non-pure, as they allow the object being laid out to be added to a destination variable in addition to returning it.</p>
554 <p>Note that horizontal positioning does not care about the object's vertical extent, and vice versa. This is not only apparent in the example with the block labeled “High”, but also in the examples where the new block is a plain label centered at its leftmost baseline point.</p>
555 <p>The function <binding extension="blockdraw" name="putblockOrigin" /> is different from the others in that it puts the block at the origin instead of relative to another block.</p>
556 <p>The functions using the various label margins should only be used if this non-pure behavior is desired; labels are generally better placed using the pure functions described in <a id="extensions/blockdraw/labels" />.</p>
557 </caption>
558 </example-with-output>
561 <function>
562 <case>
563 <arguments>
566 </state>
569 </arg>
570 </arguments>
571 <result>
573 </result>
574 <description>
575 <p>Simply tacks <arg name="newBlock" /> to <state-arg name="dst" />, and then returns <arg name="newBlock" />. This function is typically used to place the first block added to the block diagram, but may also be used in other situations when manual tweaking is required to get a block in the right location. In the latter case, this function is called with an object which has already been shifted to the right location; applying the shift to the result of calling this function would be meaningless, since the un-shifted object would already have been added to <state-arg name="dst" /> then.</p>
576 <p>Although this is a very simple task, use of this function makes the code more homogeneous.</p>
577 </description>
578 </case>
579 </function>
580 </system-binding>
583 <function>
584 <case>
585 <arguments>
588 </state>
591 </arg>
594 </arg>
597 </arg>
598 </arguments>
599 <result>
601 </result>
602 <description>
603 <p>This function is considered low-level; the user should prefer functions which call this function with standardized values for <arg name="dist" /> instead.</p>
604 <p>Positions <arg name="newBlock" /> to the left of <arg name="oldBlock" />, such that the horizontal distance between the bounding boxes equals <arg name="dist" />. The vertical positioning will make the origin of <arg name="newBlock" /> level with the vertical midpoint of <arg name="oldBlock" />'s bounding box.</p>
605 </description>
606 <see-also>
613 </see-also>
614 </case>
615 </function>
616 </system-binding>
619 <function>
620 <case>
621 <arguments>
624 </state>
627 </arg>
630 </arg>
633 </arg>
634 </arguments>
635 <result>
637 </result>
638 <description>
640 </description>
641 <see-also>
648 </see-also>
649 </case>
650 </function>
651 </system-binding>
654 <function>
655 <case>
656 <arguments>
659 </state>
662 </arg>
665 </arg>
668 </arg>
669 </arguments>
670 <result>
672 </result>
673 <description>
675 </description>
676 <see-also>
683 </see-also>
684 </case>
685 </function>
686 </system-binding>
689 <function>
690 <case>
691 <arguments>
694 </state>
697 </arg>
700 </arg>
703 </arg>
704 </arguments>
705 <result>
707 </result>
708 <description>
710 </description>
711 <see-also>
718 </see-also>
719 </case>
720 </function>
721 </system-binding>
724 <function>
725 <case>
726 <arguments>
729 </state>
732 </arg>
735 </arg>
736 </arguments>
737 <result>
739 </result>
740 <dynamic-references><dynvar extension="blockdraw" name="blockspaceverynear" /></dynamic-references>
741 <description>
742 <p>Calls <binding extension="blockdraw" name="putblockLeft" /> with the distance argument given by the dynamic variable corresponding to the name of this function.</p>
743 </description>
744 </case>
745 </function>
746 </system-binding>
748 <function>
749 <case>
750 <arguments>
753 </state>
756 </arg>
759 </arg>
760 </arguments>
761 <result>
763 </result>
765 <description>
766 <p>Calls <binding extension="blockdraw" name="putblockLeft" /> with the distance argument given by the dynamic variable corresponding to the name of this function.</p>
767 </description>
768 </case>
769 </function>
770 </system-binding>
772 <function>
773 <case>
774 <arguments>
777 </state>
780 </arg>
783 </arg>
784 </arguments>
785 <result>
787 </result>
788 <dynamic-references><dynvar extension="blockdraw" name="blockspacelabelspace" /></dynamic-references>
789 <description>
790 <p>Calls <binding extension="blockdraw" name="putblockLeft" /> with the distance argument given by the dynamic variable corresponding to the name of this function.</p>
791 </description>
792 </case>
793 </function>
794 </system-binding>
796 <function>
797 <case>
798 <arguments>
801 </state>
804 </arg>
807 </arg>
808 </arguments>
809 <result>
811 </result>
813 <description>
814 <p>Calls <binding extension="blockdraw" name="putblockLeft" /> with the distance argument given by the dynamic variable corresponding to the name of this function.</p>
815 </description>
816 </case>
817 </function>
818 </system-binding>
820 <function>
821 <case>
822 <arguments>
825 </state>
828 </arg>
831 </arg>
832 </arguments>
833 <result>
835 </result>
836 <dynamic-references><dynvar extension="blockdraw" name="blockspaceveryfar" /></dynamic-references>
837 <description>
838 <p>Calls <binding extension="blockdraw" name="putblockLeft" /> with the distance argument given by the dynamic variable corresponding to the name of this function.</p>
839 </description>
840 </case>
841 </function>
842 </system-binding>
844 <function>
845 <case>
846 <arguments>
849 </state>
852 </arg>
855 </arg>
856 </arguments>
857 <result>
859 </result>
860 <dynamic-references><dynvar extension="blockdraw" name="leftrightlabelmargin" /></dynamic-references>
861 <description>
862 <p>Calls <binding extension="blockdraw" name="putblockLeft" /> with the distance argument given by the dynamic variable corresponding to the name of this function.</p>
863 </description>
864 </case>
865 </function>
866 </system-binding>
869 <function>
870 <case>
871 <arguments>
874 </state>
877 </arg>
880 </arg>
881 </arguments>
882 <result>
884 </result>
885 <dynamic-references><dynvar extension="blockdraw" name="blockspaceverynear" /></dynamic-references>
886 <description>
887 <p>Calls <binding extension="blockdraw" name="putblockRight" /> with the distance argument given by the dynamic variable corresponding to the name of this function.</p>
888 </description>
889 </case>
890 </function>
891 </system-binding>
893 <function>
894 <case>
895 <arguments>
898 </state>
901 </arg>
904 </arg>
905 </arguments>
906 <result>
908 </result>
910 <description>
911 <p>Calls <binding extension="blockdraw" name="putblockRight" /> with the distance argument given by the dynamic variable corresponding to the name of this function.</p>
912 </description>
913 </case>
914 </function>
915 </system-binding>
917 <function>
918 <case>
919 <arguments>
922 </state>
925 </arg>
928 </arg>
929 </arguments>
930 <result>
932 </result>
933 <dynamic-references><dynvar extension="blockdraw" name="blockspacelabelspace" /></dynamic-references>
934 <description>
935 <p>Calls <binding extension="blockdraw" name="putblockRight" /> with the distance argument given by the dynamic variable corresponding to the name of this function.</p>
936 </description>
937 </case>
938 </function>
939 </system-binding>
941 <function>
942 <case>
943 <arguments>
946 </state>
949 </arg>
952 </arg>
953 </arguments>
954 <result>
956 </result>
958 <description>
959 <p>Calls <binding extension="blockdraw" name="putblockRight" /> with the distance argument given by the dynamic variable corresponding to the name of this function.</p>
960 </description>
961 </case>
962 </function>
963 </system-binding>
965 <function>
966 <case>
967 <arguments>
970 </state>
973 </arg>
976 </arg>
977 </arguments>
978 <result>
980 </result>
981 <dynamic-references><dynvar extension="blockdraw" name="blockspaceveryfar" /></dynamic-references>
982 <description>
983 <p>Calls <binding extension="blockdraw" name="putblockRight" /> with the distance argument given by the dynamic variable corresponding to the name of this function.</p>
984 </description>
985 </case>
986 </function>
987 </system-binding>
989 <function>
990 <case>
991 <arguments>
994 </state>
997 </arg>
1000 </arg>
1001 </arguments>
1002 <result>
1004 </result>
1005 <dynamic-references><dynvar extension="blockdraw" name="leftrightlabelmargin" /></dynamic-references>
1006 <description>
1007 <p>Calls <binding extension="blockdraw" name="putblockRight" /> with the distance argument given by the dynamic variable corresponding to the name of this function.</p>
1008 </description>
1009 </case>
1010 </function>
1011 </system-binding>
1014 <function>
1015 <case>
1016 <arguments>
1019 </state>
1022 </arg>
1025 </arg>
1026 </arguments>
1027 <result>
1029 </result>
1030 <dynamic-references><dynvar extension="blockdraw" name="blockspaceverynear" /></dynamic-references>
1031 <description>
1032 <p>Calls <binding extension="blockdraw" name="putblockBelow" /> with the distance argument given by the dynamic variable corresponding to the name of this function.</p>
1033 </description>
1034 </case>
1035 </function>
1036 </system-binding>
1038 <function>
1039 <case>
1040 <arguments>
1043 </state>
1046 </arg>
1049 </arg>
1050 </arguments>
1051 <result>
1053 </result>
1054 <dynamic-references><dynvar extension="blockdraw" name="blockspacenear" /></dynamic-references>
1055 <description>
1056 <p>Calls <binding extension="blockdraw" name="putblockBelow" /> with the distance argument given by the dynamic variable corresponding to the name of this function.</p>
1057 </description>
1058 </case>
1059 </function>
1060 </system-binding>
1062 <function>
1063 <case>
1064 <arguments>
1067 </state>
1070 </arg>
1073 </arg>
1074 </arguments>
1075 <result>
1077 </result>
1078 <dynamic-references><dynvar extension="blockdraw" name="blockspacelabelspace" /></dynamic-references>
1079 <description>
1080 <p>Calls <binding extension="blockdraw" name="putblockBelow" /> with the distance argument given by the dynamic variable corresponding to the name of this function.</p>
1081 </description>
1082 </case>
1083 </function>
1084 </system-binding>
1086 <function>
1087 <case>
1088 <arguments>
1091 </state>
1094 </arg>
1097 </arg>
1098 </arguments>
1099 <result>
1101 </result>
1103 <description>
1104 <p>Calls <binding extension="blockdraw" name="putblockBelow" /> with the distance argument given by the dynamic variable corresponding to the name of this function.</p>
1105 </description>
1106 </case>
1107 </function>
1108 </system-binding>
1110 <function>
1111 <case>
1112 <arguments>
1115 </state>
1118 </arg>
1121 </arg>
1122 </arguments>
1123 <result>
1125 </result>
1126 <dynamic-references><dynvar extension="blockdraw" name="blockspaceveryfar" /></dynamic-references>
1127 <description>
1128 <p>Calls <binding extension="blockdraw" name="putblockBelow" /> with the distance argument given by the dynamic variable corresponding to the name of this function.</p>
1129 </description>
1130 </case>
1131 </function>
1132 </system-binding>
1134 <function>
1135 <case>
1136 <arguments>
1139 </state>
1142 </arg>
1145 </arg>
1146 </arguments>
1147 <result>
1149 </result>
1150 <dynamic-references><dynvar extension="blockdraw" name="belowlabelmargin" /></dynamic-references>
1151 <description>
1152 <p>Calls <binding extension="blockdraw" name="putblockBelow" /> with the distance argument given by the dynamic variable corresponding to the name of this function.</p>
1153 </description>
1154 </case>
1155 </function>
1156 </system-binding>
1159 <function>
1160 <case>
1161 <arguments>
1164 </state>
1167 </arg>
1170 </arg>
1171 </arguments>
1172 <result>
1174 </result>
1175 <dynamic-references><dynvar extension="blockdraw" name="blockspaceverynear" /></dynamic-references>
1176 <description>
1177 <p>Calls <binding extension="blockdraw" name="putblockAbove" /> with the distance argument given by the dynamic variable corresponding to the name of this function.</p>
1178 </description>
1179 </case>
1180 </function>
1181 </system-binding>
1183 <function>
1184 <case>
1185 <arguments>
1188 </state>
1191 </arg>
1194 </arg>
1195 </arguments>
1196 <result>
1198 </result>
1199 <dynamic-references><dynvar extension="blockdraw" name="blockspacenear" /></dynamic-references>
1200 <description>
1201 <p>Calls <binding extension="blockdraw" name="putblockAbove" /> with the distance argument given by the dynamic variable corresponding to the name of this function.</p>
1202 </description>
1203 </case>
1204 </function>
1205 </system-binding>
1207 <function>
1208 <case>
1209 <arguments>
1212 </state>
1215 </arg>
1218 </arg>
1219 </arguments>
1220 <result>
1222 </result>
1223 <dynamic-references><dynvar extension="blockdraw" name="blockspacelabelspace" /></dynamic-references>
1224 <description>
1225 <p>Calls <binding extension="blockdraw" name="putblockAbove" /> with the distance argument given by the dynamic variable corresponding to the name of this function.</p>
1226 </description>
1227 </case>
1228 </function>
1229 </system-binding>
1231 <function>
1232 <case>
1233 <arguments>
1236 </state>
1239 </arg>
1242 </arg>
1243 </arguments>
1244 <result>
1246 </result>
1248 <description>
1249 <p>Calls <binding extension="blockdraw" name="putblockAbove" /> with the distance argument given by the dynamic variable corresponding to the name of this function.</p>
1250 </description>
1251 </case>
1252 </function>
1253 </system-binding>
1255 <function>
1256 <case>
1257 <arguments>
1260 </state>
1263 </arg>
1266 </arg>
1267 </arguments>
1268 <result>
1270 </result>
1271 <dynamic-references><dynvar extension="blockdraw" name="blockspaceveryfar" /></dynamic-references>
1272 <description>
1273 <p>Calls <binding extension="blockdraw" name="putblockAbove" /> with the distance argument given by the dynamic variable corresponding to the name of this function.</p>
1274 </description>
1275 </case>
1276 </function>
1277 </system-binding>
1279 <function>
1280 <case>
1281 <arguments>
1284 </state>
1287 </arg>
1290 </arg>
1291 </arguments>
1292 <result>
1294 </result>
1295 <dynamic-references><dynvar extension="blockdraw" name="abovelabelmargin" /></dynamic-references>
1296 <description>
1297 <p>Calls <binding extension="blockdraw" name="putblockAbove" /> with the distance argument given by the dynamic variable corresponding to the name of this function.</p>
1298 </description>
1299 </case>
1300 </function>
1301 </system-binding>
1303 </body>
1304 </section>
1308 <body>
1309 <p>A basic design choice of this extension is to use a plain <named-type name="Drawable" /> object to model a block. Hence, the points where connections attach to a block is not part of the object representation itself. Instead, a standardized way of selecting points on the bounding box is provided.</p>
1310 <p>A connection point is specified by selecting one of the four sides of a block (by calling the appropriate function), the total number of connection points on that side, and the index of the current point. Thanks to the use of default values, it is often sufficient to only select the side of the block; then the mid-point of that side will be selected.</p>
1315 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/blockdraw-con-points.shape" -->]]>
1316 </source>
1317 <caption>
1318 <p>How to select points on a block where connections attach. Note that it is assumed that the block is rectangular, so that the rectangular bounding box follows the contour of the object; this is why summation blocks can only be used with one connection on each side. Also note that the provided numbers shall be floats, nor is the index required to be in the range from 1 to the total number of points, but use these freedoms with caution!</p>
1319 </caption>
1320 </example-with-output>
1323 <function>
1324 <case>
1325 <arguments>
1328 </state>
1332 </arg>
1336 </arg>
1337 </arguments>
1338 <result>
1340 </result>
1341 <description>
1342 <p>Select a point on the left side of the rectangular bounding box of <arg name="pic" />, selecting point number <arg name="i" /> among a total of <arg name="n" /> on this side.</p>
1343 </description>
1344 </case>
1345 </function>
1346 </system-binding>
1348 <function>
1349 <case>
1350 <arguments>
1353 </state>
1357 </arg>
1361 </arg>
1362 </arguments>
1363 <result>
1365 </result>
1366 <description>
1368 </description>
1369 </case>
1370 </function>
1371 </system-binding>
1373 <function>
1374 <case>
1375 <arguments>
1378 </state>
1382 </arg>
1386 </arg>
1387 </arguments>
1388 <result>
1390 </result>
1391 <description>
1393 </description>
1394 </case>
1395 </function>
1396 </system-binding>
1398 <function>
1399 <case>
1400 <arguments>
1403 </state>
1407 </arg>
1411 </arg>
1412 </arguments>
1413 <result>
1415 </result>
1416 <description>
1418 </description>
1419 </case>
1420 </function>
1421 </system-binding>
1423 </body>
1424 </section>
1428 <body>
1429 <p>These functions are, for the same reason as the layout functions (see <a id="extensions/blockdraw/layout" />), non-pure. One difference, though, is that instead of returning the <em>painted</em> path, only the <named-type name="Path" /> object itself is returned. The reason is that the path is much more useful for further operations, such as putting labels along it.</p>
1430 <p>While the most high-level functions take entire blocks as arguments and assume that there is just one connection point on each side of a block, the more low-level functions take the connection points as arguments, allowing the user to select the point using the functions in <a id="extensions/blockdraw/con-points" />.</p>
1431 <p>In most situations, <binding extension="blockdraw" name="connect" /> is able to figure out the path from the blocks being connected alone, and in these cases this function should be used. In most cases when <binding extension="blockdraw" name="connect" /> picks the wrong path, this is because it makes the connection to the wrong sides of the blocks, and then functions such as <binding extension="blockdraw" name="brconnect" /> (connect the <em>bottom</em> side of the first block with the <em>right</em> of the second block) come in handy. These functions will still be insufficient if the path shall connect, say, a bottom side to another bottom side, since they cannot figure out the vertical coordinate for the horizontal part of such a path. Then the most low-level functions, such as <binding extension="blockdraw" name="vvconnect" /> (construct a path with is initially <em>vertical</em> and <em>vertical</em> at the end as well), are required. It is only the most low-level functions that operate on points rather than blocks.</p>
1432 <p>So, there were three levels of functions, and they are presented in order low to high. The listing of the functions on each level is preceded by an example..</p>
1434 <example-with-output title="Connection primitives" internal-id="blockdraw/connections/primitives">
1435 <image pdf="doc/blockdraw-connections-primitive_3.pdf" jpg="doc/blockdraw-connections-primitive_70%.jpg" />
1437 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/blockdraw-connections-primitive.shape" -->]]>
1438 </source>
1439 <caption>
1440 <p>These are the primitive functions that construct connection paths. They operate on points, and are named after the direction at the beginning and end of the constructed path, for instance <binding extension="blockdraw" name="hvconnect" /> constructs a path that is <em>horizontal</em> at the beginning and <em>vertical</em> at the end. If the path shall begin and end along the same axis, the user must also tell at which coordinate the beginning and end shall connect with each other. This is done using a pair of mediation and slide values; the mediation is a linear interpolation between the start (mediation is <eq>0</eq>) and end (mediation is <eq>1</eq>) points, and the slide is an absolute length added to the coordinate given by the slide.</p>
1441 </caption>
1442 </example-with-output>
1444 <function>
1445 <case>
1446 <arguments>
1449 </state>
1452 </arg>
1455 </arg>
1456 </arguments>
1457 <result>
1459 </result>
1460 <dynamic-references><dynvar extension="blockdraw" name="connectionlw" /> <dynvar extension="blockdraw" name="connectpainter" /></dynamic-references>
1461 <description>
1462 <p>Constructs a path from <arg name="pa" /> to <arg name="pb" /> which consists of two line segments; first a <em>vertical</em> and then a <em>horizontal</em>. Besides returning the path, it is painted using <dynvar extension="blockdraw" name="connectpainter" /> with <dynvar name="width" /> being set to <dynvar extension="blockdraw" name="connectionlw" />, and the resulting <named-type name="Drawable" /> is added to <state-arg name="dst" />.</p>
1463 </description>
1464 </case>
1465 </function>
1466 </system-binding>
1468 <function>
1469 <case>
1470 <arguments>
1473 </state>
1476 </arg>
1479 </arg>
1480 </arguments>
1481 <result>
1483 </result>
1484 <dynamic-references><dynvar extension="blockdraw" name="connectionlw" /> <dynvar extension="blockdraw" name="connectpainter" /></dynamic-references>
1485 <description>
1486 <p>Analogous to <binding extension="blockdraw" name="hvconnect" />; just exchange <em>horizontal</em> and <em>vertical</em> in the description.</p>
1487 </description>
1488 </case>
1489 </function>
1490 </system-binding>
1492 <function>
1493 <case>
1494 <arguments>
1497 </state>
1500 </arg>
1503 </arg>
1506 </arg>
1509 </arg>
1510 </arguments>
1511 <result>
1513 </result>
1514 <dynamic-references><dynvar extension="blockdraw" name="connectionlw" /> <dynvar extension="blockdraw" name="connectpainter" /></dynamic-references>
1515 <description>
1516 <p>Constructs a path from <arg name="pa" /> to <arg name="pb" /> which consists of three line segments; initially <em>horizontal</em> and <em>horizontal</em> also at the end. The horizontal coordinate of the vertical line segment in the middle is given by the <arg name="mediation" /> and <arg name="slide" /> values. The mediation is relative to the horizontal coordinates of <arg name="pa" /> and <arg name="pb" />, while the slide enters the coordinate as a term. See the example for illustration!</p>
1517 <p>Besides returning the path, it is also painted to <state-arg name="dst" />, just like <binding extension="blockdraw" name="vhconnect" /> does.</p>
1518 </description>
1519 </case>
1520 </function>
1521 </system-binding>
1523 <function>
1524 <case>
1525 <arguments>
1528 </state>
1531 </arg>
1534 </arg>
1537 </arg>
1540 </arg>
1541 </arguments>
1542 <result>
1544 </result>
1545 <dynamic-references><dynvar extension="blockdraw" name="connectionlw" /> <dynvar extension="blockdraw" name="connectpainter" /></dynamic-references>
1546 <description>
1547 <p>Analogous to <binding extension="blockdraw" name="hhconnect" />; just exchange <em>horizontal</em> and <em>vertical</em> in the description.</p>
1548 </description>
1549 </case>
1550 </function>
1551 </system-binding>
1554 <example-with-output title="Connection intermediate level functions" internal-id="blockdraw/connections/intermediate">
1555 <image pdf="doc/blockdraw-connections-intermediate_3.pdf" jpg="doc/blockdraw-connections-intermediate_70%.jpg" />
1557 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/blockdraw-connections-intermediate.shape" -->]]>
1558 </source>
1559 <caption>
1560 <p>These are the intermediate level functions that construct connection paths. They operate on blocks, and are named after the blocks' sides at the beginning and end of the constructed path, for instance <binding extension="blockdraw" name="rbconnect" /> constructs a path from the <em>right</em> side of the first block to the <em>bottom</em> side of the second block. If the path shall connect to the same side of the two blocks, the user must also tell how far from the closest block the path shall turn.</p>
1561 <p>When the underlying primitive function being used is <binding extension="blockdraw" name="vvconnect" /> or <binding extension="blockdraw" name="hhconnect" /> the mediation parameter is <eq>0.5</eq> and the slide zero.</p>
1562 </caption>
1563 </example-with-output>
1565 <function>
1566 <case>
1567 <arguments>
1570 </state>
1573 </arg>
1576 </arg>
1577 </arguments>
1578 <result>
1580 </result>
1581 <dynamic-references><dynvar extension="blockdraw" name="connectionlw" /> <dynvar extension="blockdraw" name="connectpainter" /></dynamic-references>
1582 <description>
1583 <p>Calls the appropriate low-level function to create a path from the <em>top</em> of the first block to the <em>right</em> side of the second block.</p>
1584 </description>
1585 </case>
1586 <see-also>
1588 </see-also>
1589 </function>
1590 </system-binding>
1592 <function>
1593 <case>
1594 <arguments>
1597 </state>
1600 </arg>
1603 </arg>
1604 </arguments>
1605 <result>
1607 </result>
1608 <dynamic-references><dynvar extension="blockdraw" name="connectionlw" /> <dynvar extension="blockdraw" name="connectpainter" /></dynamic-references>
1609 <description>
1611 </description>
1612 </case>
1613 <see-also>
1615 </see-also>
1616 </function>
1617 </system-binding>
1619 <function>
1620 <case>
1621 <arguments>
1624 </state>
1627 </arg>
1630 </arg>
1631 </arguments>
1632 <result>
1634 </result>
1635 <dynamic-references><dynvar extension="blockdraw" name="connectionlw" /> <dynvar extension="blockdraw" name="connectpainter" /></dynamic-references>
1636 <description>
1638 </description>
1639 </case>
1640 <see-also>
1642 </see-also>
1643 </function>
1644 </system-binding>
1646 <function>
1647 <case>
1648 <arguments>
1651 </state>
1654 </arg>
1657 </arg>
1658 </arguments>
1659 <result>
1661 </result>
1662 <dynamic-references><dynvar extension="blockdraw" name="connectionlw" /> <dynvar extension="blockdraw" name="connectpainter" /></dynamic-references>
1663 <description>
1665 </description>
1666 </case>
1667 <see-also>
1669 </see-also>
1670 </function>
1671 </system-binding>
1673 <function>
1674 <case>
1675 <arguments>
1678 </state>
1681 </arg>
1684 </arg>
1685 </arguments>
1686 <result>
1688 </result>
1689 <dynamic-references><dynvar extension="blockdraw" name="connectionlw" /> <dynvar extension="blockdraw" name="connectpainter" /></dynamic-references>
1690 <description>
1692 </description>
1693 </case>
1694 <see-also>
1696 </see-also>
1697 </function>
1698 </system-binding>
1700 <function>
1701 <case>
1702 <arguments>
1705 </state>
1708 </arg>
1711 </arg>
1712 </arguments>
1713 <result>
1715 </result>
1716 <dynamic-references><dynvar extension="blockdraw" name="connectionlw" /> <dynvar extension="blockdraw" name="connectpainter" /></dynamic-references>
1717 <description>
1719 </description>
1720 </case>
1721 <see-also>
1723 </see-also>
1724 </function>
1725 </system-binding>
1727 <function>
1728 <case>
1729 <arguments>
1732 </state>
1735 </arg>
1738 </arg>
1739 </arguments>
1740 <result>
1742 </result>
1743 <dynamic-references><dynvar extension="blockdraw" name="connectionlw" /> <dynvar extension="blockdraw" name="connectpainter" /></dynamic-references>
1744 <description>
1746 </description>
1747 </case>
1748 <see-also>
1750 </see-also>
1751 </function>
1752 </system-binding>
1754 <function>
1755 <case>
1756 <arguments>
1759 </state>
1762 </arg>
1765 </arg>
1766 </arguments>
1767 <result>
1769 </result>
1770 <dynamic-references><dynvar extension="blockdraw" name="connectionlw" /> <dynvar extension="blockdraw" name="connectpainter" /></dynamic-references>
1771 <description>
1773 </description>
1774 </case>
1775 <see-also>
1777 </see-also>
1778 </function>
1779 </system-binding>
1782 <function>
1783 <case>
1784 <arguments>
1787 </state>
1790 </arg>
1793 </arg>
1797 </arg>
1801 </arg>
1802 </arguments>
1803 <result>
1805 </result>
1806 <dynamic-references><dynvar extension="blockdraw" name="connectionlw" /> <dynvar extension="blockdraw" name="connectpainter" /></dynamic-references>
1807 <description>
1808 <p>Calls the appropriate low-level function to construct a path from the <em>top</em> of the first block to the <em>bottom</em> of the second block. The <arg name="mediation" /> and <arg name="slide" /> values are simply passed on to the low-level function.</p>
1809 </description>
1810 </case>
1811 <see-also>
1813 </see-also>
1814 </function>
1815 </system-binding>
1817 <function>
1818 <case>
1819 <arguments>
1822 </state>
1825 </arg>
1828 </arg>
1832 </arg>
1836 </arg>
1837 </arguments>
1838 <result>
1840 </result>
1841 <dynamic-references><dynvar extension="blockdraw" name="connectionlw" /> <dynvar extension="blockdraw" name="connectpainter" /></dynamic-references>
1842 <description>
1844 </description>
1845 </case>
1846 <see-also>
1848 </see-also>
1849 </function>
1850 </system-binding>
1852 <function>
1853 <case>
1854 <arguments>
1857 </state>
1860 </arg>
1863 </arg>
1867 </arg>
1871 </arg>
1872 </arguments>
1873 <result>
1875 </result>
1876 <dynamic-references><dynvar extension="blockdraw" name="connectionlw" /> <dynvar extension="blockdraw" name="connectpainter" /></dynamic-references>
1877 <description>
1879 </description>
1880 </case>
1881 <see-also>
1883 </see-also>
1884 </function>
1885 </system-binding>
1887 <function>
1888 <case>
1889 <arguments>
1892 </state>
1895 </arg>
1898 </arg>
1902 </arg>
1906 </arg>
1907 </arguments>
1908 <result>
1910 </result>
1911 <dynamic-references><dynvar extension="blockdraw" name="connectionlw" /> <dynvar extension="blockdraw" name="connectpainter" /></dynamic-references>
1912 <description>
1914 </description>
1915 </case>
1916 <see-also>
1918 </see-also>
1919 </function>
1920 </system-binding>
1923 <function>
1924 <case>
1925 <arguments>
1928 </state>
1931 </arg>
1934 </arg>
1937 </arg>
1938 </arguments>
1939 <result>
1941 </result>
1942 <dynamic-references><dynvar extension="blockdraw" name="connectionlw" /> <dynvar extension="blockdraw" name="connectpainter" /></dynamic-references>
1943 <description>
1944 <p>Calls the appropriate low-level function to construct a path from the <em>top</em> of the first block to the <em>top</em> of the second block. The <arg name="slide" /> value is simply passed on to the low-level function, and the mediation value is chosen as the reasonable choice of <eq>0</eq> or <eq>1</eq>.</p>
1945 </description>
1946 </case>
1947 <see-also>
1949 </see-also>
1950 </function>
1951 </system-binding>
1953 <function>
1954 <case>
1955 <arguments>
1958 </state>
1961 </arg>
1964 </arg>
1967 </arg>
1968 </arguments>
1969 <result>
1971 </result>
1972 <dynamic-references><dynvar extension="blockdraw" name="connectionlw" /> <dynvar extension="blockdraw" name="connectpainter" /></dynamic-references>
1973 <description>
1975 </description>
1976 </case>
1977 <see-also>
1979 </see-also>
1980 </function>
1981 </system-binding>
1983 <function>
1984 <case>
1985 <arguments>
1988 </state>
1991 </arg>
1994 </arg>
1997 </arg>
1998 </arguments>
1999 <result>
2001 </result>
2002 <dynamic-references><dynvar extension="blockdraw" name="connectionlw" /> <dynvar extension="blockdraw" name="connectpainter" /></dynamic-references>
2003 <description>
2005 </description>
2006 </case>
2007 <see-also>
2009 </see-also>
2010 </function>
2011 </system-binding>
2013 <function>
2014 <case>
2015 <arguments>
2018 </state>
2021 </arg>
2024 </arg>
2027 </arg>
2028 </arguments>
2029 <result>
2031 </result>
2032 <dynamic-references><dynvar extension="blockdraw" name="connectionlw" /> <dynvar extension="blockdraw" name="connectpainter" /></dynamic-references>
2033 <description>
2035 </description>
2036 </case>
2037 <see-also>
2039 </see-also>
2040 </function>
2041 </system-binding>
2043 <example-with-output title="Connection by automatic choice" internal-id="blockdraw/connections/connect" id="blockdraw/connections/connect-example">
2044 <image pdf="doc/blockdraw-connections-connect_3.pdf" jpg="doc/blockdraw-connections-connect_70%.jpg" />
2046 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/blockdraw-connections-connect.shape" -->]]>
2047 </source>
2048 <caption>
2049 <p>The function <binding extension="blockdraw" name="connect" /> makes an automatic selection among the intermediate level functions. Note that the first block's left and right sides are preferred to its bottom and top sides, and that one never obtains a path which connects to the same side of both blocks. Hence, only eight of the intermediate level functions are accessed through <binding extension="blockdraw" name="connect" />.</p>
2050 </caption>
2051 </example-with-output>
2054 <function>
2055 <case>
2056 <arguments>
2059 </state>
2062 </arg>
2065 </arg>
2066 </arguments>
2067 <result>
2069 </result>
2070 <dynamic-references><dynvar extension="blockdraw" name="connectionlw" /> <dynvar extension="blockdraw" name="connectpainter" /></dynamic-references>
2071 <description>
2072 <p>Makes an automatic selection among the intermediate level connection functions. See <a id="blockdraw/connections/connect-example" />.</p>
2073 </description>
2074 </case>
2075 </function>
2076 </system-binding>
2078 </body>
2079 </section>
2083 <body>
2087 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/blockdraw-labels.shape" -->]]>
2088 </source>
2089 <caption>
2090 <p>Functions used to position labels relative to a given point. That these functions do take the point to be labeled as an argument counteracts separation of concerns, which would require that these function only position labels relative to the origin. However, it is very convenient to incorporate the shift in the functions, and in case one doesn't want the shift, one may always pass the origin.</p>
2092 <p>Note how the vertical positioning is independent of the vertical extent of the label. This ensures that labels with different vertical extent still end up on the same baseline if the points they label are level.</p>
2093 </caption>
2094 </example-with-output>
2097 <function>
2098 <case>
2099 <arguments>
2102 </arg>
2105 </arg>
2108 </arg>
2109 </arguments>
2110 <result>
2112 </result>
2113 <dynamic-references><dynvar extension="blockdraw" name="leftrightlabelmargin" /></dynamic-references>
2114 <description>
2115 <p>Position <arg name="lbl" /> to the left of <arg name="z" />, centering vertically at <arg name="y" />. For instance, <arg name="y" /><eq>=1</eq> gives a label below <arg name="z" />, while <eq>-1</eq> gives a label above.</p>
2116 </description>
2117 <see-also>
2119 </see-also>
2120 </case>
2121 </function>
2122 </system-binding>
2124 <function>
2125 <case>
2126 <arguments>
2129 </arg>
2132 </arg>
2135 </arg>
2136 </arguments>
2137 <result>
2139 </result>
2140 <dynamic-references><dynvar extension="blockdraw" name="leftrightlabelmargin" /></dynamic-references>
2141 <description>
2143 </description>
2144 <see-also>
2146 </see-also>
2147 </case>
2148 </function>
2149 </system-binding>
2151 <function>
2152 <case>
2153 <arguments>
2156 </arg>
2159 </arg>
2162 </arg>
2163 </arguments>
2164 <result>
2166 </result>
2167 <dynamic-references><dynvar extension="blockdraw" name="belowlabelmargin" /></dynamic-references>
2168 <description>
2169 <p>Position <arg name="lbl" /> below <arg name="z" />, treating the label as if it had the height of an <eq>X</eq>, centering horizontally at <arg name="x" />. For instance, <arg name="x" /><eq>=1</eq> gives a label to the left of <arg name="z" />, while <eq>-1</eq> gives a label to the right.</p>
2170 </description>
2171 <see-also>
2173 </see-also>
2174 </case>
2175 </function>
2176 </system-binding>
2178 <function>
2179 <case>
2180 <arguments>
2183 </arg>
2186 </arg>
2189 </arg>
2190 </arguments>
2191 <result>
2193 </result>
2194 <dynamic-references><dynvar extension="blockdraw" name="abovelabelmargin" /></dynamic-references>
2195 <description>
2196 <p>Position <arg name="lbl" /> above <arg name="z" />, centering horizontally at <arg name="x" />. For instance, <arg name="x" /><eq>=1</eq> gives a label to the left of <arg name="z" />, while <eq>-1</eq> gives a label to the right.</p>
2197 </description>
2198 </case>
2199 </function>
2200 </system-binding>
2202 </body>
2203 </section>
2205 </book>