The intermediary document : Boxes structure (spring)

1. Definition

A spring is an element that is able to stretch on a single axis. It must be placed in a non-final box (hbox or vbox).

You can specify attributes for a tag spring. Here are the different attributes you can specify for a spring :

2. Example

To illustrate how springs work, save the following code under editor/XML/Examples/spring.grp :

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE grp SYSTEM "../grp.dtd">
    <grp>
      <vbox>
        <hbox>
          <spring minSize="10"/>
          <tbox fontSize="30" fontStyle="italic">Hello</tbox>
          <spring minSize="40"/>
        </hbox>

        <spring minSize="10"/>

        <hbox>
          <spring/>
          <tbox fontSize="30" fontStyle="italic">world</tbox>
          <spring/>
        </hbox>

        <spring minSize="10"/>

        <hbox>
          <spring/>
          <tbox fontSize="30" fontStyle="italic">!</tbox>
          <spring maxSize="10"/>
        </hbox>
      </vbox>
    </grp>
  

We will use the same definitions document than previously. 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 spring.grp -defs examples.def -svg_dtd ../svg.dtd
  

You should see the following output :

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

The SVG looks like this :

Hard to see how springs acted. To show it more clearly, transform the document with the -debug parameter :

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

Now we can see springs :

3. Example explained

The outermost vbox contains 3 hbox. These boxes are separated by 2 spring with a minSize set to 10. There is no special constraint on the vbox that contains them, so their size (in this case a height) is 10.

Each hbox in this vbox must have the same width. This is where act springs they contain.

The first hbox contains 2 spring that have respectivly a minSize set to 10 and 40. The width of the tbox contained by the hbox is 80 wide. Where does this information come ? From the window shown in debug mode :

So the width of this hbox, depending of its content, is 130.

The same way, we can determine that the width of the second hbox is 84, and the third hbox's is 18.

The first hbox is the widest, so the second and the third have to grow to be 130 wide too. The growth of the box will be operated via the springs it contains and the springs of the boxes it contains.

The second hbox's 2 springs will both grow evenly so that the tbox is centered.

The third hbox's 2 springs won't grow the same way as the second one has a maxSize of 10. So the second spring will grow up to 10, and the first one will fill the remaining gap.

3. Test

A question certainly came up in your mind : what happens if one of the 3 hbox has no spring or has some but with maxSize too small so that they can't stretch enough for the hbox to grow to 130 wide ? Let's try this.

Modify the code by adding the maxSize attribute to the first spring of the third hbox :

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE grp SYSTEM "../grp.dtd">
    <grp>
      <vbox>
        <hbox>
          <spring minSize="10"/>
          <tbox fontSize="30" fontStyle="italic">Hello</tbox>
          <spring minSize="40"/>
        </hbox>

        <spring minSize="10"/>

        <hbox>
          <spring/>
          <tbox fontSize="30" fontStyle="italic">world</tbox>
          <spring/>
        </hbox>

        <spring minSize="10"/>

        <hbox>
          <spring maxSize="10"/>
          <tbox fontSize="30" fontStyle="italic">!</tbox>
          <spring maxSize="10"/>
        </hbox>
      </vbox>
    </grp>
  

Generate the SVG in debug mode :

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

The following output appears :

    Parsing file examples.def
    Parsing file spring.grp
    Warning: vertical box whose id is '' contains 2 boxes with different width (38.0 & 130.0)
    Creating SVG document
    Generating SVG file spring.svg
  

You got 1 warning. We won't detail now its meaning. It tells you that something is wrong with your boxes structure. In this case, this is about the vertical box : the 2 first hbox are 130 wide, and the third, only 38, but the boxes contained by a vbox must all have the same width. This is obviously not the case.

We will come back on warnings and their meaning later.

As you got warning the SVG graphic is probably incorrect, but has nonetheless be generated, and looks like this :