CIF/SVG input mappings

CIF/SVG input mappings couple ids of SVG elements to events or updates in the CIF specification. CIF/SVG input mappings are CIF/SVG declarations, similar to CIF/SVG output mappings. If the CIF specification contains input mappings, and SVG input mode is not used, the input mappings are simply ignored.

Single event input mapping

The simplest form of an SVG input mapping maps to a single event. For instance:

svgin id "button" event machine.button.toggle;

This input mapping maps the SVG element with id button to the machine.button.toggle event from the CIF specification.

Every input mapping must specify the id of an SVG element, and an SVG element with that id must exist in the SVG image. Specifying an input mapping for an SVG element turns that SVG element into an interactive SVG element. Note that groups may be used as interactive SVG elements as well.

if event input mapping

Sometimes, the simple single event input mapping is not enough. Consider for instance the following CIF specification:

automaton button:
  event u_pushed, u_released;

  location Released:
    initial;
    edge u_pushed goto Pushed;

  location Pushed:
    edge u_released goto Released;
end

This specification models a button that is initially released (location Released). When the button is pushed (event u_pushed), the location is updated to Pushed. If we now want to couple a graphical representation of a button to this CIF specification, the event to choose depends on the current location of the button automaton. This can be mapped using an if event input mapping, as follows:

svgin id "button" event
  if   button.Released: button.u_pushed
  elif button.Pushed:   button.u_released
  end;

If the button is released, the u_pushed event is chosen, and if the button is pushed, the u_released event is chosen.

The if event input mappings are essentially an if expressions that result in an event rather than a value. The conditions (such as button.Released are guard expressions that evaluates to a boolean value. The guard expressions may be arbitrary expressions, similar to the use of expressions in output mappings.

If a condition holds, the corresponding event is chosen. The entries are processed in the order they are specified: if the first guard (of the if) holds, the first event is chosen, otherwise if the second guard (of an elif) holds, the second event is chosen, etc.

The last part of the if is allowed to be an else, to indicate that if none of the previous guards hold, the event of the else is to be chosen. Using an else entry is optional, but if used, there may only be one such entry, and it must be the last entry of the input mapping.

Update input mapping

SVG input mappings with updates are currently an experimental work-in-progress language feature. Their design may change in a backward incompatible manner.

With SVG input mappings the values of input variables can be updated. For instance:

input int counter;

svgin id "increase" do counter := counter + 1;
svgin id "decrease" do counter := counter - 1;

In this example, by clicking the SVG element with id increase the value of counter is increased by one. Similarly, clicking the SVG element with id decrease decreases the value of counter by one.

Be aware that the initial value of an input variable cannot be set in the specification. Instead, the initial value must be set via the initialization option of the simulator.

Uniqueness

Similar to output mappings, all input mappings must be unique, per SVG image. That is, no two input mappings for the same SVG image may use the same SVG element id. Note that it is allowed to have an input mapping and an output mapping (or even multiple output mappings) for the same SVG element.

Completeness

Input mappings for events must be complete. Single event input mappings are always complete, as are if event input mappings with an else, and update input mappings. For if event input mappings without an else, at least one of the guards must hold. If none of the guards holds, the mapping results in a runtime error during simulation.