This chapter describes the optional DOM Level 3 Views and
Formatting feature. A DOM application can use the
hasFeature
method of the DOMImplementation
interface to determine whether this feature is supported or not. The
feature string for generic interfaces is "ViewsAndFormatting". The
feature string for visual properties and interfaces is
"VisualViewsAndFormatting". The additional feature strings will be
used to identify support specific to other media,
DOM implementations frequently create views of the document content available through DOM APIs. Such views present content in different ways using various processing, styling, and presentation systems. While a strong separation is typically maintained between content and the view, DOM applications may need to correlate characteristics such as position within a visual view with specific content presented within the view in order to augment and interact with the presentation.
This API allows a DOM application access to a view's computed layout and presentation. This feature functions independently from any specific styling system that may have been applied. An implementation of this API must be able to maintain a correspondence between specific content and its presentation within the view, however the presentation was computed. Presentation state such as selection or scrolling may be manipulatable though this interface, but state which is computed or supplied from the content must be manipulated through the content.
Two versions of the API have been supplied, which are redundant in their functionality. The DOM WG has not decided which of the two is better, or if both are needed. The generic API, described first, is more robust because the specifics are contained in identifying strings passed to general mechanisms. The medium-specific APIs, described last, directly expose the attributes of the medium on the interface, which provides a flatter, simpler model for the user, but one which is less able to adapt to new or extended media types or different uses.
A Segment
is a distinct part of a view. Each Segment
is privately owned and maintained by the containing view, which may
destroy or reconstruct it at any time. Each Segment has a type
related to the presentation medium and the function of that part of
the presentation. Additional properties specific to the segment type
contain information about that part of the view and identify the
corresponding content, if any. Segments may also contain embedded
segments where appropriate to the structure of the presentation.
A Segment
is not expected to have any particular structure
beyond its properties, any contained segments, and dependency on the
content it presents. Containment of one segment within another does not
change the fact that properties such as offsets are relative to the
entire view so that they may be matched, applied, and compared from
anywhere within the view.
The actual segments or parts of the view are not directly
available to the DOM application, but this API provides generic
Segment
objects which can more-generally find and
return items of the actual parts of the view.
A View
is the root of a presentation, owned and
maintained by a Document
. A view formats the contents
of a document into a particular type of presentation. A view may
contain general properties of the view, resource segments, and
segments representing the content of a document, prepared for
presentation.
A Segment
object specifies the actual criteria of
segments to match, and captures items of each matched segment.
Generic and Medium-Specific APIs
The generic API provides access to variety of view and segment types by way of a medium-specific table of strings used to identify properties of medium-specific segment types:
// Find all selected runs of characters in the view at least half an inch from the edges. View v = (View)((DocumentView)document).getDefaultView(); Segment q = v.createSegment(); q.setOrder("Content"); MatchSet m = q.createMatchSet(m.SET_ALL); int hu = v.getIntegerProperty("HorizontalDPI"); int vu = v.getIntegerProperty("VerticalDPI"); n.addMatch(q.createMatchString(m.IS_EQUAL, "Type", "VisualCharacterRun"); m.addMatch(q.createMatchInteger(m.INT_FOLLOWS_OR_EQUALS, "LeftOffset", hu/2)); m.addMatch(q.createMatchInteger(m.INT_FOLLOWS_OR_EQUALS, "RightOffset", hu/2)); m.addMatch(q.createMatchInteger(m.INT_FOLLOWS_OR_EQUALS, "TopOffset", vu/2)); m.addMatch(q.createMatchInteger(m.INT_FOLLOWS_OR_EQUALS, "RightOffset", vu/2)); m.addMatch(q.createMatchBoolean(m.IS_EQUAL, "Selected", true); q.setCriteria(m); ContentItem start = q.createContentItem("StartContent"); ContentItem end = q.createContentItem("EndContent"); q.addItem(start); q.addItem(end); v.matchFirstSegment(q, 0); while (q.getExists()) { // ... do Something with range from start to end... q.getNext(); }
Medium-specific APIs are flatter and easier to use, but usually sacrifice capabilities of the more-general API.
// Find all selected runs of characters in the view at least half an inch from the edges. VisualView v = (VisualView)((DocumentView)document).getDefaultView(); int hu = v.getHorizontalDPI(); int vu = v.getVerticalDPI(); CharacterRun cr = v.createCharacterRun(); cr.setMatchInside(true); cr.setMatchX(hu / 2); cr.setMatchY(vu / 2); cr.setMatchXR(v.getWidth() - hu); cr.setMatchYR(v.getHeight() - vu); cr.setMatchSelected(true); v.matchSegment(cr); while (cr.getExists()) { // ... do Something with range from start to end... cr.getNext(); }
This is the verbose, general-purpose mechanism that can handle all properties of all media types. This relies on a separate table of segment types and the associated properties and property types, because it is a single API.
View
is used as the root Segment
, as well as
providing additional global functionality such as selection.
// Introduced in DOM Level 3: interface View { void select(in Node boundary, in unsigned long offset, in boolean extend, in boolean add); Segment createSegment(); boolean matchFirstSegment(inout Segment todo) raises(DOMException); long getIntegerProperty(in DOMString name) raises(DOMException); DOMString getStringProperty(in DOMString name) raises(DOMException); boolean getBooleanProperty(in boolean name) raises(DOMException); Node getContentPropertyNode(in DOMString name) raises(DOMException); unsigned long getContentPropertyOffset(in DOMString name) raises(DOMException); };
createSegment
A new segment object, that can be set up to obtain information about the view. |
getBooleanProperty
Match
es and Item
s.name
of type
boolean
|
The value of the named property of the
|
|
NOT_SUPPORTED_ERR: Raised if the named property does not exist on the view or is not a boolean. |
getContentPropertyNode
Match
es and Item
s.name
of type
DOMString
|
The Node value of the named property of the
|
|
NOT_SUPPORTED_ERR: Raised if the named property does not exist on the view or is not content. |
getContentPropertyOffset
Match
es and Item
s.name
of type
DOMString
|
The offset value of the named property of the
|
|
NOT_SUPPORTED_ERR: Raised if the named property does not exist on the view or is not content. |
getIntegerProperty
Match
es and Item
s.name
of type
DOMString
|
The value of the named property of the
|
|
NOT_SUPPORTED_ERR: Raised if the named property does not exist on the view or is not an integer. |
getStringProperty
Match
es and Item
s.name
of type
DOMString
|
The value of the named property of the
|
|
NOT_SUPPORTED_ERR: Raised if the named property does not exist on the view or is not a string. |
matchFirstSegment
select
boundary
of type
Node
offset
of type
unsigned long
extend
of type
boolean
add
of type
boolean
Segment
is used to retrieve specific items from specific
segments. Segments may be nested as a match and may be repeatedly applied for
traversing multiple matching segments.
Note: Types and names of properties of segments of Visual media types
Integer TopOffset Integer BottomOffset Integer LeftOffset Integer RightOffset Integer Width Integer Height Boolean Visible Boolean Selected Integer ForegroundColor Integer BackgroundColor String FontName String FontHeight String FontBaseline String FontSpace Width String FontMaximum Width
// Display info and root (the default segment) Display // An area that objects or text lines flow in // or are anchored to Frame // A single character Character // Sequentially-appearing characters // with identical properties CharacterRun FormField {Text | Label | Button | Menu ...} Embedded Object Image
(Image) String URL (Image) Boolean isLoaded (Image) Integer ScalingFactor (Button) Boolean isPressed (Frame) Boolean isScrollable
// Introduced in DOM Level 3: interface Segment : Match { attribute Match criteria; attribute DOMString order; void addItem(in Item add); MatchString createMatchString(in unsigned short test, in DOMString name, in DOMString value); MatchInteger createMatchInteger(in unsigned short test, in DOMString name, in long value); MatchBoolean createMatchBoolean(in unsigned short test, in DOMString name, in boolean value); MatchContent createMatchContent(in unsigned short test, in DOMString name, in unsigned long offset, in Node nodeArg); MatchSet createMatchSet(in unsigned short test); StringItem createStringItem(in DOMString name); IntegerItem createIntegerItem(in DOMString name); BooleanItem createBooleanItem(in DOMString name); ContentItem createContentItem(in DOMString name); void getItem(in unsigned long index); boolean getNext(); };
criteria
of type Match
criteria
Match
of a
Segment
, specified during creation, controls which
Segment
s will match.getNext
are unpredictable until the segment has
been requested again by calling matchFirstSegment
.order
of type DOMString
order
string of a Segment
, specified
during creation, controls the order in which matching segments
will be returned. If this attribute is not specified, the order
defaults to an implementation-specific order.getNext
are unpredictable until the segment has
been requested again by calling matchFirstSegment
.addItem
createBooleanItem
name
of type
DOMString
The requested |
createContentItem
name
of type
DOMString
The requested |
createIntegerItem
name
of type
DOMString
The requested |
createMatchBoolean
test
of type
unsigned short
name
of type
DOMString
value
of type
boolean
The requested |
createMatchContent
test
of type
unsigned short
name
of type
DOMString
offset
of type
unsigned long
nodeArg
of type
Node
The requested |
createMatchInteger
test
of type
unsigned short
name
of type
DOMString
value
of type
long
The requested |
createMatchSet
createMatchString
test
of type
unsigned short
name
of type
DOMString
value
of type
DOMString
The requested |
createStringItem
name
of type
DOMString
The requested |
getItem
Item
, of the list specified
during the creation of the Segment
, which is to be
fetched during Segment
execution, or returns null if
the specified index does not correspond to a Item
.
index
of type
unsigned long
Item
to be retrieved.getNext
Segment
, if any.
|
|
The Match
identifies Segment
s of which a
Segment
should fetch the Item
s.
// Introduced in DOM Level 3: interface Match { // MatchTestGroup const unsigned short IS_EQUAL = 0; const unsigned short IS_NOT_EQUAL = 1; const unsigned short INT_PRECEDES = 2; const unsigned short INT_PRECEDES_OR_EQUALS = 3; const unsigned short INT_FOLLOWS = 4; const unsigned short INT_FOLLOWS_OR_EQUALS = 5; const unsigned short STR_STARTS_WITH = 6; const unsigned short STR_ENDS_WITH = 7; const unsigned short STR_CONTAINS = 8; const unsigned short SET_ANY = 9; const unsigned short SET_ALL = 10; const unsigned short SET_NOT_ANY = 11; const unsigned short SET_NOT_ALL = 12; readonly attribute unsigned short test; };
test
of type unsigned short
, readonlytest
value of a Match
, specified
during creation, controls the test to be applied.The MatchString
identifies Segment
s where a
string property matches a specific value.
// Introduced in DOM level 3: interface MatchString : Match { readonly attribute DOMString name; readonly attribute DOMString value; };
The MatchInteger
identifies Segment
s where an
integer property matches a specific value.
// Introduced in DOM level 3: interface MatchInteger : Match { readonly attribute DOMString name; readonly attribute long value; };
The MatchBoolean
identifies Segment
s where a
boolean property matches a specific value.
// Introduced in DOM level 3: interface MatchBoolean : Match { readonly attribute DOMString name; readonly attribute boolean value; };
The MatchContent
identifies Segment
s where a
content property matches a specific value.
// Introduced in DOM level 3: interface MatchContent : Match { readonly attribute DOMString name; readonly attribute Node nodeArg; readonly attribute unsigned long offset; };
name
of type DOMString
, readonlySegment
to be compared against, which is specified during construction.nodeArg
of type Node
, readonlyoffset
of type unsigned long
, readonlyThe MatchSet
identifies Segment
s where a
set of matches evaluate in a specified way.
// Introduced in DOM level 3: interface MatchSet : Match { readonly attribute Node nodeArg; void addMatch(in Match add); Match getMatch(in unsigned long index); };
nodeArg
of type Node
, readonlyaddMatch
getMatch
Match
, of the set, which is to be matched during
MatchSet
evaluation, or returns null if the specified index
does not correspond to a Match
.index
of type
unsigned long
Match
to be retrieved.
The requested match, if any, or null. |
The Item
represents information to be fetched by a Segment
.
// Introduced in DOM Level 3: interface Item { readonly attribute boolean exists; readonly attribute DOMString name; };
exists
of type boolean
, readonlyexists
boolean of a Segment
, initially
set to false during creation, is set after an attempt to fetch the
values of a Item
to indicate whether or not the
required data was present. A true value indicates that it was.name
of type DOMString
, readonlySegment
to be fetched, which is specified during construction.The StringItem
represents a string property to be fetched by a
Segment
.
// Introduced in DOM Level 3: interface StringItem : Item { readonly attribute DOMString value; };
The IntegerItem
represents an integer property to be fetched by a
Segment
.
// Introduced in DOM Level 3: interface IntegerItem : Item { readonly attribute long value; };
The BooleanItem
represents a boolean property to be fetched by a
Segment
.
// Introduced in DOM Level 3: interface BooleanItem : Item { attribute boolean value; };
The ContentItem
represents a content property to be fetched by a
Segment
.
// Introduced in DOM Level 3: interface ContentItem : Item { attribute Node nodeArg; attribute unsigned long offset; };
This is the flatter mechanism that handles only one specific medium, in this case, visual. This does not rely on a table of property names, because all supported criteria and properties are attributes of the interfaces.
Presents a flatter model of a visual view.
interface VisualView { readonly attribute DOMString fontScheme; readonly attribute unsigned long width; readonly attribute unsigned long height; readonly attribute unsigned long horizontalDPI; readonly attribute unsigned long verticalDPI; VisualCharacter createVisualCharacter(); VisualCharacterRun createVisualCharacterRun(); VisualFrame createVisualFrame(); VisualImage createVisualImage(); VisualFormButton createVisualFormButton(); VisualFormField createVisualFormField(); void select(in Node boundary, in unsigned long offset, in boolean extend, in boolean add); void matchSegment(in VisualResource segment); };
fontScheme
of type DOMString
, readonlyheight
of type unsigned long
, readonlyhorizontalDPI
of type unsigned long
, readonlyverticalDPI
of type unsigned long
, readonlywidth
of type unsigned long
, readonlycreateVisualCharacter
The requested |
createVisualCharacterRun
The requested |
createVisualFormButton
The requested |
createVisualFormField
The requested |
createVisualFrame
The requested |
createVisualImage
The requested |
matchSegment
select
boundary
of type
Node
offset
of type
unsigned long
extend
of type
boolean
add
of type
boolean
Visual segments allow things within a visual view to be accessed.
interface VisualResource { };
Visual font resources contain match criteria and result attributes for getting information about fonts available to a view.
interface VisualFont : VisualResource { attribute DOMString matchFontName; readonly attribute boolean exists; readonly attribute DOMString fontName; boolean getNext(); };
exists
of type boolean
, readonlyfontName
of type DOMString
, readonlymatchFontName
of type DOMString
getNext
VisualFont
, if any.
|
Visual segments contain match criteria attributes and result
attributes common to visual views of a document. When this
structure is created, all booleans are set to false, all integral
values are set to 0, and all strings and object references are set
to null. Match criteria are then set. After setting match
criteria, matchSegment
is called passing this
segment or another segment that references this segment, which
finds a matching segment and sets result attributes.
interface VisualSegment : VisualResource { attribute boolean matchPosition; attribute boolean matchInside; attribute boolean matchContaining; attribute long matchX; attribute long matchY; attribute long matchXR; attribute long matchYR; attribute boolean matchContent; attribute boolean matchRange; attribute Node matchNode; attribute unsigned long matchOffset; attribute Node matchNodeR; attribute unsigned long matchOffsetR; attribute boolean matchContainsSelected; attribute boolean matchContainsVisible; readonly attribute boolean exists; readonly attribute Node startNode; readonly attribute unsigned long startOffset; readonly attribute Node endNode; readonly attribute unsigned long endOffset; readonly attribute long topOffset; readonly attribute long bottomOffset; readonly attribute long leftOffset; readonly attribute long rightOffset; readonly attribute unsigned long width; readonly attribute unsigned long height; readonly attribute boolean selected; readonly attribute boolean visible; readonly attribute unsigned long foregroundColor; readonly attribute unsigned long backgroundColor; readonly attribute DOMString fontName; readonly attribute DOMString fontHeight; boolean getNext(); };
backgroundColor
of type unsigned long
, readonlybottomOffset
of type long
, readonlyendNode
of type Node
, readonlyendOffset
of type unsigned long
, readonlyexists
of type boolean
, readonlyfontHeight
of type DOMString
, readonlyfontName
of type DOMString
, readonlyforegroundColor
of type unsigned long
, readonlyheight
of type unsigned long
, readonlyleftOffset
of type long
, readonlymatchContaining
of type boolean
matchX
, matchY
,
matchXR
, and matchYR
.matchContainsSelected
of type boolean
matchContainsVisible
of type boolean
matchContent
of type boolean
matchNode
content, offset by
matchOffset
.matchInside
of type boolean
matchX
, matchY
,
matchXR
, and matchYR
.matchNode
of type Node
matchNodeR
of type Node
matchOffset
of type unsigned long
matchOffsetR
of type unsigned long
matchPosition
of type boolean
matchX
and
matchY
positions.matchRange
of type boolean
matchNode
offset matchOffset
and
Node matchNodeR
offset matchOffsetR
.matchX
of type long
matchXR
of type long
matchY
of type long
matchYR
of type long
rightOffset
of type long
, readonlyselected
of type boolean
, readonlystartNode
of type Node
, readonlystartOffset
of type unsigned long
, readonlytopOffset
of type long
, readonlyvisible
of type boolean
, readonlywidth
of type unsigned long
, readonlygetNext
VisualResource
, if any.
|
interface VisualCharacter : VisualSegment { };
interface VisualCharacterRun : VisualSegment { };
interface VisualFrame : VisualSegment { readonly attribute VisualSegment embedded; };
embedded
of type VisualSegment
, readonlyinterface VisualImage : VisualSegment { readonly attribute DOMString imageURL; readonly attribute boolean isLoaded; };
interface VisualFormButton : VisualSegment { readonly attribute boolean isPressed; };
isPressed
of type boolean
, readonlyinterface VisualFormField : VisualSegment { readonly attribute DOMString formValue; };
formValue
of type DOMString
, readonly