6 XML Events integration

6.1 XML Events

XML Events is an XML syntax for integrating event listeners and handlers with DOM Event interfaces. Declarative event handling in SVG 1.1 is hardwired into the language, in that the developer is required to embed the event handler in the element syntax (e.g. an element has an onclick attribute). SVG 1.2 adds support for XML Events, providing the ability to listen to custom events, as well as specifying the event listener separately from the graphical content.

SVG 1.2 makes the following modifications to XML Events:

1. Namespaced events: As SVG 1.2 supports DOM Level 3 Events, which are namespaced, XML Events in SVG 1.2 much also allow namespaced events. SVG 1.2 follows the rules defined in DOM Level 3 (namespaces are specified as "namespace-prefix:event-name".
2. URIREFs instead of IDREFs: the observer and target attributes from XML Events are currently IDREFs. Since SVG 1.2 requires a declarative syntax for event handling in more than one document, it uses URIREFs for those attributes, with the following restriction: Only documents that are declaratively referenced as part of the current document, via the use, image and feImage elements, can be referred to. Referring to any other arbitrary external document is an error.

The following is an example of an SVG file using XML Events:

<svg xmlns="http://www.w3.org/2000/svg" version="1.2"
     xmlns:ev="http://www.w3.org/2001/xml-events">

  <rect id="myRect" x="10" y="20" width="200" height="300" 
        fill="red"/>

  <!-- register a listener for a myRect.click event -->
  <ev:listener ev:event="click" ev:observer="myRect"
               ev:handler="#myClickHandler" />

  <handler id="myClickHandler" type="text/ecmascript">
    var myRect = document.getElementById("myRect");
    var width = parseFloat(myRect.getAttribute("width"));
    myRect.setAttribute("width", (width+10));
  </handler>

</svg>

In the above example, the ev:listener element registers that the myClickHandler element should be invoked whenever a "click" event happens on "myRect".

The combination of the XML Events syntax and the new handler element allows event handling to be more easily processed in a compiled language. Below is an example of an event handler using the Java language:

<svg xmlns="http://www.w3.org/2000/svg" version="1.2"
     xmlns:ev="http://www.w3.org/2001/xml-events"
     xmlns:foo="http://www.example.com/foo">

  <rect id="myRect" x="10" y="20" width="200" height="300" 
        fill="red"/>

  <!-- register a listener for a myRect.click event -->
  <ev:listener ev:event="click" ev:observer="myRect"
               ev:handler="#myClickHandler" />

  <handler id="myClickHandler" type="application/java"
           xml:base="http://example.com/myJar.jar"
           xlink:href="#com.example.MyXMLEventHandler"/>
      <foo:offset>10</foo:offset>
  </handler>

</svg>

In this case, the handler element specifies the location of compiled code that conforms to the XMLEventHandler interface. The user agent invokes the handleEvent method within the targeted interface.

In this case, the MyXMLEventHandler has the following definition:

package com.example;

import org.w3c.svg.XMLEventHandler;
import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.events.Event;

public class MyXMLEventHandler implements XMLEventHandler {

  Document document;

  public void init(Document doc, Element handlerElement) {
    document = doc;
    // ...
  }

  public void handleEvent(Event event) {
    Element myRect = document.getElementById("myRect");
    float width = Float.parseFloat(myRect.getAttribute("width"));
    myRect.setAttribute(width, "" + (width + 10));
  }
}

The definition of the XMLEventHandler Interface is shown below:

 /**
 * XMLEventHandler
 */
 interface XMLEventHandler extends org.w3c.dom.events.EventHandler {

  /**
   * Gives the handler an opportunity to do any type of
   * initialization it requires.
   * This should be called before the onload event is
   * dispatched on the Document.
   *
   * @param doc reference to the Document this handler is
   *        attached to
   * @param handler reference to the handler element
   */
  void init(in Document doc, in Element handler);
 }

6.2 The handler element

The handler element is similar to the script element: its contents, either included inline or referenced, are code that is to be executed by the scripting engine(s) used by user agent.

However, where the script element evaluates its contents when the document is loaded, the handler element evaluates its contents in response to a event. This makes handler functionally equivalent to using the event attributes.

For example, consider the following SVG 1.1 document:

<svg xmlns="http://www.w3.org/2000/svg" version="1.1"> 

  <rect id="myRect" x="10" y="20" width="200" height="300" fill="red" 
     onclick="var width =  parseFloat(
                  document.getElementById('myRect').getAttribute('width')); 
              document.setAttribute('myRect', 'width', (width+10));"/> 

</svg> 

The above example can be rewritten to use the handler element and XML Events (described below) as shown:

<svg xmlns="http://www.w3.org/2000/svg" version="1.2"
     xmlns:ev="http://www.w3.org/2001/xml-events"> 

  <rect id="myRect" x="10" y="20" width="200" height="300" fill="red"> 

    <handler type="text/ecmascript" ev:event="click"> 
        var myRect = evt.target;
        var width = parseFloat(myRect.getAttribute("width")); 
        myRect.setAttribute("width", (width+10)); 
    </handler> 

  </rect>

</svg> 

In ECMAScript, the contents of the handler element behave as if they are the contents of a new function object, created as shown:

function(evt) {
  // contents of handler
}

Other interpreted languages behave in as similar a manner as possible.

The 'evt' parameter shown above is an Event object corresponding to the event that has triggered the handler.

The following is a schema extract which defines the handler element:

<xs:element name="handler">
  <xs:complexType>
    <xs:attributeGroup ref="commonAttrs"/>
    <xs:attribute name="type" use="required"/>
    <xs:attribute ref="xlink:href"/>
    <xs:attribute ref="ev:event"/>
  </xs:complexType>
</xs:element>     

Attributes:

type = "content-type":

Identifies the language used for the handler element. The value specifies a media type, per RFC2045. Animatable: no.

xlink:href:

If this attribute is present, then the script content of the handler element should be loaded from this resource. Animatable: no.

ev:event:

The name of the event to handle.

For compiled languages, the xlink:href attribute has the same meaning as the combination of the classid and codebase attributes in HTML 4.01. The reference must resolve to a class that implements the XMLEventHandler interface (described below).

6.2.1 Parameters to handler elements

In many situations, the script author uses the handler as a template for calling other functions, using the content of the handler element to pass parameters. However, for compiled languages the handler element does not have any executable content.

In this case, the author should embed the parameters into the handler as custom content. The execution of the handler code retrieves the contents of the parameters using the DOM.

Below is an example of using parameters on the handler element:

<svg xmlns="http://www.w3.org/2000/svg" version="1.2"
     xmlns:ev="http://www.w3.org/2001/xml-events"
     xmlns:foo="http://www.example.com/foo">

  <rect id="myRect" x="10" y="20" width="200" height="300" 
        fill="red"/>

  <!-- register a listener for a myRect.click event -->
  <ev:listener ev:event="click" ev:observer="myRect"
               ev:handler="#myClickHandler" />

  <handler id="myClickHandler" type="application/java"
           xlink:href="http://example.com/myJar.jar#com.example.MyXMLEventHandler"/>
      <foo:offset value="10"/>
      <foo:person>
         <foo:name>Victor Vector</foo:name>
         <foo:age>42</foo:age>
      </foo:person>
  </handler>

</svg>

In this case, the object com.example.MyXMLEventHandler has its handleEvent method called whenever a 'click' event on the 'myRect' object is observed. The object can then retrieve the children of the handler element in order to obtain the contents of the elements from the "foo" namespace.