This chapter defines a set of objects and interfaces for accessing and
manipulating WebCGM documents. The functionality specified in this section
enables script writers to manipulate WebCGM documents and access information
found in standard WebCGM XML companion files. The WebCGM DOM API focuses its
methods on: tree traversal, style changes, and providing access to
metadata.

Although inspired by the XML DOM 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
a set of interfaces similar to the XML DOM Node, Element and Document
interfaces. However, since WebCGM is expressed in a non-XML syntax, several
changes had to be made to commonly known interfaces and methods in order to
improve the user experience of WebCGM script writers.

The WebCGM DOM could almost be perceived as a 'readonly' DOM. Some
interface methods allow users to change the visual appearance of Application
Structures, but unlike the XML DOM specification, it does not allow for
removal or insertion of WebCGMNodes into the object model. This constitute a
significant difference between the specifications.

While WebCGM 1.0 offered interactivity support via hyperlinking and
highlighting, the WebCGM 2.0 DOM took it to the next level. WebCGM 2.1
further enhances the DOM. The WebCGM DOM borrows concepts from the DOM3
Events specification, and introduces the concept of EventListeners and
mouse Events in order to meet the requirements of WebCGM users.

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; language sensitive
screentips. The WebCGM DOM can then be used to 'apply' the information from
the XML companion file to the WebCGM document (see Example 5.3) . For more
information on XML companion file syntax, please refer to Chapter 4, WebCGM XML Companion
File.

Another benefit of the XML Companion File is to carry application specific
data (or metadata) concerning a WebCGM illustration (see Example 4.2). This
information is expressed using namespace attributes and elements in the XML
Companion File. The WebCGM DOM provides a method for loading the XML metadata
into the user agent's object model. Using the WebCGM DOM, a user can gain
access to the metadata. Here is a detailed example to better illustrate the
concept.

Example 5.1a:This WebCGM document (expressed in
clearText encoding) will be updated by an XML companion file.

The in-memory tree representation of this illustration should be similar
to the illustration found below. The metafile contains a picture, the picture
contains a child node Application Structure of type layer, and the layer
contains a child node Application Structure of type grobject, as illustrated
in Figure 7.

Figure 7. Original tree structure

Example 5.1b:XML companion file to be 'applied' on
example.cgm of example 5.1a.

The WebCGM DOM provides methods for 'applying' an XML Companion File, like
the one shown in example 5.1b, to a picture in a WebCGM document. A
conforming user agent is expected to load and parse the XML Companion File
and possibly 'apply' updates from the XML Companion File to the user agent's
object model. A user may want to apply a companion file for the following
reasons:

i) To replace standard Application Structure Attribute values present in
the WebCGM instance with new values from the XML Companion File.

ii) To supply standard Application Structure Attribute values to
Application Structures which do not contain attribute values with values from
the XML companion file.

iii) To transiently modify the Style Properties (stoke-color, text-size,
etc) with which an object (APS or picture) is displayed.

iv) To add XML metadata to the user agent's object model to be retrieved
at a later stage using WebCGM DOM APIs.

Once the user agent has loaded the XML Companion File into its memory
model, the tree should resemble this:

Figure 8. New tree structure

The overall set of rules that a user agent must follow when applying an
XML Companion File is as follows:

Process unknown attributes if any on root element, see below about
processing namespace attributes.

Process all child elements using a depth-first algorithm.

More specific rules for processing namespace attributes
are:

If the target APS is not present in the CGM file, all attributes of the
current element are ignored.

If the attribute is not part of the base WebCGM DTD, it must be an
extended namespace attribute, else the attribute is ignored.

An attribute that already exists on the corresponding APS must be
updated with the new attribute value.

In the case where an attribute with the same local name and namespace
IRI is already present on the APS, its prefix is changed to be the prefix
part of the qualifiedName, and its value is changed to be the attribute
value. If the attribute does not exist on the APS, the namespace
attribute is appended onto the APS.

The target APS (the parent element) must be present in the CGM file, if
that is not the case, all child elements of the current element are
ignored.

The target APS must not be of type 'grnode'. Type 'grnode' elements are
not accessible via XCF. Nor are they accessible via most DOM calls, with
the principal exception of the WebCGMNode interface
(firstChild, nextSibling, etc).

If the element is not part of the base WebCGM DTD, it must be an
extended namespace element. Namespace elements and their attributes are
appended at the end of the target's list of child elements.

Elements that are defined in the WebCGM DTD are processed as follows:

namespace attributes are processed as specified above.

attributes relevant to this element, are updated on the APS.

other attributes are ignored.

If the element is a <linkuri>, the following rules apply:

If one or more 'linkuri' attribute(s) already exist on the parent
element, they are all deleted and replaced with the corresponding set
of 'linkuri's from the XCF. It is not possible to add links from the
XCF to already existing links.

The attributes of each <linkuri> element are combined to
create a single WebCGM 'linkuri' APS attribute (as defined in WebCGM
1.0) on the parent element.

If the element is a <bindById>, only namespace attributes and
attributes relevant to the target APS type are added to the target (i.e.,
if the <bindById> has a 'screentip' attribute and the target APS is
of type 'layer', the 'screentip' attribute will be ignored).

If the element is a <bindByName>, the user agent has to find all
Application Structures that have a matching 'name' or 'layername'
attribute. All found Application Structures are then subject to new
attribute values (refer to the <bindById> description above).

This section describes how APS Attributes are
inherited in a WebCGM structure tree. It also describes how Style Properties are inherited, which is similar
but differs in a few key details. The inheritance models are based closely on
the inheritance model of CSS 2.0.
Some details have been adapted to the particulars of the WebCGM format. This
chapter is the normative reference for inheritance of APS Attributes and of Style Properties in WebCGM.

WebCGM user agents are required to support the inheritance model defined
in this section for eligible Style Properties.
Once a user agent has loaded a document and constructed a document tree, it
must assign, for every Application Structure in the tree, a value to every
Style Property.

Very similar to the CSS model, the final value of a Style Properties is
the result of a four-step calculation: the value is determined through
specification (the "Specified Value"), then resolved into a value that may be
used for inheritance (the "Computed Value"), then converted into an absolute
value if necessary (the "Used Value"), and finally transformed according to
the limitations of the local environment (the "Actual Value").

User agents must first assign a Specified Value to each Style Property
based on the following mechanisms (in order of precedence):

If the Style Property is assigned a value (via a DOM call, or via an
XCF), use it.

Otherwise, if the Style Property is inherited (i.e., its definition
includes "Inherited:yes") and the Application Structure is not the root
of the document tree, use the Computed Value of the parent Application
Structure.

Otherwise use the Style Property's Initial Value. The Initial Value of
each Property is indicated in the Style Property's definition.

Note: In the context of WebCGM inheritance, the root of the document tree
is the Picture node.

In the CSS2 model from which the WebCGM model is derived, Computed Values
can be relative to each other; for example a width could be set as a
percentage, which is dependent on the containing block's width. The Used
Value is the result of taking the Computed Value and resolving these
dependencies into a final absolute value used for the actual display. In this
version of WebCGM, there are no examples where Used Value differs from the
Computed Value. This may change in a future version of the specification.

A Used Value is in principle the value used for rendering, but a user
agent may not be able to make use of the value in a given environment. For
example, a user agent may only be able to render borders with integer pixel
widths and may therefore have to approximate the computed width, or the user
agent may be forced to use only black and white shades instead of full
colour. The Actual Value is the used value after any approximations have been
applied.

WebCGM user agents are required to support the inheritance model of
Application Structure (APS) Attributes defined in this section. Once a user
agent has loaded a document and constructed a document tree, it must resolve,
for every Application Structure in the tree, if an Attribute has a value
(i.e., no value is possible for some attributes).

Very similar to the CSS model, the final value of an APS Attribute is the
result of a four-step calculation: the value is determined through
specification (the "Specified Value"), then resolved into a value that may be
used for inheritance (the "Computed Value"), then converted into an absolute
value if necessary (the "Used Value"), and finally transformed according to
the limitations of the local environment (the "Actual Value").

User agents must first assign a Specified Value to each APS Attribute
based on the following mechanisms (in order of precedence):

If the Attribute is assigned a value in the CGM document or assigned a
new value via a DOM call or an XCF, use it.

Otherwise, if the Attribute is inherited (i.e., its definition includes
"Inherited:yes") and the Application Structure is not the root of the
document tree, use the Computed Value of the parent Application
Structure.

Otherwise use the Attribute's Initial Value. The Initial Value of each
Attribute is indicated in the Attribute's definition.

In the context of WebCGM inheritance, the root of the document tree is the
Picture node. For the purposes of this inheritance model, the Picture root
node is treated as if it were an Application Structure.

In this specification, Computed Values of Application Structure
Attributes, with the exception of the 'inherit' value are identical to the
Specified Values. When the Specified Value is 'inherit', it must be replaced
for the Computed Value as defined below in the section on
inheritance. The Computed Value exists even when the Attribute doesn't
apply (as defined by the 'Applies To' line in the Attribute's definition).

In the CSS2 model from which the WebCGM model is derived, Computed Values
can be relative to each other; for example a width could be set as a
percentage, which is dependent on the containing block's width. The Used
Value is the result of taking the Computed Value and resolving these
dependencies into a final absolute value used for the actual display. In this
version of WebCGM, there are no examples where Used Value differs from the
Computed Value. This may change in a future version of the specification.

A Used Value is in principle the value used for rendering, but a user
agent may not be able to make use of the value in a given environment. For
example, a user agent may only be able to render borders with integer pixel
widths and may therefore have to approximate the computed width, or the user
agent may be forced to use only black and white shades instead of full
colour. The Actual Value is the Used Value after any approximations have been
applied. In this version of WebCGM, there are no examples where Actual Value
differs from the Used Value. This may change in a future version of the
specification.

Some values are inherited by the children of an Application Structure in
the document tree, as described above. Each Style Property and Application
Structure Attribute defines whether it is inherited or not. As a general
rule, when inheritance occurs, Application Structures inherit Computed values
of Style Properties and Application Structure Attributes (unless implicitly
stated in the Property or Attribute definition).

Application Structure Attributes and Style Properties may also have a
Specified Value of 'inherit'; which means that, for a given Application
Structure, the Property or Attribute takes the same Computed value of the
Application Structure's parent. The 'inherit' value can be used to strengthen
inherited values, and it can also be used on Style Properties that are not
normally inherited. There are no examples of the latter in this version of
Web CGM.

5.5.2.1 IDL types and binding types

Each interface of this DOM definition is normatively specified by a
section of IDL code. The IDL uses basic data types such as unsigned short,
boolean, long, etc. DOM applications are written in some programming language
binding of the IDL, such as ECMAScript or Java. The only normatively
specified binding for WebCGM DOM is the ECMAScript binding.

Null return
value. WebCGM DOM attributes and method return values of type
WebCGMNode and WebCGMNodeList sometimes have to represent the case of no
data, i.e., zero nodes. In the DOM functional specification of this chapter,
the term null is uniformly used to used to represent this
case. In DOM bindings such as the ECMAScript binding the
null return value maps naturally to an ECMAScript
null reserved keyword. (For example,
myNode.childnodes==null evaluates to true, and
myPicture.getAppStructureById()==null evaluates to true.)

One heavily used data type in the IDL definition is the WebCGMString, and
some of the DOM interfaces do specify substructure or sub-types for some
WebCGMString attributes and parameters.

WebCGMString

A WebCGMString is a sequence of 16-bit units in WebCGM DOM.

IDL Definition

valuetype WebCGMString sequence<unsigned short>;

In WebCGM DOM, like XML DOM Level 3, the UTF-16 encoding was chosen
because of its widespread industry practice. For ECMAScript and Java,
WebCGMString is bound to the String type because both languages also use
UTF-16 as their encoding. The WebCGM 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 WebCGMStrings.

Empty
string. WebCGM DOM attributes and method return values of type
WebCGMString sometimes have to represent a string that has no data, i.e.,
zero characters. In the DOM functional specification of this chapter, the
term empty string is uniformly used to used to represent
this case. In DOM bindings such as the ECMAScript binding, the WebCGM
empty string maps naturally to an ECMAScript string of length zero, i.e.,
zero characters. (For example, myEmptyString.length==0 evaluates
to true, and myEmptyString=="" evaluates to true.)

The WebCGM DOM has a number of WebCGMString attributes or parameters that
in fact encode other data — such as numbers, colors, sub-strings, etc
— into the string format. For the purposes of this specification, we
define the following rules for how WebCGMString sub-types
are encoded and represented within WebCGMString objects.

A real number value encoded in a WebCGMString. The representation of the
number can be either decimal notation or scientific
notation. Decimal notation consists of either an integer, or an
optional sign character followed by zero or more digits followed by a dot (.)
followed by one or more digits. Scientific notation consists of a
decimal-notation representation immediately followed by the letter "e" or "E"
immediately followed by an integer.

Percent

A percent, encoded in a WebCGMString, is a number
followed by a percent-sign character, "%".

Color

A color, encoded in a WebCGMString, is a "#", followed by exactly six hex
digits, [0-9a-fA-F]. The first two digits represent the red component, the
second two represent the green component, and the last two represent the blue
component. Conceptually: #RRGGBB. Examples: #FF0000 is full red, #e1e1e1 is
the gray background of the IDL definitions in this chapter, #00FFFF is full
cyan, etc.

Some WebCGMString attributes may encode multiple substrings, e.g., the APS
Attributes, 'name' and 'linkuri'. For historical reasons, this is known as
Delimited String sub-type (although functionally it is a
"list-of-string").

The definition of ValidChar depends on the particular WebCGM entity that
is being encoded. For example, in the APS Attributes
table for DOM access (in section 5.7.6, Interface WebCGMAppStructure),
the valid characters for each of the APS Attributes that are encoded by
Delimited String are determined by the WebCGM datatype of the particular APS
Attribute (linked from the table), in combination with the Character Repertoire rules of
section 3.1.1.3.

In the case of the 'linkuri' APS
attribute, the value always contains 3 * n strings, n representing the
number of 'linkuri' attributes specified on the Application Structure. When
meaningful values are not supplied for some of the components, the components
must be represented by an empty string. The restriction of 3 * n strings
simplifies scripts aimed at manipulating Delimited Strings.

Example: a multilink consisting of two links could be
represented with the following delimited string:'http://www.w3.org/' 'W3C' '_blank' 'http://www.cgmopen.org/' 'CGMOpen'
'_self'.

A Delimited String is a list of wsp-separated substrings. If the Delimited
String only contains a single substring, then it is coded as a simple
string.

Example: to set a 'region' APS Attribute that consists of
a single subregion:setAppStructureAttr("region", "1 0 0 100 100")

Note. This Delimited String syntax, when combined with handling of string
parameters in languages such as ECMAScript, imposes some constraints on the
content of Delimited String substrings. In particular, it would not be
possible to have a substring that contained both a QUOTE character and an
APOSTROPHE character.

The XML Companion File (XCF) provides
access to many of the APS Attributes and Style Properties that are accessible
via the WebCGM DOM. APS Attributes and Style Properties that occur in WebCGM
DOM as attributes and method parameters are represented in XCF as XML
attributes. The values are encoded in the XML attribute strings of XCF
exactly as they would be encoded in the WebCGMString type or a WebCGMString sub-type of the corresponding
WebCGM DOM parameter or attribute.

In a WebCGM instance, the representation of coordinates (VDC) is
influenced by several CGM elements: VDC TYPE, VDC EXTENT, and SCALE MODE.
WebCGM requires that SCALE MODE be 'metric', but places few other
constraints. Therefore VDC (times some scale factor) are equivalent to
millimeters, but otherwise the coordinate system could have a lot of
variability: upper-left or lower-left origin, right-handed or left-handed,
integer values or real values (floating or fixed), etc.

To simplify working with coordinates, the WebCGM DOM defines and uses a
canonical, normalized coordinate system, Normalized VDC (NVDC).

NVDC units are millimeters, in a coordinate system whose origin
corresponds to the lower left corner of the VDC extent, with the X axis
pointing to the right, and the Y axis pointing up. The following examples
illustrate the correspondence between NVDC and VDC values for several WebCGM
instances.

Example 1: Simplest possible example, the VDC and the
NVDC are identical

VDC Type: Real

VDC Extent (lower-left & upper-right corners): (0.,0.)
(150.,100.)

Scale Factor: 'metric', 1.0

The picture's VDC have lower-left origin, X increases to right, Y
increases up, picture is 150 mm wide and 100 mm high. The NVDC are
identical,: (0.,0.) for lower-left corner, (150.,100.) for upper-right
corner. If (x,y) are VDC and (x',y') are NVDC,
then:

x' = x

y' = y

Example 2: The VDC define an upper-left origin, and
correspond to a U.S. paper size of 8.5x11.0 inches:

VDC Type: Real

VDC Extent (lower-left & upper-right corners): (0.,11.0)
(8.5,0.)

Scale Factor: 'metric', 25.4

In VDC space, the origin is the upper-left corner, X increases to right, Y
increases down. In NVDC space, the lower-left corner coordinates (as always)
are (0,0) and the upper right corner is (215.9,279.4). If (x,y)
are VDC and (x',y') are NVDC, then:

x' = 25.4*x

y' = 279.4 - 25.4*y

Example 3: In the general case, if VDC
Extent coordinates are (xll, yll), (xur, yur), and
Scale Factor is 'metric', s, then (x',y') NVDC is
derived from (x,y) VDC by:

A geometric transform may be attached to eligible APS nodes by a DOM call
or XCF data, and leads to transient visual modification of the displayed
image. Eligible APS nodes are: grobject, para, subpara, layer.

Geometric transforms on nodes in the WebCGM object tree, whether the
default (Identity) or explicitly specified, compose or combine with the
transforms on ancestor and descendant nodes, to define a composite transform
— the Current Transformation Matrix — for every node in the
tree.

Terminology: WebCGM geometric transforms are defined in the
two-dimensional NVDC coordinate space. In principle, any rotate and scale
operations can be represented by a 2x2 matrix M, which is
multiplied by the 2x1 vector represenation for of a point p
to apply the transform. A translation by d=(dx,dy) is
performed by adding d to p.

WebCGM uses the homogeneous coordinate system to define and describe the
effect of transforms. In this system, the matrix representation
M is 3x3, with the six unique numbers associated with
rotation, scale, and translation comprising the first two rows, and the third
row always being (0,0,1). The point p is represented by the 3x1 vector
(x,y,1).

a c e
b d f
0 0 1

For convenience, this matrix form M will be referred to
as: [a b c d e f]. The application of the transform
M to the point p is then defined by:

p' = M * p

The following definitions specify how to form M
cooresponding to basic operations such as translate, rotate, scale:

Successive basic operations are performed by left-multiplying the matrices
corresponding to the operations. For example, a translation by Mt followed by
a rotation by Ma is performed by:

p' = Ma * Mt * p

As another example, a rotation of angle a about an
arbitrary point c = (cx,cy) is performed by the sequence of
operations:

M1: translate(-cx,-cy)

M2: rotate(a)

M3: translate(cx,cy)

Forming M1, M2, and M3
by the above rules, then the matix M for the rotation by
a about (cx,cy) is:

M = M3 * M2 * M1

The WebCGMAppStructure Interface contains methods for
applying scale, rotate, translate, and general matrix transforms to
Application Structures. Each of the methods has a parameter,
replace, whose values may be 'combine' or
'replace'. These have the following meanings:

replace: replace any existing, explicitly-defined
transform on the APS with the new transform.

combine: combine the new transform with any existing
explicitly-specified transform by left multiplying. If
Mn is the newly specified transform, and
Me is the existing explicitly-specified transform, then
the new explicitly-specified transform M is:

Assume that an object tree has this structure, where A contains B, which
contains C and D:

APS-A

....APS-B

........APS-C

........APS-D

Placing a transform on node A transforms all of the geometry within A,
including the contents of B, C, and D. But it doesn't supersede any transform
that might be on B, C, and D. Rather, it combines with them — you
post-multiply the matrix representations so that the various contents in the
tree are transformed as follows:

Ma — inside APS-A, but outside APS-B.

Ma*Mb — inside APS-B, but outside APS-C and
APS-D.

Ma*Mb*Mc — inside APS-C.

Ma*Mb*Md — inside APS-D.

The resultant composite transform as defined in these illustrations is
known as the Current Transformation Matrix (CTM) of
the node. Every node in the object tree conceptually has an associated CTM,
even if it is just the Identity matrix.

There is a parameter associated with the WebCGM geometric transform that
determines, when the DOM method specifies a 'transform' on a node in the
object tree, whether it is defined in 'replace' mode or
'combine' mode. But once that transform-specifying method has
been executed, then there is some well-defined explicitly-specified transform
on that node, and it combines with its ancestors and descendants according to
the usual rules to compute the CTM for each node.

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 WebCGMNode 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:

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
WebCGMNodeList
interface enables the handling of ordered lists of WebCGMNodes. The
WebCGMEvent
interface provides contextual information regarding mouse events.
WebCGMNodeList objects in the DOM are live; that is, changes to the
underlying document structure are reflected in all relevant NodeList objects.
For example, if a DOM user gets a WebCGMNodeList object containing the
children of an WebCGMAppStructure, then changes one of its children in the
tree, all changes are reflected in the NodeList objects and in fact to all
references to that Node in NodeList objects.

The WebCGMPicture node is the root of the document tree for DOM and
inheritance model purposes:

While it may seem natural that WebCGMMetafile should inherit from
WebCGMNode, the WebCGM profile takes the view that the metafile is simply
a placeholder for generic data formatting information for the picture(s)
in a metafile.

Although WebCGM is a one-picture profile, extensibility to
multi-picture profiles is already designed into the interfaces, and that
extensibility relies on the DOM-tree (inheritance) root being the
picture.

This simple example shows how to catch a WebCGMException from HTML
& ECMAScript. In a WebCGM-DOM enabled browser, correct execution of
this HTML-ECMAScript code should cause an alert box to appear that an
attempt to change a readonly attribute is made.

Performs matrix multiplication. This matrix is post-multiplied
by another matrix, returning a new matrix.

Example: newMatrix = thisMatrix x m.

Parameters

m of type
WebCGMMatrix

in WebCGMMatrix m The matrix which is
post-multiplied to this matrix.

Return value

WebCGMMatrix; The resulting matrix.

Exceptions

No exceptions.

inverse

Returns the inverse as a new matrix.

Parameters

No parameters.

Return value

WebCGMMatrix; The resulting matrix.

Exceptions

WebCGMException; INVALID_ACCESS_ERR: Raised if this
matrix is not invertable.

translate

Post-multiplies a translate transform on the current matrix and
returns a new matrix. Result: newMatrix = thisMatrix x
translateMatrix.

Parameters

x, y of type
float

The distances to translate respectively in the
x-direction and y-direction. Units are NVDC.

Return value

WebCGMMatrix; The resulting matrix.

Exceptions

No exceptions.

scale

Post-multiplies a (possibly) non-uniform scaling transform on
the current matrix and returns a new matrix. Result: newMatrix =
thisMatrix x scaleMatrix.

Parameters

sx, sy of type
float

The scale factors to apply respectively in the
x-direction and y-direction.

Return value

WebCGMMatrix; The resulting matrix.

Exceptions

No exceptions.

rotate

Post-multiplies a rotation transform on the current matrix and
returns a new matrix. The rotation transform allows for a point
of rotation to be specified. Result: newMatrix = thisMatrix x
translate(rx,ry) x rotate(angle) x translate(-rx,-ry).

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

The WebCGMMetafile interface
is the entry point to the entire WebCGM document. The interface exposes
information regarding the metafile and provides access to the first
WebCGMPicture of the WebCGM document.

This simple example shows how to use a method of the WebCGMMetafile
interface from HTML & ECMAScript. In a WebCGM-DOM enabled browser,
correct execution of this HTML-ECMAScript code should display the
metafileID parameter of the BEGIN METAFILE element in a message below
the picture.

Returns the Metafile Description of the WebCGM document,
which is a string consisting of QUOTE-delimited substrings, as
defined in the WebCGM
PPF. For example: "ProfileId:WebCGM""ProfileEd:2.1""Source:A
software vendor""Date:20040602""ColourClass:monochrome". Also as
specified by the WebCGM PPF,
a valid metafileDescription will always contain
the ProfileId: and the ProfileEd:, other information such as
Source, ColourClass etc... is optional. If no WebCGM document is
open in the viewer, an empty string
is returned.

firstPicture of type
WebCGMPicture, readonly

Returns the first WebCGMPicture element of the WebCGM
document. Subsequent WebCGMPictures can be accessed using the
WebCGMPicture interface. A WebCGM document (version 2.0 and
later) contains exactly one WebCGMPicture. If no WebCGM document
is open in the viewer, null is
returned.

metafileID of type
WebCGMString, readonly

Returns the Metafile Identifier, which is the parameter of
the BEGIN METAFILE element in the CGM document. If no WebCGM
document is open in the viewer, an empty
string is returned.

metafileVersion of type
unsigned short, readonly

Returns the Metafile Version of the WebCGM document. If no
WebCGM document is open in the viewer, the value zero is
returned

The IRI of the current document. On setting, the new
document pointed to by the IRI is loaded by the user agent. The
user agent must fully parse the fragment identifier (if
any) in the IRI and execute the indicated behavior. The "Picture behaviors"
rule does apply to the 'src' attribute — if a IRI fragment contains a
picBehavior, the viewer shall ignore the picBehavior. If the CGM
resource pointed to by the IRI is currently loaded for the
object, the user agent shall not reload the CGM (similar to the
specification of a same-CGM IRI for the _replace behavior on a
CGM-to-CGM link.) On retrieval, if no WebCGM document is
open in the viewer, an empty string
is returned.

EXAMPLE. The 'src' attribute is an IRI, with
possible fragment containing object selection and object behavior
terms. It is not a full 'linkuri' (APS Attribute) data
record, and any fragment does not contain picture
behavior terms. So to open myCGM.cgm using (ECMAscript) DOM calls
that reference an HTML <object> element with
ID of 'myObjElt':

This method allows the registration of event listeners on the
WebCGMMetafile. If a WebCGMEventListener is added to the
WebCGMMetafile while it is processing an event, it will not be
triggered by the current actions. If multiple identical
WebCGMEventListeners are registered on the WebCGMMetafile with
the same parameters the duplicate instances are discarded. They
do not cause the WebCGMEventListener to be called twice.

Note: Although all WebCGMEventListeners on the WebCGMMetafile
are guaranteed to be triggered by any event which is received, no
specification is made as to the order in which the WebCGMMetafile
will receive the event with regards to the other
WebCGMEventListeners on the WebCGMMetafile.

Parameters

type of type
WebCGMString

The event type for which the user is
registering, (for example: "click", "mouseover").

listener of type
WebCGMEventListener

The listener parameter takes an interface
implemented by the user which contains the methods to
be called when the event occurs.

Return value

No return value.

Exceptions

No exceptions.

removeEventListener

This method allows the removal of event listeners on the
WebCGMMetafile. If an WebCGMEventListener is removed from the
WebCGMMetafile while it is processing an event, it will not be
triggered by the current actions. WebCGMEventListeners can never
be invoked after being removed. Calling removeEventListener with
arguments which do not identify any currently registered
WebCGMEventListener on the WebCGMMetafile has no effect.

Parameters

type of type
WebCGMString

Specifies the event type of the
WebCGMEventListener being removed (for example:
"click", "mouseover").

Disables or enables the redrawing of the metafile. The default
value is enableAll. Note when this interface is used and set to
enableAll a redraw of the picture automatically will occur. Care
should be used when disabling the redrawing function to insure it
is set back to enableAll

The WebCGMNode
interface is the base datatype of the WebCGM Document Object Model. The
WebCGMNode object is the basis of several other interfaces. the WebCGMNode
object is the basis of several other interfaces, including interfaces to
WebCGM specific elements (eg: WebCGMAppStructure), and to non-WebCGM elements
such as Metadata nodes. The WebCGMNode interface specifies the attributes and
methods to perform simple and generic tree traversal. For these attributes
and methods in particular, APS of type 'grnode' are DOM-visible and
DOM-accessible, unlike most other DOM interfaces.

This simple example shows how to use an attribute on the WebCGMNode
interface from HTML & ECMAScript. In a WebCGM-DOM enabled browser,
correct execution of this HTML-ECMAScript code should display a message
below the picture, with a 2nd line indicating nodeType "1".

The parent (immediate ancestor node of a node) of this node.
All nodes, except WebCGMPicture and WebCGMAttr, may have a
parent.

childNodes of type
WebCGMNodeList, readonly

A WebCGMNodeList that contains all children of this node. If
there are no children, this returns null.

firstChild of type
WebCGMNode, readonly

The first child of this node. If there is no such node, this
returns null.

lastChild of type WebCGMNode,
readonly

The last child of this node. If there is no such node, this
returns null.

previousSibling of type
WebCGMNode, readonly

The node immediately preceding this node. If there is no
such node, this returns null.

nextSibling of type
WebCGMNode, readonly

The node immediately following this node. If there is no
such node, this returns null.

ownerPicture of type
WebCGMPicture, readonly

The WebCGMPicture object associated with this node. When the
node is a WebCGMPicture node, this returns null

attributes of type
WebCGMNodeList, readonly

A WebCGMNodeList containing all attributes (WebCGM and
namespaced) of this node or null
if the WebCGMNode doesn't have any attributes. Always null when nodeType is
APS_STRUCTURE_NODE and nodeName is 'grnode'. The 'apsid'
parameter of the Begin APS element is considered to be an
attribute of its APS for DOM purposes, and the 'pictid' parameter
of the Begin Picture element is considered to be an attribute of
its Picture for DOM purposes. This table summarizes the contents
of 'attributes' for the various node types:

The namespace IRI of this node. For example, on the element
foo:someElement, returns the IRI of the (xmlns)
namespace declaration that associates the prefix foo
with the namespace. 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 IRI given at
creation time. This returns empty
string if the WebCGMNode is not of type XML_METADATA_NODE or
ATTR_NODE.

prefix of type WebCGMString,
readonly

The namespace prefix of this node (e.g., foo:elementName,
returns "foo"). This returns empty
string if the WebCGMNode is not of type XML_METADATA_NODE or
ATTR_NODE.

localName of type
WebCGMString, readonly

Returns the local part of the qualified name of this node
(e.g., foo:elementName, returns "elementName"). This returns empty string if the WebCGMNode is not of
type XML_METADATA_NODE or ATTR_NODE.

WebCGMString; The WebCGMAttr value as a string, or the empty string if that attribute
does not have a specified value.

Exceptions

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

namespaceIRI of
type WebCGMString

The namespace IRI of the attribute to create or
alter.

qualifiedName of
type WebCGMString

The qualified name of the attribute to create or
alter.

value of type
WebCGMString

The value to set, in string form.

Return value

No return value.

Exceptions

WebCGMException; INVALID_CHARACTER_ERR: Raised if the
specified qualified name contains an illegal character. The
legal-character constraints of the qualified name match
those of the attribute
name construct of XML 1.0 Third
Edition.

getElementsByTagNameNS

Returns a WebCGMNodeList of all the descendant XML companion
file elements (application
specific metadata) with a given local name and namespace IRI
in the order in which they are encountered in a preorder
traversal of the WebCGMNode tree. Returns null if there are no such elements.

This simple example shows how to use a method of the WebCGMPicture
interface from HTML & ECMAScript. In a WebCGM-DOM enabled browser,
execution of this HTML-ECMAScript code should cause the initial view of
the technical illustration to appear with a blue-gray background,
instead of a white background:

Reads an XML Companion File (XCF) into the user agent's
object model. If application-specific
metadata 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 this WebCGMPicture interface, on WebCGMAppStructure and on WebCGMNode. If the fileIRI
parameter of this method is a relative IRI, then that relative
IRI is resolved similarly to resolving relative
IRIs for XCF resources referenced in the WebCGM IRI fragment syntax,
i.e., the IRI is resolved relative to location of the CGM
resource to which the XCF resource is a companion.

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

WebCGMException; FILE_NOT_FOUND_ERR; if the referenced
document could not be accessed.

WebCGMException; FILE_INVALID_ERR: if the referenced
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. Returns null if apsid
corresponds to an APS of type 'grnode'. 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 foreign namespace
elements (application-specific
metadata elements).

Parameters

apsId of type
WebCGMString

The unique id value for an Application
Structure.

Return value

WebCGMAppStructure; a WebCGMAppStructure object
containing the Application Structure with the matching
id.

Exceptions

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
depth-first-order traversal of the WebCGMPicture tree. If no such
Application Structures exists, returns null. Only WebCGM Application
Structures may be retrieved using getAppStructuresByName, it does
not retrieve foreign namespace elements (application-specific
metadata elements).

Highlights a collection of Application Structures (APSs).
WebCGM also allows for highlighting of APSs using the IRI fragment syntax. The
exact method of highlighting is viewer dependent. The highlight
method provides a way for WebCGM script writers to highlight APSs
in the same way a IRI fragment would. It also allows for
highlighting of entire layers. Highlighting is not defined for
WebCGMPicture nodes or XML Metadata nodes. APS of type 'grnode' are not valid
in the node list, and shall cause no change to the viewed image
or the DOM tree.

Clears highlighting for all currently highlighted APSs in the
picture. The behavior is identical to the special-form
object behavior fragment,
id(*,clearHighlight), that is defined in the enumeration of behaviors
of the fragment syntax.

Parameters

None.

Return value

No return value.

Exceptions

No exceptions.

setPictureVisibility

Sets the visibility on or off for the whole picture. Note that
for the purposes of the inheritance model,
the Picture node behaves like an Application Structure, and the
visibility as set by this method behaves like the 'visibility' APS Attribute.

Common specifications. The following common
specifications, related to the inheritance
model, apply to all of the Style Properties:

Inherited: yes: Each Style Property may be
inherited.

Value "inherit": Each Style Property may
take the value "inherit", in addition to the values listed
for the individual property.

Computed Value: The Computed Value of each
Style Property is the same as the specified value, with the
exception of the elimination of the value "inherit" as
specified in the inheritance model.

Units in the table. RGB colors are expressed
as hexadecimal values. Relative scale values are expressed as a
positive or non-negative number (depending on the property)
followed by a '%' unit designator. Relative values of some
properties can exceed 100%. Relative intensity values are
expressed as a number followed by a '%' unit, ex: "75%". Relative
intensity values cannot exceed 100%.

Color representation. Absolute RGB colors are
expressed using a hexadecimal representation for all three RGB
channels, #RRGGBB. Examples of colors expressed in hexadecimal
representation: red is expressed as #FF0000, and cyan which uses
both full green and full blue is expressed as #00FFFF. The
representation must be exactly 6 digits, 2 each for R, G, and B.
Shorthand hexadecimal notation, e.g., the 3-digit #RGB notation,
is not supported in this specification.

Replacement mode. When Style Properties have
values of "%" (percent), the respective attribute value used for
display is adjusted by applying the appropriate formulae to the
attribute values in the metafile (for the appropriate target
object). For example, stroke-weight of 60% means that the
metafile-defined LINE WIDTH and EDGE WIDTH attributes are
multiplied by 0.6. Successive setting of the same Style Property
replaces any previous setting of the same Style Property (rather
than accumulating with it). So, for example, stroke-weight 60%
followed later by stroke-weight 40% results in stroke-weight 40%,
not stroke-weight 24%.

Order counts. Some Style Properties have
overlapping effects. For example, intensity and fill-color both
affect the color of filled areas. When both properties are
defined for a target APS, the latter definition supersedes and
replaces the earlier definition. So for example intensity 40%
followed by fill-color 60% results in 60% fill color, while
fill-color #FF0000 followed by intensity 40% results in
fill-color 40% (of the filled-areas colors in the metafile, for
the target object).

Style Property Definitions. The following are
the detailed functional definitions of each of the Style
Properties:

background-color is the color of the
rendering surface for the entire picture, on which all elements
are drawn. It corresponds to the BACKGROUND COLOUR attribute of
the CGM standard. Example: a value of #000000 for the
background-color style property will override what is in the
WebCGM instance, and display a black background for all elements
to render over.

text-size redefines the size of all
text in the target object. If text-size is "%", then it adjusts
the text restriction boxes (heights and widths) and the CGM
CHARACTER HEIGHT attribute by that amount. If the text-size value
is NVDC, for each text element in the target object, compute the
ratio (effectively, a percent) of the new NVDC value and the
restriction box height, and apply the resulting ratio as would be
done for the same "%" value.

fill-color is the style property
applied to a closed area inside the path of a shape. It
corresponds to the CGM attribute FILL COLOUR, and will override
the current values of that attribute within the target object
(APS or picture), if the fill-color Style Property is applied to
object.

intensity is a way to make the
current color fade towards white. An intensity value of 0%
applied to an Application Structure (APS) will make its contents
completely white while a value of 100% will keep the current
colors intact. The intensity equation is as follows:

Setting a relative intensity value is allowed on a number of
individual style properties, see table above. The 'intensity'
style property, however, represents a convenience property that
simultaneously controls the intensity value of the following four
properties: fill-color, stroke-color, text-color and
raster-intensity.

stroke-color defines the color for
the lines and edges within the target object (APS or picture) to
which the property is applied. Stroke-color overrides the CGM
attributes LINE COLOUR and EDGE COLOUR. This style property will
apply an absolute or a relative intensity color change to
metafile-defined values of those CGM attributes within the target
object.

stroke-weight redefines the
thickness of the pen strokes for drawing of lines and edges
within the target object (APS or picture) to which it is applied.
Stroke-weight overrides CGM attributes LINE WIDTH and EDGE WIDTH.
This stroke-weight property can apply a relative scale change to
the metafile-defined value of those attributes, or can provide an
absolute (NVDC) replacement for those current values.

text-color redefines the color for
the graphical text within the target object (APS or picture) to
which the property is applied. Text-color overrides the CGM
attribute TEXT COLOUR. This style property will apply an absolute
or a relative intensity color change to metafile-defined value of
that CGM attribute within the APS.

text-font specifies a replacement
font for all text in the target object. If the characters that
are needed for all text in the target object are available in the
specified replacement font, and if the specified font is
available, then use it for all text in the target object.
Otherwise, ignore the specified replacement font. The initial
value of text-font, which is the reserved keyword "metafile",
means that the font specifications of the metafile are used.

raster-intensity is a way to make
the current color fade towards white in a raster element. It
applies to the colors within CELL ARRAY, TILE, and BITONAL TILE
elements within the target object (APS or picture) to which it is
applied. An intensity value of 0% applied to an Application
Structure (APS) will make its raster contents completely white
while a value of 100% will keep the current raster colors intact.
The equations for computing new color values are the same as for
the intensity property, above.

stroke-type defines the line type
within the target object (APS or picture) to which the property
is applied. stroke-type overrides the CGM attribute elements LINE
TYPE and EDGE TYPE. Valid values are: integers 1-5 (which
correspond to solid, dash, dot, dash-dot, dash-dot-dot), integers
6-15 (the registered or user defined values that are defined
within the WebCGM.

stroke-offset defines the percentage
of the first cycle of the stroke type that is omitted when
starting to draw a non-solid stroke. Stroke offset overrides the
CGM attribute elements LINE TYPE INITIAL OFFSET and EDGE TYPE
INITIAL OFFSET within the target object (APS or picture).

interior-style determines which
style of interior is used to draw a filled-areas. It corresponds
to the CGM attribute element INTERIOR STYLE and will override the
current values of that attribute within the target object (APS or
picture). The valid Style Property values {0,1,2,3,4,6}
corresponding respectively to {‘hollow', ‘solid',
‘pattern', ‘hatch', ‘empty',
'‘interpolated'}.

hatch-index determines which hatch to
use within filled-area elements of the target object (APS or
picture). Hatch-index corresponds to the CGM attribute element
HATCH INDEX and overrides the current values of that attribute
within the target object (APS or picture). It must refer to a
CGM:1999 pre-defined hatch index or a negative hatch index that
has been defined with a HATCH STYLE DEFINITION with the WebCGM.
Note: valid pre-defined hatch indexes are 1-6 (corresponding to:
horizontal, vertical, positive slope, negative slope,
horizontal/vertical cross, positive/negative slope cross)

pattern-index determines which of
pattern to use within filled-area elements of the target object
(APS or picture). Pattern-index corresponds to the CGM attribute
element PATTERN INDEX and overrides the current values of that
attribute within the target object (APS or picture). It must
refer to a pattern that has been defined with a PATTERN TABLE
with the WebCGM.

edge-visibility determines if the edge
of filled-area elements of the target object (APS or picture) are
drawn. Edge visibility corresponds to the CGM attribute element
EDGE VISIBILITY and overrides the current values of that
attribute within the target object (APS or picture)

fill-offset sets a reference point for
patterns or hatch fills within the target object (APS or
picture). Fill-offset corresponds to the CGM attribute element
FILL REFERENCE POINT and overrides the current values of that
attribute within the target object (APS or picture)

Parameters

style of type
WebCGMString

The name of the style property to modify.

value of type
WebCGMString

The new value for the given style. Note that
"inherit" is a valid value for every Style Property,
and per the inheritance model,
it has the effect of restoring the style property to
its initial (load time) value (as determined by the
inheritance model).

Return value

No return value.

Exceptions

No exceptions.

reloadPicture

Notifies the user agent to immediately redraw the entire
WebCGMPicture. The user agent will reload the WebCGMPicture while
preserving the current user agent's zoom and pan level. The
reloading of the WebCGMPicture also discards any existing
companion information that may have been loaded into memory via
the applyCompanionFile
method.

Retrieves a style property by name on the given Picture. Please
refer to the Style Properties
Table for more detailed information on retrievable and
modifiable Style Properties.

Parameters

style of type
WebCGMString

The name of the style property to retrieve.

Return value

WebCGMString; the Style Property value as a string, or
the empty string if that Style
Property has not been explicitly set on the picture by a
setStyleValue call (or equivalent XCF). For Style
Properties that may be set in different modes -- e.g., NVDC
or percentage -- the return value shall be in the mode in
which it was set. For example, if stroke-weight were most
recently set to a percentage value by a setStyleValue call,
then getStyleValue shall return a percentage value. (See
the inheritance model for further related discussion). The
value may be a Delimited String.

Sets a view to the specified rectangle expressed in NVDC units.
The WebCGM viewer shall fit the NVDC rectangle specified by the
'viewRect' parameter into the viewer’s display rectangle
and center it, while maintaining the aspect ratio of the
'viewRect' rectangle.

WebCGMAppStructure::getObjectExtent and WebCGMRect::unionRect
can be used to set the view around more than one APS.

Parameters

viewRect of type
WebCGMRect

The view rectangle in NVDC.

Return value

boolean: true if new view was set; false if rectangle was
invalid and the view could not be set.

The WebCGMAppStructure
interface offers methods for setting and retrieving Application Structure
(APS) attributes. The main methods for accessing Application Structure
attributes are getAppStructureAttr and setAppStructureAttr. It is important
to note that some attributes, like 'name' and 'linkuri', may have multiple
values. In that case, a Delimited String is returned.
Delimited String is also used for 'region', which may contain several
sub-regions. The WebCGMAppStructure interface has limited impact on APS of
type 'grnode'. See the
particular methods and attributes for details.

The following table identifies which APS attribute values can be expressed
as a Delimited String. Each entry in the table points to the detailed
description of the attribute, as it appears in WebCGM content.

The WebCGMAppStructure
interface, like the WebCGMPicture
interface, also provides methods for modifying Style Properties at the
Application Structure level. For more information about available Style
Properties, refer to the Style Properties
Table.

This simple example shows how to use methods of the
WebCGMAppStructure interface from HTML & ECMAScript. In a
WebCGM-DOM enabled browser, correct execution of this HTML-ECMAScript
code should display "Layer name is fleet" under the picture.

The more advanced example in Appendix F shows
how to use methods of the WebCGMAppStructure interface from HTML &
ECMAScript to perform a regular expression searching based on the
contents of APS attributes.

Attributes

apsId of type WebCGMString,
readonly

The unique identifier of the Application Structure. Always
the empty string if the APS is of
type 'grnode'.

nameCount of type unsigned
long, readonly

Represents the number of 'name' attribute values present on
this Application Structure. Always zero if the APS is of type 'grnode'.

linkuriCount of type unsigned
long, readonly

Represents the number of 'linkuri' attribute values present
on this Application Structure. Always zero if the APS is of type
'grnode'.

Adds a new Application Structure attribute. If an attribute
with that name is already present in the APS, its value is
changed to be that of the value parameter. Please refer to the Application Structure Attributes table
for more detailed information on retrievable and modifiable
Application Structure attributes. If the APS is of type 'grnode', this method
shall have no effect, neither on the viewed image nor the DOM
tree.

Parameters

name of type
WebCGMString

The name of the Application Structure attribute
to create or alter.

value of type
WebCGMString

Value to set in string form. The value may be a
delimited string.

Return value

No return value.

Exceptions

WebCGMException; NO_MODIFICATION_ALLOWED_ERR: Raised if
the Application Structure Attribute is readonly.

removeAppStructureAttr

Removes an Application Structure attribute. Please refer to
the Application Structure Attributes
table for more detailed information on retrievable and
modifiable Application Structure attributes. If the APS is of
type 'grnode', this
method shall have no effect, neither on the viewed image nor the
DOM tree.

Parameters

name of type
WebCGMString

The name of the Application Structure attribute
to remove.

Return value

No return value.

Exceptions

WebCGMException; NO_MODIFICATION_ALLOWED_ERR: Raised if
the Application Structure Attribute is readonly.

setStyleProperty

Set a style property by name on the given Application
Structure. Please refer to the Style
Properties Table for more detailed information on style
properties. If the APS is of type 'grnode', this method
shall have no effect, neither on the viewed image nor the DOM
tree.

Parameters

style of type
WebCGMString

The name of the style attribute to modify.

value of type
WebCGMString

The new value for the given style.

Return value

No return value.

Exceptions

No exceptions.

toNodeList

Creates a new WebCGMNodeList object and inserts the current
Application Structure node into the list. The list count is 1.

Parameters

No parameters.

Return value

WebCGMNodeList; A WebCGMNodeList object containing the
Application Structure. Always null if the APS is of type
'grnode'.

Retrieves the axis-aligned bounding box rectangle of the
Graphical Primitive elements within an APS. The bounding box
calculation is based on the locus of the
primitives within the APS. Other than text attributes and
text-related Style Properties, the calculation is not affected by
CGM Primitive Attribute (such as line width) or Control elements,
nor by APS Attributes or non-text Style Properties. It is affected by
geometric transform —
the defining coordinates of the WebCGMRect return value are
expressed in NVDC, computed after the application of the Current Transformation Matrix
to the object's contents.

The contribution of text elements to the object extent is
conceptually calculated from the containing parallellogram of the
displayed text, defined as follows. The length of the side in the
text-up direction is the bottomline-to-topline distance of the
font, after computation of the effective font size that reflects
all text attributes, the height of the Restricted Text box, the
Restricted Text Type, and the Style Properties text-size and
text-font. The length of the side in the text-baseline direction
is the length of the restricted text box if the entire Restricted
Text element is contained within the object, or the sum of the
glyph widths if only an Append Text element is within the
object.

Parameters

No parameters.

Return value

WebCGMRect; the bounding rectangle of the APS, or null if the APS has no
Graphical Primitive elements. Always the null if the APS is of type
'grnode'.

Retrieves a style property by name on the given Application
Structure. Please refer to the Style
Properties Table for more detailed information on retrievable
and modifiable Style Properties.

Parameters

style of type
WebCGMString

The name of the style property to retrieve.
Always the empty string
if the APS is of type 'grnode'.

Return value

WebCGMString; the Style Property value as a string, or
the empty string if that Style
Property has not been explicitly set on the APS by a
setStyleValue call (or equivalent XCF). For Style
Properties that may be set in different modes -- e.g., NVDC
or percentage -- the return value shall be in the mode in
which it was set. For example, if stroke-weight were most
recently set to a percentage value by a setStyleValue call,
then getStyleValue shall return a percentage value. (See
the inheritance model for further related discussion). The
value may be a Delimited String. Always the empty string if the APS is of type
'grnode'.

Exceptions

No exceptions.

translate

Defines on the APS a new geometric transform that consists
of a translate operation. Please refer to "Geometric transform" for more
detailed information about geometric transforms and the
parameters of this method. If the APS is of type 'grnode', this method
shall have no effect, neither on the viewed image nor the DOM
tree.

Parameters

dx of type
WebCGMString

The displacement of the translate operation in
the x direction, as a number in NVDC.

dy of type
WebCGMString

The displacement of the translate operation in
the y direction (NVDC), as a number in NVDC.

replace of type
WebCGMString

How to apply the new transform, {combine |
replace}.

Return value

No return value.

Exceptions

No exceptions.

rotate

Defines on the APS a new geometric transform that consists
of a rotate operation. Please refer to "Geometric transform" for more
detailed information about geometric transforms and the
parameters of this method. If the APS is of type 'grnode', this method
shall have no effect, neither on the viewed image nor the DOM
tree.

Parameters

angle of type
WebCGMString

The angle of the rotation operation, in degrees,
as a number sub-type.
The positive angular direction is counterclockwise in
NVDC space.

rx of type
WebCGMString

The x coordinate (NVDC) of the
center point about which the rotation is defined, as
a number in NVDC.

ry of type
WebCGMString

The y coordinate (NVDC) of the
center point about which the rotation is defined, as
a number in NVDC.

replace of type
WebCGMString

How to apply the new transform, {combine |
replace}.

Return value

No return value.

Exceptions

No exceptions.

scale

Defines on the APS a new geometric transform that consists
of a scale operation. Please refer to "Geometric transform" for more
detailed information about geometric transforms and the
parameters of this method. If the APS is of type 'grnode', this method
shall have no effect, neither on the viewed image nor the DOM
tree.

Parameters

sx of type
WebCGMString

The x coordinate (NVDC) of the
reference point about which the scaling operation is
defined, as a number in
NVDC.

sy of type
WebCGMString

The y coordinate (NVDC) of the
reference point about which the scaling operation is
defined, as a number in
NVDC.

replace of type
WebCGMString

How to apply the new transform, {combine |
replace}.

Return value

No return value.

Exceptions

No exceptions.

setTransform

Defines on the APS a new local geometric transform by
specifying the contents of the transform matrix. Please refer to
"Geometric transform" for more
detailed information about geometric transforms and the
parameters of this method. If the APS is of type 'grnode', this method
shall have no effect, neither on the viewed image nor the DOM
tree.

How to apply the matrix to determine the new
local transform, {combine | replace}, as described in
"Transform basic
concepts".

Return value

No return value.

Exceptions

No exceptions.

getTransform

Returns current geometric transform information for the APS.
Please refer to "Geometric
transform" for more detailed information about geometric
transforms and the parameters of this method.

Parameters

type of type
WebCGMString

Determines which matrix to return, {local |
ctm}.

When type is "ctm", the Current Transformation
Matrix for this APS is returned. i.e., the
accumulation of all transformations that have been
defined on this node and all its ancestors, up to the
Picture's normalized coordinate system.

When type is "local", the transformation defined
on this APS only is returned; ancestor
transformations are ignored. Note: the returned
matrix must respect previous transform operation
modes (replace | combine), if any.

Return value

WebCGMMatrix; The matrix corresponding to the
requested tranform on the node.

This simple example shows how to use a method of the WebCGMNodeList
interface from HTML & ECMAScript. In a WebCGM-DOM enabled browser,
execution of this HTML-ECMAScript code should count the number of
planes in the fleet application structure..

The WebCGMAttr interface represents an attribute in a
XML_METADATA_NODE, a PICTURE_NODE or a APP_STRUCTURE_NODE.

Note that WebCGMAttr objects inherit the WebCGMNode interface, but since
they are not actually child nodes of the element they describe, the WebCGM
DOM does not consider them part of the document tree. Thus, the WebCGMNode
attributes parentNode, previousSibling, and nextSibling have a null value for WebCGMAttr objects.

This simple example shows how to use the addEventListener method of
the WebCGMMetafile interface from HTML & ECMAScript. In a
WebCGM-DOM enabled browser, execution of this HTML-ECMAScript code
should display a picture with two black-framed square figures, and a
mouse click anywhere on either of them should result in an alert saying
"Event handler installed successfully."

The WebCGMEvent interface is used to provide contextual information about
an event to the handler processing the event.

There exists three levels of interactivity in WebCGM:

User-initiated actions such as a mouse click can be captured by the
host environment and execute scripts.

The user can initiate hyperlinks to Web pages or other WebCGM
illustrations.

User agent, users are able to zoom into and pan around WebCGM
content.

This section also describes how a user agent processes the three different
levels of interactivity.

When a mouse event occurs, the WebCGM user agent determines the target
object of the mouse event. For the purposes of this discussion, "object"
means Application Structure (APS). The target object is the topmost object
whose interactive
region is under the mouse at the time of the event. (Note that the
definition of interactive region excludes objects that are fully transparent
due to the setting of their graphical attributes.)

An application structure of type 'grnode' or 'layer' cannot be a target of
a mouse event. Instead, if the mouse pointer was over a 'grnode' when the
event occurred; its closest ancestor object of type 'grobject', 'para' or
'subpara' will be designated as the target element. When an object is not
displayed (i.e., 'visibility' attribute is set to off) or made
non-interactive (i.e., 'interactivity' attribute is set to off), that object
cannot be the target of mouse events.

The event is either initially dispatched to the Metafile, or else not
dispatched, depending on the following:

If there are no graphics objects whose interactive region
is under the mouse (i.e., there is no target object), the event is not
dispatched.

Otherwise, the Metafile is checked to see if it has an appropriate
event handler. The event is dispatched to the event handler if an
appropriate one is found.

Event handlers assigned to a WebCGMMetafile get the event first via the
potential event bubbling. If none of the activation event handlers take
an explicit action (by invoking the preventDefault() WebCGM DOM method)
to prevent further processing of the given event, then the event is
passed on for:

Cursor change, screentip and hyperlink 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. 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.

This simple example shows how to use the attributes of the
WebCGMEvent interface from HTML & ECMAScript. In a WebCGM-DOM
enabled browser, successful execution of this HTML-ECMAScript code
should display a picture with two black-framed square figures. A mouse
click anywhere on the left black background should report the X/Y
location of the click, and a mouseover of the left ellipse should
report the mouseover.

The name of the event (case-insensitive). The name must be
an XML name.

target of type WebCGMNode,
readonly

Used to indicate the WebCGMNode (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 Normalized VDC.

clientY of type float,
readonly

The vertical coordinate at which the event occurred
expressed in Normalized VDC.

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 canceling the
event. Any default action associated with the event will not
occur.

Parameters

No parameters.

Return value

No return value.

Exceptions

No exceptions.

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 WebCGMEvent.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
WebCGMEvent.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 is populated in the WebCGMEvent.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 WebCGMEvent.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 from is populated in the WebCGMEvent.target
property.

load The load event occurs when the WebCGM DOM
implementation finishes loading all content within a WebCGM metafile.

unload The unload event occurs when the WebCGM DOM
implementation removes a WebCGM metafile from a window or frame.