Interactivity

Introduction

SVG content can be interactive (i.e., responsive to user-initiated events) by utilizing the following features in the SVG language:

• User-initiated actions such as button presses on the pointing device (e.g., a mouse) can cause animations or scripts to execute.
• The user can initiate hyperlinks to new Web pages (see Links out of SVG content: the 'a' element) by actions such as mouse clicks when the pointing device is positioned over particular graphics elements.
• In many cases, depending on the value of the 'zoomAndPan' attribute on the 'svg' element and on the characteristics of the user agent, users are able to zoom into and pan around SVG content.
• User movements of the pointing device can cause changes to the cursor that shows the current position of the pointing device.

This chapter describes:

• information about events, including under which circumstances events are triggered
• how to indicate whether a given document can be zoomed and panned
• how to specify which cursors to use

Related information can be found in other chapters:

• hyperlinks are discussed in Links
• scripting and event attributes are discussed in Scripting
• SVG's relationship to DOM2 events is discussed in Relationship with DOM2 event model
• animation is discussed in Animation

Complete list of supported events

The following aspects of SVG are affected by events:

• Using SVG Document Object Model (DOM), a script can register DOM 2 event listeners ([DOM2EVENTS], section 1.3) so that script can be invoked when a given event occurs.
• SVG includes event attributes on selected elements which define script that can be executed when a given event occurs in association with the given element.
• SVG's animation elements can be defined to begin or end based on events.

The following table lists all of the events which are recognized and supported in SVG. The Event name in the first column is the name to use within SVG's animation elements to define the events which can start or end animations. The DOM2 name in the second column is the name to use when defining DOM 2 event listeners ([DOM2EVENTS], section 1.3). The Event attribute name in the fourth column contains the corresponding name of the event attributes that can be attached to elements in the SVG language.

Requirements in the table on whether an event of a given type bubbles or is cancelable apply only to events that are created and dispatched by the user agent. Events of those types created from script using the createEvent method on the DocumentEvent interface can be made to bubble or be cancelable with the initEvent method.

As in DOM 2 Key events ([DOM2EVENTS], section 1.6.3), the SVG specification does not provide a key event set. An event set designed for use with keyboard input devices will be included in a later version of the DOM and SVG specifications.

Details on the parameters passed to event listeners for the event types from DOM2 can be found in the DOM2 specification. For other event types, the parameters passed to event listeners are described elsewhere in this specification.

Event listener attributes can be specified on some elements to listen to a given event. The script in such attributes is run only in response to "bubbling" and "at target" phase events dispatched to the element.

Likewise, event-value timing specifiers used in animation element 'animate/begin' and 'animate/end' attributes are resolved to concrete times only in response to "bubbling" and "at target" phase events dispatched to the relevant element.

User interface events

On user agents which support interactivity, it is common for authors to define SVG documents such that they are responsive to user interface events. Among the set of possible user events are pointer events, keyboard events, and document events.

In response to user interface (UI) events, the author might start an animation, perform a hyperlink to another Web page, highlight part of the document (e.g., change the color of the graphics elements which are under the pointer), initiate a "roll-over" (e.g., cause some previously hidden graphics elements to appear near the pointer) or launch a script which communicates with a remote database.

Pointer events

User interface events that occur because of user actions performed on a pointer device are called pointer events.

Many systems support pointer devices such as a mouse or trackball. On systems which use a mouse, pointer events consist of actions such as mouse movements and mouse clicks. On systems with a different pointer device, the pointing device often emulates the behavior of the mouse by providing a mechanism for equivalent user actions, such as a button to press which is equivalent to a mouse click.

For each pointer event, the SVG user agent determines the target element of a given pointer event. The target element is the topmost graphics element whose relevant graphical content is under the pointer at the time of the event. (See property 'pointer-events' for a description of how to determine whether an element's relevant graphical content is under the pointer, and thus in which circumstances that graphic element can be the target element for a pointer event.) When an element is not displayed (i.e., when the 'display' property on that element or one of its ancestors has a value of none), that element cannot be the target of pointer events.

If a target element for the pointer event exists, then the event is dispatched to that element according to the normal event flow ([DOM2EVENTS], section 1.2). Note, however, that if the target element is in a 'use' element shadow tree, that the event flow will include SVGElementInstance objects. See The 'use' element for details.

If a target element for the pointer event does not exist, then the event is ignored.

Hit-testing and processing order for user interface events

There are two distinct aspects of pointer-device interaction with an element or area:

1. hit-testing, to determine if a pointer event (such as a mouse movement or mouse click) occurred within the interaction area of an element, and the subsequent DOM event flow;
2. functional processing of actions associated with any relevant element.

Hit-testing

Determining whether a pointer event results in a positive hit-test depends upon the position of the pointer, the size and shape of the graphics element, and the computed value of the 'pointer-events' property on the element. The definition of the 'pointer-events' property below describes the exact region that is sensitive to pointer events for a given type of graphics element.

Note that the 'svg' element is not a graphics element, and in a Conforming SVG Stand-Alone File a rootmost 'svg' element will never be the target of pointer events, though events can bubble to this element. If a pointer event does not result in a positive hit-test on a graphics element, then it should evoke any user-agent-specific window behavior, such as a presenting a context menu or controls to allow zooming and panning of an SVG document fragment.

This specification does not define the behavior of pointer events on the rootmost 'svg' element for SVG images which are embedded by reference or inclusion within another document, e.g., whether the rootmost 'svg' element embedded in an HTML document intercepts mouse click events; future specifications may define this behavior, but for the purpose of this specification, the behavior is implementation-specific.

Event processing

An element which is the target of a user interface event may have particular interaction behaviors, depending upon the type of element and whether it has explicit associated interactions, such as scripted event listeners, CSS pseudo-classes matches, or declarative animations with event-based timing. The algorithm and order for processing user interface events for a given target element, after dispatching the DOM event, is as follows:

1. If an event handler registered on this element invokes the preventDefault() DOM method, then no further processing for this element is performed, and the event follows the event flow processing as described in DOM Level 2 Events [DOM2EVENTS] (or its successor);
2. If the element has an associated title or description, such as a 'title element' element or an 'xlink:title' attribute, and the user agent supports the display of such information (e.g. via a tooltip or status-bar message), that information should be displayed, as appropriate to the type of pointer event;
3. If the element matches any relevant dynamic pseudo-class selectors appropriate to the type of pointer event, such as :hover, :active, or :focus as described in [CSS2], section 5.11, then the relevant class properties are applied;
4. If the element and the event type are associated with the activation or cancelation of declarative animation though the use of event-value timing specifiers, any corresponding instance times must be resolved, and any conseqential actions of this instance time resolution (such as immediately starting or stopping the animation) must be performed;
5. If the element is a hyperlink (e.g., it is a descendant element of an 'a' element), and the pointer event is of a type that activates that hyperlink (e.g. via a mouse click), and if the hyperlink traversal changes the context of the content (e.g. opens a different document, or moves the pointer away from this element by moving to another part of the same document), then no further processing for this element is performed;
6. If the element is a text content element, and the event type is one which the user agent recognizes as part of a text-selection operation (e.g., a mouse click and drag, or a double-click), then the text selection algorithm is performed;
7. If the event type is one which the user agent associates with the evocation of special user-interface controls (e.g., a right-click or command-click evoking a context menu), the user agent should evoke such user-agent-specific behavior, such as presenting a context menu or controls to allow zooming and panning of an SVG document fragment.

The 'pointer-events' property

In different circumstances, authors may want to control under what conditions particular graphic elements can become the target of pointer events. For example, the author might want a given element to receive pointer events only when the pointer is over the stroked perimeter of a given shape. In other cases, the author might want a given element to ignore pointer events under all circumstances so that graphical elements underneath the given element will become the target of pointer events.

The effects of masking and clipping differ with respect to pointer-events. A clip path is a geometric boundary, and a given point is clearly either inside or outside that boundary; thus, pointer events must be captured normally over the rendered areas of a clipped element, but must not be captured over the clipped areas, as described in the definition of clipping paths. By contrast, a mask is not a binary transition, but a pixel operation, and different behavior for fully transparent and almost-but-not-fully-transparent may be confusingly arbitrary; as a consequence, for elements with a mask applied, pointer-events must still be captured even in areas where the mask goes to zero opacity. If an author wishes to achieve an effect where the transparent parts of a mask allow pointer-events to pass to an element below, a combination of masking and clipping may be used.

The 'filter property' property has no effect on pointer-events processing, and must in this context be treated as if the 'filter property' wasn't specified.

For example, suppose a circle with a 'stroke' of red (i.e., the outline is solid red) and a 'fill' of none (i.e., the interior is not painted) is rendered directly on top of a rectangle with a 'fill' of blue. The author might want the circle to be the target of pointer events only when the pointer is over the perimeter of the circle. When the pointer is over the interior of the circle, the author might want the underlying rectangle to be the target element of pointer events.

The 'pointer-events' property specifies under what circumstances a given graphics element can be the target element for a pointer event. It affects the circumstances under which the following are processed:

• user interface events such as mouse clicks
• dynamic pseudo-classes (i.e., :hover, :active and :focus; [CSS2], section 5.11)
• hyperlinks (see Links out of SVG content: the 'a' element)

visiblePainted

The given element can be the target element for pointer events when the 'visibility' property is set to visible and when the pointer is over a "painted" area. The pointer is over a painted area if it is over the interior (i.e., fill) of the element and the 'fill' property has an actual value other than none or it is over the perimeter (i.e., stroke) of the element and the 'stroke' property is set to a value other than none.

visibleFill

The given element can be the target element for pointer events when the 'visibility' property is set to visible and when the pointer is over the interior (i.e., fill) of the element. The value of the 'fill' property does not affect event processing.

visibleStroke

The given element can be the target element for pointer events when the 'visibility' property is set to visible and when the pointer is over the perimeter (i.e., stroke) of the element. The value of the 'stroke' property does not affect event processing.

visible

The given element can be the target element for pointer events when the 'visibility' property is set to visible and the pointer is over either the interior (i.e., fill) or the perimeter (i.e., stroke) of the element. The values of the 'fill' and 'stroke' do not affect event processing.

painted

The given element can be the target element for pointer events when the pointer is over a "painted" area. The pointer is over a painted area if it is over the interior (i.e., fill) of the element and the 'fill' property has an actual value other than none or it is over the perimeter (i.e., stroke) of the element and the 'stroke' property has an actual value other than none. The value of the 'visibility' property does not effect event processing.

fill

The given element can be the target element for pointer events when the pointer is over the interior (i.e., fill) of the element. The values of the 'fill' and 'visibility' properties do not affect event processing.

stroke

The given element can be the target element for pointer events when the pointer is over the perimeter (i.e., stroke) of the element. The values of the 'stroke' and 'visibility' properties do not affect event processing.

all

The given element can be the target element for pointer events whenever the pointer is over either the interior (i.e., fill) or the perimeter (i.e., stroke) of the element. The values of the 'fill', 'stroke' and 'visibility' properties do not affect event processing.

none

The given element does not receive pointer events.

For text elements, hit-testing is performed on a character cell basis:

• The value visiblePainted means that the text string can receive events anywhere within the character cell if either the 'fill' property is set to a value other than none or the 'stroke' property is set to a value other than none, with the additional requirement that the 'visibility' property is set to visible.
• The values visibleFill, visibleStroke and visible are equivalent and indicate that the text string can receive events anywhere within the character cell if the 'visibility' property is set to visible. The values of the 'fill' and 'stroke' properties do not affect event processing.
• The value painted means that the text string can receive events anywhere within the character cell if either the 'fill' property is set to a value other than none or the 'stroke' property is set to a value other than none. The value of the 'visibility' property does not affect event processing.
• The values fill, stroke and all are equivalent and indicate that the text string can receive events anywhere within the character cell. The values of the 'fill', 'stroke' and 'visibility' properties do not affect event processing.
• The value none indicates that the given text does not receive pointer events.

For raster images, hit-testing is either performed on a whole-image basis (i.e., the rectangular area for the image is one of the determinants for whether the image receives the event) or on a per-pixel basis (i.e., the alpha values for pixels under the pointer help determine whether the image receives the event):

• The value visiblePainted means that the raster image can receive events anywhere within the bounds of the image if any pixel from the raster image which is under the pointer is not fully transparent, with the additional requirement that the 'visibility' property is set to visible.
• The values visibleFill, visibleStroke and visible are equivalent and indicate that the image can receive events anywhere within the rectangular area for the image if the 'visibility' property is set to visible.
• The value painted means that the raster image can receive events anywhere within the bounds of the image if any pixel from the raster image which is under the pointer is not fully transparent. The value of the 'visibility' property does not affect event processing.
• The values fill, stroke and all are equivalent and indicate that the image can receive events anywhere within the rectangular area for the image. The value of the 'visibility' property does not affect event processing.
• The value none indicates that the image does not receive pointer events.

Note that for raster images, the values of properties 'opacity', 'fill-opacity', 'stroke-opacity', 'fill' and 'stroke' do not affect event processing.

Magnification and panning

Magnification represents a complete, uniform transformation on an SVG document fragment, where the magnify operation scales all graphical elements by the same amount. A magnify operation has the effect of a supplemental scale and translate transformation placed at the outermost level on the SVG document fragment (i.e., outside the outermost svg element).

Panning represents a translation (i.e., a shift) transformation on an SVG document fragment in response to a user interface action.

SVG user agents that operate in interaction-capable user environments are required to support the ability to magnify and pan.

The outermost svg element in an SVG document fragment has attribute 'svg/zoomAndPan', which takes the possible values of disable and magnify, with the default being magnify.

If disable, the user agent shall disable any magnification and panning controls and not allow the user to magnify or pan on the given document fragment.

If magnify, in environments that support user interactivity, the user agent shall provide controls to allow the user to perform a "magnify" operation on the document fragment.

If a 'svg/zoomAndPan' attribute is assigned to an inner 'svg' element, the 'svg/zoomAndPan' setting on the inner 'svg' element will have no effect on the SVG user agent.

Animatable: no.

Cursors

Introduction to cursors

Some interactive display environments provide the ability to modify the appearance of the pointer, which is also known as the cursor. Three types of cursors are available:

• Standard built-in cursors
• Platform-specific custom cursors
• Platform-independent custom cursors

The 'cursor property' property is used to specify which cursor to use. The 'cursor property' property can be used to reference standard built-in cursors by specifying a keyword such as crosshair or a custom cursor. Custom cursors are referenced via a <funciri> and can point to either an external resource such as a platform-specific cursor file or to a 'cursor element' element, which can be used to define a platform-independent cursor.

The 'cursor' property

This property specifies the type of cursor to be displayed for the pointing device. Values have the following meanings:

auto

The UA determines the cursor to display based on the current context.

crosshair

A simple crosshair (e.g., short line segments resembling a "+" sign).

default

The platform-dependent default cursor. Often rendered as an arrow.

pointer

The cursor is a pointer that indicates a link.

move

Indicates something is to be moved.

e-resize, ne-resize, nw-resize, n-resize, se-resize, sw-resize, s-resize, w-resize

Indicate that some edge is to be moved. For example, the 'se-resize' cursor is used when the movement starts from the south-east corner of the box.

text

Indicates text that can be selected. Often rendered as an I-bar.

wait

Indicates that the program is busy. Often rendered as a watch or hourglass.

help

Help is available for the object under the cursor. Often rendered as a question mark or a balloon.

<funciri>

The user agent retrieves the cursor from the resource designated by the URI. If the user agent cannot handle the first cursor of a list of cursors, it shall attempt to handle the second, etc. If the user agent cannot handle any user-defined cursor, it must use the generic cursor at the end of the list.

P { cursor : url("mything.cur"), url("second.svg#curs"), text; }

The 'cursor property' property for SVG is identical to the 'cursor' property defined in CSS2 ([CSS2], section 18.1), with the additional requirement that SVG user agents must support cursors defined by the SVG 'cursor element' element. This gives a single, cross-platform, interoperable cursor format, with PNG as the raster component.

The 'cursor' element

DOM interfaces

Interface SVGCursorElement