The intermediary document : Links (how to)

The boxes structure is used to place all the graphical elements. But you cannot use boxes for all graphical elements, especially for drawing lines. For instance, try to figure out which boxes structure you should use to produce this tree :

Pretty hard with boxes only, and this is a very simple tree, imagine with a bigger one !

1. Description

A link is used to connect 2 boxes. The first box is called the parent, and the second one, the child. When the transformation is applied, a line will be drawn on the graphic. On the graphic, links are always displayed behind any other graphical element.

In the intermediary document, links are placed after the boxes structure. You can place as many links as you want, they are optional. The tag used is boxLink. A box owns 9 possible anchors for a link. Here they are :

This is an example of link: 

    <boxLink parentBox="id_of_the_parent_box" parentAnchor="topMiddle"
             childBox="id_of_the_child_box" childAnchor="middleLeft"/>

You must specify attributes for a boxLink. Here is the list :

Attribute name Description Allowed values Default value Mandatory
childAnchor Specifies the anchor of the child box to connect to. topLeft, topMiddle, topRight, middleLeft, middleMiddle, middleRight, bottomLeft, bottomMiddle, or bottomRight. - Yes
childBox Specifies the id of the child box to connect to. An existing box's id. - Yes
parentAnchor Specifies the anchor of the parent box to connect to. topLeft, topMiddle, topRight, middleLeft, middleMiddle, middleRight, bottomLeft, bottomMiddle, or bottomRight. - Yes
parentBox Specifies the id of the parent box to connect to. An existing box's id. - Yes
style Specifies the style of the link. Styles allowed by the SVG specification for the SVG tag line. stroke:black; stroke-width:2; stroke-linecap:round; No

2. Example

To show how links work, we will produce this graphic :

2.1. First step

Let's begin with the boxes structure. Save the following code under editor/XML/Examples/links.grp :

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE grp SYSTEM "../grp.dtd">
    <grp>
      <vbox>
        <hbox>
          <spring/>
          <tbox id="tbox1" background="text" fontSize="20">node a</tbox>
          <spring/>
        </hbox>

        <spring minSize="40"/>

        <hbox>
          <tbox id="tbox2" background="text" fontSize="20">node b</tbox>
          <spring minSize="40"/>
          <tbox id="tbox3" background="text" fontSize="20">node c</tbox>
        </hbox>
      </vbox>
    </grp>

In a console, change to directory editor/XML/Examples (if not already done), and then type :

    java -cp ../../lib/taxi.jar fr.loria.taxi.transformer.TransformerGRPToSVG -grp_in links.grp -defs examples.def -svg_dtd ../svg.dtd

You should see the following output :

    Parsing file examples.def
    Parsing file links.grp
    Creating SVG document
    Generating SVG file links.svg

The graphic looks like that :

2.1. Second step

Now, let's add the links. Modify editor/XML/Examples/links.grp (changes are shown in bold) :

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE grp SYSTEM "../grp.dtd">
    <grp>
      <vbox>
        <hbox>
          <spring/>
          <tbox id="tbox1" background="text" fontSize="20">node a</tbox>
          <spring/>
        </hbox>

        <spring minSize="40"/>

        <hbox>
          <tbox id="tbox2" background="text" fontSize="20">node b</tbox>
          <spring minSize="40"/>
          <tbox id="tbox3" background="text" fontSize="20">node c</tbox>
        </hbox>
      </vbox>

      <boxLink parentBox="tbox1" parentAnchor="bottomMiddle"
               childBox="tbox2" childAnchor="topMiddle"
               style="stroke:red; stroke-width:3; stroke-linecap:butt; stroke-dasharray:5,3"/>
      <boxLink parentBox="tbox1" parentAnchor="bottomMiddle"
               childBox="tbox3" childAnchor="topMiddle"
               style="stroke:red; stroke-width:3; stroke-linecap:butt; stroke-dasharray:5,3"/>
    </grp>

In a console, change to directory editor/XML/Examples (if not already done), and then type :

    java -cp ../../lib/taxi.jar fr.loria.taxi.transformer.TransformerGRPToSVG -grp_in links.grp -defs examples.def -svg_dtd ../svg.dtd

You should see the following output :

    Parsing file examples.def
    Parsing file links.grp
    Creating SVG document
    Generating SVG file links.svg

The graphic looks like that :