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 a key-press can cause timed elements to start or stop, scripts to execute or 'listener'
elements to trigger 'handler' elements.
- The user can initiate hyperlinks to new Web pages (see the 'a' element) by actions such
as a stylus click on a particular graphics element.
- In many cases, depending on the value of the 'zoomAndPan' attribute on the 'svg' element and on the
characteristics of the SVG user agent, users are able to zoom
into and pan around SVG content.
This chapter describes:
Related information can be found in other chapters:
Complete list of supported events
The following aspects of SVG are affected by events:
The following table lists all of the events which must be
recognized and supported in SVG. The "Description" column describes the required conditions for the event to occur.
| Event Type |
Description |
Animation event name |
Bubbles |
Cancelable |
uDOM interface |
| DOMFocusIn |
Occurs when an element receives focus.
See the DOM 2 Events definition of DOMFocusIn ([DOM2EVENTS], section 1.6.1).
|
focusin |
Yes |
No |
UIEvent |
| DOMFocusOut |
Occurs when an element loses focus.
See the DOM 2 Events definition of DOMFocusOut ([DOM2EVENTS], section 1.6.1).
|
focusout |
Yes |
No |
UIEvent |
| DOMActivate |
Occurs when an element is activated, for instance, through a mouse click or a keypress.
See the DOM 2 Events definition of DOMActivate ([DOM2EVENTS], section 1.6.1).
|
activate |
Yes |
Yes |
UIEvent |
| click |
Occurs when the pointing device button is clicked over an element. A click is defined as a mousedown and mouseup over the same screen location. The sequence of these events is: mousedown, mouseup, click. If multiple clicks occur at the same screen location, the sequence repeats with the detail attribute incrementing with each repetition.
See the DOM 2 Events definition of click ([DOM2EVENTS], section 1.6.2).
|
click |
Yes |
Yes |
MouseEvent |
| mousedown |
Occurs when the pointing device button is pressed over an element.
See the DOM 2 Events definition of mousedown ([DOM2EVENTS], section 1.6.2).
|
mousedown |
Yes |
Yes |
MouseEvent |
| mouseup |
Occurs when the pointing device button is released over an element.
See the DOM 2 Events definition of mouseup ([DOM2EVENTS], section 1.6.2).
|
mouseup |
Yes |
Yes |
MouseEvent |
| mouseover |
Occurs when the pointing device is moved onto an element.
See the DOM 2 Events definition of mouseover ([DOM2EVENTS], section 1.6.2). |
mouseover |
Yes |
Yes |
MouseEvent |
| mousemove |
Occurs when the pointing device is moved while it is over an element.
See the DOM 2 Events definition of mousemove ([DOM2EVENTS], section 1.6.2).
|
mousemove |
Yes |
Yes |
MouseEvent |
| mouseout |
Occurs when the pointing device is moved away from an element.
See the DOM 2 Events definition of mouseout ([DOM2EVENTS], section 1.6.2).
|
mouseout |
Yes |
Yes |
MouseEvent |
| mousewheel |
Occurs when a rotational input device has been activated.
See the description of the
MouseWheelEvent
event for details.
|
none |
Yes |
Yes |
MouseWheelEvent |
| textInput |
One or more characters have been entered.
See the Text events section below for details.
|
none |
Yes |
Yes |
TextEvent |
| keydown |
A key is pressed down.
See the Key events section below for details.
|
none |
Yes |
Yes |
KeyboardEvent |
| keyup |
A key is released.
See the Key events section below for details.
|
none |
Yes |
Yes |
KeyboardEvent |
| load |
The event is triggered at the point at which the user agent
finishes loading the element and any dependent resources (such
as images, style sheets, or scripts). In the case the element
references a script, the event will be raised only after an
attempt to interpret the script has been made. Dependent
resources that fail to load will not prevent this event from
firing if the element that referenced them is still in the
document tree unless they are designated as
externalResourcesRequired.
The event is independent of the means by which the element was
added to DOM tree.
|
load |
No |
No |
Event |
| SVGLoad |
This event is deprecated and is for backwards compatibility
only, see notes below. The
This event must be dispatched immediately after the
load event is dispatched.
|
none |
No |
No |
Event |
| resize |
Occurs when a document view is being resized. This event is only applicable to 'svg' elements and is dispatched after the resize operation has taken place. The target of the event is the 'svg' element.
|
resize |
Yes |
No |
Event |
| SVGResize |
This event is deprecated and is for backwards compatibility only, see notes below.
This event must be dispatched immediately after the resize event is dispatched.
|
none |
Yes |
No |
Event |
| scroll |
Occurs when a document view is being shifted along the X or Y or
both axis, either through a direct user interaction or any
change on the currentTranslate
property available on SVGSVGElement
interface. This event is only applicable to
'svg'
elements and is dispatched after the shift modification has
taken place. The target of the event is the
'svg'
element.
|
scroll |
Yes |
No |
Event |
| SVGScroll |
This event is deprecated and is for backwards compatibility only, see notes below.
This event must be dispatched immediately after the scroll event is dispatched.
|
none |
Yes |
No |
Event |
| SVGZoom |
Occurs when the zoom level of a document view is being changed,
either through a direct user interaction or any change to the
currentScale
property available on SVGSVGElement
interface. This event is only applicable to
'svg'
elements and is dispatched after the zoom level modification has
taken place. The target of the event is the
'svg'
element.
|
zoom |
No |
No |
Event |
| SVGRotate |
Occurs when the rotation of a document view is being changed,
either through a direct user interaction or any change to the
currentRotate
property available on SVGSVGElement
interface. This event is only applicable to
'svg'
elements and is dispatched after the rotation modification has
taken place. The target of the event is the
'svg'
element.
|
rotate |
No |
No |
Event |
| beginEvent |
Occurs when a timed element
begins.
See the SMIL 2.1 definition of beginEvent ([DOM2EVENTS], section 10.6.2).
|
beginEvent |
Yes |
No |
TimeEvent |
| endEvent |
Occurs when a timed element
ends.
See the SMIL 2.1 definition of endEvent ([DOM2EVENTS], section 10.6.2).
|
endEvent |
Yes |
No |
TimeEvent |
| repeatEvent |
Occurs when a timed element
repeats. It is raised each time the element repeats, after the
first iteration.
See the SMIL 2.1 definition of repeatEvent ([DOM2EVENTS], section 10.6.2).
|
repeatEvent |
Yes |
No |
TimeEvent |
| loadstart |
A load operation has begun.
See the description of the
ProgressEvent
interface for details on this event.
|
none |
No |
No |
ProgressEvent |
| progress |
Progress has occurred in loading a given resource.
See the description of the
ProgressEvent
interface for details on this event.
|
none |
No |
No |
ProgressEvent |
| loadend |
A load operation has completed.
See the description of the
ProgressEvent
interface for details on this event.
|
none |
No |
No |
ProgressEvent |
| SVGTimer |
Occurs when the specified timer interval has elapsed for a
timer. This event is triggered only by 'running' timers in the
current global execution context of the SVG document (i.e. for
timers which have been instantiated via the
SVGGlobal
interface and started via the start()
method of the SVGTimer
interface). The target of the event is the
SVGTimer
object itself. The event processing is limited to the at target
phase.
See the description of the
SVGTimer
interface for more details.
|
none |
No |
No |
Event |
Note that in order to unify event names with other W3C specifications,
SVG Tiny 1.2 deprecates some of the SVG 1.1 event types. (The term
"deprecate" in this case means that user agents which are compatible
with both SVG 1.1 and SVG Tiny 1.2 must support both the old deprecated
event names and the new event names. Content creators who are making
content that targets SVG Tiny 1.2 should use the new event types, not
the deprecated event types.) Specifically:
- The
"SVGLoad" event is deprecated in favor of "load"
- The
"SVGResize" event is deprecated in favor of "resize"
- The
"SVGScroll" event is deprecated in favor of "scroll"
Details on the values of attributes on the event object passed to event
listeners for the event types defined in DOM Level 2 Events can be
found in the description for that event in that specification. For
other event types, the values of the attributes are are described
elsewhere in this specification.
User interface events
On SVG 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.
The following example shows the use of a DOMActivate event to
trigger an ECMAScript event handler:
Pointer events
Note: The W3C's Web Content Accessibility Guidelines (WCAG)
advise content creators to create device-independent content;
in particular, content should not require that the user has access to a pointer device.
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,
trackball, stylus or joypad. 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.
One difference between stylus-based pointers and mouse-based pointers is that for a mouse, the cursor always has a position; for a stylus which may be lifted, the cursor may only have a position when the stylus is tapped on the screen. Thus, content which assumes that all pointer devices will generate mouseover and mouseout events will not work on all devices.
Text events
User interface events that occur because of user actions that
generate text are called text events. They are usually generated
by a keyboard, but can also be generated by a different input
method such as an IME (for Japanese text, for example), by speech
input, etc. The event is dispatched whenever a string of Unicode
characters is sent to the document and is thus independent of
the input device or method used.
Key events
Note: The W3C's Web Content Accessibility Guidelines
(WCAG) advise content creators
to create device-independent content;
in particular, content should not require that the user has access to a
(full-size) keyboard.
User interface events that occur because of user actions that generate
key presses (as opposed to text — for example, function keys, key
presses for a game, etc.) are called key events.
Event flow
DOM Level 2 Events
defines the event flow model
([DOM2EVENTS], section 1.2),
which defines three phases in which event listeners in the document are
triggered: capture, at target and bubbling.
An SVG Tiny 1.2 user agent is not required to support the capture phase
of the event flow model. If the capture phase is not supported:
-
Registering an event listener for the capture phase by
passing true for the useCapture
parameter of EventTarget::addEventListener()
will result in that listener never being triggered. Since there is no
way with the SVG uDOM to determine whether a listener has been
registered on a node or not, such calls to
EventTarget::addEventListener()
can be ignored.
-
Registering an event listener for the capture phase by specifying
phase="capture" on a
'listener'
will result in an event listener being registered for the
at target and default phases, since a value of
'capture' will be ignored, resulting
in the lacuna value of 'default'
being used. Conforming
SVG documents must use 'default'
as the value of the 'phase'
attribute if it is specified.
-
Any keydown
event that corresponds to an
accessKey-value
in an animation timing specifier list will never cause any appropriate
listeners to be triggered, since, as described in the definition of
the accessKey-value syntax, the
SVG user agent
behaves as if stopPropagation() and
preventDefault()
had been invoked on the event object in the capture phase.
Event dispatching
For each pointer event, text event or key event, the SVG user agent determines the
target object of a given event. The target
object must be the topmost graphics element
or SVGElementInstance object
whose relevant
graphical content is under the pointer (for pointer events) or has focus (for text and key events) 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 graphics element can be the target object 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 must not be the
target of pointer events.
The decision on whether to dispatch the event to the target object or to one of the target elements ancestors shall depend on the following:
- If there is no target
object, the event is not dispatched.
- Otherwise, if the target object has an appropriate event
handler for the given event, the event is dispatched to the
target object.
- Otherwise, each ancestor of the target object (starting
with its immediate parent) is checked to see if it has an
appropriate event handler. If an ancestor is found with an
appropriate event handler, the event is dispatched to that
ancestor element.
- Otherwise, the event is discarded.
If an event is defined to
bubble
([DOM2EVENTS], section 1.2.3),
bubbling occurs up to all direct ancestors of the target object.
Descendant elements receive events before their ancestors. Thus, if a
'path'
element is a child of a 'g'
element and they both have event listeners for
click events, then the event will
be dispatched to the 'path'
element before the 'g'
element.
After an event is initially dispatched to a particular
element, unless an appropriate action has been taken to prevent further processing, the event must be passed to the appropriate event handlers (if
any) for that element's ancestors (in the case of event bubbling) for further processing.
Processing order for user interface events
The processing order for user interface events shall be as follows:
-
Event handlers assigned to the topmost graphics element under the
pointer (and the various ancestors of that graphics element via
potential event bubbling) receive the event first. If none of the
activation event handlers take an explicit action to prevent further
processing of the given event, then the event is passed on for:
-
(For those user interface events which invoke hyperlinks, such as
mouse clicks in some user agents) Link processing. If a hyperlink is
invoked in response to a user interface event, the hyperlink
typically will disable further activation event processing (e.g.,
often, the link will define a hyperlink to another Web page). If
link processing does not disable further processing of the given
event, then the event is passed on for:
-
(For those user interface events which can select text, such as
mouse clicks and drags on 'text' elements) Text selection
processing. When a text selection operation occurs, typically it
will disable further processing of the given event; otherwise, the
event is passed on for:
-
Document-wide event processing, such as user agent facilities to
allow zooming and panning of an SVG document fragment.
The 'use' element creates shadow content which can be the target of user interface events.
User interface events within the shadow content shall participate in the
processing of user interface events in the same manner as if the shadow content were part
of the main document. In other words, if shadow content contains a graphics element that
renders above other content at the current pointer location, then it represents the
topmost graphics element and will receive the pointer events before other elements.
In this case, the user interface events bubble up through the target's ancestors, and
then across the document border into the referencing element, and then through the ancestors
of the referencing element. This process continues as necessary if there are multiple levels
of nested shadow trees.
The 'pointer-events' property
In different circumstances, authors may want to control
under what circumstances particular graphics element 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 graphics elements underneath the given element will become the target of
pointer events.
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 'rect' 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 'rect' 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 a key press
- hyperlinks (see the 'a'
element)
- 'pointer-events'
-
| Value: |
boundingBox | visiblePainted | visibleFill | visibleStroke |
visible |
painted | fill | stroke | all | none |
inherit |
| Initial: |
visiblePainted |
| Applies to: |
graphics
elements |
| Inherited: |
yes |
| Percentages: |
N/A |
| Media: |
visual |
| Animatable: |
yes |
| Computed value: |
Specified value, except inherit |
-
boundingBox
- 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 must only be a 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 is set to a
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 must only be a 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 effect
event processing.
- visibleStroke
- The given element must only be a 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
effect event processing.
- visible
- The given element must only be a 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 effect event
processing.
- painted
- The given element must only be a 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 is set to a
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. The value of the 'visibility' property does not
effect event processing.
- fill
- The given element must only be a 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
effect event processing.
- stroke
- The given element must only be a 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
effect event processing.
- all
- The given element must be a 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
effect event processing.
- none
- The given element must not receive pointer events.
For text elements, hit detection shall be 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
effect 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
effect 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
effect event processing.
- The value none indicates
that the given text does not receive pointer events.
For raster images, hit detection shall either be 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 basic (i.e., the alpha values for
pixels under the pointer help determine whether the image
receives the event). The following rules must be adhered to:
- 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
effect 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
effect event processing.
- The value none indicates
that the image does not receive pointer events.
Note that for raster images, the values of properties
'fill-opacity', 'stroke-opacity', 'fill' and 'stroke' do not effect 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 rootmost level on the SVG document fragment (i.e. outside the
rootmost '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.
Attribute definition:
-
zoomAndPan =
"magnify" | "disable"
Can be specified on the 'svg'
element. The attribute is intended for applications where SVG
is used for both the content and for the user interface, e.g. a mapping application.
The default zoom might move critical user interface components from view, confusing
the user; disabling the default zoom, pan and rotate while providing zoom, pan and
rotate controls for a smaller content area would give a better user experience. The
effect of
'zoomAndPan'
applies solely to user interface aspects, and must not disable
script-initiated zooming and panning on the corresponding element.
The attribute value can be one of the following:
- magnify
- The lacuna value.
If magnify, in environments that support user interactivity,
the user agent must provide controls to allow the user to perform a
"magnify" operation on the document fragment.
- disable
- If disable, the user agent shall in its default interaction
mode disable any magnification and panning controls and not allow
the user to magnify or pan on the given document fragment. The
SVG user agent
may provide another mode which continues to allow zoom and pan at
user option.
Animatable: no.
Element focus
The 'focusable' attribute
In many cases, such as text editing, the user is required to place focus on a particular element, ensuring that input events, such as keyboard input, are sent to that element.
All renderable elements are required to be able to accept focus if specified by the author, including container elements (except 'defs'), graphics elements, 'tspan' and 'foreignObject'. A focusable container element may contain focusable descendants.
Attribute definition:
- focusable = "true" | "false" | "auto"
Defines if an element can get keyboard focus (i.e. receive keyboard events) and be a target for field-to-field navigation actions. (Note: in some environments, field-to-field navigation can be accomplished with the tab key.)
The attribute value can be one of the following:
- true
- The element is keyboard-aware and must be treated as any other UI component that can get focus.
- false
- The element is not focusable.
- auto
The lacuna value. Equivalent to 'false', except that it must be treated like 'true' for the following cases:
Animatable: yes.
Navigation
Navigation behavior
System-dependent input facilities (e.g., the tab key on most desktop
computers) should be supported to allow navigation between elements that
can obtain focus (i.e. elements for which the value of the
'focusable'
attribute is 'true').
The document has the concept of a focus ring, which is the
order in which elements obtain focus. By default the focus
ring shall be obtained using document order. All focusable elements
must be part of the default focus ring.
A document's focus ring includes any focusable objects within shadow trees
for 'use' elements.
The focus attributes may be used to modify the default focus ring.
The SVG language supports a flattened notion of field navigation between focusable elements where an author may define field navigation between any two focusable elements defined within a given SVG document without regard to document hierarchy. For example:
<rect xml:id="r1" focusable="true" .../>
<g xml:id="g1" focusable="true">
<circle xml:id="c1" focusable="true" .../>
</g>
In the above example, the author may specify field-to-field
navigation such the user can navigate directly from any
of the three elements. Thus, assuming a desktop computer which
uses the tab key for field navigation, the author may specify
focus navigation order such that the tab key takes the user from
"r1" to "c1" to "g1".
When navigating to an element that is not visible on the canvas the following rules shall apply:
The SVG user agent must not navigate to an element which has display="none". (An element which has display="none" is not focusable.)
The SVG user agent must allow navigation to elements which are not visible (i.e. which has a 100% transparency or which is hidden by another element).
The SVG user agent must allow navigation to elements which are located outside of the current viewport. In this case it is recommended that the SVG user agent should change the current viewport so that the focused element becomes visible.
SVG's flattened notion of field navigation shall extend to referenced content and shadow trees as follows:
-
Focusable elements within the content referenced by a 'use' element
participate in field navigation operations using the flattened focus
model. (Note: If a referenced group contains a focusable element,
and that group is referenced by two 'use' elements, then the document
will have two separate focusable fields, not just one.)
-
If an 'animation' element references an SVG document, then all of the
focusable fields defined within the referenced SVG document
participate in field navigation operations using the flattened focus
model.
Focus navigation shall behave as specified:
When the document is loaded the focus is first offered
to the SVG user agent.
-
Once the SVG user agent releases focus, then
focus passes to the entity that
first matches the following criteria:
-
the rootmost 'svg' element if it is focusable,
-
the element referenced by the 'nav-next'
attribute on the rootmost 'svg' element, if the
attribute is present,
-
the first focusable element in the document
starting from the rootmost 'svg' element,
-
the SVG user agent
-
If the focus is held by an element in the
document, then the next element in navigation order shall be
the entity that first matches the following
criteria:
-
the element referenced by the 'nav-next'
attribute on the focused element,
-
the next focusable element in document order,
-
the SVG user agent
-
If the focus is held by an element in the
document, then the previous element in navigation
order shall be
the entity that first matches the following
criteria:
-
the element referenced by the 'nav-prev'
attribute on the focused element,
-
the previous focusable element in document order,
-
the SVG user agent
For stand-alone SVG documents, the SVG user agent must always have a currently
focused object. If focus is not held by any object in the document tree, the
SVG user agent must give focus to the SVGDocument object.
For SVG documents which are referenced by a non-SVG host document (e.g.,
XHTML), the SVG document may participate within the host document's focus
ring, which would allow direct navigation from an SVG focusable element
onto a focusable element within the host document.
Other compound document specifications may define supplemental SVG focus navigation rules for
situations when SVG content is used as a component within a compound document.
User agents should provide a mechanism for a user to escape from a focus ring.
When the user activates this mechanism, the user agent should change focus to
the user agent, sending the appropriate focusout
event to the element currently in focus.
Specifying navigation
Navigation order can be specified using the ten
navigation attributes
defined below.
Attribute definitions:
- nav-next,
- nav-prev = "<FuncIRI>" | "auto" | "self"
-
Specifies the next element (when using 'nav-next')
or previous element (when using 'nav-prev')
in the focus ring.
The attribute value for 'nav-next'
and 'nav-prev'
can be one of the following:
- <FuncIRI>
- Specifies the element that must receive focus when navigation in the next direction (for 'nav-next') or previous direction (for 'nav-prev') is triggered. The specified element must be within the current SVG document fragment.
- auto
- The lacuna value. Means that the behavior shall be as if the attribute was not specified
(navigation must follow the rules specified in Navigation behavior).
- self
- The focus must stay on the element itself.
Animatable: yes.
- nav-up,
- nav-up-right,
- nav-right,
- nav-down-right,
- nav-down,
- nav-down-left,
- nav-left,
- nav-up-left = "<FuncIRI>" | "auto" | "self"
-
Each of these eight attributes specifies an element to receive
focus when navigating in a particular direction. For each of
the attributes, the direction for which an element is being
specified for navigation is suggested by the name of the attribute.
The following table lists these directions explicitly:
| Attribute name |
Direction |
| 'nav-up' |
↑ upward |
| 'nav-up-right' |
↗ up-and-rightward |
| 'nav-right' |
→ rightward |
| 'nav-down-right' |
↘ down-and-rightward |
| 'nav-down' |
↓ downward |
| 'nav-down-left' |
↙ down-and-leftward |
| 'nav-left' |
← leftward |
| 'nav-up-left' |
↖ up-and-leftward |
The value for each of these attributes can be one of the following:
- <FuncIRI>
- Specifies the element that must receive focus when navigation in the given direction is triggered. The specified element must be within the current SVG document fragment.
- auto
- The lacuna value. Means that the behavior is left up to the SVG user agent.
- self
- The focus must stay on the element itself.
Animatable: yes.
This example illustrates how it is possible for an author to control
the focus order between several focusable elements displayed on the canvas.
On a device which provides a 2-way navigation system (a TAB
mechanism for instance), here are the interesting behaviors:
Whenever the focus is located on a program which is at the beginning of the timeline of a given channel, there are 3 options when the user wants to go to the previous focusable item (i.e., the user presses the "Reverse-Tab" key on most desktop computers):
- option 1: the focus goes up to the first program of the previous channel
- option 2: the focus goes up to the last program of the previous channel
- option 3: the focus remains at the same place
Here, in this example, for channel 2, because there is nav-prev="url(#Chan1Prog1)" attribute in element 'g' with id="Chan2Prog1", option 1 will be applied.
In order to apply option 2, we could have set nav-prev="url(#Chan1Prog3)" instead.
In order to apply option 3, we could have set nav-prev="self" instead.
Whenever the focus is located on a program which is at the end of the timeline of a given channel, there are 2 options when the user wants to go to the next focusable item (i.e., the user presses the "Tab" key on most desktop computers):
- option 1: the focus goes down to the first program of the next channel
- option 2: the focus remains at the same place
Here, in this example, for channel 1, because there is nav-next="self" attribute in element 'g' with id="Chan1Prog3", option 2 will be applied.
In order to apply option 1, we could have set nav-next="url(#Chan2Prog1)" instead.
Whenever the focus is located on "Chan2Prog1" container, if the user wants to go to the next focusable element, the concept of a focus ring will apply because of value nav-next="auto". Here, according to the focus ring navigation rules, focus will be offered to the SVG user agent because there is no more focusable element in the document order.
On a device which provides a 4-way navigation system (i.e. a joystick
for instance), here are the interesting behaviors:
Whenever the focus is located at the beginning of the timeline of a given channel, when the user wants to go "Left", focus remains on the same element because both element 'g' with id="Chan1Prog1" and element 'g' with id="Chan2Prog1" have nav-left="self".
Whenever the focus is located on "Chan1Prog1" container, if the user wants to go 'Right', the focus will be put on container element "Chan1Prog2" because of the nav-right="url(#Chan1Prog2)" value. But, because some part of "Chan1Prog2" bounding box is outside of the current viewport, the SVG user agent should change the current viewport so that the new focused element becomes visible.
 |
|
 |
Before element "Chan1Prog2" receives focus |
|
After element "Chan1Prog2" receives focus (UA scrolls automatically) |
On element 'g' with id="Chan2Prog1", there is a value nav-right="auto". This value is the default one for navigation attributes and therefore the behavior is the same as if no 'nav-right' attribute was defined. This value 'auto' means that it's up to the SVG user agent to choose which focusable element should receive focus when the user wants to go 'right'.
Specifying focus highlighting
Automated highlighting upon focus can be specified using the 'focusHighlight' attribute. This hint indicates whether the SVG user agent should highlight an element on focus. The highlighting method is implementation dependent and the SVG user agent should pick a method that works well for varying content. This attribute is available on all graphical and container elements.
- focusHighlight = "auto" | "none"
Specifies whether a SVG user agent should highlight an element on focus.
The attribute value can be one of the following:
- auto
The lacuna value. This indicates that the element should be highlighted on focus. The highlighting method is left up to the SVG user agent.
- none
The SVG user agent should not highlight this element on focus.
Animatable: no.
In the above SVG example:
Highlight of the focus on the first two textual links is left up to
the SVG user agent (underline the text, highlight of the bounding
box, change color of the text, ...) since the lacuna value is focusHighlight="auto". This
text may have been retrieved from a database where there may be no
notion of graphical styling or no way to know in advance the kind of
focusable elements it contains, therefore the author doesn't handle
focus highlight on that part of the document.
Highlight of the focus on the two graphical buttons is designed by
the author and therefore the SVG user agent doesn't need to highlight
it as well. Therefore, focusHighlight="none" is used to disable the
default focus highlight behavior.
Obtaining and listening to focus programmatically
When the user agent gives an element focus it receives a DOMFocusIn event which has the new focused object as the event target and a DOMFocusOut event which has the previously focused object as the event target.
The SVGSVGElement interface has a setFocus method that puts the focus on the requested object.
Calling setFocus with an element that is not focusable causes focus to stay on the currently focused object.
The SVGSVGElement interface has a moveFocus(short motionType) which moves current focus to a different object based on the value of motionType.
SVG user agents which support pointer devices such as a mouse must allow users to put focus onto focusable elements. For example, it should be possible to click on a focusable element in order to give focus.
Empty text fields in SVG theoretically take up no space, but
they have a point or zero-width line segment that represents the
location of the empty text field. SVG user agents should allow users
with pointer devices to put focus into empty text fields by
initiating a select action (e.g., a mouse click) at the location
of the empty text field.
An author may change the field navigation order from a script by using the setTrait method to change the current value of
navigation attributes
on a given element (see Example below).