WebCGM Document Object Model (DOM) Specification
Version 1.0
Working Draft August 2, 2004
This version:
Latest version:
Previous version:
Editors:
Authors:
Abstract
Status of this document
Table of contents
Expanded Table of Contents
Copyright Notice
1. WebCGM Document Object Model
Appendix A: Changes
Appendix B: IDL Definitions
Appendix C: ECMAScript Language Binding
Appendix D: Acknowledgements
Glossary
References
Index
Possible work for the Editor:
|
1. WebCGM Document Object Model
1.1 Overview of the WebCGM DOM Interfaces
This section defines a set of objects and interfaces for accessing and manipulating WebCGM documents. The functionality specified in this section is to allow script writers to manipulate WebCGM documents and to access information found in standard WebCGM XML companion files. The WebCGM DOM API does not allow for the creation of new Nodes but instead provides methods to update a WebCGM Picture based on external metadata (XML companion file).
1.1.b Relationship with XML DOM Level 3
Although inspired by the DOM Level 2 and Level 3 specifications, the WebCGM DOM remains oriented towards WebCGM specific functionality. Since WebCGM uses a tree structure to group graphical primitives, it was therefore appropriate to use interfaces similar to DOM Level 3 Node, Element and Document. However, since WebCGM is expressed in a non-XML syntax, several changes had to be made to a number of commonly known interfaces to improve the user experience for WebCGM script writers.
The WebCGM DOM could almost be perceived as a 'readonly' DOM. It is true that some methods on interfaces allow users to change an Application Structure style but, unlike the DOM Level 3 specification, it does not allow for removal or insertion of new Nodes into the object model. This constitute a significant difference between DOM Level 3 and the WebCGM DOM.
Since WebCGM currently offers interactivity functionality via hyperlinking and highlighting; the WebCGM DOM is based on some functionality found in the DOM Events Level 2 specification. The WebCGM DOM is making use of the addEventListener method and also customized an Event interface in order to meet the requirements of WebCGM users.
1.1.1 Relationship with XML companion file
The WebCGM DOM is designed to provide access to XML metadata found in XML companion files. Practice has shown that some CGM illustrations are easier to maintain if some of the non graphical information remains outside the illustration. An example of such information could be for example; language sensitive tooltips. A scaled down DOM is then required to 'apply' the information from the XML companion file to the WebCGM document. For more information on XML companion files, please refer to the WebCGM XML companion file section.
Another benefit of the XML companion file is to carry application specific data (or metadata) concerning a WebCGM illustration. This information is expressed using namespace attributes and elements in the XML companion file. The WebCGM DOM provides method to load the XML metadata into the user agent's object model. Using the DOM, a user can gain access to the metadata. Here is an example to better illustrate the concept, let us assume we are working with the following WebCGM document (expressed in clearText encoding):
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;
|
The in memory tree representation of this illustration should be similar to the illustration found below. It is a simple tree structure with a root element Metafile, one of the children of the root is a Picture; the Picture contains a Layer and the layer contains an Application Structure of type grobject.
Now let us assume example.cgm has the following XML companion file:
<cgmCompanion id="example" xmlns:wiring="http://namespace_declaration">
<grobject apsId="G1" screentip="A new screentip">
<wiring:data color="rgb(255,0,0)"/>
</grobject>
</cgmCompanion>
|
| We need to verify that the final DTD and this example have the same tagNames |
As mentioned above, the WebCGM provides methods to 'apply' an XML companion file to a WebCGM document. A comforming user agent is expected to load and parse the XML companion file and possibly 'apply' the XML companion file to the user agent's object model. The purpose of applying a companion file is to:
i) Replace standard Application Structure Attributes that are present in the WebCGM instance with new values (if found in XML companion file).
ii) Supply standard Application Structure Attributes to Application Structures in the WebCGM instance that contain no values.
iii) Add XML metadata to the user agent's object model to be retrieved using DOM APIs at a later stage (e.g., the <wiring:data> element is added as a child node of grobject G1; this would then allow the data to be used in an interactive -scripted- wiring application).
In its current form, the DOM methods do not allow for the creation of new Application Structures within the WebCGM document, only to modify existing ones.
Once the user agent has loaded the XML companion file into its memory model, the tree should resemble this:
1.1.2 Basic Data Types
Type definition DOMString
A DOMString is a sequence of 16-bit units.
IDL Definition
valuetype DOMString sequence<unsigned short>; |
In WebCGM, like DOM Level 3, the UTF-16 encoding was chosen because of its widespread industry practice. For Java and ECMAScript, DOMString is bound to the String type because both languages also use UTF-16 as their encoding.The DOM has many interfaces that imply string matching. For XML, string comparisons are case-sensitive and performed with a binary comparison of the 16-bit units of the DOMStrings.
LinkURIs
When using the WebCGM DOM, a linkURI is represented using a DOMStringList object. WebCGM uses three attributes to define a linkURI: href: the location of the referenced object, expressed as a URI reference; title: a string used to describe the meaning of a link or resource in a human-readable fashion; behavior: describes to the viewer how to display the picture. Since a single WebCGM hyperlink may contain up to three strings and WebCGM allows for multiple linkuris to exist on an Application Structure, the DOM imposes a restriction that a linkURI must be defined using three strings. The DOM also makes it possible to represent a list of linkURIs using a DOMStringList object. In that case, the DOMStringList will contain 3 * n strings, n being the number of linkURI within the list. Here is an example of how two linkURIs are represented within a DOMStringList; 3 * (2 linkURIs) = 6 strings in total.
| DOMStringList | ||||||||||||||||
|
1.1.3 Coordinate values
In WebCGM, the values representing coordinates are influenced by several CGM elements, e.g., the VDC type, the VDC extent, and the scale mode. To simplify working with coordinates, the WebCGM DOM uses metric values in a coordinate system that has its origin at the lower left corner of the VDC extent with the X axis pointing to the right, and the Y axis pointing up. Coordinate values are the resulting values after having read the WebCGM.
| An illustration and a few examples would be very useful here. |
1.2 Fundamental Interfaces
The interfaces within this section are considered fundamental, and must be
fully implemented by all conforming implementations of the WebCGM DOM. The
WebCGM DOM presents WebCGM documents as a hierarchy of Node objects that also implement other, more
specialized interfaces. Some of the node types may have child nodes of
various types, and others are leaf nodes that cannot have anything below them
in the WebCGM document structure. WebCGM has the following node types and
children:
Metafile -- contains a list of
Picture nodes.
Picture -- may contain
AppStructures or XML metadata nodes.
AppStructure -- may contain
AppStructures or XML metadata nodes.
Attr -- no children.
Text -- no children.
The WebCGM DOM also specifies several other interfaces to facilitate
access to WebCGM attributes. The GetWebCGMDocument interface is
the medium between the host environment and the WebCGM functionality. The
NodeList interface
allows to handle ordered lists of Nodes. Similar to the NodeList interface,
the DOM also offers a DOMStringList interface to handle
lists of DOMStrings. The Event interface provides contextual
information regarding mouse events.
Exception DOMException
WebCGM operations only raise exceptions when an operation is impossible to perform.
IDL Definition
exception DOMException {
unsigned short code;
};
// ExceptionCode
const unsigned short INDEX_SIZE_ERR = 1;
const unsigned short DOMSTRING_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 VALIDATION_ERR = 8;
const unsigned short FILE_NOT_FOUND_ERR = 9;
const unsigned short FILE_INCOMPATIBILITY_ERR = 10;
|
Definition group ExceptionCode
An integer indicating the type of error generated
Defined Constants
INDEX_SIZE_ERR; if index or size is negative, or greater than the allowed value.
DOMSTRING_SIZE_ERR; if the specified range of text does not fit into a DOMString.
INVALID_CHARACTER_ERR; if an invalid or illegal character is specified, such as in an XML name.
NO_DATA_ALLOWED_ERR; if data is specified for a node which does not support data.
NO_MODIFICATION_ALLOWED_ERR; if an attempt is made to modify an object where modifications are not allowed.
NOT_SUPPORTED_ERR; if the implementation does not support the requested type of object or operation.
INVALID_ACCESS_ERR; if a parameter or an operation is not supported by the underlying object.
FILE_NOT_FOUND_ERR; if the reference document could not be accessed
FILE_INVALID_ERR; if the reference document was not well-formed or was in error.
Interface GetWebCGMDocument
Since WebCGM documents are often embedded within a host document such as XHTML, WebCGM user agents are required to implement the GetWebCGMDocument interface for the element which references the WebCGM document (e.g., the 'object' tag).
IDL Definition
interface GetWebCGMDocument {
Metafile getWebCGMDocument ( ) raises ( DOMException );
};
|
Methods
getWebCGMDocument
Returns the Metafile object for the referenced WebCGM document.
No parameters
Return value
Metafile; The Metafile object for the referenced WebCGM document.
Exceptions
DOMException; NOT_SUPPORTED_ERR: No Metafile object is available.
Attributes
Interface Metafile
The Metafile interface is the entry point to the entire WebCGM document. The interface expose information regarding the metafile and provides access to the first Picture of the WebCGM document.
IDL Definition
interface Metafile {
readonly attribute DOMString metafileDescription;
readonly attribute Picture firstPicture;
readonly attribute DOMString metafileID;
readonly attribute usigned short metafileVersion;
attribute DOMString src;
};
|
Attributes
metafileDescription of type DOMString, readonly
Returns the Metafile Descriptor of the WebCGM document (e.g., "ProfileId:WebCGM,ProfileEd:1.0,Source:A software vendor,Date:20040602,ColourClass:monochrome" ). The cgmDescription must contain the ProfileId: and the ProfileEd:, other information such as Source, ColourClass etc... is considered optional.
firstPicture of type Picture, readonly
Returns the first Picture element of the WebCGM document. Subsequent Pictures can be accessed using the Picture interface. A WebCGM document contains at least one Picture.
metafileID of type DOMString, readonly
Returns the Metafile Identifier (also known as the CGM ID).
metafileVersion of type unsigned short, readonly
Returns the Metafile Version of the WebCGM document.
src of type DOMString
The URI of the current document. On setting, the new document pointed to by the URI is loaded by the user agent. The user agent must fully parse the fragment identifier (if any) in the URI and execute the indicated behavior.
Interface Node
The Node interface is the base datatype of the WebCGM Document Object Model. The Node object is the basis of several other interfaces; XMLElements and WebCGM specific elements (i.e., AppStructure & Picture). The Node interface specifies the attributes and methods to perform simple and generic tree traversal routines.
IDL Definition
interface Node {
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 DOMString nodeName;
readonly attribute DOMString nodeValue;
// raises(DOMException) on retrieval
readonly attribute unsigned short nodeType;
readonly attribute Node parentNode;
readonly attribute NodeList childNodes;
readonly attribute Node firstChild;
readonly attribute Node lastChild;
readonly attribute Node previousSibling;
readonly attribute Node nextSibling;
readonly attribute Picture ownerPicture;
boolean hasChildNodes();
boolean hasAttributes();
boolean hasAttributeNS(in DOMString namespaceURI,
in DOMString localName);
readonly attribute NodeList attributes;
readonly attribute DOMString namespaceURI;
readonly attribute DOMString prefix;
readonly attribute DOMString localName;
DOMString getAttributeNS(in DOMString namespaceURI,
in DOMString localName);
DOMString setAttributeNS(in DOMString namespaceURI,
in DOMString qualifiedName,
in DOMString value);
NodeList getElementsByTagNameNS(in DOMString namespaceURI,
in DOMString localName);
};
|
Definition group NodeType
An integer indicating which type of node this is.
Defined Constants:
PICTURE_NODE; the node is a Picture.
APP_STRUCTURE_NODE; the node is an AppStructure.
XML_METADATA_NODE; the node is XML companion information attached to a CGM element.
TEXT_NODE; the node is a Text.
ATTR_NODE; the node is an Attr.
The values of nodeName and nodeValue vary according to the node type as follows:
| Interface | nodeName | nodeValue |
| AppStructure | AppStructure type ("layer" | "grobject" | "para" | "subpara") | null |
| Attr | Attr.name | null |
| Picture | "#picture" | null |
| Text | "#text" | content of the text node |
| XML Metadata | prefix + localName | null |
Attributes
nodeName of type DOMString, readonly
The name of this node, depending on its type; see the table above.
nodeValue of type DOMString
The value of this node, depending on its type; see the table above.
Exceptions on setting
DOMException; NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly and if it is not defined to be null.
Exceptions on retrieval
DOMException; DOMSTRING_SIZE_ERR: Raised when it would return more characters than fit in a DOMString variable on the implementation platform.
nodeType of type unsigned short, readonly
A code representing the type of the underlying object, see the table above.
parentNode of type Node, readonly
The parent (immediate ancestor node of a node) of this node. All nodes, except Picture may have a parent.
childNodes of type NodeList, readonly
A NodeList that contains all children of this node. If there are no children, this returns an empty NodeList.
firstChild of type Node, readonly
The first child of this node. If there is no such node, this returns null.
lastChild of type Node, readonly
The last child of this node. If there is no such node, this returns null.
previousSibling of type Node, readonly
The node immediately preceding this node. If there is no such node, this returns null.
nextSibling of type Node, readonly
The node immediately following this node. If there is no such node, this returns null.
ownerPicture of type Picture, readonly
The Picture object associated with this node. When the node is a Picture node, this returns null.
attributes of type NodeList, readonly
A NodeList containing the all attributes (WebCGM and namespeced) of this node or null if the Node doesn't have any attributes.
namespaceURI of type DOMString, readonly
The namespace URI of this node (e.g., elementName xmlns="http://www.example.org/2004", returns "http://www.example.org/2004"). This is not a computed value that is the result of a namespace lookup based on an examination of the namespace declarations in scope.It is the namespace URI given at creation time. This returns null if the Node is not of type XML_METADATA_NODE.
prefix of type DOMString, readonly
The namespace prefix of this node (e.g., foo:elementName, returns "foo"). This returns null if the Node is not of type XML_METADATA_NODE or ATTR_NODE.
localName of type DOMString, readonly
Returns the local part of the qualified name of this node (e.g., foo:elementName, returns "elementName"). This returns null if the Node is not of type XML_METADATA_NODE or ATTR_NODE.
Methods
hasChildNodes
Returns whether this node has any children.
No Parameters
Return Value
boolean; true if this node has any children, false otherwise.
No Exceptions
hasAttributes
Returns whether this node has any attributes.
No Parameters
Return Value
boolean; true if this node has any attributes, false otherwise.
No Exceptions
hasAttributeNS
Returns true when an attribute with a given local name and namespace URI is specified on this Node, returns false otherwise.
No Parameters
Return Value
boolean; true if this node has any children, false otherwise.
No Exceptions
getAttributeNS
Returns the node attribute value by local name and namespace URI.
Parameters
namespaceURI of type DOMString
The namespace URI of the attribute to retrieve.
localName of type DOMString
The local name of the attribute to retrieve.
Return Value
DOMString; The Attr value as a string, or the empty string if that attribute does not have a specified value.
No Exceptions
setAttributeNS
Adds a new attribute. If an attribute with that name is already present on the node, its value is changed to be that of the value parameter.
Parameters
namespaceURI of type DOMString
The namespace URI of the attribute to create or alter.
qualifiedName of type DOMString
The qualified name of the attribute to create or alter.
value of type DOMString
The value to set in string form.
No Return Value
DOMString; The Attr value as a string, or the empty string if that attribute does not have a specified value.
Exception INVALID_CHARACTER_ERR: Raised if the specified qualified name contains an illegal character.
Exception NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
getElementsByTagNameNS
Returns a NodeList of all the descendant XML elements (companion information) with a given local name and namespace URI in the order in which they are encountered in a preorder traversal of the Node tree.
Parameters
namespaceURI of type DOMString
The namespace URI of the XML elements to match on.
localName of type DOMString
The local name of the XML elements to match on.
Return Value
NodeList; A list of matching XML element nodes.
No Exceptions
Interface Picture
The Picture interface allows for access to the application structures of the WebCGM document. It also specifies how to load and apply an XML companion file to a WebCGM document.
IDL Definition
interface Picture : Node {
readonly attribute float width;
readonly attribute float height;
readonly attribute DOMString pictid;
void addEventListener(in DOMString type,
in EventListener listener);
void removeEventListener(in DOMString type,
in EventListener listener));
boolean applyCompanionFile(in DOMString fileURI);
Node getAppStructureById(in DOMString apsId);
NodeList getAppStructuresByName(in DOMString apsName);
void highlight(in NodeList nodes,
in boolean state);
void setStyleAttr(in DOMString style,
in DOMString value);
void clearStyleAttr(in DOMString style);
void reloadPicture();
};
|
Attributes
width of type float, readonly
Represents the Picture width in millimeters. Please refer to Coordinate Values section for more information.
height of type float, readonly
Represents the Picture height in millimeters. Please refer to Coordinate Values section for more information.
pictid of type DOMString, readonly
Represents the Picture id, which is the id parameter in the BEGIN PICTURE element in the CGM document.
Methods
addEventListener
This method allows the registration of event listeners on the current Picture node. If an EventListener is added to the Picture while it is processing an event, it will not be triggered by the current actions. If multiple identical EventListeners are registered on the same Picture with the same parameters the duplicate instances are discarded. They do not cause the EventListener to be called twice. Although all EventListeners on the Picture are guaranteed to be triggered by any event which is received by that Node, no specification is made as to the order in which they will receive the event with regards to the other EventListeners on the Node.
Parameters
type of type DOMString
The event type for which the user is registering, (for example: "click", "mousemove").
listener of type EventListener
The listener parameter takes an interface implemented by the user which contains the methods to be called when the event occurs.
No Return Value
No Exceptions
removeEventListener
This method allows the removal of event listeners on the current Picture node. If an EventListener is removed from the Picture while it is processing an event, it will not be triggered by the current actions. EventListeners can never be invoked after being removed. Calling removeEventListener with arguments which do not identify any currently registered EventListener on the Picture has no effect.
Parameters
type of type DOMString
Specifies the event type of the EventListener being removed (for example: "click", "mousemove").
listener of type EventListener
The EventListener parameter indicates the EventListener to be removed.
No Return Value
No Exceptions
applyCompanionFile
The applyCompanionFile reads an XML companion file into the user agent's object model. If companion information is found in the companion file (in the form of namespace attributes and namespace children elements), the user agent will create new namespace application structures as children of existing WebCGM Application Structures within it's object model. This information will then be accessible using methods found on the Picture, AppStructure and Node interfaces. Please refer to the Relationship with XML companion file section for more detail.
Parameters
fileURI of type DOMString
The file name and location of the XML companion file to load and apply into the object model.
Return value
boolean; true if the implementation was able to load and parse the XML companion file into memory as requested; false otherwise.
Exceptions FILE_NOT_FOUND_ERR; if the reference document could not be accessed.
Exceptions FILE_INVALID_ERR; if the reference document was not well-formed or in error.
getAppStructureById
Returns the Application Structure whose ID is given by apsId. If no such Application Structure exists, returns null. Behavior is not defined if more than one element has this ID. Only WebCGM Application Structures may be retrieved using getAppStructureById, it does not retrieve arbitrary namespace elements (metadata elements).
Parameters
apsId of type DOMString
The unique id value for an Application Structure.
Return value
Node; the matching Application Structure.
No Exceptions
getAppStructuresByName
Returns the list of Application Structures whose names are given by apsName in the order in which they are encountered in a preorder traversal of the Picture tree. If no such Application Structures exists, returns null. Only WebCGM Application Structures may be retrieved using getAppStructuresByName.
Parameters
apsName of type DOMString
A non-unique name value for an Application Structure.
Return value
NodeList; A NodeList object containing all the matching Application Structure Nodes.
No Exceptions
highlight
Highlights a collection of Application Structures. WebCGM allows for highlighting of application structures using the URI fragment syntax (insert ref to REC?). The exact method of highlighting is viewer dependent. The highlight method provides a way for WebCGM script writers to highlight application structures in the same way a URI fragment would. It also allows for highlighting of entire layers. Highlighting is not defined for Picture nodes or XML Metadata nodes.
Parameters
nodes of type NodeList
A NodeList of APP_STRUCTURE_NODEs to highlight.
state of type boolean
A true value will highlight the nodes, whereas false will remove the highlight.
No Return value
No Exceptions
setStyleAttr
Set a style attribute at the picture level by name. The following table describes in more details each style attribute, their scope and allowed values:
| Style Attribute Name | Picture level | APS level | Attribute value(s) | Example |
| background-color | yes | no | absolute RGB or relative intensity (0..100%) | "#000000" or "75%" |
| character-height | yes | yes | relative scale (> 0%) | "225%" |
| fill-color | yes | yes | absolute RGB or relative intensity (0..100%) | "#FF0000" or "75%" |
| intensity | yes | yes | intensity (0..100%) | "75%" |
| stroke-color | yes | yes | absolute RGB or relative intensity (0..100%) | "#FF0000" or "75%" |
| stroke-weight | yes | yes | relative scale (> 0%) | "225%" |
| text-color | yes | yes | absolute RGB or relative intensity (0..100%) | "#FF0000" or "75%" |
| text-font | yes | yes | DOMString | "Helvetica" |
| raster-intensity | yes | yes | relative intensity (0..100%) | "75%" |
| visibility | no | yes | DOMString | "visible" | "hidden" |
Note: Descriptions of all style attributes have to be provided. stroke-color includes CGM attributes edge-color, line-color and marker-color. stroke-weight includes CGM attributes edge-weight and line-weight. RGB colors are expressed has hexadecimal values. Relative scale values are expressed as a non-negative number followed by a '%' unit, ex: "225%", the value can exceed 100%. Relative intensity values are expressed as a number followed by a '%' unit, ex: "75%", the value cannot exceed 100%.
absolute RGB colors are expressed using a hexadecimal representation for all three RGB channels, #RRGGBB. The following are two examples of colors expressed in hexadecimal representation: red is expressed as #FF0000 and cyan which uses both green and blue channels is expressed as #00FFFF. The shorthand hexadecimal notation is not supported in this specification.
| relative scale: |
| background-color: |
| character-height: |
| fill-color: |
intensity is a way to make the current color fade towards white. An intensity value of 0% will make the current application structure completely white while a value of 100% will keep the current color intact. The intensity equation is as follows:
normalizedNewRed = 1 - intensity * (1 - normalizedOldRed).
normalizedNewGreen = 1 - intensity * (1 -
normalizedOldGreen).
normalizedNewBlue = 1 - intensity * (1 -
normalizedOldBlue).
Here is an example of the computations when applying an intensity of 40% to the color 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.6.
The new color is %FFDB99.
Setting a relative intensity value is allowed on a number of style attributes, see table found above. The 'intensity' attribute however, represents a convinence attribute that controls the intensity value of the following four attributes: fill-color, stroke-color, text-color and raster-intensity.
| stroke-color: |
| stroke-weight: |
| text-color: |
| text-font: |
| raster-intensity: |
| visibility: |
Parameters
style of type DOMString
The name of the style attribute to modify.
value of type DOMString
The new value for the given style.
No Return value
| If visibility and interactivity are added to WebCGM 2, they will have to be moved down to the section below. |
No Exceptions
clearStyleAttr
Restores a style attribute to its original value (load time).
Parameters
style of type DOMString
The name of the style attribute. The special value "*" matches all style attributes.
No Return value
No Exceptions
reloadPicture
Notifies the user agent to immediately redraw the entire Picture. The user agent will reload the Picture while preserving the current user agent's zoom and pan level. The reloading of the Picture also discards any existing companion information that may have been loaded into memory via the applyCompanionFile method.
No Parameters
No Return value
No Exceptions
Interface AppStructure
The AppStructure interface offers methods for setting and retrieving Application Structure attributes. The general methods for accessing Application Structure attributes are getAppStructureAttr and setAppStructureAttr, however; since some attributes are allowed to be set multiple times (e.g., linkuri), the setting and retrieving functions are making use of DOMStringList objects. The following table identifies the attributes which can get access using getAppStructureAttrList and setAppStructureAttList:
| APS Attribute Name | getAppStructureAttrList | setAppStructureAttrList | Return/parameter type | Example |
| content | allowed | allowed | DOMStringList | "car engine transmission" |
| interactivity | allowed | allowed | DOMStringList (interactive | none) | "interactive" |
| layerdesc | allowed | allowed | DOMStringList | "This layer contains English instructions" |
| layername | allowed | no, readonly | DOMStringList | "English instructions" |
| linkuri | allowed | allowed | DOMStringList | "http://w3.org" "W3C" "_blank" |
| name | allowed | no, readonly | DOMStringList | "firstName" "anotherName" |
| region | allowed | allowed | DOMStringList (comma delimited SDR) | "1,0,0,100,100" |
| screentip | allowed | allowed | DOMStringList | "This is a screentip" |
| viewContext | allowed | allowed | DOMStringList (two corner points) | "0,0,100,100" |
| virtualViewContext | allowed | no, readonly | DOMStringList (two corner points) | "0,0,100,100" |
| content: |
interactivity is an attribute that enables or disables event processing. When set to a value of 'none', event handlers and linkURIs are not processed.
| layerdesc: |
| layername: |
| linkuri: |
| name: |
| region: |
| screentip: |
| viewContext: |
| virtualViewContext: |
The AppStructure interface, like the Picture interface, provides methods for modifying style attributes at the Application Structure level. For more information about available style attributes, refer to the Style Attributes Table.
IDL Definition
interface AppStructure : Node {
readonly attribute DOMString apsId;
DOMStringList getAppStructureAttrList(in DOMString name);
void setAppStructureAttrList(in DOMString name,
in DOMStringList values);
void removeAppStructureAttr(in DOMString name);
void setStyleAttr(in DOMString style,
in DOMString value);
void clearStyleAttr(in DOMString style);
};
|
Attributes
apsId of type DOMString, readonly
The unique identifier of the Application Structure.
Methods
getAppStructureAttrList
Returns the Application Structure attribute value(s) or an empty DOMStringList if that attribute does not have a value. Please refer to the Application Structure Attributes table for more detailed information on retrievable and modifiable Application Structure attributes.
Parameters
name of type DOMString
The name of the Application Structure attribute to retrieve.
Return value
DOMStringList; the Application Structure attribute value(s). The DOMStringList will have a length of zero if the attribute does not have a value; a length of one if the attribute contains a single value; or a length greater than one for attributes with multiple values.
No Exceptions
setAppStructureAttrList
Sets an Application Structure attribute value(s) by name. Please refer to the Application Structure Attributes table for more detailed information on retrievable and modifiable Application Structure attributes.
Parameters
name of type DOMString
The name of the Application Structure attribute to set.
values of type DOMStringList
The new list of values for the given attribute.
No Return value
No Exceptions
removeAppStructureAttr
Removes an Application Structure attribute by name. Please refer to the Application Structure Attributes table for more detailed information on retrievable and modifiable Application Structure attributes.
Parameters
name of type DOMString
The name of the Application Structure attribute to remove.
No Return value
No Exceptions
setStyleAttr
Set a style attribute by name on the given Application Structure. Please refer to the Style Attributes Table for more detailed information on style attributes.
Parameters
style of type DOMString
The name of the style attribute to modify.
value of type DOMString
The new value for the given style.
No Return value
No Exceptions
clearStyleAttr
Restores a style attribute to its original value (load time).
Parameters
style of type DOMString
The name of the style attribute. The special value "*" matches all style attributes.
No Return value
No Exceptions
Interface NodeList
The NodeList interface provides the abstraction of an ordered collection of nodes. NodeList objects in the WebCGM DOM are live. The index with the NodeList starts at 0.
IDL Definition
interface NodeList {
readonly attribute unsigned long length;
Node item(in unsigned long index);
};
|
Attributes
length of type unsigned long, readonly
The number of nodes in the list. The range of valid child node indices is 0 to length-1 inclusive.
Methods
items
Returns the index th item in the collection.
Parameters
index of type unsigned long
Index into the collection.
Return value
Node; The node of the index th position in the NodeList, or null if that is not a valid index.
No Exceptions
Interface DOMStringList
The DOMStringList interface provides the abstraction of an ordered collection of DOMString values. The items in the DOMStringList are accessible via an integral index, starting from 0.
IDL Definition
interface DOMStringList {
readonly attribute unsigned long length;
DOMString item(in unsigned long index);
};
|
Attributes
length of type unsigned long, readonly
The number of DOMStrings in the list. The range of valid child node indices is 0 to length-1 inclusive.
Methods
items
Returns the index th item in the collection.
Parameters
index of type unsigned long
Index into the collection.
Return value
DOMString; The DOMString at the index th position in the DOMStringList, or null if that is not a valid index.
No Exceptions
Interface Attr
The Attr interface represents an attribute in a
XML_METADATA_NODE, a PICTURE_NODE or a APP_STRUCTURE_NODE.
IDL Definition
interface Attr: Node {
attribute DOMString name;
attribute DOMStringList value;
attribute Node ownerNode;
};
|
Attributes
name of type DOMString, readonly
Returns the name of this attribute. If Node.localName is different from null, this attribute is a qualified name.
value of type DOMStringList
The value of the attribute is returned as a list of strings. Most
attribute values will be expressed as a single string, however for some
attributes such as 'linkuri', a list of strings is required. Extracting the
first string of a DOMStringList is done using value.item(0).
Character and general entity references are replaced with their values. See
also the method getAttribute on the Element interface.
Exceptions on setting
DOMException; NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly and if it is not defined to be null.
ownerNode of type Node, readonly
The Element node this attribute is attached to or null if this attribute is not in use.
Interface Text
The Text interface represents the textual content of an
XML_METADATA_NODE and ATTR_NODE.
IDL Definition
interface Text: Node {
readonly attribute DOMString data;
readonly attribute unsigned long length;
};
|
Attributes
data of type DOMString, readonly
The character data of the node that implements this interface.
Exceptions on retrieval
DOMException, DOMSTRING_SIZE_ERR: Raised when it would return more characters than fit in a DOMString variable on the implementation platform.
length of type unsigned long, readonly
The number of 16-bit units that are available through 'data'. This may have the value zero, i.e., Text nodes may be empty.
Interface
EventListener
The EventListener interface is the primary method for handling events. Users implement the EventListener interface and register their listener on a Picture Node using the AddEventListener method.
IDL Definition
interface EventListener {
void handleEvent(in Event evt);
};
|
Methods
handleEvent
This method is called whenever an event occurs of the type for which the EventListener interface was registered.
Parameters
evtof type
Event The Event contains contextual information about
the event.
No return value
InterfaceEvent
The Event interface is used to provide contextual information about an event to the handler processing the event. The processing order for user interface events is as follows:
- Events handlers assigned to a Picture the event first. If none of the activation event handlers take an explicit action (by invoking the preventDefault() DOM method) to prevent further processing of the given event, then the event is passed on for:
- Link processing. If a hyperlink is invoked in response to a user interface event, the hyperlink typically will disable further activation event processing (e.g., hyperlink to another Web page). If link processing does not disable further processing of the given event, then the event is passed on for:
- Document-wide event processing, such as user agent facilities to allow zooming and panning of a WebCGM document.
Since hyperlinks will in general change the context of a document it is more appropriate to allow explicit handlers to act on an event first and then process the hyperlink. The reverse order cannot guarantee that the script would get executed. When the Application Structure attribute interactivity is set to none, the given Application Structure does not receive any events (i.e., no event handlers or hyperlinks will be processed). Script writers should be made aware that this specification does not cover user agent event facilities such as zooming, panning or context menus. The mechanism to invoke such functionality will likely be different between vendors. Script writers are encouraged to become aware of those differences and thus, write highly interoperable WebCGM scripts.
IDL Definition
interface Event {
readonly attribute DOMString type;
readonly attribute Node 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();
};
|
Attributes
type of type DOMString, readonly
The name of the event (case-insensitive). The name must be an XML name.
target of type Node, readonly
Used to indicate the Node (Application Structure) to which the event was originally dispatched.
button of type unsigned short, readonly
During mouse events caused by the depression or release of a mouse button, button is used to indicate which mouse button changed state. The values for button range from zero to indicate the left button of the mouse, one to indicate the middle button if present, and two to indicate the right button. For mice configured for left handed use in which the button actions are reversed the values are instead read from right to left.
numPressed of type long, readonly
Indicates the number of times a mouse button has been pressed and released over the same screen location during a user action. The attribute value is 1 when the user begins this action and increments by 1 for each full sequence of pressing and releasing. If the user moves the mouse between the mousedown and mouseup the value will be set to 0, indicating that no click is occurring.
clientX of type float, readonly
The horizontal coordinate at which the event occurred expressed in WebCGM user space.
clientY of type float, readonly
The vertical coordinate at which the event occurred expressed in WebCGM user space.
| How should clientX/Y be worded? |
ctrlKey of type boolean, readonly
Used to indicate whether the 'ctrl' key was depressed during the firing of the event.
shiftKey of type boolean, readonly
Used to indicate whether the 'shift' key was depressed during the firing of the event.
altKey of type boolean, readonly
Used to indicate whether the 'alt' key was depressed during the firing of the event. On some platforms this key may map to an alternative key name.
metaKey of type boolean, readonly
Used to indicate whether the 'meta' key was depressed during the firing of the event. On some platforms this key may map to an alternative key name.
Methods
preventDefault
Calling preventDefault has the effect of cancelling the event. Any default action associated with the event will not occur.
No Parameters
No return value
WebCGM supports the following types of events:
click The click event occurs when the pointing device button is clicked. A click is defined as a mousedown and mouseup over the same screen location. The sequence of these events is: mousedown, mouseup, click. If multiple clicks occur at the same screen location, the sequence repeats with the detail attribute incrementing with each repetition. The Application Structure (if any) which was under the mouse pointer when clicked is populated in the Event.target property.
mousedown The mousedown event occurs when the pointing device button is pressed. The Application Structure (if any) which was under the mouse pointer when it was pressed down is populated in the Event.target property.
mouseup The mouseup event occurs when the pointing device button is released. The Application Structure (if any) which was under the mouse pointer when it was released populated in the Event.target property.
mouseover The mouseover event occurs when the pointing device is moved onto an Application Structure. The Application Structure that the mouse pointer moved over is populated in the Event.target property.
mouseout The mouseout event occurs when the pointing device is moved away from an Application Structure. The Application Structure that the mouse pointer moved away is populated in the Event.target property.
load The load event occurs when the DOM implementation finishes loading all content within a WebCGM Metafile.
unload The unload event occurs when the DOM implementation removes a WebCGM Metafile from a window or frame.
Appendix A: Changes
| Is this appendix required? Maybe to talk about some changes that were introduced in WebCGM 2.0 because of the DOM. Maybe this should be mentioned in the WebCGM 2.0 specification instead? |
Appendix B: IDL Definitions
| Itedo will provide the IDL definition. |
Appendix C: ECMAScript Language Binding
| Itedo will provide the ECMAScript binding. |
Appendix D: Acknowledgements
| For the Editor? |
Glossary
| For the Editor? |
References
| For the Editor? |
Index
| For the Editor? |
