wiki:rp_xml_ele_sequence
Last modified 13 months ago Last modified on 06/15/13 03:22:05

<sequence>

A sequence object represents a series of results that evolve with time or some other parameter. In the simplest case, you can wrap a series of <image> elements in a sequence, and the user can play the sequence like a movie. Right now, sequences are used only for output.

  <sequence id="movie">
    <about>
      <label>Animated sequence</label>
    </about>
    <index>
      <label>Frame</label>
    </index>
    <element id="0">
      <index>1</index>
      <image>
        <current>/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwc
        ...
        </current>
      </image>
    </element>
    <element id="1">
      <index>2</index>
      <image>
        <current>/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwc
      </image>
    </element>
    ...
  </sequence>
  ...

Each sequence contains a series of elements, each with an index and a value. The label of the index is set once, at the same level as the <about> section. The label for each index is set just inside each <element>. Note that the various elements will appear in the order associated with their <index> value. The index does not have to be an integer; it can be a real number or any arbitrary string. If one or more of the items is not recognized as a real or an integer, then all indices are treated as strings and ordered according to a dictionary sort. See below for instructions on including units in index values.

The actual value within each element can be an <image>, a <curve>, a <field>, etc. (Right now, only a few cases are supported. In time, all output types will be handled properly within a sequence.)

<index> with Units

If you want to include units in your <index> values, then be sure to declare the units in the <index> section at the topmost level of the <sequence>. For example, here is a sequence where the values are in picoseconds:

  <sequence id="movie">
    <about>
      <label>Animated sequence</label>
    </about>
    <index>
      <label>Time</label>
      <units>ps</units>
    </index>
    <element id="0">
      <index>0.05</index>
      <image>
        <current>/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwc
        ...
        </current>
      </image>
    </element>
    <element id="1">
      <index>40fs</index>
      <image>
        <current>/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwc
      </image>
    </element>
    ...
  </sequence>
  ...

In this example, the <units>ps</units> declares the default units for all index values. Therefore, the index "0.05" for element 0 is interpreted as "0.05ps". Note that element 1 has a value 40fs, which will put it before 0.05ps in the sequence order.

If you forget to declare the <units> for an index, then the individual <index> values won't pass the test of being real numbers, and the elements will be sorted in dictionary order as if they were ordinary string values. This may put them in a rather strange order.

You can see working code in the zoo of examples in the sequence example or on the hub in the directory /apps/rappture/examples/zoo/sequence.