## SVG input mode

In the SVG input mode, SVG interaction is used. It allows SVG images that are used for SVG visualization to be used to interactively control the simulation. Since the SVG images are reused, using the SVG input mode requires the use of SVG visualization. If the CIF specification contains CIF/SVG input mappings, and SVG input mode is not used, the simulator simply ignores the input mappings.

This page explains the use of the SVG input mode of the CIF simulator at runtime (during simulation).

### How it works

During simulation, as long as none of the interactive SVG elements (the SVG elements for which an input mapping exists) are clicked, the corresponding events or updates are never executed. For the other events (the non-interactive events), a choice is made using the automatic input component. The automatic input component makes a choice based on its own settings.

#### Hovering

When moving over one of the interactive SVG elements of the SVG visualization, using the mouse pointer, the border of the SVG element is highlighted in red. This makes it easier to identify the interactive SVG elements in the SVG visualizer. When an interactive SVG element is clicked, the color is changed from red to green, for as long as the mouse button is not released.

#### Clicking

The mouse click (and not the release) makes that the input component will interrupt any time transition that is currently being taken by the simulator. Then, when asked to choose a next transition, it will apply the input mapping for the interactive SVG element that was clicked. The event or update that results from the input mapping is then chosen. If the event is not enabled at that time, no transition is taken and a warning is printed to the console. To prevent such situations, you can use a monitor automaton. If multiple transitions are possible for an event, the choice (between the transitions for that event only) is deferred to the automatic input component, which makes a choice based on its own settings. Note that multiple transitions are only possible if complete mode is enabled.

#### Queue

The SVG input mode allows interactively choosing certain events by clicking on interactive elements of an SVG image. The SVG input mode is however not officially an interactive input mode.

The image plays the part of the environment. Whenever an interactive element is clicked, the element is added to a queue. If a user quickly clicks the same element multiple times, or quickly clicks different elements, they are all stored in the queue, and the queue can grow. The transition to take is automatically chosen, based on the queue of events. If the queue is empty, the environment (the SVG image and the user) doesn’t allow the interactive events. If the queue is not empty, the environment allows exactly one interactive event, the one at the head of the queue. The model, together with the queue, form a closed model, without further interaction. Each interactive SVG element that is clicked, will be used in the order they were clicked, to choose transitions.

The SVG input mode internally acts as an automated input mode, that makes choices about which transitions to take, without further user interaction. Since no further user interaction is possible, undo and reset are also not supported.

### Debugging

The console debugging output for CIF/SVG mappings includes debugging output for SVG input mappings. Input mappings that encounter runtime errors have stack traces similar to those of output mappings.

### Responsiveness

SVG input is usually combined with real-time simulation. Clicking an interactive SVG element results in the application of an input mapping, which results in an event or update. That mapping is put in the queue. If a time transition is being taken by the simulator, the simulator will continue to take that time transition until the input component interrupts it. However, an input component can only interrupt a time transition during intermediate frames. As such, choosing a low frame rate (typically less than 10 frames per second) can significantly reduce the responsiveness of the SVG input.

Hovering interactive SVG elements highlights their borders in red. This too becomes less responsive when a low frame rate is used.

### Interactive groups

It is possible to make a group of SVG elements (an `svg:g` element) an interactive element. By doing so, all the elements that are part of the group together become one single interactive element.

One practical example where this is very useful, is for buttons with a text label. In SVG, this requires the use of a rectangle and a text label. To ensure that clicking either one of them results in the same event, group the rectangle and text label together in a group. Then assign an id to the group and use that id in an input mapping. During simulation, when hovering over either the rectangle or the text label, both will be highlighted. Clicking on either of them results in the corresponding input mapping being applied, and the resulting event or update being chosen by the SVG input component.

In general, if an SVG image is clicked, the simulator will figure out on which graphical element the user clicked. If that element is itself an interactive SVG element, then the corresponding mapping is applied. If it is not an interactive SVG element, its parent (which may be a group) is checked. If the parent is not an interactive SVG element either, the parent of the parent is checked, etc. If none of the ancestors is an interactive SVG element, clicking the element has no effect on the simulation. Because of this behavior, it is strongly recommended not to make a child (or descendant in general) of an interactive SVG element interactive as well.