Page de couverture | Retour au fichier XCF de WebCGM | Vers le profil

WebCGM 2.0 : Le modèle DOM de WebCGM

5. Le modèle objet de document (DOM) de WebCGM

Cette section et ses sous-sections sont normatives, sauf indication contraire.

5.1 Vue d'ensemble

Cette sous-section est informative (non normative).

Ce chapitre définit un ensemble d'objets et d'interfaces pour l'accès et le traitement des documents WebCGM. La fonctionnalité décrite dans cette section permet aux créateurs de scripts de manipuler les documents WebCGM et d'accéder aux informations trouvées dans le fichier d'accompagnement XML normalisé de WebCGM. L'interface de programmation (API) du DOM de WebCGM 2.0 concentre ses méthodes sur la traversée de l'arbre, les changements de style et l'accès aux métadonnées.

5.2 Les relations avec le modèle DOM de XML

Cette sous-section est informative (non normative).

Bien qu'il s'inspire des spécifications DOM de XML, le modèle DOM de WebCGM reste orienté vers une fonctionnalité WebCGM spécifique. Puisque WebCGM utilise une structure d'arbre pour regrouper les primitives graphiques, il était de fait approprié d'employer un jeu d'interfaces similaires aux interfaces Node, Element et Document du DOM de XML. Toutefois, comme WebCGM est exprimé dans une syntaxe non-XML, plusieurs changements ont dû être apportés aux interfaces et méthodes connues afin d'améliorer l'expérience d'utilisateur des créateurs de scripts WebCGM.

Le DOM de WebCGM pourrait presque être perçu comme un DOM « en lecture seule ». Quelques méthodes d'interfaces permettent aux utilisateurs de changer l'apparence visuelle des structures d'application, mais contrairement à la spécification DOM XML, elles ne permettent pas la suppression ou l'insertion d'objets de type WebCGMNode dans le modèle d'objets. C'est une différence importante entre les spécifications.

Tandis que WebCGM 1.0 offre une interactivité via l'hyperliaison et la mise en évidence, le DOM de WebCGM 2.0 porte celle-ci au stade suivant. Le modèle DOM de WebCGM 2.0 emprunte des concepts de la spécification DOM3 Events, et introduit le concept de guetteurs d'événements (N.d.T. EventListeners) et d'événements de souris pour satisfaire aux besoins des utilisateurs WebCGM.

5.3 Les relations avec le fichier d'accompagnement XML

Le DOM de WebCGM est conçu pour accéder aux métadonnées XML trouvées dans les fichiers d'accompagnement XML. L'expérience a montré que certaines illustrations CGM sont plus faciles d'entretien si certaines informations non graphiques restent hors de l'illustration. Un exemple de telles informations seraient celui d'infobulles sensibles à la langue. On peut alors utiliser le DOM de WebCGM pour « appliquer » les informations du fichier d'accompagnement XML au document WebCGM (cf. l'exemple 5.3). Pour plus de renseignements sur la syntaxe du fichier d'accompagnement XML, veuillez consulter le chapitre « 4. Le fichier d'accompagnement XML de WebCGM ».

Un autre avantage du fichier d'accompagnement XML est de porter les données (ou métadonnées) spécifiques d'une application concernant une illustration WebCGM (cf. l'exemple 4.2). Ces informations sont exprimées en utilisant les attributs et éléments d'un espace de noms dans le fichier d'accompagnement XML. Le DOM de WebCGM fournit une méthode pour charger les métadonnées XML dans le modèle d'objets de l'agent utilisateur. En utilisant le DOM de WebCGM, l'utilisateur peut accéder aux métadonnées. Voici un exemple détaillé pour mieux illustrer le concept.

BEGMF 'example.cgm';
...
BEGPIC 'Picture 1';
...
BEGAPS 'L1' 'layer' STLIST;
  APSATTR 'layername' "14 1 'Standard layer'";
  BEGAPSBODY;
  BEGAPS 'G1' 'grobject' STLIST;
    BEGAPSBODY;
    LINE 210,265 210,200 300,200;
    LINE 300,200 300,265 210,265;
  ENDAPS;
ENDAPS;
...
ENDPIC;
...
ENDMF;

La représentation de l'arbre en mémoire de cette illustration devrait être similaire à l'illustration trouvée ci-dessous. Le métafichier contient une image, l'image contient un sous-nœud de structure d'application de type layer, et la structure layer contient un sous-nœud de structure d'application de type grobject, comme illustré dans la figure n° 7.

Figure n° 7. Structure originale de l'arbre

<webcgm id="example" xmlns:wiring="http://www.example.org">
    <grobject apsId="G1" apsid="G1" screentip="A new screentip">
        <wiring:data wire-bundle="E132-NAV"/>
    </grobject>
</webcgm>

Le DOM de WebCGM fournit des méthodes pour l'« application » d'un fichier d'accompagnement XML, comme celui montré dans l'exemple 5.1b, à une image dans un document WebCGM. Un agent utilisateur conforme est censé charger et analyser le fichier d'accompagnement XML, et « appliquer » peut-être des mises à jour du fichier d'accompagnement au modèle d'objets de l'agent utilisateur. Un utilisateur peut vouloir appliquer un fichier d'accompagnement pour les raisons suivantes :

1. Pour remplacer les valeurs des attributs de structures d'application standards présents dans l'instance WebCGM par de nouvelles valeurs du fichier d'accompagnement XML ;
2. Pour procurer des valeurs d'attributs de structures d'application standards aux structures d'application qui ne contiennent pas de valeurs d'attributs à partir de valeurs du fichier d'accompagnement XML ;
3. Pour modifier temporairement les propriétés de style (stroke-color, text-size, etc.) pour l'affichage d'un objet (APS ou image) ;
4. Pour ajouter des métadonnées XML au modèle d'objets de l'agent utilisateur, à récupérer ultérieurement en utilisant les interfaces de programmation DOM de WebCGM.

Une fois le fichier d'accompagnement XML chargé dans le modèle en mémoire de l'agent utilisateur, l'arbre devrait ressembler à ceci :

Figure n° 8. La nouvelle structure de l'arbre

L'ensemble de règles générales que doit suivre un agent utilisateur pour l'application d'un fichier d'accompagnement XML est le suivant :

1. Vérifier que l'élément racine est bien webcgm, sinon interrompre tout traitement et lancer une exception FILE_INVALID_ERR ;
2. Traiter, le cas échéant, les attributs inconnus sur l'élément racine, voir ci-dessous le traitement des attributs d'espaces de noms ;
3. Traiter tous les sous-éléments en utilisant un algorithme de profondeur.

Les règles plus spécifiques du traitement des attributs d'espaces de noms sont les suivantes :

1. Si la structure d'application cible n'est pas présente dans le fichier CGM, tous les attributs de l'élément courant sont ignorés ;
2. Si l'attribut ne fait pas partie de la définition DTD de base de WebCGM, alors celui-ci doit être un attribut d'espace de noms étendu, sinon l'attribut est ignoré ;
3. Un attribut déjà présent sur la structure d'application correspondante doit être mis à jour avec la nouvelle valeur d'attribut ;
4. Au cas où un attribut avec les mêmes nom local et adresse IRI d'espace de noms est déjà présent sur la structure d'application, son préfixe change pour devenir la partie préfixe du nom qualifié (qualifiedName) et sa valeur change pour devenir la valeur d'attribut. Si l'attribut n'existe pas sur la structure d'application, l'attribut d'espace de noms lui est ajouté.

Les règles plus spécifiques du traitement des sous-éléments sont les suivantes :

1. La structure d'application cible (l'élément parent) doit être présent dans le fichier CGM, sinon tous les sous-éléments de l'élément courant sont ignorés. La structure d'application cible ne doit pas être de type grnode. Les éléments grnode ne sont pas accessibles via des appels DOM ;
2. Si l'élément ne fait pas partie de la définition DTD de base de WebCGM, alors celui-ci doit être un élément d'espace de noms étendu. Les éléments d'espaces de noms et leurs attributs sont ajoutés à la fin de la liste de sous-éléments de la cible ;
3. Les éléments définis dans la définition DTD de WebCGM sont traités comme suit :
   • Les attributs d'espaces de noms sont traités comme décrit précédemment ;
   • Les attributs pertinents de cet élément sont mis à jour sur la structure d'application ;
   • Les autres attributs sont ignorés.
4. Si c'est un élément linkuri, les règles suivantes s'appliquent :
   • S'il existe un ou plusieurs attributs linkuri sur l'élément parent, ils sont tous effacés et remplacés par le jeu correspondant d'attributs linkuri du fichier XCF. Il n'est pas possible d'ajouter des liens du fichier XCF à des liens déjà existants ;
   • Les attributs de chaque élément linkuri sont combinés pour créer un seul attribut APS linkuri WebCGM (comme défini dans WebCGM 1.0) sur l'élément parent.
5. Si c'est un élément bindById, seuls les attributs d'espaces de noms et les attributs pertinents au type de la structure APS cible sont ajoutés à la cible (c'est-à-dire, si l'élément bindById a un attribut screentip et que la structure APS cible est de type layer, l'attribut screentip sera ignoré) ;
6. Si c'est un élément bindByName, l'agent utilisateur doit trouver toutes les structures d'application dont les attributs name ou layername correspondent. Toutes les structures d'application identifiées reçoivent alors de nouvelles valeurs d'attributs (cf. la description de bindById ci-dessus).

5.4 L'héritage des attributs APS et des propriétés de style

Cette section décrit comment les attributs APS sont hérités dans un arbre de structures WebCGM. Elle décrit également l'héritage des propriétés de style, qui est similaire mais en diffère par quelques détails clés. Ces modèles d'héritage sont très proches du modèle d'héritage de CSS 2.0. Certains détails ont été adaptés aux particularités du format WebCGM. Ce chapitre constitue la référence normative de l'héritage des attributs APS et des propriétés de style dans WebCGM.

5.4.1 Les valeurs spécifiées, calculées et réelles des propriétés de style

Les agents utilisateurs WebCGM 2.0 sont tenus d'utiliser le modèle d'héritage des propriétés de style défini dans cette section. Une fois le document chargé et l'arbre du document construit par l'agent utilisateur, celui-ci doit assigner une valeur à chaque propriété de style, pour chaque structure d'application dans l'arbre.

Très similaire au modèle CSS, la valeur finale d'une propriété de style est le résultat d'un calcul en quatre étapes : la valeur est déterminée au travers de la spécification (la « valeur spécifiée »), puis celle-ci se résoud en une valeur utilisable pour l'héritage (la « valeur calculée »), celle-ci est convertie ensuite si nécessaire en une valeur absolue (la « valeur utilisée »), et enfin transformée en fonction des limitations de l'environnement local (la « valeur réelle »).

5.4.1.1 Les valeurs spécifiées des propriétés de style

Les agents utilisateurs doivent d'abord assigner une valeur spécifiée à chaque propriété de style en se fondant sur les mécanismes suivants (en ordre de priorité) :

1. Si la propriété de style a reçu une valeur (via un appel DOM ou via un fichier XCF), alors l'utiliser ;
2. Sinon, si la propriété de style est héritée (c'est-à-dire que sa définition contient « Héritée : oui ») et que la structure d'application n'est pas la racine de l'arbre du document, utiliser la valeur calculée de la structure d'application parente ;
3. Sinon utiliser la valeur initiale de la propriété de style. La valeur initiale de chaque propriété de style est indiquée dans sa définition.

Remarque : Dans le contexte de l'héritage WebCGM, la racine de l'arbre du document est le nœud PICTURE.

5.4.1.2 Les valeurs calculées des propriétés de style

Les valeurs spécifiées se résolvent en valeurs calculées après que l'arbre du document a été créé.

• Si la valeur spécifiée n'est pas "inherit", la valeur calculée d'une propriété de style est déterminée comme indiqué par la ligne « Valeur calculée » dans la définition de la propriété ;
• Si la valeur spécifiée est "inherit", elle doit être remplacée par la valeur calculée telle que définie ci-dessous dans la section à propos de l'héritage.

La valeur calculée existe même si la propriété ne s'applique pas, comme définie par la ligne « S'applique à ».

5.4.1.3 Les valeurs utilisées des propriétés de style

Dans le modèle CSS2 dont le modèle WebCGM est dérivé, les valeurs calculées peuvent être relatives entre elles ; par exemple, une largeur peut être fixée en pourcentage, qui dépend de la largeur du bloc conteneur. La valeur utilisée est le résultat de la résolution de ces dépendances de la valeur calculée en une valeur absolue finale utilisée pour l'affichage réel. Dans cette version de WebCGM, il n'y a aucun exemple où la valeur utilisée diffère de la valeur calculée. Cela pourrait changer dans une version future de la spécification.

5.4.1.4 Les valeurs réelles des propriétés de style

La valeur utilisée est, en principes, la valeur servant au rendu, mais l'agent utilisateur sera peut-être incapable d'exploiter la valeur dans un environnement donné. Par exemple, l'agent utilisateur est peut-être seulement capable de rendre des bordures avec des épaisseurs en pixels entiers et, par conséquent, doit faire une approximation de l'épaisseur calculée, ou l'agent utilisateur est peut-être obligé d'utiliser des nuances de noir et blanc au lieu de couleurs réelles. La valeur réelle est la valeur utilisée après que toutes les approximations ont été appliquées.

5.4.2 Les valeurs spécifiées, calculées et réelles des attributs de structures d'application

Les agents utilisateurs WebCGM 2.0 sont tenus d'utiliser le modèle d'héritage des attributs de structures d'applications (APS) défini dans cette section. Une fois le document chargé et l'arbre du document construit par l'agent utilisateur, celui-ci doit établir, pour toutes les structures d'application dans l'arbre, si un attribut a une valeur (à savoir que certains attributs n'ont aucune valeur possible).

Très similaire au modèle CSS, la valeur finale d'un attribut APS est le résultat d'un calcul en quatre étapes : la valeur est déterminée au travers de la spécification (la « valeur spécifiée »), puis celle-ci se résoud en une valeur utilisable pour l'héritage (la « valeur calculée »), celle-ci est convertie ensuite si nécessaire en une valeur absolue (la « valeur utilisée », et enfin transformée en fonction des limitations de l'environnement local (la « valeur réelle »).

5.4.2.1 Les valeurs spécifiées des attributs de structures d'application

Les agents utilisateurs doivent d'abord assigner une valeur spécifiée à chaque attribut APS en se fondant sur les mécanismes suivants (en ordre de priorité) :

1. Si l'attribut a reçu une valeur dans le document CGM ou une nouvelle valeur via un appel DOM ou un fichier XCF, alors l'utiliser ;
2. Sinon, si l'attribut est hérité (c'est-à-dire que sa définition contient « Hérité : oui ») et que la structure d'application n'est pas la racine de l'arbre du document, alors utiliser la valeur calculée de la structure d'application parente ;
3. Sinon utiliser la valeur initiale de l'attribut. La valeur initiale de chaque attribut est indiquée dans sa définition.

Dans le contexte de l'héritage WebCGM, la racine de l'arbre du document est le nœud PICTURE.

5.4.2.2 Les valeurs calculées des attributs de structures d'application

Dans cette spécification, les valeurs calculées des attributs de structures d'application, à l'exception de la valeur "inherit", sont identiques aux valeurs spécifiées. Lorsque la valeur spécifiée est "inherit", elle doit être remplacée par la valeur calculée comme défini ci-dessous dans la section à propos de l'héritage. La valeur calculée existe même si l'attribut ne s'applique pas (comme défini par la ligne « S'applique à » dans la définition de l'attribut).

5.4.2.3 Les valeurs utilisées des attributs de structures d'application

Dans le modèle CSS2 dont le modèle WebCGM est dérivé, les valeurs calculées peuvent être relatives entre elles ; par exemple, une largeur peut être fixée en pourcentage, qui dépend de la largeur du bloc conteneur. La valeur utilisée est le résultat de la résolution de ces dépendances de la valeur calculée en une valeur absolue finale utilisée pour l'affichage réel. Dans cette version de WebCGM, il n'y a aucun exemple où la valeur utilisée diffère de la valeur calculée. Cela pourrait changer dans une version future de la spécification.

5.4.2.4 Les valeurs réelles des attributs de structures d'application

La valeur utilisée est, en principes, la valeur servant au rendu, mais l'agent utilisateur sera peut-être incapable d'exploiter la valeur dans un environnement donné. Par exemple, l'agent utilisateur est peut-être seulement capable de rendre des bordures avec des épaisseurs en pixels entiers et, par conséquent, doit faire une approximation de l'épaisseur calculée, ou l'agent utilisateur est peut-être obligé d'utiliser des nuances de noir et blanc au lieu de couleurs réelles. La valeur réelle est la valeur utilisée après que toutes les approximations ont été appliquées.

5.4.3 L'héritage

Certaines valeurs sont héritées par les sous-éléments d'une structure d'application dans l'arbre du document, comme décrit précédemment. Chaque propriété de style et chaque attribut de structure d'application définissent s'ils sont hérités ou non. En règle générale, si héritage il y a, les structures d'application héritent des valeurs calculées des propriétés de style et des attributs de structure d'application (sauf déclaration implicite dans la définition de la propriété ou de l'attribut).

5.4.3.1 La valeur "inherit"

Les attributs de structures d'application et les propriétés de style peuvent aussi avoir la valeur spécifiée "inherit", ce qui veut dire que, pour une structure d'application donnée, la propriété ou l'attribut prennent la même valeur calculée que celle de la structure d'application parente. La valeur "inherit" peut être utilisée pour renforcer les valeurs héritées, et peut aussi être utilisée sur les propriétés de style qui ne sont normalement pas héritées. Il n'y a aucun exemple de ce dernier cas dans cette version de WebCGM.

5.5 Les types de données de base

WebCGM consiste en trois composants où les définitions de types de données doivent être examinées : les instances des métafichiers, le modèle DOM et le fichier XCF.

5.5.1 Les types de données des métafichiers

Les instances WebCGM sont des fichiers binaires. Les types de données et codages des métafichiers sont entièrement définis dans le standard CGM:1999, et dans les chapitres 3 et 6 de cette spécification WebCGM.

5.5.2 Les types de données du modèle DOM

5.5.2.1 Les types IDL et les types de liaison

Chaque interface de cette définition du modèle DOM est décrite normativement par une section de code IDL. Le code IDL utilise des types de données de base tels que unsigned short, boolean, long, etc. Les applications DOM sont écrites dans une liaison de langage de programmation, tel que ECMAScript ou Java. La seule liaison définie normativement pour le DOM de WebCGM est la liaison ECMAScript.

La liaison ECMAScript associe sans ambiguïté les types de données du langage ECMAScript aux types de données IDL, qui fournit tous les renseignements nécessaires concernant les types de données pour écrire des applications DOM WebCGM en >ECMAscript.

La valeur de retour "null". Les attributs et les valeurs de retour de méthode du type WebCGMNode et WebCGMNodeList du DOM de WebCGM ont parfois à représenter le cas de l'absence de donnée, c'est-à-dire zéro nœud. Dans la spécification fonctionnelle du modèle DOM de ce chapitre, le terme null est uniformément utilisé pour représenter ce cas. Dans les liaisons DOM telle que la liaison ECMAScript, la valeur de retour null WebCGM correspond naturellement au mot-clé réservé null ECMAScript. (Par exemple, l'expression vraie myNode.childnodes==null et l'expression vraie myPicture.getAppStructureById()==null).

5.5.2.2 Le type WebCGMString

Le type de données WebCGMString est l'un des plus employés dans les définitions IDL, et quelques interfaces DOM définissent des sous-structures ou sous-types de certains attributs et paramètres de type WebCGMString.

WebCGMString

Un objet WebCGMString est une séquence d'unités 16-bit dans le DOM de WebCGM.

Définition IDL

valuetype WebCGMString sequence<unsigned short>;

Dans le DOM de WebCGM, comme dans le DOM niveau 3 de XML, le codage UTF-16 a été choisi à cause de sa pratique répandue dans l'industrie. Pour ECMAScript et Java, le type WebCGMString est lié au type String car les deux langages utilisent également UTF-16 comme codage. Le DOM de WebCGM offre beaucoup d'interfaces impliquant la correspondance des chaînes. Pour XML, les comparaisons de chaînes, sensibles à la casse, sont effectuées avec une comparaison binaire des unités 16-bit des objets WebCGMString.

La chaîne vide. Les attributs et les valeurs de retour des méthodes de type WebCGMString du DOM de WebCGM ont parfois à représenter une chaîne sans donnée, c'est-à-dire zéro caractère. Dans la spécification fonctionnelle du modèle DOM de ce chapitre, le terme chaîne vide est uniformément utilisé pour représenter ce cas. Dans les liaisons DOM telle que la liaison ECMAScript, la chaîne vide WebCGM correspond naturellement à la chaîne vide ECMAScript. (Par exemple, l'expression vraie myEmptyString.length==0 et l'expression vraie myEmptyString=="").

5.5.2.3 Les sous-types de WebCGMString

Le modèle DOM de WebCGM comporte plusieurs attributs ou paramètres WebCGMString qui codent en réalité d'autres données, tels que des nombres, des couleurs, des sous-chaînes, etc., dans un format de chaîne. Pour les besoins de cette spécification, nous définissons les règles suivantes de codage et de représentation des sous-types WebCGMString dans les objets WebCGMString.

Nombre

Une valeur de nombre réel codé dans un objet WebCGMString. La représentation du nombre peut être soit en notation décimale, soit en notation scientifique. La notation décimale consiste soit en un entier, soit en un caractère de signe optionnel suivi de zéro à plusieurs chiffres, suivis d'un point « . », suivi d'un à plusieurs chiffres. La notation scientifique consiste en une représentation en notation décimale suivie immédiatement d'une lettre « e » ou « E », suivie immédiatement d'un entier.

Pourcentage

Un pourcentage codé dans un objet WebCGMString est un nombre suivi d'un caractère pour cent « % ».

Couleur

Une couleur codée dans un objet WebCGMString se compose d'un caractère « # », suivi d'exactement six chiffres hexadécimaux [0-9a-fA-F]. Les deux premiers chiffres représente la composante rouge (red), les deux suivants la composante verte (green) et les deux derniers la composante bleue (blue). Conceptuellement : #RRGGBB. Exemples : #FF0000 est le rouge plein, #e1e1e1 est le fond gris des définitions IDL dans ce chapitre, #00FFFF est le cyan plein, etc.

Liste de nombres

Le bloc EBNF suivant définit la liste de nombres (list-of-number), les nombres (number) étant définis ci-dessus :

list-of-number  ::= number | number Wsp list-of-number
Wsp             ::= (#x20 | #x9 | #xD | #xA)+

Chaîne délimitée (liste de chaînes)

Certains attributs WebCGMString peuvent coder plusieurs sous-chaînes, par exemple, les attributs APS name et linkuri. Pour des raisons historiques, c'est le sous-type Delimited String (bien qu'il s'agisse fonctionnellement d'une « liste de chaînes »).

Le type Delimited String est conforme à la notation suivante :

DelimitedString ::= ListOfX | ListOfXX
ListX           ::= '"'Name'"' | '"'Name'"' Wsp ListX
ListXX          ::= "'"Name"'" | "'"Name"'" Wsp ListXX
Wsp             ::= (#x20 | #x9 | #xD | #xA)+
Name            ::= (ValidChar)*

La définiton de la production ValidChar dépend de l'entité WebCGM particulière qui est codée. Par exemple, dans le tableau des attributs APS d'accès au DOM (dans la section « 5.7.6 L'interface WebCGMAppStructure »), les caractères valides pour chaque attribut APS codé par le type Delimited String sont déterminés par le type de données WebCGM de l'attribut APS particulier (appelé depuis le tableau), en combinaison avec les règles des répertoires de caractères de la section 3.1.1.3.

Dans le cas de l'attribut APS linkuri, la valeur contient toujours 3n chaînes, n représentant le nombre d'attributs linkuri définis sur la structure d'application. Si aucune valeur significative n'est fournie pour un composant, celui-ci doit être représenté par une chaîne vide. La restriction de 3n chaînes simplifie les scripts destinés à manipuler les chaînes de type Delimited String.

Une chaîne délimitée est une liste de sous-chaînes, séparées par des blancs (Wsp). Si la chaîne délimitée ne contient qu'une seule sous-chaîne, alors celle-ci est codée comme une chaîne simple.

Remarque : La syntaxe de ce type Delimited String, lorsqu'elle est combinée à la manipulation de paramètres de type chaîne dans des langages tel que ECMAScript, impose quelques contraintes sur le contenu des sous-chaînes de type Delimited String. En particulier, il ne serait pas possible d'avoir une sous-chaîne contenant à la fois un caractère guillemet double « " » et un caractère apostrophe « ' ».

5.5.3 Les types de données XCF

Le fichier d'accompagnement XML (XCF) fournit un accès à beaucoup d'attributs APS et de propriétés de style identifiables par le DOM de WebCGM. Les attributs APS et les propriétés de style qui apparaissent dans le DOM de WebCGM comme attributs et paramètres de méthodes sont représentés dans le fichier XCF par des attributs XML. Les valeurs sont codées dans les chaînes d'attributs XML du fichier XCF exactement comme elles le seraient dans le type WebCGMString, ou dans un sous-type de WebCGMString, du paramètre ou de l'attribut correspondant dans le DOM de WebCGM.

5.6 Les valeurs de coordonnées - Normalized VDC (NVDC)

Dans une instance WebCGM, la représentation des coordonnées (VDC) est influencée par plusieurs éléments CGM : VDC TYPE, VDC EXTENT et SCALE MODE. WebCGM impose que la valeur de l'élément SCALE MODE soit "metric", mais n'exerce que peu d'autres contraintes. Ainsi, les coordonnées VDC (multipliées par un facteur d'échelle) équivalent à des millimètres, mais le système de coordonnées peut sinon avoir une grande variabilité : l'origine au coin gauche supérieur ou inférieur, à main droite ou à main gauche, des valeurs entières ou réelles (flottantes ou fixes), etc.

Pour simplifier le travail avec les coordonnées, le DOM de WebCGM définit et utilise un système de coordonnées normalisé canonique : le système « Normalized VDC (NVDC) ».

Les unités NVDC sont en millimètres, dans un système de coordonnées où l'origine correspond au coin inférieur gauche de l'étendue VDC, avec l'axe des X pointant vers la droite et l'axe des Y pointant vers le haut. Les exemples suivants illustrent la correspondance entre les valeurs NVDC et VDC de plusieurs instances WebCGM.

5.7 Les interfaces fondamentales

Les interfaces dans cette section sont jugées fondamentales et elles doivent être entièrement mises en œuvre par toutes les mises en œuvre conforme du DOM de WebCGM. Le DOM de WebCGM présente les documents WebCGM comme une hiérarchie d'objets WebCGMNode qui utilisent également d'autres interfaces plus spécialisées. Certains types de nœuds peuvent avoir des sous-nœuds de types variés, d'autres sont des nœuds terminaux qui ne peuvent pas contenir autre chose dans la structure de document WebCGM. WebCGM comprend les types de nœuds suivants :

WebCGMMetafile — contient une liste de nœuds WebCGMPicture.

WebCGMPicture — peut contenir des sous-nœuds WebCGMAppStructure ou des sous-nœuds de métadonnées XML.

WebCGMAppStructure — peut contenir des sous-nœuds WebCGMAppStructure ou des sous-nœuds de métadonnées XML.

WebCGMAttr — aucun sous-élément.

Le DOM de WebCGM définit également plusieurs autres interfaces afin de faciliter l'accès aux attributs WebCGM. L'interface GetWebCGMDocument est le médium entre l'environnement hôte et la fonctionnalité WebCGM. L'interface WebCGMNodeList permet de manipuler des listes ordonnées d'objets WebCGMNode. L'interface WebCGMEvent fournit une information contextuelle concernant les événements de souris. Les objets WebCGMNodeList dans le DOM sont vivants, c'est-à-dire que les changements de la structure de document sous-jacente sont reflétés dans tous les objets NodeList pertinents. Par exemple, si un utilisateur du DOM récupère un objet WebCGMNodeList contenant les sous-éléments d'un objet WebCGMAppStructure, alors les changements sur l'un de ses sous-éléments dans l'arbre sont tous reflétés dans les objets NodeList et, en fait, dans toutes les références à ce nœud dans les objets NodeList.

Le nœud WebCGMPicture est la racine de l'arbre du document pour les besoins du DOM et du modèle d'héritage :

• Quoiqu'il puisse sembler naturel que WebCGMMetafile hérite de WebCGMNode, le profil WebCGM adopte le point de vue que le métafichier est simplement un paramètre fictif (N.d.T. placeholder) pour les informations de formatage de données génériques de l'image (ou des images) dans le métafichier ;
• La racine d'héritage (cf. le modèle d'héritage) devrait correspondre à l'élément racine webcgm du fichier d'accompagnement XML (XCF), et la conception XCF a déterminé que les fichiers d'accompagnement devraient être par image ;
• Bien que WebCGM soit un profil à une seule image, la possibilité d'extension à des profils multi-images est déjà prévue dans les interfaces, et cette extensibilité repose sur le fait que l'image soit la racine (d'héritage) de l'arbre DOM.

5.7.1 L'exception WebCGMException

Les opérations WebCGM ne soulèvent des exceptions que si elles sont impossibles à réaliser.

Définition IDL

exception WebCGMException { unsigned short code; }; // ExceptionCode const unsigned short INDEX_SIZE_ERR = 1; const unsigned short WEBCGMSTRING_SIZE_ERR = 2; const unsigned short INVALID_CHARACTER_ERR = 3; const unsigned short NO_DATA_ALLOWED_ERR = 4; const unsigned short NO_MODIFICATION_ALLOWED_ERR = 5; const unsigned short NOT_SUPPORTED_ERR = 6; const unsigned short INVALID_ACCESS_ERR = 7; const unsigned short FILE_NOT_FOUND_ERR = 8; const unsigned short FILE_INVALID_ERR = 9;

Exemple de base

EXEMPLE :

Cet exemple simple montre comment capturer une exception WebCGMException depuis du HTML & ECMAScript. Dans un navigateur prêt au DOM de WebCGM, l'exécution correcte de ce code HTML-ECMAScript devrait provoquer l'apparition d'une boîte d'alerte lors d'une tentative de changer un attribut en lecture seule.

<html>
<head>
<title>Example, WebCGMException interface</title>
<script type="text/ecmascript">
  function causeException(evt) {
    alert("Try to change the readonly attribute layername");
    try {
      var webcgm = document.getElementById('ivx1').getWebCGMDocument();
      var pic = webcgm.firstPicture;
      var obj = pic.getAppStructureByID("A");
      obj.setAppStructureAttr("layername","anotherName");
    } catch (e) {
      alert("Catch the exception: " + e.description);
    }
  }
</script>
</head>

<body onload="causeException()">
<table border="1" rules="cols">
  <tr style="text-align:center;">
    <th>Example, causeException interface</th>
  </tr>
  <tr>
    <td><object id="ivx1" data="ex_Exception.cgm" 
                type="image/cgm;Version=4;ProfileId=WebCGM" 
                width="480" height="360"></object>
    </td>
  </tr>
</table>
</body>
</html>

Voir cet exemple en HTML-CGM (seulement les navigateurs prêts pour le DOM de WebCGM).

Code d'exception du groupe de définition

Un entier indiquant le type d'erreur générée.

Constantes définies

INDEX_SIZE_ERR : si l'index (ou la dimension) est négative, ou supérieure à la valeur permise.

DOMSTRING_SIZE_ERR : si l'étendue de texte spécifiée ne tient pas dans un objet WebCGMString.

INVALID_CHARACTER_ERR : si un caractère invalide ou illégal est spécifié, tel que dans un nom XML.

NO_DATA_ALLOWED_ERR : si des données sont définies pour un nœud qui ne les gère pas.

NO_MODIFICATION_ALLOWED_ERR : si a lieu une tentative de modifier un objet où les modifications ne sont pas permises.

NOT_SUPPORTED_ERR : si la mise en œuvre ne gère pas le type d'objet ou l'opération demandés.

INVALID_ACCESS_ERR : si un paramètre ou une opération ne sont pas gérés par l'objet sous-jacent.

FILE_NOT_FOUND_ERR : si le document de référence n'a pu être accédé.

FILE_INVALID_ERR : si le document de référence n'était pas bien formé ou était en condition d'erreur.

5.7.2 Interface GetWebCGMDocument

Puisque les documents WebCGM sont souvent incorporés dans un document hôte tel que XHTML, les agents utilisateurs WebCGM doivent obligatoirement mettre en œuvre l'interface GetWebCGMDocument pour l'élément qui référence le document WebCGM (par exemple, la balise object).

Définition IDL

interface GetWebCGMDocument { WebCGMMetafile getWebCGMDocument ( ) raises ( WebCGMException ); WebCGMString getAppName(); WebCGMString getAppVersion(); };

Exemple de base

Cf. tout exemple dans les autres sous-sections d'interfaces. Chacun d'eux utilise et illustre la méthode getWebCGMDocument.

Attributs

Aucun attribut défini.

Méthodes

getWebCGMDocument

Retourne l'objet WebCGMMetafile du document WebCGM appelé. Si aucun document WebCGM n'est ouvert dans le visualisateur, l'objet WebCGMMetafile sera quand même retourné.

Paramètres

Aucun paramètre.

Valeur retournée

WebCGMMetafile; L'objet WebCGMMetafile du document WebCGM appelé.

Exceptions

WebCGMException; NOT_SUPPORTED_ERR : Aucun objet WebCGMMetafile n'est disponible.

getAppName

Retourne le nom de l'application de visualisation.

Paramètres

Aucun paramètre.

Valeur retournée

WebCGMString; Le nom de l'application de visualisation.

Exceptions

Aucune exception.

getAppVersion

Retourne la version de l'application de visualisation.

Paramètres

Aucun paramètre.

Valeur retournée

WebCGMString; La version de l'application de visualisation.

Exceptions

Aucune exception.

5.7.3 L'interface WebCGMMetafile

L'interface WebCGMMetafile est le point d'entrée du document WebCGM en entier. L'interface expose les informations concernant le métafichier et donne accès au premier objet WebCGMPicture du document WebCGM.

Définition IDL

interface WebCGMMetafile { readonly attribute WebCGMString metafileDescription; readonly attribute WebCGMPicture firstPicture; readonly attribute WebCGMString metafileID; readonly attribute unsigned short metafileVersion; attribute WebCGMString src; void addEventListener(in WebCGMString type, in WebCGMEventListener listener); void removeEventListener(in WebCGMString type, in WebCGMEventListener listener)); };

Exemple de base

EXEMPLE :

Cet exemple simple montre l'utilisation d'une méthode de l'interface WebCGMMetafile depuis HTML & ECMAScript. Dans un navigateur prêt au DOM de WebCGM, l'éxécution correcte de ce code HTML-ECMAScript devrait afficher le paramètre metafileID de l'élément BEGIN METAFILE dans un message sous l'image.

<html>
<head>
<title>Exemple, Metafile interface</title>
<script type="text/ecmascript">
  function metafileInfo() {
    try {
      var webcgm = document.getElementById('ivx1').getWebCGMDocument();
      document.getElementById("_1").firstChild.data = "The metafileID is \"" + webcgm.metafileID + "\"";
    } catch (e) {
      alert(e.description);
    }
  }
</script>
</head>

<body onload="metafileInfo()">
<table border="1" rules="cols">
  <tr style="text-align:center;">
    <th>Example, WebCGMMetafile interface</th>  </tr>
  <tr>
    <td><object id="ivx1" data="ex_Metafile.cgm" 
                          type="image/cgm;Version=4;ProfileId=WebCGM" 
                          width="480" height="360"></object>
    </td> </tr>
</table>
<p id="_1">Metafile ID is:</p>
</body>
</html>

Voir cet exemple en HTML-CGM (seulement les navigateurs prêts pour le DOM de WebCGM).

Attributs

metafileDescription de type WebCGMString, en lecture seule

Retoure la description de métafichier du document WebCGM, qui est une chaîne constituée de sous-chaînes délimitées par des caractères guillemets « " », comme défini dans le proforma de profil (PPF) de WebCGM. Par exemple : "ProfileId:WebCGM""ProfileEd:2.0""Source:A software vendor""Date:20040602""ColourClass:monochrome". Comme défini également par le proforma de profil (PPF) de WebCGM, une description de métafichier (metafileDescription) contiendra toujours les valeurs « ProfileId: » et « ProfileEd: », les autres informations telles que les valeurs « Source », « ColourClass », etc. sont optionnelles. Si aucun document WebCGM n'est ouvert dans le visualisateur, une chaîne vide est retournée.

firstPicture de type WebCGMPicture, en lecture seule

Retourne le premier élément WebCGMPicture du document WebCGM. Les éléments WebCGMPicture suivants sont accessibles à l'aide de l'interface WebCGMPicture. Un document WebCGM 2.0 contient exactement un seul élément WebCGMPicture. Si aucun élément WebCGM n'est ouvert dans le visualisateur, la valeur "null" est retournée.

metafileID de type WebCGMString, en lecture seule

Retourne l'identificateur de métafichier, qui est le paramètre de l'élément BEGIN METAFILE dans le document CGM. Si aucun document WebCGM n'est ouvert dans le visualisateur, une chaîne vide est retournée.

metafileVersion de type unsigned short, en lecture seule

Retourne la version de métafichier du document WebCGM. Si aucun document WebCGM n'est ouvert dans le visualisateur, la valeur "0" est retournée.

src de type WebCGMString

L'adresse IRI du document courant. À l'initialisation (on setting), le nouveau document pointé par l'adresse IRI est chargé par l'agent utilisateur. Celui-ci doit analyser entièrement l'identificateur de fragment (le cas échéant) dans l'adresse IRI et exécuter le comportement indiqué. Les règles de la section « Les comportements d'images » s'appliquent à l'attribut src (si un fragment IRI contient un paramètre picBehavior, le visualisateur devra l'ignorer). Si la ressource CGM pointée par l'adresse IRI est déjà chargée pour l'objet, l'agent utilisateur ne devra pas recharger le fichier CGM (similaire à la définition d'une adresse IRI pour le même fichier CGM du comportement _replace sur un lien CGM-à-CGM). À la récupération (on retrieval), si aucun document WebCGM n'est ouvert dans le visualisateur, une chaîne vide est retournée.

EXEMPLE : L'attribut src est une adresse IRI, avec un éventuel fragment contenant des termes de sélection d'objet et de comportement d'objet. Il ne s'agit pas d'un enregistrement de données linkuri complet (attribut APS), et un fragment ne contient pas de terme de comportement d'objet. Donc pour ouvrir le fichier « myCGM.cgm » en utilisant des appels DOM (ECMAscript) référençant un élément HTML <object> dont l'identificateur vaut "myObjElt" :

Exemples corrects :

document.getElementById('myObjElt').getWebCGMDocument().src= 'myCGM.cgm#myId';

[...].getWebCGMDocument().src= 'myCGM.cgm#id(myId,full)';

Incorrect :

[...].getWebCGMDocument().src= 'myCGM.cgm#"myId" "myTitle" "_blank"'

[...].getWebCGMDocument().src= "myCGM.cgm#id(myId).picseqno(1,_blank)"

Méthodes

addEventListener

Cette méthode permet d'enregistrer des guetteurs d'événements sur l'objet WebCGMMetafile. Si un événement WebCGMEventListener est ajouté à l'objet WebCGMMetafile pendant qu'il traite un événement, celui-ci ne sera pas déclenché par les actions courantes. Si plusieurs objets WebCGMEventListener sont enregistrés sur l'objet WebCGMMetafile avec les mêmes paramètres, les instances en double sont écartées. Elles n'entraînent pas un double appel de l'objet WebCGMEventListener.

Remarque : Bien que tous les objets WebCGMEventListener sur l'objet WebCGMMetafile soient assurés d'être déclenchés par tout événement reçu, l'ordre où l'objet WebCGMMetafile recevra l'événement relativement aux autres objets WebCGMEventListener sur l'objet WebCGMMetafile n'est pas défini.

Paramètres

type de type WebCGMString

Le type d'événement que l'utilisateur enregistre (par exemple, "click", "mouseover", etc.).

listener de type WebCGMEventListener

Le paramètre listener représente une interface mise en œuvre par l'utilisateur, laquelle contient les méthodes à appeler lorsque l'événement se produit.

Valeur retournée

Aucune valeur retournée.

Exceptions

Aucune exception.

removeEventListener

Cette méthode permet de supprimer des guetteurs d'événéments sur l'objet WebCGMMetafile. Si un objet WebCGMEventListener est ôté de l'objet WebCGMMetafile pendant qu'il traite un événement, celui-ci ne sera pas déclenché par les actions courantes. Les objets WebCGMEventListener ne peuvent jamais être invoqués après avoir été supprimés. L'appel de la méthode removeEventListener avec des arguments qui n'identifient pas d'objet WebCGMEventListener actuellement enregistré sur l'objet WebCGMMetafile est sans effet.

Paramètres

type de type WebCGMString

Définit le type d'événement de l'objet WebCGMEventListener à supprimer (par exemple : "click", "mouseover").

listener de type WebCGMEventListener

Indique l'objet WebCGMEventListener à supprimer.

Valeur retournée

Aucune valeur retournée.

Exceptions

Aucune exception.

5.7.4 L'interface WebCGMNode

L'interface WebCGMNode est le type de données de base du DOM de WebCGM. L'objet WebCGMNode est la base de plusieurs autres interfaces, y compris les interfaces d'éléments WebCGM spécifiques (par exemple, WebCGMAppStructure) et d'éléments non-WebCGM tels que les nœuds de métadonnées. L'interface WebCGMNode définit les attributs et les méthodes pour effectuer une traversée de l'arbre simple et générique.

Définition IDL

interface WebCGMNode { const unsigned short PICTURE_NODE = 1; const unsigned short APP_STRUCTURE_NODE = 2; const unsigned short XML_METADATA_NODE = 3; const unsigned short TEXT_NODE = 4; const unsigned short ATTR_NODE = 5; readonly attribute WebCGMString nodeName; readonly attribute WebCGMString nodeValue; // raises(WebCGMException) on retrieval readonly attribute unsigned short nodeType; readonly attribute WebCGMNode parentNode; readonly attribute WebCGMNodeList childNodes; readonly attribute WebCGMNode firstChild; readonly attribute WebCGMNode lastChild; readonly attribute WebCGMNode previousSibling; readonly attribute WebCGMNode nextSibling; readonly attribute WebCGMPicture ownerPicture; boolean hasChildNodes(); boolean hasAttributes(); readonly attribute WebCGMNodeList attributes; readonly attribute WebCGMString namespaceIRI; readonly attribute WebCGMString prefix; readonly attribute WebCGMString localName; WebCGMString getAttributeNS(in WebCGMString namespaceIRI, in WebCGMString localName); void setAttributeNS(in WebCGMString namespaceIRI, in WebCGMString qualifiedName, in WebCGMString value); WebCGMNodeList getElementsByTagNameNS(in WebCGMString namespaceIRI, in WebCGMString localName); };

Exemple de base

EXEMPLE :

Cet exemple simple montre l'utilisation d'un attribut sur l'interface WebCGMNode depuis HTML & ECMAScript. Dans un navigateur prêt au DOM de WebCGM, l'exécution correcte de ce ce code HTML-ECMAScript devrait afficher un message sous l'image, indiquant sur la deuxième ligne une valeur "1" pour le type de nœud.

<html>
<head>
<title>Example, WebCGMNode interface</title>
<script type="text/ecmascript">
  function getNodeType(evt) {
    var webcgm = document.getElementById('ivx1').getWebCGMDocument();
    if( webcgm ) {
      var pic = webcgm.firstPicture;
      if( pic ) {
        var elem = document.getElementById('result').lastChild;
        var text = elem.nodeValue;
        text = text + pic.nodeType;
        elem.nodeValue = text;
      }
    }
  }
</script>
</head>

<body onload="getNodeType()">
<table border="1" rules="cols" width="480">
  <tr style="text-align:center;">
    <th>Example, WebCGMNode interface</th>  </tr>
  <tr>
    <td><object id="ivx1" data="ex_Node.cgm" 
                type="image/cgm;Version=4;ProfileId=WebCGM" 
                width="480" height="360"></object>
    </td>  </tr>
  <tr style="text-align:left;" >
    <td id="result">The <strong>WebCGMNode.nodeType</strong> 
                    value of...<br/><em>getWebCGMDocument().firstPicture</em> is: </td>  </tr>  
</table>
</body>
</html>

Voir cet exemple en HTML-CGM (seulement les navigateurs prêts pour le DOM de WebCGM).

Groupe de définiton de nodeType

Un entier indiquant le type de nœud dont il s'agit.

Constantes définies

PICTURE_NODE; le nœud est un objet WebCGMPicture.

APP_STRUCTURE_NODE; le nœud est un objet WebCGMAppStructure.

XML_METADATA_NODE; le nœud est une information du fichier d'accompagnement XML associée à un élément CGM.

TEXT_NODE; le nœud contient des données textuelles.

ATTR_NODE; le nœud est un objet WebCGMAttr.

Attributs

nodeName de type WebCGMString, en lecture seule

Le nom de ce nœud, dépendant de son type ; cf. le tableau ci-dessous.

nodeValue de type WebCGMString, en lecture seule

La valeur de ce nœud, dépendant de son type ; cf. le tableau ci-dessous.

Exceptions à l'initialisation

WebCGMException; NO_MODIFICATION_ALLOWED_ERR : Soulevée lorsque le nœud est en lecture seule et qu'il n'est pas défini comme valant "null".

Exceptions à la récupération

WebCGMException; DOMSTRING_SIZE_ERR : Soulevée s'il serait retourné plus de caractères que ne peut contenir une variable WebCGMString dans la plateforme de mise en œuvre.

nodetype de type unsigned short, en lecture seule

Un code représentant le type de l'objet sous-jacent.

Les valeurs de nodeName et nodeValue varient selon le type de nœud comme suit :

Interface	nodeName	nodeValue
WebCGMAppStructure	Type WebCGMAppStructure : "layer" | "grobject" | "para" | "subpara" | "grnode"	chaîne vide
WebCGMAttr	WebCGMAttr.name	chaîne vide
WebCGMPicture	"#picture"	chaîne vide
Données textuelles	"#text"	contenu du nœud de texte
Métadonnées XML	prefix + localName	chaîne vide

parentNode de type WebCGMNode, en lecture seule

Le parent (le nœud ancêtre immédiat) de ce nœud. Tous les nœuds, sauf WebCGMPicture et WebCGMAttr, peuvent avoir un parent.

childNodes de type WebCGMNodeList, en lecture seule

Un objet WebCGMNodeList qui contient tous les sous-éléments de ce nœud. S'il n'y a pas de sous-élément, la valeur "null" est retournée.

firstChild de type WebCGMNode, en lecture seule

Le premier sous-élément de ce nœud. S'il n'y en a pas, la valeur "null" est retournée.

lastChild de type WebCGMNode, en lecture seule

Le dernier sous-élément de ce nœud. S'il n'y en a pas, la valeur "null" est retournée.

previousSibling de type WebCGMNode, en lecture seule

Le nœud qui précéde immédiatement ce nœud. S'il n'y en a pas, la valeur "null" est retournée.

nextSibling de type WebCGMNode, en lecture seule

Le nœud qui suit immédiatement ce nœud. S'il n'y en a pas, la valeur "null" est retournée.

ownerPicture de type WebCGMPicture, en lecture seule

L'objet WebCGMPicture associé à ce nœud. S'il s'agit d'un nœud WebCGMPicture, la valeur "null" est retournée

attributes de type WebCGMNodeList, en lecture seule

Un objet WebCGMNodeList contenant tous les attributs (WebCGM et avec espace de noms) de ce nœud ou la valeur "null" si l'objet WebCGMNode n'a pas d'attribut. Le paramètre apsid de l'élément APS BEGIN est considéré comme étant un attribut de sa strucutre d'application pour les besoins du DOM, et le paramètre pictid de l'élément BEGIN PICTURE est considéré comme étant un attribut de son image pour les besoins du DOM. Ce tableau résume le contenu de attributes pour les divers types de nœuds :

Type de nœud	attributes
PICTURE_NODE	pictid (toujours), les attributs à espace de noms
APP_STRUCTURE_NODE	apsid (toujours), les attributs à espace de noms, les attributs APS
XML_METADATA_NODE	les attributs à espace de noms
ATTR_NODE	aucun (toujours "null")
TEXT_NODE	aucun (toujours "null")

namespaceIRI de type WebCGMString, en lecture seule

L'adresse IRI de l'espace de noms de ce nœud. Par exemple, sur l'élément « foo:someElement », retourne l'adresse IRI de la déclaration d'espace de noms (xmlns) qui associe le préfixe « foo » à l'espace de noms. Il ne s'agit pas d'une valeur calculée qui serait le résultat d'une recherche d'espace de noms fondée sur un examen des déclarations d'espaces de noms en vue. C'est l'adresse IRI de l'espace de noms donnée à la création. Une chaîne vide est retournée si l'objet WebCGMNode n'est pas de type XML_METADATA_NODE ou ATTR_NODE.

prefix de type WebCGMString, en lecture seule

Le préfixe d'espace de noms de ce nœud (par exemple, pour « foo:elementName », retourne « foo »). Une chaîne vide est retournée si l'objet WebCGMNode n'est pas de type XML_METADATA_NODE ou ATTR_NODE.

localName de type WebCGMString, en lecture seule

Retourne la partie locale du nom qualifié de ce nœud (par exemple, pour « foo:elementName », retourne « elementName »). Une chaîne vide est retournée si l'objet WebCGMNode n'est pas de type XML_METADATA_NODE ou ATTR_NODE.

Méthodes

hasChildNodes

Indique si ce nœud a des sous-éléments.

Paramètres

Aucun paramètre.

Valeur retournée

boolean; "true" si ce nœud à des sous-éléments, "false" sinon.

Exceptions

Aucune exception.

hasAttributes

Indique si ce nœud a des attributs. (Pour plus de renseignements, cf. l'attribut attributes).

Paramètres

Aucun paramètre.

Valeur retournée

boolean; "true" si ce nœud a des attributs, "false" sinon.

Exceptions

Aucune exception.

getAttributeNS

Retourne la valeur d'attribut du nœud par nom local et adresse IRI d'espace de noms.

Paramètres

namespaceIRI de type WebCGMSTring

L'adresse IRI de l'espace de noms de l'attribut à récupérer.

localName de type WebCGMString

Le nom local de l'attribut à récupérer.

Valeur retournée

WebCGMString; La valeur WebCGMAttr en tant que chaîne, ou la chaîne vide si cet attribut n'a pas de valeur spécifiée.

Exceptions

Aucune exception.

setAttributeNS

Ajoute un nouvel attribut. Si un attribut de ce nom est déjà présent sur ce nœud, sa valeur change pour celle du paramètre value.

Paramètres

namespaceIRI de type WebCGMSTring

L'adresse IRI de l'espace de noms de l'attribut à créer ou à altérer.

qualifiedName de type WebCGMSTring

Le nom qualifié de l'attribut à créer ou à altérer.

value de type WebCGMString

La valeur à attribuer, sous forme d'une chaîne.

Valeur retournée

Aucune valeur retournée.

Exceptions

WebCGMException; INVALID_CHARACTER_ERR : Soulevée si le nom qualifié spécifié contient un caractère illégal. Les contraintes de caractères légaux du nom qualifié correspondent à celle de la structure du nom d'attribut de la spécification « XML 1.0, troisième édition ».

getElementsByTagNameNS

Retourne un objet WebCGMNodeList de tous les éléments descendants du fichier d'accompagnement XML (les métadonnées spécifiques de l'application) ayant un nom local et une addresse IRI d'espace de noms donnés, dans une traversée préordonnée (preorder traversal) de l'arbre du nœud WebCGMNode. Retourne la valeur "null" s'il n'y a pas de tels éléments.

Paramètres

namespaceIRI de type WebCGMSTring

L'adresse IRI de l'espace de noms des éléments XML auquel correspondre.

localName de type WebCGMString

Le nom local des éléments XML auquel correspondre.

Valeur retournée

WebCGMNodeList; Une liste de nœuds d'éléments XML correspondants.

Exceptions

Aucune exception.

5.7.5 L'interface WebCGMPicture

L'interface WebCGMPicture permet d'accéder aux structures d'application du document WebCGM. Elle définit également comment charger un fichier d'accompagnement XML (XCF) et l'appliquer à un document WebCGM.

Définition IDL

interface WebCGMPicture : WebCGMNode { readonly attribute float width; readonly attribute float height; readonly attribute WebCGMString pictid; boolean applyCompanionFile(in WebCGMString fileIRI); WebCGMAppStructure getAppStructureById(in WebCGMString apsId); WebCGMNodeList getAppStructuresByName(in WebCGMString apsName); void highlight(in WebCGMNodeList nodes, in WebCGMString type); void clearHighlight(); void setPictureVisibility(in WebCGMString visibility); void setStyleProperty(in WebCGMString style, in WebCGMString value); void reloadPicture(); };

Exemple de base

EXEMPLE :

Cet exemple simple montre l'utilisation d'une méthode de l'interface WebCGMPicture dans HTML & ECMAScript. Dans un navigateur prêt au DOM de WebCGM, l'exécution de ce code HTML-ECMAScript ferait apparaître la vue initiale de l'illustration technique avec un fond gris bleu au lieu de blanc :

<html>
<head>
<title>Example, WebCGMPicture interface</title>
<script type="text/ecmascript">
  function changeBackground(evt) {
    var webcgm = document.getElementById('ivx1').getWebCGMDocument();
    if( webcgm ) {
      var pic = webcgm.firstPicture;
      if( pic ) {
        pic.setStyleProperty("background-color","#A0A0D0");
      }
    }
  }
</script>
</head>

<body onload="changeBackground()">
<table border="1" rules="cols">
  <tr style="text-align:center;">
    <th>Example, WebCGMPicture interface</th>
  </tr>
  <tr>
    <td><object id="ivx1" data="ex_Picture.cgm" 
                type="image/cgm;Version=4;ProfileId=WebCGM" 
                width="480" height="360"></object>
    </td>
  </tr>
</table>
</body>
</html>

Voir cet exemple en HTML-CGM (seulement les navigateurs prêts pour le DOM de WebCGM).

Attributs

width de type float, en lecture seule

Représente la largeur de l'objet WebCGMPicture en millimètres. Veuillez consulter la section concernant les valeurs de coordonnées pour plus de renseignements.

height de type float, en lecture seule

Représente la hauteur de l'objet WebCGMPicture en millimètres. Veuillez consulter la section concernant les valeurs de coordonnées pour plus de renseignements.

pictid de type WebCGMString, en lecture seule

Représente l'identificateur de l'objet WebCGMPicture, qui est le paramètre id de l'élément BEGIN PICTURE dans le document CGM.

Méthodes

applyCompanionFile

Lit un fichier d'accompagnement XML (XCF) dans le modèle d'objets de l'agent utilisateur. S'il y a des métadonnées spécifiques de l'application dans le fichier d'accompagnement (sous la forme d'attributs et de sous-éléments à espaces de noms), l'agent utilisateur créera de nouvelles structures d'application à espace de noms comme sous-éléments des structures d'application WebCGM existantes au sein de son modèle d'objets. Ces informations seront alors accessibles en utilisant les méthodes trouvées dans cette interface WebCGMPicture, dans WebCGMAppStructure et dans WebCGMNode. Si le paramètre fileIRI de cette méthode est une adresse IRI relative, alors celle-ci se résoud de la même façon que pour la résolution des adresses IRI relatives des ressources XCF référencées dans la syntaxe de fragment IRI de WebCGM , c'est-à-dire que l'adresse IRI est résolue par rapport à l'adresse de la ressource CGM que la ressource XCF accompagne.

Veuillez consulter la section « Les relations avec le fichier d'accompagnement XML » pour plus de renseignements.

Paramètres

fileIRI de type WebCGMString

Le nom de fichier et l'adresse du fichier d'accompagnement XML à charger et appliquer dans le modèle d'objets.

Valeur retournée

boolean; "true" si la mise en œuvre a pu charger et parcourir le fichier d'accompagnement XML en mémoire comme souhaité, "false" sinon.

Exceptions

WebCGMException; FILE_NOT_FOUND_ERR : si le document référencé n'a pas pu être obtenu.

WebCGMException; FILE_INVALID_ERR : si le document référencé n'était pas bien formé ou était en condition d'erreur.

getAppStructureById

Retourne la structure d'application dont l'identificateur est donné par le par le paramètre apsID. S'il n'existe pas de telle structure, retourne la valeur "null". Le comportement n'est pas défini si plusieurs éléments ont cet identificateur. Seules les structures d'application WebCGM sont récupérables par la méthode getAppStructureById, elle ne récupère pas les éléments d'espaces de noms étrangers (les éléments de métadonnées spécifiques de l'application).

Paramètres

apsId de type WebCGMString

La valeur d'identificateur unique d'une structure d'application.

Valeur retournée

WebCGMAppStructure; un objet WebCGMAppStructure contenant la structure d'application dont l'identificateur correspond.

Exceptions

Aucune exception.

getAppStructuresByName

Retourne la liste des structures d'application dont les noms sont donnés par le paramère apsName, dans l'ordre de leur rencontre dans une traversée en profondeur de l'arbre de WebCGMPicture. S'il n'existe pas de telle structure d'application, retourne la valeur "null". Seules les structures d'application WebCGM sont récupérables par la méthode getAppStructuresByName, elle ne récupère pas les éléments d'espaces de noms étrangers (les éléments de métadonnées spécifiques de l'application).

Paramètres

apsName de type WebCGMString

Une valeur de nom non unique pour une structure d'application.

Valeur retournée

WebCGMNodeList; Un objet WebCGMNodeList contenant tous les objets WebCGMNode des structures d'application correspondantes.

Exceptions

Aucune exception.

highlight

Met en évidence une collection de structures d'application (APS). WebCGM permet également la mise en évidence des structures d'aplication en utilisant la syntaxe de fragment IRI. La méthode exacte de la mise en évidence dépend du visualisateur. La méthode highlight fournit aux créateurs de scripts WebCGM un moyen de mettre en évidence les structures d'application de la même façon que le ferait un fragment IRI. Elle permet également de mettre en évidence des couches entières. La mise en évidence n'est pas définie pour les nœuds WebCGMPicture ou les nœuds de métadonnées XML.

Paramètres

nodes de type WebCGMNodeList

Un objet WebCGMNodeList composé des nœuds de type APP_STRUCTURE_NODE à mettre en évidence.

type de type WebCGMString

Dénote un comportement identique aux mots-clés de comportement d'objet de mise en évidence correspondants de la syntaxe de fragment. Les valeurs possibles : "add" ou "new".

Valeur retournée

Aucune valeur retournée.

Exceptions

Aucune exception.

clearHighlight

Ôte la mise en évidence de toutes les structures d'applications actuellement en évidence dans l'image. Le comportement est identique au fragment de comportement d'objet de forme spéciale, id(*,clearHighlight), qui est défini dans l'énumération des comportements de la syntaxe de fragment.

Paramètres

Aucun paramètre.

Valeur retournée

Aucune valeur retournée.

Exceptions

Aucune exception.

setPictureVisibility

Établit la visibilité ou non de l'image entière. Notez que pour les besoins du modèle d'héritage, le nœud WebCGMPicture se comporte comme une structure d'application et la visibilité fixée par cette méthode adopte le comportement de l'attribut APS visibility.

Paramètres

visibility de type WebCGMSTring

La valeur de la visibilité de l'image : "on" ou "off".

Valeur retournée

Aucune valeur retournée.

Exceptions

Aucune exception.

setStyleProperty

Fixe une propriété de style au niveau de l'image par son nom.

Le tableau et le texte suivants décrivent en détails chaque propriété de style, sa portée et les valeurs permises :

Les règles & codages de la manipulation DOM des propriétés de style

Propriété de style Nom	Au niveau de l'image	Au niveau de la structure APS	Valeur(s) d'attribut	Valeur initiale	Exemple
background-color	oui	non	valeur RGB absolue ou intensité relative (0..100%)	100%	"#000000" ou "75%"
text-size	oui	oui	valeur NVDC absolue ou échelle relative (les deux > 0)	100%	"225%"
fill-color	oui	oui	valeur RGB absolue ou intensité relative (0..100%)	100%	"#FF0000" ou "75%"
intensity	oui	oui	intensité (0..100%)	100%	"75%"
stroke-color	oui	oui	valeur RGB absolue ou intensité relative (0..100%)	100%	"#FF0000" ou "75%"
stroke-weight	oui	oui	valeur NVDC absolue ou échelle relative (les deux > 0)	100%	"225%"
text-color	oui	oui	valeur RGB absolue ou intensité relative (0..100%)	100%	"#FF0000" ou "75%"
text-font	oui	oui	WebCGMString	"metafile"	"Helvetica"
raster-intensity	oui	oui	intensité relative (0..100%)	100%	"75%"

Les définitions communes. Les définitions communes suivantes, liées au modèle d'héritage, s'appliquent à toutes les propriétés de style :

• Héritée : oui : chaque propriété de style est héritable ;
• La valeur "inherit" : chaque propriété de style admet la valeur "inherit" en plus des valeurs listées pour la propriété individuelle ;
• La valeur calculée : la valeur calculée de chaque propriété de style est la même que la valeur spécifiée, à l'exception de la valeur "inherit" qui est éliminée, comme défini dans le modèle d'héritage ;

Les unités dans le tableau. Les couleurs RGB sont exprimées en valeurs hexadécimales. Les valeurs d'échelle relative sont exprimées comme un nombre positif ou non négatif (selon la propriété), suivi d'un indicateur d'unité « % ». Les valeurs relatives de certaines propriétés peuven excéder 100%. Les valeurs d'intensité relative sont exprimées par un nombre suivi d'une unité « % », par exemple, "75%". Les valeurs d'intensité relative ne peuvent pas excéder 100%.

La représentation des couleurs. Les couleurs RGB absolues s'expriment en utilisant une représentation hexadécimale : le rouge s'exprime par #FF0000 et le cyan utilisant la totalité du vert et du bleu par #00FFFF. La représentation doit faire exactement 6 chiffres, deux chacun pour R, G et B. La notation hexadécimale abrégée, par exemple, la notation #RGB de 3 chiffres, n'est pas gérée dans cette spécification.

Le mode de remplacement. Lorsque les propriétés de style ont des valeurs en « % » (pourcentage), la valeur d'attribut respective utilisée pour l'affichage est ajustée en appliquant la formule appropriée aux valeurs d'attributs dans le métafichier (pour l'objet cible concerné). Par exemple, une valeur stroke-weight de 60% signifie que les attributs LINE WIDTH et EDGE WIDTH définis dans le métafichier sont multipliés par 0,6. Le paramétrage successif de la même propriété de style remplace tout paramétrage précédent (au lieu de s'y ajouter). Ainsi, par exemple, l'application d'une valeur stroke-weight de 60% suivie d'une valeur stroke-weight de 40% résulte en une valeur stroke-weight de 40%, et non de 24%.

L'ordre compte. Quelques propriétés de style ont des effets chevauchants. Par exemple, les propriétés intensity et fill-color affectent toutes deux la couleur des zones remplies. Lorsque les deux propriétés sont définies pour une structure d'application cible, la dernière définition annule et remplace la première. Ainsi, par exemple, une valeur intensity de 40% suivie d'une valeur fill-color de 60% résulte en une couleur de remplissage à 60%, tandis qu'une valeur fill-color de #FF0000 suivie d'une valeur intensity de 40% résulte en une valeur fill-color de 40% (des couleurs de zones remplies dans le métafichier, pour l'objet cible).

Les définitions de propriétés de style. Les définitions fonctionnelles détaillées de chaque propriété de style suivent :

background-color : la couleur de la surface de rendu de l'image entière, sur laquelle tous les éléments sont dessinés. Elle correspond à l'attribut BACKGROUND COLOUR du standard CGM. Exemple : la propriété de style background-color avec une valeur de #000000 écrasera ce qui se trouve dans l'instance WebCGM et affichera un fond noir pour tous les éléments à rendre par-dessus.

text-size : redéfinit la taille de tout le texte dans l'objet cible. Si l'unité de text-size est le pourcentage « % », alors elle ajuste les boîtes de restriction du texte (hauteurs et largeurs) et l'attribut CGM CHARACTER HEIGHT de cette quantité. Si la valeur de text-size est en coordonnées NVDC, alors, pour chaque élément de texte dans l'objet cible, calculer le rapport (en fait, un pourcentage) de la nouvelle valeur NVDC et de la hauteur de la boîte de restriction, et appliquer ce rapport comme ce serait le cas pour la même valeur en pourcentage « % ».

fill-color : la propriété de style appliquée à une zone fermée à l'intérieur du tracé d'une forme. La propriété fill-color correspond à l'attribut CGM FILL COLOUR, et elle écrasera les valeurs courantes de cet attribut dans l'objet cible (structure d'application ou image), si elle est appliquée à l'objet.

intensity : un moyen de diluer la couleur courante vers le blanc. Une valeur d'intensité de 0% appliquée à une structure d'application (APS) rendra son contenu complètement blanc tandis qu'une valeur de 100% gardera intactes les couleurs courantes. L'équation d'intensité est la suivante :

normalizedNewRed   = 1 - intensity * (1 - normalizedOldRed)
normalizedNewGreen = 1 - intensity * (1 - normalizedOldGreen)
normalizedNewBlue  = 1 - intensity * (1 - normalizedOldBlue)

Exemple : Voici les calculs pour l'application d'une intensité de 40% à la couleur orange #FFA500 :

normalizedNewRed = 1 - 0.4 * (1 - 1) = 1
normalizedNewGreen = 1 - 0.4 * (1 - 0.647) = 0.859
normalizedNewBlue = 1 - 0.4 * (1 - 0) = 0.5

La nouvelle couleur est %FFDB99.

Le paramétrage d'une valeur d'intensité relative est autorisé sur plusieurs propriétés de style individuelles, cf. le tableau précédent. La propriété de style intensity représente toutefois une propriété commode qui contrôle simultanément la valeur d'intensité des quatres propriétés suivantes : fill-color, stroke-color, text-color et raster-intensity.

stroke-color : définit la couleur des lignes et des bords dans l'objet cible (structure d'application ou image) auquel la propriété s'applique. La propriété stroke-color écrase les attributs CGM LINE COLOUR et EDGE COLOUR. Cette propriété de style appliquera un changement de couleur d'intensité absolue ou relative aux valeurs définies dans le métafichier de ces attributs CGM dans l'objet cible.

stroke-weight : redéfinit l'épaisseur des traits de dessin des lignes et bords dans l'objet cible (structure d'application ou image) auquel elle s'applique. La propriété stroke-weight écrase les attributs CGM LINE WIDTH et EDGE WIDTH. Cette propriété stroke-weight peut appliquer un changement d'échelle relatif aux valeurs définies dans le métafichier de ces attributs, ou peut fournir un remplacement absolu (NVDC) de ces valeurs courantes.

text-color : redéfinit la couleur du texte graphique dans l'objet cible (structure d'application ou image) auquel la propriété s'applique. La propriété text-color écrase l'attribut CGM TEXT COLOUR. Cette propriété de style appliquera un changement de couleur d'intensité absolu ou relatif aux valeurs définies dans le métafichier de cet attribut CGM dans la structure d'application.

text-font : définit une fonte de remplacement pour tout le texte dans l'objet cible. Si les caractères nécessaires pour la totalité du texte dans l'objet cible sont disponibles dans la fonte de remplacement, et si celle-ci est disponible, alors l'utiliser pour tout le texte dans l'objet cible. Sinon ignorer la fonte de remplacement indiquée. La valeur initiale de la propriété text-font, le mot-clé réservé "metafile", signifie que les définitions de fontes du métafichier sont utilisées.

raster-intensity : un moyen de diluer la couleur courante vers le blanc dans un élément matriciel. La propriété s'applique aux couleurs des éléments CELL ARRAY, TILE et BITONAL TILE dans l'objet cible (structure d'application ou image) auquel elle s'applique. Une valeur d'intensité de 0% appiquée à une structure d'application (APS) rendra son contenu matriciel complètement blanc tandis qu'une valeur de 100% gardera intactes ses couleurs matricielles courantes. Les équations pour calculer les nouvelles valeurs de couleur sont les mêmes que pour la propriété intensity ci-dessus.

Paramètres

style de type WebCGMString

Le nom de la propriété de style à modifier.

value de type WebCGMString

La nouvelle valeur du style donné. Notez que la valeur "inherit" est valide pour toutes les propriétés de style, et a pour effet, conformément au modèle d'héritage, de restaurer la valeur initiale (de chargement) de la propriété de style, qui est définie par le modèle d'héritage.

Valeur retournée

Aucune valeur retournée.

Exceptions

Aucune exception.

reloadPicture

Instruit l'agent utilisateur de redessiner immédiatement l'image WebCGMPicture entière. L'agent utilisateur rechargera l'image WebCGMPicture tout en conservant ses niveaux actuels d'agrandissement et de panoramique. Le rechargement de l'image WebCGMPicture jette également toutes les informations d'accompagnement existantes qui auraient pu être chargées en mémoire via la méthode applyCompanionFile.

Paramètres

Aucun paramètre.

Valeur retournée

Aucune valeur retournée.

Exceptions

Aucune exception.

5.7.6 L'interface WebCGMAppStructure

L'interface WebCGMAppStructure offre des méthodes pour paramétrer et récupérer les attributs des structures d'applications (APS). Les méthodes principales d'accès aux attributs de structures d'application sont getAppStructureAttr et setAppStructureAttr. Il est important de noter que certains attributs, tels name et linkuri, peuvent avoir des valeurs multiples. Auquel cas, un objet de type Delimited String est retourné. Le type Delimited String est également utilisé pour l'attribut region, qui peut contenir plusieurs sous-régions.

Le tableau suivant identifie quelles valeurs d'attributs APS peuvent être exprimés dans le type Delimited String. Chaque entrée du tableau pointe vers la description détaillée de l'attribut, tel qu'il apparaît dans un contenu WebCGM.

L'interface WebCGMAppStructure, comme l'interface WebCGMPicture, fournit également des méthodes pour modifier les propriétés de style au niveau de la structure d'application. Pour plus de renseignements à propos des propriétés de style disponibles, consultez le tableau des propriétés de style.

Définition IDL

interface WebCGMAppStructure : WebCGMNode { readonly attribute WebCGMString apsId; readonly attribute unsigned long nameCount; readonly attribute unsigned long linkuriCount; WebCGMString getAppStructureAttr(in WebCGMString name); void setAppStructureAttr(in WebCGMString name, in WebCGMString value) raises( WebCGMException ); void removeAppStructureAttr(in WebCGMString name) raises( WebCGMException ); void setStyleProperty(in WebCGMString style, in WebCGMString value); WebCGMNodeList toNodeList(); };

Exemple de base

EXEMPLE :

Cet exemple simple montre l'utilisation des méthodes de l'interface WebCGMAppStructure dans HTML & ECMAScript. Dans un navigateur prêt pour le DOM de WebCGM, l'exécution correcte de ce code HTML-ECMAScript devrait afficher le message « Layer name is fleet » sous l'image.

<html>
<head>
<title>Example, WebCGMAppStructure interface</title>
<script type="text/ecmascript">
  function OnBtnDOM() {
    try {
      // Get layernname
      var cgmDoc = document.getElementById("ivx1").getWebCGMDocument();
      var cgmPic = cgmDoc.firstPicture;
      var result = document.getElementById("_1");
      var gr = cgmPic.getAppStructureById("fleet");
      var i = gr.getAppStructureAttr("layername");
      result.firstChild.data = "Layer name is " + i ;
    }
    catch (e) {
      alert("Catch the exception: " + e.description);
    }
  }
</script>
</head>

<body onload="OnBtnDOM()">
<table border="1" rules="cols">
  <tr style="text-align:center;">
    <th>Example, WebCGMAppStructure interface</th> </tr>
  <tr>
    <td><object id="ivx1" data="ex_AppStructure.cgm" 
                type="image/cgm;Version=4;ProfileId=WebCGM" 
                width="480" height="360"></object> </td> </tr>
</table>
<p id="_1">Layer name is ...</p>
</body>
</html>

Voir cet exemple en HTML-CGM (seulement les navigateurs prêts pour le DOM de WebCGM).

Attributs

apsId de type WebCGMString, en lecture seule

L'identificateur unique de la structure d'application.

nameCount de type unsigned long, en lecture seule

Représente le nombre de valeurs d'attribut name présentes sur cette structure d'application.

linkuriCount de type unsigned long, en lecture seule

Représente le nombre de valeurs d'attribut linkuri présentes sur cette structure d'application.

Méthodes

getAppStructureAttr

Récupère une valeur d'attribut de structure d'application par son nom. Veuillez consulter le tableau des attributs de structures d'application pour des renseignements plus précis concernant les attributs de structures d'application récupérables et modifiables.

Paramètres

name de type WebCGMString

Le nom de l'attribut de structure d'application à récupérer.

Valeur retournée

WebCGMString; la valeur d'attribut de structure d'application sous forme de chaîne, ou la chaîne vide si cet attribut n'a pas de valeur fixée explicitement (cf. le modèle d'héritage pour d'autres explications en relation). La valeur peut être de type Delimited String.

Exceptions

Aucune exception.

setAppStructureAttr

Ajoute un nouvel attribut de structure d'application. Si un attribut avec ce nom est déjà présent dans la structure d'application, sa valeur change pour celle du paramètre value. Veuillez consulter le tableau des attributs de structures d'application pour des renseignements plus précis concernant les attributs de structures d'application récupérables et modifiables.

Paramètres

name de type WebCGMString

Le nom de l'attribut de structure d'application à créer ou altérer.

value de type WebCGMString

La valeur à assigner sous la forme d'une chaîne. La valeur peut être du type Delimited String.

Valeur retournée

Aucune valeur retournée.

Exceptions

WebCGMException; NO_MODIFICATION_ALLOWED_ERR : Soulevée si la structure d'application est en lecture seule.

removeAppStructureAttr

Supprime un attribut de structure d'application. Veuillez consulter le tableau des attributs de structures d'application pour des renseignements plus précis concernant les attributs de structures d'application récupérables et modifiables.

Paramètres

name de type WebCGMString

Le nom de l'attribut de structure d'application à supprimer.

Valeur retournée

Aucune valeur retournée.

Exceptions

WebCGMException; NO_MODIFICATION_ALLOWED_ERR : Soulevée si la structure d'application est en lecture seule.

setStyleProperty

Paramètre une propriété de style par son nom sur la structure d'application donnée. Veuillez consulter le tableau des propriétés de style pour des renseignements plus précis à propos des propriétés de style.

Paramètres

style de type WebCGMString

Le nom de l'attribut de style à modifier.

value de type WebCGMString

La nouvelle valeur du style donné.

Valeur retournée

Aucune valeur retournée.

Exceptions

Aucune exception.

toNodeList

Crée un nouvel objet WebCGMNodeList et insère le nœud de la structure d'application courante dans la liste. Le compte de la liste est de 1.

Paramètres

Aucun paramètre.

Valeur retournée

WebCGMNodeList; Un objet WebCGMNodeList contenant la structure d'application.

Exceptions

Aucune exception.

5.7.7 L'interface WebCGMNodeList

L'interface WebCGMNodeList fournit l'abstraction d'une collection ordonnée de nœuds. Les objets WebCGMNodeList dans le DOM de WebCGM sont vivants. L'index d'une liste WebCGMNodeList commence à 0.

Définition IDL

interface WebCGMNodeList { readonly attribute unsigned long count; WebCGMNode item(in unsigned long index); WebCGMNode removeItem ( in unsigned long index ) raises( WebCGMException ); WebCGMNode appendItem ( in WebCGMNode newItem ) raises( WebCGMException ); };

Exemple de base

EXEMPLE :

Cet exemple simple montre l'utilisation d'une méthode de l'interface WebCGMNodeList dans HTML & ECMAScript. Dans un navigateur prêt au DOM de WebCGM, l'exécution de ce code HTML-ECMAScript devrait compter le nombre d'avions dans la structure d'application « fleet » (N.d.T. flotte).

<html>
<head>
<title>Example, NodeList interface</title>
<script type="text/ecmascript">
  function getNodeList() {
    try {
      var webcgm = document.getElementById('ivx1').getWebCGMDocument();
      var pic = webcgm.firstPicture;
      var mylist = pic.getAppStructureByID("fleet").childNodes;
      document.getElementById("_1").firstChild.data = "The fleet contains "+mylist.count+" planes." ;
    } catch (e) {
      alert(e.description);
    }
  }
</script>
</head>

<body onload="getNodeList()">
<table border="1" rules="cols">
  <tr style="text-align:center;">
    <th>Example, WebCGMNodeList interface</th>  </tr>
  <tr>
    <td><object id="ivx1" data="ex_NodeList.cgm" 
                  type="image/cgm;Version=4;ProfileId=WebCGM" 
                  width="480" height="360"></object>  </td>  </tr>
</table>
<p id="_1">The fleet contains xx planes.</p>
</body>
</html>

Voir cet exemple en HTML-CGM (seulement les navigateurs prêts pour le DOM de WebCGM).

Attributs

count de type unsigned long, en lecture seule

Le nombre de nœuds dans la liste. L'intervalle des index des sous-nœuds va de 0 à count-1 inclus.

Méthodes

item

Retourne l'élément indexé dans la collection.

Paramètres

index de type unsigned long

L'index dans la collection.

Valeur retournée

WebCGMNode; Le nœud de la position indexée dans la liste WebCGMNodeList avec un index valide, ou la valeur "null" si ce n'est pas un index valide.

Exceptions

Aucune exception.

removeItem

Supprime un élément existant de la liste.

Paramètres

index de type unsigned long

L'index de l'élément à supprimer. L'index du premier élément est 0.

Valeur retournée

WebCGMNode; L'élément supprimé.

Exceptions

WebCGMException; NO_MODIFICATION_ALLOWED_ERR : Soulevée si la liste ne peut pas être modifiée.

appendItem

Insère un nouvel élément à la fin de la liste. Si l'élément newItem est déjà dans une liste, il en est supprimé avant son insertion dans cette liste.

Paramètres

newItem de type WebCGMNode

L'élément à insérer dans la liste.

Valeur retournée

WebCGMNode; L'élément inséré.

Exceptions

WebCGMException; NO_MODIFICATION_ALLOWED_ERR : Soulevée si la liste ne peut pas être modifiée.

5.7.8 L'interface WebCGMAttr

L'interface WebCGMAttr représente un attribut dans un nœud de type XML_METADATA_NODE, PICTURE_NODE ou APP_STRUCTURE_NODE.

Notez que les objets WebCGMAttr héritent de l'interface WebCGMNode, mais puisque ce ne sont pas en réalité des sous-nœuds de l'élément qu'ils décrivent, le DOM de WebCGM ne les considère pas comme faisant partie de l'arbre du document. Les attributs de WebCGMNode parentNode, previousSibling et nextSibling ont donc une valeur "null" pour les objets WebCGMAttr.

Définition IDL

interface WebCGMAttr: WebCGMNode { readonly attribute WebCGMString name; attribute WebCGMString value; readonly attribute WebCGMNode ownerNode; };

Attributs

name de type WebCGMString, en lecture seule

Retourne le nom de cet attribut. Si la valeur de WebCGMNode.localName est différente de la chaîne vide, cet attribut est un nom qualifié.

value de type WebCGMString, en lecture seule

À la récupération, la valeur de l'attribut est retournée en tant que chaîne, cf. la méthode WebCGMNode.getAppStructureAttr(). À l'initialisation, elle équivaut à WebCGMNode.setAppStructureAttr().

Exceptions à l'initialisation

WebCGMException; NO_MODIFICATION_ALLOWED_ERR : Soulevée lorsque le nœud est en lecture seule.

ownerNode de type WebCGMNode, en lecture seule

Le nœud de type Element auquel cet attribut est associé, ou la valeur "null" si cet attribut n'est pas utilisé.

Méthodes

Aucune méthode définie.

5.7.9 L'interface WebCGMEventListener

L'interface WebCGMEventListener est la méthode principale pour manipuler les événements. Les utilisateurs enregistrent leurs guetteurs sur le nœud WebCGMMetafile avec la méthode addEventListener.

Définition IDL

interface WebCGMEventListener { void handleEvent(in WebCGMEvent evt); };

Exemple d'enregistrement avec addEventListener

EXEMPLE :

Cet exemple simple montre l'utilisation de la méthode addEventListener de l'interface WebCGMMetafile dans HTML & ECMAScript. Dans un navigateur prêt pour le DOM de WebCGM, l'exécution de ce code HTML-ECMAScript devrait afficher une image avec deux figures carrées dans un cadre noir, et un clic de souris n'importe où sur l'une d'elles devrait produire un message d'alerte disant « Event handler installed successfully. »

<html>
<head>
<title>Example for WebCGMEventListener</title>
<script type="text/ecmascript">

var cgmDoc;

function InstallEventListener() {
  try {
    cgmDoc = document.getElementById("ivx1").getWebCGMDocument();
    cgmDoc.src = 'ex_WebCGM_Event.cgm';
    cgmDoc.addEventListener( "click", handleClick);
  }
  catch(e) {
    alert( "Failed:  " + e.description );
  }
}
function handleClick(evt) {
  alert( "Event handler installed successfully." );
}
</script>
</head>

<body onload="InstallEventListener();">
  <table border="1" rules="cols">
    <tr style="text-align:center;">
      <th>Example, WebCGMEventListener Interface</th> <