## 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 mouse pointer is changed and the outline 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 outline color is changed from red to green, for as long as the mouse button is not released.

The style for the outline of interactive elements can be changed using the SVG input outline style option (in the Input category). Specify `off` to not show any outline. Specify a hover color, click color and stroke width, separated by colons, to specify a specific style. For colors, there are two ways to specify them. The first way to specify a color is to use one of the named colors: `black`, `blue`, `cyan`, `dark-gray`, `gray`, `green`, `light-gray`, `magenta`, `orange`, `pink`, `red`, `white`, or `yellow`. The second way to specify a color is to indicate an RGB color, by specifying comma-separated red, green and blue components, each in range [0..255]. For the stroke width, specify the width in pixels as a positive floating point number. Note that if the element that gets an outline is scaled differently in the x and y directions, the stroke width may not be accurate. Some examples of valid option values are: `blue:magenta:2.0`, `255,0,128:black:0.5`. The default value is `red:green:1.5`.

The outlines, if not disabled using the SVG input outline style option (using its `off` value), can be selectively disabled for certain interactive SVG elements, using the SVG input outline filters option (in the Input category). By default, all interactive SVG elements get an outline when hovering or clicking them. By specifying filters, you can change the default. For this option, specify comma-separated node names of SVG elements for which to show the outline. Note that you must specify node names of the elements, as specified in the SVG standard. So, not the ids of the elements that you can specify yourself. For example, use option value `circle,rect,text` to only show outlines for circles, rectangles and texts. You can use `*` in a filter to match zero or more characters of an element name. Prefix a filter with `-` to exclude elements with matching node names, rather than including them. Initially, before applying any filters, all elements get an outline, as if `*,` if prefixed to the filters. The filters are applied in the order they are specified. As an example, specify `*,-text` or simply `-text`, to give all interactive elements an outline, except for SVG `text` elements.

Disabling the outline does exactly only that: it prevents the outlines from being shown. It does not prevent the mouse pointer from being changed. Also, interactive elements can still can be clicked and this will still have the same effect.

See the section on interactive groups for how hovering and outlines work for groups and elements of groups.

#### 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. Therefore, it is a semi-interactive input mode, as interactive inputs are combined with automatic behavior.

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 interactive elements. If the queue is empty, the environment (the SVG image and the user) doesn’t allow the associated interactive events. If the queue is not empty, the environment allows exactly one interactive event, the one matching 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.

### Reset the simulation

The simulation can be reset to its initial state. To do this, right-click on the SVG image and select Reset simulation.

Note that if the simulation has already terminated, it cannot be reset. A reset in the initial state is delayed until at least one other transition has taken place.

Unlike some other input modes, the SVG input mode does not provide a button or mechanism to undo a previously chosen transition.

### Debugging

The console debugging output for CIF/SVG declarations 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.

The Reset simulation menu item behaves like a queued click. It is processed by the simulator only when an intermediate frame allows the interruption of the current time transition, so its effect may be delayed if the frame rate is low.

Hovering interactive SVG elements highlights their borders, unless this is disabled. 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 or update, 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, by default 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.

By default, when hovering an interactive group, all its direct non-group descendants are highlighted. For example, if an interactive group contains a rectangle and a text label, both the rectangle and the text label are highlighted by default. If an interactive group contains two sub-groups and both these sub-groups contain two rectangles, then all four rectangles are highlighted by default. You can configure which elements get highlighted using the SVG input outline style option. For example, for an interactive group representing a button, consisting of a rectangle and a text label, you can specify `*,-text` (or simply `-text`) to highlight the rectangle, but the text label. For more information about this option, see the section about hovering and outlines.