previous next contents properties index

# 16 Interactivity

### Contents

## 16.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) or keyboard events 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 enableZoomAndPanControls 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 user interface events, including under which circumstances user interface 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

## 16.2 User interface events

On user agents which support interactivity, it is common for authors to define SVG document 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.

For all UI event-related features defined as part of the SVG language via event attributes or animation, the event model corresponds to the event bubbling model described in DOM2 [DOM2-EVBUBBLE]. The event capture model from DOM2 [DOM2-EVCAPTURE] can only be established from DOM method calls.

## 16.3 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 graphics content is under the pointer at the time of the event. (See property 'pointer-events' for a description of how to determine the situations in which a graphic element receives pointer events.)

The event is either initially dispatched to the target element, to one of the target element's ancestors, or not dispatched, depending on the following:

- If there are no graphics elements whose relevant graphics content is under the pointer (i.e., there is no target element), the event is not dispatched.
- Otherwise, there is a target element. If there is an ancestor of the target element which has specified an event handler with event capturing [DOM2-EVCAPTURE] for the given event, then the event is dispatched to that ancestor element.
- Otherwise, if the target element has an appropriate event handler for the given event, the event is dispatched to the target element.
- Otherwise, each ancestor of the target element (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.

When event bubbling [DOM2-EVBUBBLE] is active, 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.

When event capturing [DOM2-EVCAPTURE] is active, ancestor elements receive events before their descendants.

After an event is initially dispatched to a particular element, unless an appropriate action has been taken to prevent further processing (e.g., by invoking the preventCapture() or preventBubble() DOM method call), the event will be passed to the appropriate event handlers (if any) for that element's ancestors (in the case of event bubbling) or that element's descendants (in the case of event capture) for further processing.

## 16.4 Processing order for user interface events

The processing order for user interface events is as follows:

- Event handlers assigned to the topmost graphics element under the pointer (and the various ancestors of that graphics element) receive the event first. If none of the activation event handlers take an explicit action to prevent further processing of the given event (e.g., by invoking the preventDefault() DOM method), then the event is passed on for:
- Processing of any relevant CSS2's dynamic pseudo-classes (i.e., :hover, :active and :focus) [CSS2-DYNPSEUDO], after which 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.

## 16.5 The 'pointer-events' property

In different circumstances, authors may or may not want events to be triggered when the pointer is over the unfilled interior of a graphics element or the pointer is over an invisible graphics element. The 'pointer-events' property specifies under what circumstances a given graphics element receive pointer events.

'pointer-events'

  Value: | visiblePainted | visibleFill | visibleStroke | visibleFillStroke | visible | painted | fill | stroke | fillstroke | all | none | inherit
  Initial: | visiblePainted
  Applies to: | container elements and graphics elements
  Inherited: | yes
  Percentages: | N/A
  Media: | visual
  Animatable: | yes

visiblePainted
  The given element receives 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 receives 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 receives 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.
visibleFillStroke
  The given element receives pointer events when the 'visibility' property is set to visible and when 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' properties do not effect event processing.
visible
  The given element receives pointer in all cases when the 'visibility' property is set to visible. The values of the 'fill' and 'stroke' do not effect event processing.
painted
  The given element receives 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 receives 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 receives 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.
fillStroke
  The given element receives pointer events when 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.
all
  The given element receives pointer in all cases. The values of the 'fill', 'stroke' and 'visibility' properties do not effect event processing.
none
  The given element does not receive pointer events.

For text elements, hit detection is performed on a character cell basis. The values visiblePainted, visibleFill, visibleStroke and visibleFillStroke are all defined to be equivalent to the value visible, and the values painted, fill, stroke and fillStroke are all defined to be equivalent to the value all.

For raster elements, hit detection can be defined to be dependent on whether the pixel under the pointer is fully transparent. For any of the values visiblePainted, visibleFill, visibleStroke and visibleFillStroke, the raster element receives the event if the 'visibility' property is set to visible and the pixel under the pointer is not fully transparent. For a value of visible, the raster element receives the event if the 'visibility' property is set to visible even if the pixel under the pointer is fully transparent. For any of the values painted, fill, stroke and fillStroke, the raster element receives the event if the the pixel under the pointer is not fully transparent, no matter what the value is for the 'visibility' property. For a value of all, the raster element receives the event even if the pixel under the pointer is fully transparent, no matter what the value is for the 'visibility' property.

## 16.6 Zooming panning and magnification

Zooming represents a (potentially non-uniform) scale transformation on an SVG document fragment in response to a user interface action. All elements which are specified in user coordinates will scale uniformly, but elements which use CSS unit identifiers to define coordinates or lengths may be transformed differently. A zoom operation has the effect of a supplemental scale and translate transformation inserted into the transformation hierarchy between the outermost 'svg' element and its children, as if an extra 'g' element enclosed all of the children and that 'g' element specified a transformation to achieve the desired zooming effect.

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

Magnification represents complete, uniform transformation on an 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)..

Some ability to zoom and pan SVG document fragments are required for SVG user agents that operate in interaction-capable user environments. Document-level magnification capabilities are recommended for SVG user agents to enable accessibilty to those who are partially visually impaired.

The outermost 'svg' element in an SVG document fragment has attribute enableZoomAndPanControls, which takes the possible values of true and false, with the default being true. If true, in environments that support user interactivity, the user agent shall provide user interface controls to allow the user to zoom in, zoom out and pan around the given document fragment. If false, the user agent shall disable these controls and not allow the user to zoom and pan on the given document fragment. If a enableZoomAndPanControls attribute is assigned to an inner 'svg' element, the enableZoomAndPanControls setting on the inner 'svg' element will have no effect on the SVG user agent.

Animatable: no.

## 16.7 Cursors

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

### 16.7.2 The 'cursor' property

'cursor'

  Value: | [ [<uri> ,]* [ auto | crosshair | default | pointer | move| e-resize | ne-resize | nw-resize | n-resize | se-resize | sw-resize | s-resize | w-resize| text | wait | help ] ] | inherit
  Initial: | auto
  Applies to: | container elements and graphics elements
  Inherited: | yes
  Percentages: | N/A
  Media: | visual, interactive
  Animatable: | yes

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

Example(s):

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

The 'cursor' property for SVG is identical to the 'cursor' property defined in the "Cascading Style Sheets (CSS) level 2" specification [CSS2], with the exception that SVG user agents must support cursors defined by the 'cursor' element.

### 16.7.3 The 'cursor' element

The 'cursor' element can be used to define a platform-independent custom cursor. A recommended approach for defining a platform-independent custom cursor is to create a PNG [PNG01] image and define a 'cursor' element that references the PNG image and identifies the exact position within the image which is the pointer position (i.e., the hot spot).

    <!ELEMENT cursor (%descTitle;) >
    <!ATTLIST cursor
      %stdAttrs;
      %testAttrs;
      x %Coordinate; "0"
      y %Coordinate; "0"
      %xlinkRefAttrs;
      xlink:href %URI; #REQUIRED
      externalResourcesRequired %Boolean; #IMPLIED >

Attribute definitions:

x = "<coordinate>"
  The x-coordinate of the position in the cursor's coordinate system which represents the precise position that is being pointed to.
  Animatable: yes.
y = "<coordinate>"
  The y-coordinate of the position in the cursor's coordinate system which represents the precise position that is being pointed to.
  Animatable: yes.
xlink:href = "<uri>"
  A URI reference to the file or element which provides the image of the cursor.
  Animatable: yes.

Attributes defined elsewhere:
  %stdAttrs;, %testAttrs;, %xlinkRefAttrs;.

SVG user agents are required to support PNG format images as targets of the xlink:href property.

## 16.8 DOM interfaces

The following interfaces are defined below: SVGCursorElement.

### Interface SVGCursorElement

The SVGCursorElement interface corresponds to the 'cursor' element.

IDL Definition

      interface SVGCursorElement : SVGElement, SVGTests, SVGURIReference {
                 attribute SVGLength x;
                 attribute SVGLength y;
      };

Attributes
  SVGLength x
    Corresponds to attribute x on the given 'cursor' element.
  SVGLength y
    Corresponds to attribute y on the given 'cursor' element.

previous next contents properties index