Lisez-moi S.V.P. 

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.

Sommaire

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.

Exemple 5.1a : Ce document WebCGM (exprimé dans un codage en clair des textes) sera mis à jour par un fichier d'accompagnement XML.

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
Figure n° 7. Structure originale de l'arbre

Exemple 5.1b : Le fichier d'accompagement XML à « appliquer » au fichier example.cgm de l'exemple 5.1a.

<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
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 :
  4. Si c'est un élément linkuri, les règles suivantes s'appliquent :
  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éé.

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.

Exemple : Pour définir un attribut APS region constitué de deux sous-régions :
setAppStructureAttr("region", "''1 0 0 100 100' '1 25 25 75 75'")

Exemple : On pourrait représenter un multilien composé de deux liens par la chaîne délimitée suivante :
'http://www.w3.org/' 'W3C' '_blank' 'http://www.cgmopen.org/' 'CGMOpen' '_self'.

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.

Exemple : Pour définir un attribut APS region constitué d'une seule sous-région :
setAppStructureAttr("region", "1 0 0 100 100")

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.

Exemple 1 : L'exemple le plus simple possible, où les coordonnées VDC et NVDC sont identiques

Les coordonnées VDC de l'image ont leur origine en bas à gauche, la coordonnée X augmente vers la droite, la coordonnée Y augmente vers le haut, l'image est large de 150 mm et haute de 100 mm. Les coordonnées NVDC sont identiques : (0.,0.) pour le coin inférieur gauche, (150.,100.) pour le coin supérieur droit. Si (x, y) sont des coordonnées VDC et (x', y') des coordonnées NVDC, alors :

Exemple 2 : Les coordonnées VDC définissent une origine en haut à gauche et correspondent au format de papier U.S. de 8.5x11.0 pouces :

Dans l'espace VDC, l'origine est le coin supérieur gauche, la coordonnée X augmente vers la droite, la coordonnée Y augmente vers le bas. Dans l'espace NVDC, les coordonnées du coin inférieur gauche (lower-left) sont, comme toujours, (0, 0) et du coin supérieur droit (upper-right) sont (215.9, 279.4). Si (x, y) sont des coordonnées VDC et (x', y') des coordonnées NVDC, alors :

Exemple 3 : Dans le cas général, si les coordonnées de l'étendue VDC sont (xll, yll), (xur, yur) et le facteur d'échelle est 'metric', s, alors les coordonnées NVDC (x', y') se déduisent des coordonnées VDC (x, y) par :

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 :

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

Règles & codages de l'accès DOM aux attributs APS
Nom d'attribut APS lecture/écriture Delimited string Exemple
content oui non, une seule chaîne "transmission d'un moteur de voiture"
interactivity oui non, une seule chaîne "on"
layerdesc oui non, une seule chaîne "Cette couche contient des instructions en français"
layername en lecture seule non, une seule chaîne "Instructions en français"
linkuri oui oui, multiples triplets possibles '"http://w3.org" "W3C" "_blank"'
name en lecture seule oui, multiples noms possibles '"firstName" "anotherName"'
region oui oui, multiples sous-régions possibles '"1 0 0 100 100" "1 25 25 75 75"'
screentip oui non, une seule chaîne "Voici une infobulle"
viewcontext oui non, un seule chaîne (deux points d'angle) "0 0 100 100"
visibility oui non, une seule chaîne "on"

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>
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>
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> </tr>
    <tr>
      <td><object id="ivx1" type="image/cgm;Version=4;ProfileId=WebCGM" 
                  width="480" height="360"></object>  </td>  </tr>
  </table>
</body>
</html>
Attributs
Aucun attribut défini.
Méthodes
handleEvent

Cette méthode est appelée à chaque fois que se produit un événement du type pour lequel l'interface WebCGMEventListener a été enregistrée.

Paramètres
evt de type WebCGMEvent

L'objet WebCGMEvent contenant les informations contextuelles de l'événement.

Valeur retournée
Aucune valeur retournée.
Exceptions
Aucune exception.

5.7.10 L'interface WebCGMEvent

L'interface WebCGMEvent sert à fournir les informations contextuelles concernant un événement au gestionnaire de traitement de l'événement.

Il existe trois niveaux d'interactivité dans WebCGM :

Cette section décrit également comment l'agent utilisateur traite les trois différents niveaux d'interactivité.

Lorsqu'un événement de souris a lieu, l'agent utilisateur WebCGM détermine l'objet cible de l'événement de souris. Pour les besoins de cette discussion, le terme « objet » désigne une structure d'application (APS). L'objet cible est l'objet en position supérieure dont la région interactive est sous le pointeur de la souris à l'instant de l'événement. (Notez que la définition de la région interactive exclut les objets complètement transparents du fait du paramétrage de leurs attributs graphiques).

Une structure d'application de type grnode ou layer ne peut pas être cible d'un événement de souris. Si le pointeur de la souris survolait une structure grnode lorsque l'événement s'est produit, c'est l'objet ancêtre le plus proche de type grobject, para ou subpara de celui-ci qui sera désigné comme élément cible. Si un objet n'est pas affiché (c'est-à-dire que son attribut visibility vaut "off") ou rendu non interactif (c'est-à-dire que son attribut interactivity vaut "off"), cet objet ne peut pas être la cible d'événements de souris.

L'événement est au départ affecté au métafichier, ou sinon pas affecté, selon les situations suivantes :

Cf. également les descriptions de grobject, grnode, para ou subpara pour des informations en relation.

L'ordre de traitement des événements de l'interface d'utilisateur est le suivant :

Puisque, en général, les hyperliens changeront le contexte d'un document, il est plus judicieux de d'abord laisser les gestionnaires explicites agir sur un événement et de traiter ensuite l'hyperlien. L'ordre inverse ne peut garantir l'exécution du script. Les créateurs de scripts devrait savoir que cette spécification ne couvre pas les dispositifs d'événement de l'agent utilisateur tels que l'agrandissement, le panoramique ou les menus contextuels. Le mécanisme pour invoquer l'une de ces fonctionnalités sera vraisemblablement différent entre les vendeurs. Les créateurs de scripts doivent prendre conscience de ces différences et sont donc encouragés à écrire des scripts WebCGM interopérables.

Définition IDL
interface WebCGMEvent {
  readonly attribute WebCGMString     type;
  readonly attribute WebCGMNode       target;
  readonly attribute unsigned short   button;
  readonly attribute long             numPressed;
  readonly attribute float            clientX;
  readonly attribute float            clientY;
  readonly attribute boolean          ctrlKey;
  readonly attribute boolean          shiftKey;
  readonly attribute boolean          altKey;
  readonly attribute boolean          metaKey;

  void               preventDefault();
};
Exemple de base

EXEMPLE :

Cet exemple simple montre l'utilisation des attributs de l'interface WebCGMEvent dans HTML & ECMAScript. Dans un navigateur prêt pour le DOM de WebCGM, l'exécution réussie de ce code HTML-ECMAScript devrait afficher une image avec deux figures carrées dans un cadre noir. Un clic de souris n'importe où dans le fond noir de gauche devrait indiquer la position X/Y du clic, et le survol par la souris de l'ellipse de gauche devrait faire état de ce survol.

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

  var cgmDoc;

  function handleClick(evt) {
    try {
      if( evt.target.apsId == "grobject_rect_1" ) {
          alert( "ClientX = " + evt.clientX + "  ClientY = " + evt.clientY );
      }
    }
    catch(e) {
      alert( e );
    }
  }
  function handleMOver(evt) {
    try {
      if( evt.target.apsId == "grobject_circle_1" ) {
        alert( "You have mouse-over'd grobject_circle_1" );
      }
    }
    catch(e2) {
        alert( e2 );
    }
  }
  function addHandlers() {
    try {
      cgmDoc = document.getElementById("ivx1").getWebCGMDocument();
      cgmDoc.src = 'ex_WebCGM_Event.cgm';
      cgmDoc.addEventListener ("click", handleClick);
      cgmDoc.addEventListener ("mouseover", handleMOver);
    }
    catch(e4) {
        alert( e4 );
    }      
  }
</script>
</head>
<body onload="addHandlers();">
    <table border="1" rules="cols">
        <tr style="text-align:center;">
            <th>Example, WebCGMEvent Interface</th> </tr>
        <tr> 
            <td><object id="ivx1" type="image/cgm;Version=4;ProfileId=WebCGM" 
                        width="480" height="360"></object> </td> </tr>
    </table>
</body>
</html>
Attributs
type de type WebCGMString, en lecture seule

Le nom de l'événement (insensible à la casse). Le nom doit être un nom XML.

target de type WebCGMNode, en lecture seule

Utilisé pour indiquer l'objet WebCGMNode (structure d'application) auquel l'événement a été transmis à l'origine.

button de type unsigned short, en lecture seule

Pendant les événements de souris causés par la pression ou le relâchement d'un bouton de souris, l'attribut button sert à indiquer quel bouton de souris a changé d'état. L'attribut button prend la valeur "0" pour indiquer le bouton gauche de la souris, "1" pour indiquer le bouton du milieu, le cas échéant, et "2" pour indiquer le bouton droit. Pour les souris dans une configuration pour gaucher, où les actions de bouton sont inversées, les valeurs le sont aussi.

numPressed de type long, en lecture seule

Indique le nombre de fois où un bouton de souris a été pressé et relâché dans la même position d'écran au cours d'une action de l'utilisateur. La valeur d'attribut est "1" lorsque l'utilisateur entame cette action et s'incrément de 1 pour chaque séquence de pression et relâchement. Si l'utilisateur bouge la souris entre les événements mousedown (N.d.T. pression) et mouseup (N.d.T. relâchement), la valeur sera mise à "0", indiquant qu'aucun clic n'a eu lieu.

clientX de type float, en lecture seule

La coordonnée horizontale où l'événement s'est produit, exprimée en coordonnées NVDC (Normalized VDC).

clientY de type float, en lecture seule

La coordonnée verticale où l'événement s'est produit, exprimée en coordonnées NVDC.

ctrlKey de type boolean, en lecture seule

Sert à indiquer si la touche « CTRL » a été pressée au lancement de l'événement.

shiftKey de type boolean, en lecture seule

Sert à indiquer si la touche « MAJ » a été pressée au lancement de l'événement.

altKey de type boolean, en lecture seule

Sert à indiquer si la touche « ALT » a été pressée au lancement de l'événement. Sur certaines plateformes, cette touche peut correspondre à un autre nom de touche.

metaKey de type boolean, en lecture seule

Sert à indiquer si la touche « META » a été pressée au lancement de l'événement. Sur certaines plateformes, cette touche peut correspondre à un autre nom de touche.

Méthodes
preventDefault

L'appel de la méthode preventDefault a pour effet d'annuler l'événement. Toute action par défaut associée à l'événement n'aura pas lieu.

Paramètres
Aucun paramètre.
Valeur retournée
Aucune valeur retournée.
Exceptions
Aucune exception.

WebCGM utilise les types d'événements suivants :

click
L'événement click se produit lorsque le bouton du dispositif de pointage est cliqué. On définit un événement click comme des événements mousedown et mouseup à la même position à l'écran. La séquence de ces événéments est la suivante : mousedown, mouseup, click. Si plusieurs clics se produisent au même endroit de l'écran, la séquence se répète, l'attribut detail s'incrémentant à chaque répétition. La structure d'application (le cas échéant) sous le pointeur de la souris au clic s'inscrit dans la propriété WebCGMEvent.target.
mousedown
L'événement mousedown se produit lorsque le bouton du dispositif de pointage est pressé. La structure d'application (le cas échéant) qui se trouvait sous le pointeur de la souris lors de la pression s'inscrit dans la propriété WebCGMEvent.target.
mouseup
L'événement mouseup se produit lorsque le bouton du dispositif de pointage est relâché. La structure d'application (le cas échéant) qui se trouvait sous le pointeur de la souris lors du relâchement s'inscrit dans la propriété WebCGMEvent.target.
mouseover
L'événement mouseover se produit lorsque le dispositif de pointage est déplacé sur une structure d'application. La structure d'application survolée par le pointeur de la souris s'inscrit dans la propriété WebCGMEvent.target.
mouseout
L'événement mouseout se produit lorsque le dispositif de pointage est déplacé hors d'une structure d'application. La structure d'application quittée par le pointeur de la souris s'inscrit dans la propriété WebCGMEvent.target.
load
L'événement load se produit lorsque la mise en œuvre DOM de WebCGM a fini de charger tout le contenu d'un métafichier WebCGM.
unload
L'événement unload se produit lorsque la mise en œuvre DOM de WebCGM retire un métafichier WebCGM d'une fenêtre ou d'un cadre.

Retour au début du chapitre