Events in CellML

CellML Events provide a mechanism by which changes to a CellML Document can be monitored. This could, for example, be used to update a graphical display of a model when mathematics changes.

Abstract

CellML Events provide a mechanism by which changes to a CellML Document can be monitored. This could, for example, be used to update a graphical display of a model when mathematics changes.

General approach

CellML Events are defined based on the DOM Level 2 Events defined by the World Wide Web Consortium. The events::EventListener, events::EventTarget, and events::Event interfaces defined by that specification are used in this specification. However, a new interface, inheriting from events::Event, is defined for handling CellML Events.

Although DOM events were originally designed to be used with the Document Object Model, the interfaces used in this specification do not reference the DOM at all. Instead, they define a general base class called EventTarget, and the specification stipulates that conforming implementations make DOM nodes support this interface. In this specification, however, EventTargets are implemented by both DOM nodes and CellMLElements.

The events specified in this specification can only be registered by addEventListener on EventTargets which are CellMLElement objects. They cannot be registered on DOM nodes, even when those DOM nodes represent MathML, extension elements, RDF elements(or even CellML elements, if an application is dealing with the DOM as well as the CellML API). Applications wanting detail on changes to extension elements, MathML elements, or RDF elements should use the DOM Level 2 Events API instead.

CellML events always follow the dispatch procedure for event bubbling; event capture is never supported and attempting to call addListener with useCapture set to true will result in an exception being raised.

In some situations, the target attribute of an Event is defined as a DOM node. In this case, the order of dispatch operations will remain unchanged, but CellML events will not actually be dispatched to EventTargets which are not CellMLElement objects. This means that the first element on which listeners may be called(if present) is the first CellMLElement ancestor of the target. The currentTarget will always be set to the CellMLElement to which the event is being dispatched.

CellML MutationEvent interface

module cellml_events
{
/*
 *  This interface represents an modification event in the cellml document
 */
interface MutationEvent : events::Event
{
  /**
   * For an attribute change notification, describes the type of change...
   */
  const unsigned short      MODIFICATION              = 1;
  const unsigned short      ADDITION                        = 2;
  const unsigned short      REMOVAL                         = 3;

  /**
   * The CellML Element which is related to this change(see specification for
   *   details on when this is present, and its exact value).
   */
  readonly attribute CellMLElement    relatedElement;

  /**
   * Previous value of an attribute being changed.
   */
  readonly attribute DOMString        prevValue;

  /**
   * New value of an attribute being changed.
   */
  readonly attribute DOMString        newValue;

  /**
   * The localName of the attribute being changed(or the nodeName if the
   *  localName is null or the empty string).
   */
  readonly attribute DOMString        attrLocalName;

  /**
   * The namespaceURI of the attribute being changed.
   */
  readonly attribute DOMString        attrNamespaceURI;

  /**
   * For an attribute change, one of ADDITION, REMOVAL, or MODIFICATION.
   */
  readonly attribute unsigned short   attrChange;
};
};

 

Supported types of CellML Events

  • MathModified
This event occurs when:
  • A DOM node 'A' (of type text or element) is inserted into or removed from a parent node 'B' in the MathML namespace, and the nearest ancestor 'C' of 'B', such that 'C' is not in the MathML namespace, is in a CellML namespace.
  • An attribute 'A' is modified on an element 'B' in the MathML namespace, and the nearest ancestor 'C' of 'B', such that 'C' is not in the MathML namespace, is in a CellML namespace.
  • A DOM Text node 'A'(including CDATASection text nodes), with a parent node 'B' in the MathML namespace, is modified, and the nearest ancestor 'C' of 'B', such that 'C' is not in the MathML namespace, is in a CellML namespace.
The target of the event 'D' is the MathML element ancestor of 'B' such that 'C' is the parent of 'D'. The relatedElement holds the CellMLElement corresponding to 'C'.

Applications wishing to receive finer grained notifications of MathML changes should use DOM Level 2 mutation events instead.
  • MathInserted
This event occurs when a MathMLMathElement 'A' is inserted into a CellMLElement 'B'. The target of the event is 'A'. The relatedElement holds 'B'.
  • MathRemoved
This event occurs when a MathMLMathElement 'A' is removed from a CellMLElement parent 'B'. The target of the event is 'A'. The relatedElement holds 'B'.
  • CellMLElementInserted
This event occurs when a CellMLElement 'A' is inserted into a CellMLElement 'B'. The target of the event is 'A'. The relatedElement holds 'B'.
  • CellMLElementRemoved
This event occurs when a CellMLElement 'A' is removed from a CellMLElement parent 'B'. The target of the event is 'A'. The relatedElement holds 'B'.
  • CellMLAttributeChanged
This event occurs when an attribute 'A' on a CellMLElement 'B' is added, modified, or removed. The target is 'B'. The attrLocalName attribute holds the localName of 'A', or where the localName is null or the empty string, holds the nodeName of 'A', The attrNamespaceURI attribute holds the namespaceURI of 'A'. The attrChange attribute holds one of the constant values ADDITION, REMOVAL, or MODIFICATION. prevValue holds the previous value of 'A'(or the empty string in the case of addition). newValue holds the new value of 'A'(or the empty string in the case of removal).
  • ExtensionElementInserted
This event occurs when an element not in the CellML, MathML, or RDF namespaces 'A' is inserted into a CellMLElement 'B'. The target of the event is 'A'. The relatedElement holds 'B'.
  • ExtensionElementRemoved
This event occurs when an element not in the CellML, MathML, or RDF namespaces 'A' is removed from a CellMLElement parent 'B'. The target of the event is 'A'. The relatedElement holds 'B'.