4 septembre 2001

Appendice B : Le Modèle Objet du Document (DOM) de SVG


Contenu

Cet appendice est normatif.

B.1 Aperçu du DOM de SVG

Cet appendice fournit une introduction au DOM de SVG et traite des relations entre le DOM de SVG et la spécification du Modèle Objet du Document (DOM), niveau 2 [DOM2]. Les interfaces propres au DOM de SVG, qui correspondent aux sections particulières de la spécification SVG, sont définies à la fin des chapitres correspondants dans cette spécification, comme suit :

Le DOM de SVG est construit sur, est compatble avec la spécification du Modèle Objet du Document (DOM), niveau 2 [DOM2]. Notamment :

Une application DOM peut faire appel à la méthode hasFeature de l'interface DOMImplementation pour vérifier la reconnaissance des interfaces listées dans cette section. La liste des interfaces disponibles est fournie dans la section Les chaînes de fonctionnalité pour l'appel de la méthode hasFeature.

B.2 Les conventions de nommage

Le DOM de SVG emprunte des conventions de nommage similaires à celles du Modèle Objet du Document HTML [DOM1-HTML].

Tous les noms sont définis par un ou plusieurs mots en anglais, concaténés ensemble pour former une seule chaîne. Les noms des propriétés ou des méthodes ont leur mot-clé initial en bas de casse et chaque mot subséquent commence avec une lettre en capitale. Par exemple, une propriété qui retourne une méta-information d'un document, telle que la date de création du fichier, pourrait se nommer « fileDateCreated ». Dans la corrélation avec ECMAScript, les propriétés sont exposées comme propriétés d'un objet donné. Dans Java, les propriétés sont exposées avec les méthodes get et set.

Pour les attributs avec le type de données CDATA, la casse de la valeur retournée est celle donnée dans le document source.


B.3 L'interface SVGException

Exception SVGException

Cette exception est déclenchée quand une opération SVG spécifique est impossible à réaliser.


Définition IDL
exception SVGException {
  unsigned short   code;
};

// SVGExceptionCode
const unsigned short SVG_WRONG_TYPE_ERR           = 0;
const unsigned short SVG_INVALID_VALUE_ERR        = 1;
const unsigned short SVG_MATRIX_NOT_INVERTABLE    = 2;
          

B.4 Les chaînes de fonctionnalité pour l'appel de la méthode hasFeature

Les chaînes de fonctionnalité disponibles, pour l'appel de la méthode hasFeature, qui font partie de la gestion du DOM de SVG de l'interface DOMImplementation, définie dans [DOM2-CORE], sont les mêmes chaînes de fonctionnalité pour l'attribut requiredFeatures, qui s'applique à de nombreux éléments SVG.

Pour toutes les fonctionnalités qui correspondent au langage SVG et qui sont documentées dans cette spécification (voir la section L'attribut requiredFeatures pour une liste de fonctionnalités dans le langage SVG), le numéro de version pour l'appel de la méthode hasFeature est "1.0". Pour les fonctionnalités qui correspondent à d'autres langages, se reporter aux spécifications concernées pour déterminer le numéro de version adéquat pour la fonctionnalité en question.


B.5 Les relations avec le modèle des événements de DOM2

Le DOM de SVG gère les interfaces et les types d'événement de [DOM2-EVENTS] suivants :

Chaque élément SVG, auquel au moins un attribut d'événement est assigné dans la DTD de SVG, gère les interfaces d'enregistrement d'événement de DOM2 [DOM2-EVREG] et peut être enregistré comme guetteur d'événement pour l'événement DOM2 correspondant, en utilisant ces interfaces d'enregistrement d'événement. Ainsi, par exemple, si le DTD de SVG signale qu'un élément donné gère l'attribut d'événement "onclick", alors un guetteur d'événement pour l'événement "click" peut être enregistré, avec l'élément donné comme cible de l'événement.

Les éléments d'animation de SVG gèrent également les interfaces d'enregistrement d'événement [DOM2-EVREG]. Les guetteurs d'événement pour les événements d'animation (i.e., start, end ou repeat) peuvent être enregistrés sur tous les éléments d'animation.

Les guetteurs d'événement, qui sont établis pour les interfaces d'enregistrement d'événement de DOM2 [DOM2-EVREG], reçoivent les événements avant tous les guetteurs d'événement qui correspondent aux attributs d'événement (voir la section Les attributs d'événement) ou aux animations. « errata 2002-06-06 »

En Java, une manière pour établir des guetteurs d'événement consiste à définir une classe qui implémente l'interface EventListener, comme :

class MonAction1 implements EventListener {
  public void handleEvent(Event evt) {
    // traite l'événement
  }
}
// ... plus loin ...
MonAction1 mc1 = new MonAction1();
myElement.addEventListener("DOMActivate", mc1, false);

En ECMAScript, une manière pour établir un guetteur d'événement consiste à définir une fonction puis de passer le nom de cette fonction à la méthode addEventListener :

function monAction1(evt) {
  // traite l'événement
}
// ... plus loin ...
myElement.addEventListener("DOMActivate", monAction1, false)

En ECMAScript, le contenu de données textuelles d'un attribut d'événement devient la définition de la fonction ECMAScript qui est invoquée en réponse à l'événement. Comme pour toutes les fonctions de guet d'événement ECMAScript enregistrées, cette fonction reçoit un objet Event en paramètre et le nom de cet objet est evt. Par exemple, il est possible de faire :

<rect onactivate="MonGestionnaireActivation(evt)" .../>

ce qui transmettra l'objet Event evt à la fonction MonGestionnaireActivation.

B.6 Les relations avec le modèle objet CSS (CSS OM) de DOM2


B.6.1 Introduction

Cette section décrit les facilités du Modèle Objet du Document CSS [DOM2-CSS], le modèle objet de CSS, qui font partie du DOM de SVG.

B.6.2 Les agents utilisateurs qui ne gèrent pas le style avec CSS

Les agents utilisateurs qui ne gèrent pas le style avec CSS ne sont seulement tenus que de reconnaître les interfaces suivantes de [DOM2-CSS], ainsi que toute interface nécessaire pour leur implémentation, comme les interfaces CSSPrimitiveValue et CSSValueList. Ces interfaces s'utilisent en conjonction avec l'appel de méthode getPresentationAttribute de l'interface SVGStylable. Cette méthode doit être gérée par toutes les implémentations du DOM de SVG. Les interfaces de DOM2-CSS indispensables :

B.6.3 Les agents utilisateurs qui gèrent le style avec CSS

Les agents utilisateurs qui gèrent le style avec CSS, soit le DOM de SVG et le style auditif [CSS2-AURAL vf.], doivent gérer toutes les interfaces définies dans [DOM2-CSS] qui s'appliquent aux propriétés auditives.

Pour les médias visuels [CSS2-VISUAL vf.], le DOM de SVG gère toutes les interfaces requises définies dans [DOM2-CSS]. Toutes les interfaces optionnelles pour [DOM2-CSS] sont aussi optionnelles pour le DOM de SVG.

B.6.4 Les interfaces développées

Que l'agent utilisateur gère, ou non, le style avec CSS, il doit malgré tout gérer l'interface CSSValue, étant donné que c'est le type retourné par un appel de la méthode getPresentationAttribute sur l'interface SVGStylable.

La spécification [DOM2-CSS] définit un jeu d'interfaces développées [DOM2-CSS-EI] pour une utilisation en conjonction avec l'interface CSSValue. Le tableau ci-dessous spécifie le type de CSSValue [DOM2-CSSVALUE] qui est utilisé pour représenter chaque propriété SVG concernant les médias visuels [CSS2-VISUAL vf.]. On attend de la valeur CSSValue, retournée par la méthode getPropertyCSSValue sur l'interface CSSStyleDeclaration ou par la méthode getPresentationAttribute sur l'interface SVGStylable, que celle-ci soit ramenée, en utilisant des méthodes de forçage de type corrélées spécifiques, vers l'interface dérivée donnée.

Pour celles des propriétés qui sont représentées par une interface personnalisée (l'attribut valueType de l'interface CSSValue a la valeur CSS_CUSTOM), le nom de l'interface dérivée est spécifié dans le tableau. Pour ces propriétés, le tableau précise quelles interfaces sont mandataires et lesquelles ne le sont pas.

Pour les propriétés qui consistent en listes de valeurs (l'attribut valueType de l'interface CSSValue a la valeur CSS_VALUE_LIST), l'interface dérivée est CSSValueList. Pour toutes les autres propriétés (l'attribut valueType de l'interface CSSValue a la valeur CSS_PRIMITIVE_VALUE), l'interface dérivée est CSSPrimitiveValue.

Pour les propriétés raccourcies, l'interface CSSValue aura toujours une valeur de null. Les valeurs des propriétés raccourcies ne peuvent être atteintes et modifiées que comme chaînes.

Le DOM de SVG définit les interfaces de propriété personnalisées spécifiquement SVG suivantes, toutes étant mandataires pour un agent utilisateur SVG :

Nom de propriété Représentation Mandataire ?
(seulement
interface
développée)
'alignment-baseline' identifiant  
'baseline-shift' identifiant, longueur, pourcentage  
'clip' rect, identifiant  
'clip-path' uri, identifiant  
'clip-rule' identifiant  
'color' rgbcolor, identifiant  
'color-interpolation' identifiant  
'color-profile' liste de chaînes, uri et identifiants  
'color-rendering' identifiant  
'cursor' uri, identifiant non
'direction' identifiant  
'display' identifiant  
'dominant-baseline' identifiant  
'enable-background' liste d'identifiants et de nombres  
'fill' SVGPaint oui
'fill-opacity' nombre  
'fill-rule' identifiant  
'filter' uri, identifiant  
'flood-color' SVGColor oui
'flood-opacity' nombre  
'font' null  
'font-family' liste de chaînes et identifiants  
'font-size' identifiant, longueur, pourcentage  
'font-size-adjust' nombre, identifiant  
'font-stretch' identifiant  
'font-style' identifiant  
'font-variant' identifiant  
'font-weight' identifiant  
'glyph-orientation-horizontal' identifiant  
'glyph-orientation-vertical' identifiant  
'image-rendering' identifiant  
'kerning' identifiant, longueur  
'letter-spacing' identifiant, longueur  
'lighting-color' SVGColor oui
'marker' null  
'marker-end' uri, identifiant  
'marker-mid' uri, identifiant  
'marker-start' uri, identifiant  
'mask' uri, identifiant  
'opacity' nombre  
'overflow' identifiant  
'pointer-events' identifiant  
'shape-rendering' identifiant  
'stop-color' SVGColor oui
'stop-opacity' nombre  
'stroke' SVGPaint oui
'stroke-dasharray' identifiant ou liste de longueurs  
'stroke-dashoffset' longueur  
'stroke-linecap' identifiant  
'stroke-linejoin' identifiant  
'stroke-miterlimit' longueur  
'stroke-opacity' nombre  
'stroke-width' longueur  
'text-anchor' identifiant  
'text-decoration' liste d'identifiants  
'text-rendering' identifiant  
'unicode-bidi' identifiant  
'visibility' identifiant  
'word-spacing' longueur, identifiant  
'writing-mode' identifiant  

B.7 Les valeurs illégales

Si un script assigne une valeur invalide à un attribut DOM (par exemple, un nombre négatif pour un attribut qui requiert un nombre positif ou une valeur hors-limite pour une énumération), à moins que cette spécification ne l'indique autrement, aucune exception ne sera déclenchée à l'initialisation, néanmoins, le document en question entrera techniquement en erreur comme décrit dans la section Le traitement des erreurs.