Scripting and Interactivity — SVG 2 (original) (raw)

Chapter 15: Scripting and Interactivity

Contents

1. 1. 15.1. Introduction
   2. 15.2. Supported events
      1. 15.2.1. Relationship with UI Events
   3. 15.3. User interface events
   4. 15.4. Pointer events
   5. 15.5. Hit-testing and processing order for user interface events
      1. 15.5.1. Hit-testing
      2. 15.5.2. Event processing
   6. 15.6. The ‘pointer-events’ property
   7. 15.7. Magnification and panning
   8. 15.8. Focus
   9. 15.9. Event attributes
      1. 15.9.1. Animation event attributes
   10. 15.10. The ‘script’ element
   11. 15.11. DOM interfaces
       1. 15.11.1. Interface SVGScriptElement

15.1. 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 (seeLinks 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.

This chapter describes:

• information about events, including under which circumstances events are triggered
• how to indicate whether a given document can bezoomed and panned

Related information can be found in other chapters:

• hyperlinks are discussed in Links
• animation is discussed in Animating SVG Documents

15.2. Supported events

The following aspects of SVG are affected by events:

• Using SVG Document Object Model (DOM), a script canadd or remove DOM event listeners ([DOM]) so that script can be invoked or ignored when a given event occurs on an event target
• SVG's animation elements can be defined to begin or end based on events.

A number of events defined in SVG 1.1, SVGLoad,SVGError etc, have been replaced with the equivalent unprefixed events defined in UI EVENTSand HTML.

There should be some more modern examples of using events in svg, e.g touch events (w reference to touch events spec).Device orientation events might also be of interest.

The following table lists the events defined by this specification, or that have further requirements or clarifications compared to the specification(s) where they are defined.

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_UI Event name_ in the second column is the name to use when defining DOM event listeners([DOM], section 3.6).

For events not listed in the table, such as events introduced in HTML or UI Events, the respective event type is the name to use within SVG's animation elements.

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 Document interface can be made to bubble or be cancelable with theinitEventmethod.

Details on the parameters passed to event listeners for the event types for UI Events can be found in the ([uievents]) and ([DOM]) specifications. For other event types, the parameters passed to event listeners are described elsewhere in this specification.

Likewise, event-value timing specifiersused in animation element ‘begin’ and ‘end’attributes are resolved to concrete times only in response to "bubbling" and "at target" phase events dispatched to the relevant element.

15.2.1. Relationship with UI Events

The SVG DOM is compatible with all interfaces defined in, and all the event types from,UI Events, and the event types defined inClipboard API and events([uievents], [clipboard-apis]).

All elements in the SVG namespace supportevent attributes for these events; matching IDL properties are included in the base SVGElement interface via the GlobalEventHandlers andDocumentAndElementEventHandlers mixins, respectively.

As part of SVG DOM support, conforming SVG software must support all (non-deprecated, non-obsolete) event types defined in these specifications, if the relevant events could occur in the software's use. SVG software that does not support user interactionshould nonetheless implement support for events that can fire without interaction, such as load and error events.

SVG animation elements (defined in the SVG Animations Level 2 specification) support additional events and event attributes. The following event types are triggered due to state changes in animations.

• beginEvent
• endEvent
• repeatEvent

The event attributes for these animation events have no effect on other elements.

15.3. 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.

15.4. 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 thedisplay 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([uievents], section 3.1). For shadow trees created by the ‘use’ element or via script, the event must followDispatching Events [dom]

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

15.5. Hit-testing and processing order for user interface events

hit-testing

The process of determining whether a pointer intersects a givengraphics element. Hit-testing is used in determining which element to dispatch a mouse event to, which might be done in response to the user moving the pointing device, or by changes in the position, shape and other attributes of elements in the document. Hit-testing is also known as hit detection or picking. See also the definition of thepointer-events property.

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.

15.5.1. Hit-testing

Determining whether a pointer event results in a positive hit-testdepends upon the position of the pointer, the size and shape of thegraphics element, and the computed value of the pointer-eventsproperty on the element. The definition of the pointer-eventsproperty 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 Filea outermost 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 agraphics 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 theoutermost svg element for SVG images which are embedded by reference or inclusion within another document, e.g., whether the outermost svg elementembedded 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.

15.5.2. 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 dispatch and DOM event flow processing ([uievents]);
2. If the element has an associated title or description, such as a ‘title’ element, 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 relevantdynamic 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 ofevent-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 thetext 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.

15.6. 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 topointer 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 has no effect on pointer events processing, and must in this context be treated as if the filterwasn't specified.

For example, suppose a circle with a stroke ofred (i.e., the outline is solid red) and afill of none (i.e., the interior is not painted) is rendered directly on top of a rectangle with a fill ofblue. 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 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)

bounding-box

The given element must be a target element for pointer events when the pointer is over the bounding box of the element.

visiblePainted

The given element can be the target element for pointer events when the visibility property is set tovisible 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 thevisibility 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 thevisibility 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 thevisibility 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 andstroke 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 thannone 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 thevisibility property does not affect 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 thannone or the stroke property is set to a value other than none, with the additional requirement that the visibility property is set tovisible.
• The values visibleFill,visibleStroke andvisible are equivalent and indicate that the text string can receive events anywhere within the character cell if thevisibility 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 thannone or the stroke property is set to a value other than none. The value of thevisibility 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 andvisible are equivalent and indicate that the image can receive events anywhere within the rectangular area for the image if the visibility property is set tovisible.
• 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 andstroke do not affect event processing.

15.7. 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 elementin an SVG document fragment has attribute ‘zoomAndPan’, which takes the possible values of disable and magnify, with the default being magnify.

The zoomAndPan attribute is at risk, it has no known implementations and is unlikely to be implemented. SeeGithub issue #56.

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 ‘zoomAndPan’ attribute is assigned to an inner ‘svg’element, the ‘zoomAndPan’ setting on the inner ‘svg’ element will have no effect on the SVG user agent.

15.8. Focus

SVG uses the same focus model as HTML, modified for SVG as described in this section. At most one element in each document is focused at a time; if the document as a whole has system focus, this element becomes the target of all keyboard events.

When an element is focused, the element matches the CSS :focus pseudo-class. Interactive user agents must visually indicate focus (usually with an outline) when the focus changes because of a user input event from the keyboard or other non-pointing device and may indicate focus at all times. Authors may use the :focus pseudo-class to replace the visual indication with one more suitable to the graphic, (such as a stroke on a shape) but should not use it to remove visual indications of focus completely.

The following SVG elements are focusable in an interactive document. Any instance of such an element in a use-element shadow tree is also focusable. For the purpose of the HTML focus model, interactive user agents must treat them asfocusable areas whose tabindex focus flag should be set:

• the document root element
• an ‘svg’ element which has zoom and pan controls
• any element (such as within a ‘foreignObject’) that generates a scrollable region
• ‘iframe’ elements that are browsing context containers
• ‘audio’ and ‘video’ elements with user controls
• any directly rendered element with a valid integer ‘tabindex’ attribute

In the case of user-agent supplied controls, the element may have more than one focusable area, for each sub-control.

In addition, all ‘a’ elements that are valid links are focusable, and their tabindex focus flag must be set_unless_ the user agent normally provides an alternative method of keyboard traversal of links.

For compatibility with content that used theSVG Tiny 1.2 focusable attribute, user agents should treat an element with a value oftrue for that attribute as focusable. In new content, authors should either omit the focusable attribute or use it only in combination with a correspondingtabindex value of 0.

User agents may treat other elements as focusable, particularly if keyboard interaction is the only or primary means of user input. In particular, user agents may support using keyboard focus to reveal ‘title’ element text as tooltips, and may allow focus to reach elements which have been assigned listeners for mouse, pointer, or focus events. Authors should not rely on this behavior; all interactive elements should directly support keyboard interaction.

The sequential focus order is generated from the set of all focusable elements, processing ‘tabindex’ attributes on SVG elements in the same way as tabindex attributes on HTML elements. Content within a use-element shadow tree is inserted in the focus order as if it was child content of the ‘use’ element.

A non-rendered element can never receive focus, regardless of the value of the ‘tabindex’ attribute, If a script programmatically assigns focus to a non-rendered or otherwise un-focusable element, the focusing call is aborted. Note, however, that an element that is not visible or onscreen may still be rendered.

When the user agent supports scrolling or panning of the SVG document, and focus moves to an element that is currently outside the SVG viewport, the user agent should scroll or pan the document until the focused element is within the SVG viewport.

As in HTML, an SVG element that is focusable but does not have a definedactivation behavior has an activation behaviour that does nothing (unless a script specifically responds to it).

This means that an element that is only focusable because of its ‘tabindex’ attribute will fire a click event in response to a non-mouse activation (e.g. hitting the "enter" key while the element has focus).

For documents that contain a mix of inline HTML and SVG, focus is handled for the document as a whole (with a combined sequential focus order), not with each inline SVG or HTML fragment as an isolated subdocument.

For example, in the following document, pressing Tab would cycle the focus between elements A, B and C, in that order.

First thing Third thing

Note that SVG elements do not have an equivalent of HTML'saccesskeyattribute.

15.9. Event attributes

event attribute

An event attribute always has a name that starts with "on" followed by the name of the event for which it is intended. It specifies some script to run when the event of the given type is dispatched to the element on which the attribute is specified.

For every event type that the user agent supports, SVG supports that as an event attribute, following the same requirements as for event handler content attributes [HTML]. The event attributes are available on all SVG elements.

The contents of event attributes are always interpreted as ECMAScript, as if processed with the media type 'application/ecmascript'. [rfc2046][rfc4329]

Event attributes are not animatable.

Implementors may view the setting of event attributes as the creation and registration of an EventListener on theEventTarget. Such event listeners are invoked only for the "bubbling" and "at target" phases, as if false were specified for the useCapture argument to addEventListener. This EventListener behaves in the same manner as any other which may be registered on the EventTarget.

If the attribute representing the event listener is changed, this may be viewed as the removal of the previously registeredEventListener and the registration of a new one. Futhermore, no specification is made as to the order in which event attributes will receive the event with regards to the other EventListeners on the EventTarget.

In ECMAScript, one way to establish an event listener is to define a function and pass that function to the addEventListener method:

function myAction1(evt) { // process the event } // ... later ... myElement.addEventListener("click", myAction1, false)

In ECMAScript, the character data content of anevent attribute becomes the definition of the ECMAScript function which gets invoked in response to the event. As with all registered ECMAScript event listener functions, this function receives an Event object as a parameter, and the name of the Event object isevt. For example, it is possible to write:

<rect onclick="MyClickHandler(evt)" .../>

which will pass the Event object evt into function MyClickHandler.

15.9.1. Animation event attributes

Below are the definitions for the animation event attributes. These can be specified on the animation elements.

Attribute definitions:

Specifies some script to execute when "bubbling" or "at target" phase listeners for the corresponding event are fired on the element the attribute is specified on. See supported events table to determine which event each of these event attributes corresponds to. There are no restrictions on the values of this attribute.

15.10. The ‘script’ element

A ‘script’ element is equivalent to the ‘script’ element in HTML and thus is the place for scripts (e.g., ECMAScript). Any functions defined within any ‘script’ element have a "global" scope across the entire current document.

The script's text content is never directly rendered; the display value for the ‘script’ element must always be set to none by the user agent style sheet, and this declaration must have importance over any other CSS rule or presentation attribute.

Before attempting to execute the ‘script’ element the resolved media type value for ‘type’ must be inspected. If the SVG user agent does not support the scripting language then the‘script’ element must not be executed.

This example defines a functioncircle_click which is called by the‘onclick’ event attribute on the ‘circle’ element. The drawing below on the left is the initial image. The drawing below on the right shows the result after clicking on the circle.

<!-- Outline the drawing area with a blue line -->
<rect x="1" y="1" width="598" height="498" fill="none" stroke="blue"/>

<!-- Act on each click event -->
<circle onclick="circle_click(evt)" cx="300" cy="225" r="100"
        fill="red"/>

<text x="300" y="480"
      font-family="Verdana" font-size="35" text-anchor="middle">

  Click on circle to change its size
</text>

An example demonstrating the effect of the ‘onclick’ event handler on an SVG shape.

View this example as SVG (SVG-enabled browsers only)

‘script’

Categories:

Never-rendered element, structurally external element

Content model:

Character data.

Attributes:

• core attributes — ‘id’, ‘tabindex’, ‘lang’, ‘xml:space’, ‘class’, ‘style’
• global event attributes — ‘oncancel’, ‘oncanplay’, ‘oncanplaythrough’, ‘onchange’, ‘onclick’, ‘onclose’, ‘oncuechange’, ‘ondblclick’, ‘ondrag’, ‘ondragend’, ‘ondragenter’, ‘ondragexit’, ‘ondragleave’, ‘ondragover’, ‘ondragstart’, ‘ondrop’, ‘ondurationchange’, ‘onemptied’, ‘onended’, ‘onerror’, ‘onfocus’, ‘oninput’, ‘oninvalid’, ‘onkeydown’, ‘onkeypress’, ‘onkeyup’, ‘onload’, ‘onloadeddata’, ‘onloadedmetadata’, ‘onloadstart’, ‘onmousedown’, ‘onmouseenter’, ‘onmouseleave’, ‘onmousemove’, ‘onmouseout’, ‘onmouseover’, ‘onmouseup’, ‘onmousewheel’, ‘onpause’, ‘onplay’, ‘onplaying’, ‘onprogress’, ‘onratechange’, ‘onreset’, ‘onresize’, ‘onscroll’, ‘onseeked’, ‘onseeking’, ‘onselect’, ‘onshow’, ‘onstalled’, ‘onsubmit’, ‘onsuspend’, ‘ontimeupdate’, ‘ontoggle’, ‘onvolumechange’, ‘onwaiting’
• document element event attributes — ‘oncopy’, ‘oncut’, ‘onpaste’
• deprecated xlink attributes — ‘xlink:href’, ‘xlink:title’
• ‘type’
• ‘href’
• ‘crossorigin’

DOM Interfaces:

• SVGScriptElement

Attribute definitions:

The crossorigin attribute is a CORS settings attribute, and unless otherwise specified follows the same processing rules as in html [HTML].

Identifies the scripting language for the given ‘script’ element. The value must be a valid media type, perMultipurpose Internet Mail Extensions (MIME) Part Two [rfc2046]. If a ‘type’ is not provided, then the default scripting language assumed is ECMAScript, as if processed with the‘application/ecmascript’ media type.

An URL reference to an external resource containing the script code. Refer to the common handling defined for URL reference attributes anddeprecated XLink attributes.

The URL is processed and the resource is fetchedas described in the Linking chapter.

15.11. DOM interfaces

15.11.1. Interface SVGScriptElement

An SVGScriptElement object represents a ‘script’ element in the DOM.

[Exposed=Window] interface SVGScriptElement : SVGElement { attribute DOMString type; attribute DOMString? crossOrigin; };

SVGScriptElement includes SVGURIReference;

The type IDL attributereflects the ‘type’ content attribute.

The crossOrigin IDL attribute reflects the ‘crossorigin’ content attribute.