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 APIsThe 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. |
getBooleanPropertyMatches
and Items.
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. |
getContentPropertyNodeMatches
and Items.
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. |
getContentPropertyOffsetMatches
and Items.
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. |
getIntegerPropertyMatches
and Items.
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. |
getStringPropertyMatches
and Items.
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. |
matchFirstSegmentselectboundary of type
Nodeoffset of type
unsigned longextend of type
booleanadd of type
booleanSegment 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 node);
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 Matchcriteria Match of
a Segment, specified during creation, controls which
Segments will match.getNext are unpredictable until the segment has been
requested again by calling matchFirstSegment.order of type
DOMStringorder 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.addItemcreateBooleanItemname of type
DOMString|
The requested |
createContentItemname of type
DOMString|
The requested |
createIntegerItemname of type
DOMString|
The requested |
createMatchBooleantest of type unsigned
shortname of type
DOMStringvalue of type
boolean|
The requested |
createMatchContenttest of type unsigned
shortname of type
DOMStringoffset of type
unsigned longnode of type
Node|
The requested |
createMatchIntegertest of type unsigned
shortname of type
DOMStringvalue of type
long|
The requested |
createMatchSetcreateMatchStringtest of type unsigned
shortname of type
DOMStringvalue of type
DOMString|
The requested |
createStringItemname of type
DOMString|
The requested |
getItemItem, 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 longItem to be
retrieved.getNextSegment, if any.
|
|
|
The Match identifies Segments
of which a Segment
should fetch the Items.
// 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;
};
INT_FOLLOWSINT_FOLLOWS_OR_EQUALSINT_PRECEDESINT_PRECEDES_OR_EQUALSIS_EQUALIS_NOT_EQUALSET_ALLSET_ANYSET_NOT_ALLSET_NOT_ANYSTR_CONTAINSSTR_ENDS_WITHSTR_STARTS_WITHtest of type unsigned
short, readonlytest value of a Match, specified
during creation, controls the test to be applied.The MatchString identifies Segments
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 Segments
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 Segments
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 Segments
where a content property matches a specific value.
// Introduced in DOM level 3:
interface MatchContent : Match {
readonly attribute DOMString name;
readonly attribute Node node;
readonly attribute unsigned long offset;
};
name of type
DOMString, readonlySegment
to be compared against, which is specified during
construction.node of type
Node, readonlyoffset of type
unsigned long, readonlyThe MatchSet identifies Segments
where a set of matches evaluate in a specified way.
// Introduced in DOM level 3:
interface MatchSet : Match {
readonly attribute Node node;
void addMatch(in Match add);
Match getMatch(in unsigned long index);
};
node of type
Node, readonlyaddMatchgetMatchMatch, 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 longMatch 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.
The IntegerItem represents an integer property to
be fetched by a Segment.
The BooleanItem represents a boolean property to be
fetched by a Segment.
The ContentItem represents a content property to be
fetched by a Segment.
// Introduced in DOM Level 3:
interface ContentItem : Item {
attribute Node node;
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 |
matchSegmentselectboundary of type
Nodeoffset of type
unsigned longextend of type
booleanadd of type
booleanVisual 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
DOMStringgetNextVisualFont, 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 booleanmatchX, matchY, matchXR, and
matchYR.matchContainsSelected
of type booleanmatchContainsVisible
of type booleanmatchContent of type
booleanmatchNode content, offset
by matchOffset.matchInside of type
booleanmatchX, matchY, matchXR, and
matchYR.matchNode of type
NodematchNodeR of type
NodematchOffset of type
unsigned longmatchOffsetR of type
unsigned longmatchPosition of type
booleanmatchX and
matchY positions.matchRange of type
booleanmatchNode offset matchOffset
and Node matchNodeR offset
matchOffsetR.matchX of type
longmatchXR of type
longmatchY of type
longmatchYR of type
longrightOffset 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, readonlygetNextVisualResource,
if any.
|
|
interface VisualCharacter : VisualSegment {
};
interface VisualCharacterRun : VisualSegment {
};
interface VisualFrame : VisualSegment {
readonly attribute VisualSegment embedded;
};
embedded of type VisualSegment,
readonly
interface VisualFormButton : VisualSegment {
readonly attribute boolean isPressed;
};
isPressed of type
boolean, readonly
interface VisualFormField : VisualSegment {
readonly attribute DOMString formValue;
};
formValue of type
DOMString, readonly