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
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 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 longnodeArg 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; };
test 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 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 Segments 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, 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.
// 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 |
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, 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