Document API
Variable: documentModule
Type: DocumentModule
Types and interfaces related to user interface functionality. This API describes UI Elements (basic elements that provide the basis for the user interface system and Components (more complex, composite objects that combine elements and functionality around those elements).
import * as document from "document";
const element = document.getElementById("myElement");
element.text = "Hello world";
Interface: DocumentModule
Properties
readonly default
Default export
readonly history
New in SDK 5.0
Object describing the history stack of the currently loaded views.
readonly location
New in SDK 4.0
Location object describing the location of the currently loaded SVG file.
onactivate
((this: Element, event: Event) => any) or undefined
onanimationend
((this: Element, event: AnimationEvent) => any) or undefined
onanimationiteration
((this: Element, event: AnimationEvent) => any) or undefined
onanimationstart
((this: Element, event: AnimationEvent) => any) or undefined
onbeforeunload
((this: Element or DocumentModule, event: Event) => any) or undefined
New in SDK 5.0
Called before unloading a SVG view. Unlike the 'unload' event, this can be prevented.
NOTE: If preventDefault() is called, the view will not be unloaded. If there is only a single view loaded, the app will also not exit.
onclick
((this: Element, event: MouseEvent) => any) or undefined
oncollapse
((this: Element, event: Event) => any) or undefined
ondisable
((this: Element, event: Event) => any) or undefined
onenable
((this: Element, event: Event) => any) or undefined
onexpand
((this: Element, event: Event) => any) or undefined
onhighlight
((this: Element, event: Event) => any) or undefined
onkeydown
((this: Element, event: KeyboardEvent) => any) or undefined
onkeypress
((this: Element, event: KeyboardEvent) => any) or undefined
onkeyup
((this: Element, event: KeyboardEvent) => any) or undefined
onlistbackward
((this: Element, event: ListScrollEvent) => any) or undefined
onlistforward
((this: Element, event: ListScrollEvent) => any) or undefined
onload
((this: Element, event: LoadEvent) => any) or undefined
onmousedown
((this: Element, event: MouseEvent) => any) or undefined
onmousemove
((this: Element, event: MouseEvent) => any) or undefined
onmouseout
((this: Element, event: MouseEvent) => any) or undefined
onmouseover
((this: Element, event: MouseEvent) => any) or undefined
onmouseup
((this: Element, event: MouseEvent) => any) or undefined
onpagescroll
((this: Element, event: PageScrollEvent) => any) or undefined
onreload
((this: Element, event: Event) => any) or undefined
onselect
((this: Element, event: Event) => any) or undefined
onunhighlight
((this: Element, event: Event) => any) or undefined
onunload
((this: Element, event: Event) => any) or undefined
onunselect
((this: Element, event: Event) => any) or undefined
readonly root
Element that is at the root of the element tree.
Methods
addEventListener()
addEventListener(type: K, listener: (this: Element, event: EventMap[K]) => any)
Returns: void
Add an event listener for events emitted by this element.
getEventHandler()
getEventHandler(elementType: string)
Returns: EventHandler or null
Get the registered global event handler for elements of a given type.
Parameter: elementType Type for which to get the handler.
setEventHandler()
setEventHandler(elementType: string, handler: EventHandler)
Returns: void
Register a global event handler for all elements of a given type.
Parameter: handler Event handler.
Interface: Location
New in SDK 4.0
The Location interface allows manipulation of the application's views.
Properties
readonly pathname
string
The path of the currently loaded SVG file.
NOTE: Always starts with a slash, e.g. /file.view
Methods
assign()
assign(path: string)
Returns: Promise<void>
New in SDK 5.0
Load a new SVG file and place it on top of the view stack.
NOTE: Assuming the current view is at a certain position within the location history stack, all the views on top and references to their elements will be freed. Accessing the UI elements after their references have been freed results in an error.
NOTE: When loading a new view (as with this method), references to elements in the
old view are kept, but document getters can only access elements within the current
view. In order to access old elements, the currently visible view needs to be updated
using document.history methods.
NOTE: All document and element handlers and listeners will be cleared when the
promise returned by document.location.assign is resolved. Examples of handlers and
listeners that will be cleared might be found in GlobalEvents.
Parameter: path Path to the new SVG file to be loaded. This path has to be
relative to the application root folder.
Ex: ./resources/view1.view
./resources/subdir/view2.view
replace()
replace(path: string)
Returns: Promise<void>
New in SDK 5.0
Replace the currently loaded SVG file with a new one, asynchronously.
Assuming the current view is at a certain position within the location history stack, all the views on top and references to their elements will be freed. Accessing the UI elements after their references have been freed results in an error.
When loading a new view (as with this method), any references to elements in
the old view will be invalidated, and document will refer to the newly loaded
view.
It is safe to call this method in document.onunload (for example, to implement a
viewstack), but do be careful to allow yourself to exit your app still!
NOTE: All document, element handlers, and listeners will be cleared when the
promise returned by document.location.replace is resolved. Examples of handlers and
listeners that will be cleared might be found in GlobalEvents.
Starting with FbOS 5.0, this method replaces the deprecated document.replaceSync
method.
Parameter: path Path to the new SVG file to be loaded. This path has to be relative to
the application root folder.
Ex: ./resources/view1.view
./resources/subdir/view2.view
Interface: History
New in SDK 5.0
The History interface allows manipulation of the document views history, that is the current view stack loaded in the app.
Properties
readonly length
number
Integer number representing the number of currently loaded views.
Methods
back()
Returns: void
Make the view below the current one in the location history stack visible. Equivalent
with history.go(-1).
Throws: Throws a RangeError if there's no other loaded view.
forward()
Returns: void
Make the view above the current one in the location history stack visible. Equivalent
with history.go(1).
Throws: Throws a RangeError if there's no other view in forward history. one.
go()
go(delta: number)
Returns: void
Make a specific view from the location history visible, relative to the topmost visible view.
Parameter: delta The view position in the location history to which you want to move,
relative to the current view. A negative value moves backwards, a positive value
moves forwards. So, for example, history.go(2) will display the view that's forward
two positions and history.go(-2) will display the view that's backward two
positions.
Throws: Throws a RangeError if the position is not available in the history.
Interface: ScrollIndicatorElement
Visual indicator of the current page, typically used with a panoramaview element.
(often shown as pagination dots)
This type of component is usually automatically updated by a parent component as it scrolls, but it is possible to control it directly through its API, either by setting the value property, which controls which of the indicators is currently highlighted, or by calling setPosition
Properties
length
number
Number of scroll indicator items displayed.
overflow
"inherit" or "visible" or "hidden"
Indicates whether the children are clipped or not when they overflow the bounds of the container.
When set to visible, the content is not clipped.
When set to hidden the content is clipped to the borders of the container element.
When set to inherit, the parent element's settings are inherited.
Methods
setPosition()
setPosition(position: number, pageSize: number, viewSize: number)
Returns: void
Set the current scroll position that should be displayed by the element. NOTE: this may update the value property of this element if the scroll position corresponds to a different page. While the parameters may be set in terms of pixel units, it isn't necessary, as long as all three parameters are expressed in the same arbitrary measurement unit.
Parameter: viewSize Total size of the view (all pages combined)
Interface: ComboButton
Properties
overflow
"inherit" or "visible" or "hidden"
Indicates whether the children are clipped or not when they overflow the bounds of the container.
When set to visible, the content is not clipped.
When set to hidden the content is clipped to the borders of the container element.
When set to inherit, the parent element's settings are inherited.
Methods
disable()
disable(options?: ComboButtonEnableDisableOptions | undefined)
Returns: void
Disable the button.
Parameter: options Optional operation options.
If omitted, the behavior is as if {} was passed.
enable()
enable(options?: ComboButtonEnableDisableOptions | undefined)
Returns: void
Enable the button.
Parameter: options Optional operation options.
If omitted, the behavior is as if {} was passed.
hide()
hide(options?: ComboButtonShowHideOptions | undefined)
Returns: void
Hide the button.
Parameter: options Optional operation options.
If omitted, the behavior is as if {} was passed.
show()
show(options?: ComboButtonShowHideOptions | undefined)
Returns: void
Show the button.
Parameter: options Optional operation options.
If omitted, the behavior is as if {} was passed.
Interface: ComboButtonEnableDisableOptions
Properties
animate
boolean or undefined
Indicates whether or not the item should be animated.
If set to true or isn't defined, the operation may trigger an associated animation.
If set to false the operation does not trigger an animation.
Interface: ComboButtonShowHideOptions
Properties
animate
boolean or undefined
Indicates whether or not the item should be animated.
If set to true or isn't defined, the operation may trigger an associated animation.
If set to false the operation does not trigger an animation.
Interface: VirtualTileList
A VirtualTileList is a component that displays a list of items in a vertical arrangement. A VirtualTileList may be used for lists that have a (possibly variable) number of items too large to be all explicitly instantiated. The virtual list component will automatically instantiate and recycle list items on demand as the list scrolls up or down and items become visible or hidden.
Properties
delegate
Application-defined delegate that specifies the content for the list items.
readonly firstVisibleTile
number
Index of the first visible item in the list. Between 0 (inclusive) and length (exclusive).
readonly lastVisibleTile
number
Index of the last visible item in the list.
length
number
Number of virtual tiles in the list.
overflow
"inherit" or "visible" or "hidden"
Indicates whether the children are clipped or not when they overflow the bounds of the container.
When set to visible, the content is not clipped.
When set to hidden the content is clipped to the borders of the container element.
When set to inherit, the parent element's settings are inherited.
Methods
redraw()
Returns: void
Force a redraw of the list.
This is usually called after a number of changes have been made to the list items
with a redraw option set to false, for optimization.
Interface: VirtualTileListDelegate
Interface implemented by an application, called by the system to obtain the information necessary to populate the items in the list.
Methods
configureTile()
configureTile(tile: VirtualTileListItem, tileInfo: VirtualTileListItemInfo)
Returns: void
Configure a tile list item before it is displayed.
Parameter: tileInfo Tile list info that was previously returned by this delegate for this tile item.
getTileInfo()
getTileInfo(position: number)
Returns: VirtualTileListItemInfo
Get the information for a tile, by index.
Parameter: position Index of the tile for which the info if requested. Between 0 (inclusive) and length (exclusive)
Interface: VirtualTileListItemInfo
Information about a VirtualTileListItem.
Properties
type
string
ID of the "pool" from which to obtain the tile item.
Interface: VirtualTileListItem
A VirtualTileListItem is an element that is part of a VirtualTileList component.
Properties
overflow
"inherit" or "visible" or "hidden"
Indicates whether the children are clipped or not when they overflow the bounds of the container.
When set to visible, the content is not clipped.
When set to hidden the content is clipped to the borders of the container element.
When set to inherit, the parent element's settings are inherited.
Methods
align()
align(options: TileListItemOperationOptions)
Returns: void
Align the item within the list view.
Parameter: options Operation options.
If the alignment property of the options isn't defined, calling
this method has no effect.
Interface: TileList
A TileList is a component that displays a list of items in a vertical arrangement.
Properties
readonly length
number
Number of items in the list.
Methods
getBBox()
Returns: DOMRect
Returns a DOMRect containing the element's calculated position and spatial extent at the time of being called.
getTile()
getTile(position: number)
Returns: TileListItem
Get the tile item at a given position.
Parameter: position Index of the tile within the list, between 0 (inclusive) and length (exclusive)
insertTile()
insertTile(item: TileListItem, position: number, options?: TileListItemOperationOptions | undefined)
Returns: void
Insert a tile item in the list.
Parameter: options Optional operation options.
If omitted, the behavior is as if {} was passed.
obtainTile()
obtainTile(type: string)
Returns: TileListItem or null
Obtain a tile suitable for insertion in the list.
Parameter: type ID of the "pool" (tile-list-pool element in the XML declaration) from which to obtain the tile.
Interface: TileListItem
A TileListItem is an element that is part of a TileList component.
Properties
overflow
"inherit" or "visible" or "hidden"
Indicates whether the children are clipped or not when they overflow the bounds of the container.
When set to visible, the content is not clipped.
When set to hidden the content is clipped to the borders of the container element.
When set to inherit, the parent element's settings are inherited.
Methods
align()
align(options: TileListItemOperationOptions)
Returns: void
Align the item within the list view.
Parameter: options Operation options.
If the alignment property of the options isn't defined, calling
this method has no effect.
hide()
hide(options?: TileListItemOperationOptions | undefined)
Returns: void
Hide the item.
Parameter: options Optional operation options.
If omitted, the behavior is as if {} was passed.
remove()
remove(options?: TileListItemOperationOptions | undefined)
Returns: void
Remove the item from the list.
Parameter: options Optional operation options.
If omitted, the behavior is as if {} was passed.
show()
show(options?: TileListItemOperationOptions | undefined)
Returns: void
Show the item.
Parameter: options Optional operation options.
If omitted, the behavior is as if {} was passed.
Interface: TileListItemOperationOptions
Options for item operations.
Properties
alignment
"middle" or "top" or "bottom" or undefined
When defined, indicates how the item should be aligned. If not defined, no alignment is done.
animate
boolean or undefined
Indicates whether or not the item should be animated.
If set to true or isn't defined, the operation may trigger an associated animation.
If set to false the operation does not trigger an animation.
redraw
boolean or undefined
Indicates whether or not the view should be immediately redrawn.
If set to true or isn't defined, the operation will cause a redraw of the view.
If set to false, the operation does not cause a redraw of the view.
TileListItemAlignment
String: "middle" | "top" | "bottom"
Alignment style for a tile list item.
top: the item should be aligned with the top of the view.middle: the item should be aligned with the vertical center of the view.bottom: the item should be aligned with the bottom of the view.
Interface: ImageElement
An Image element is a pixel-mapped image.
Properties
href
string
Image file name or identifier for this element.
NOTE: since a ImageElement represents an XML image property.
Methods
getBBox()
Returns: DOMRect
Returns a DOMRect containing the element's calculated position and spatial extent at the time of being called.
Interface: LineElement
A Line element is a simple line segment shape.
Properties
x1
number
X coordinate of the first point of the line segment.
x2
number
X coordinate of the second point of the line segment.
y1
number
Y coordinate of the first point of the line segment.
y2
number
Y coordinate of the second point of the line segment.
Methods
getBBox()
Returns: DOMRect
Returns a DOMRect containing the element's calculated position and spatial extent at the time of being called.
Interface: GradientArcElement
A GradientArc element is a circular or elliptical arc shape with a gradient-filled stroke.
Properties
arcWidth
number
Width of the stroke (thickness of the arc line) in pixels.
NOTE: this property corresponds to the arc-width attribute in the XML declaration.
readonly gradient
Gradient used to fill the stroke.
startAngle
number
Angle at which the arc starts, relative to the Y axis, in degrees, clockwise. For example, an arc with a starting angle of 0 starts at the middle of the top segment of the bounding rectangle.
NOTE: this property corresponds to the start-angle attribute in the XML declaration.
sweepAngle
number
Angle that the arc sweeps, in degrees (use 180 degrees for a semi-circle, 360 degrees for a full circle).
NOTE: this property corresponds to the sweep-angle attribute in the XML declaration.
Interface: ArcElement
An Arc element is a simple circular or elliptical arc shape. The arc shape is inscribed in the element's bounding rectangle defined its the top-left corner ([x] and [y] coordinates) and its width and height. If the element's bounding rectangle is a square, the arc is circular, otherwise it is elliptical.
Implemented by document.GradientArcElement
Properties
arcWidth
number
Width of the stroke (thickness of the arc line) in pixels.
NOTE: this property corresponds to the arc-width attribute in the XML declaration.
startAngle
number
Angle at which the arc starts, relative to the Y axis, in degrees, clockwise. For example, an arc with a starting angle of 0 starts at the middle of the top segment of the bounding rectangle.
NOTE: this property corresponds to the start-angle attribute in the XML declaration.
sweepAngle
number
Angle that the arc sweeps, in degrees (use 180 degrees for a semi-circle, 360 degrees for a full circle).
NOTE: this property corresponds to the sweep-angle attribute in the XML declaration.
Methods
getBBox()
Returns: DOMRect
Returns a DOMRect containing the element's calculated position and spatial extent at the time of being called.
Interface: CircleElement
A Circle element is a simple solid circle shape.
Properties
cx
number
X coordinate of the center of the circle.
NOTE: this property corresponds to the cx attribute in the XML declaration.
cy
number
Y coordinate of the center of the circle
NOTE: this property corresponds to the cy attribute in the XML declaration.
r
number
Radius of the circle.
NOTE: this property corresponds to the r attribute in the XML declaration.
Methods
getBBox()
Returns: DOMRect
Returns a DOMRect containing the element's calculated position and spatial extent at the time of being called.
Interface: GradientRectElement
A GradientRect element is a solid rectangular shape that is filled with a gradient.
Properties
gradient
Interface: RectElement
A Rect element is a simple solid rectangular shape. The area of the rectangle is defined by its top-left corner ([x] and [y] coordinates) and its width and height.
Implemented by document.GradientRectElement
Methods
getBBox()
Returns: DOMRect
Returns a DOMRect containing the element's calculated position and spatial extent at the time of being called.
Interface: TextAreaElement
A TextArea element is an element with text content that may span multiple lines.
Properties
baseline
number
Vertical position of the first row of text, in pixels, relative to the Y coordinate of the element.
NOTE: this property corresponds to the baseline attribute in the XML declaration.
displayAlign
"top" or "center" or "bottom"
Vertical alignment for the text.
top: the top of the text is aligned with the top of the element.middle: the vertical center of the text is aligned with the vertical center of the element.bottom: the bottom of the text is aligned with the bottom of the element.
NOTE: this property corresponds to the display-align attribute in the XML declaration.
letterSpacing
number
Spacing between text characters, in pixels. The value may be negative to decrease the spacing, or positive to increase the spacing.
NOTE: this property corresponds to the letter-spacing attribute in the XML declaration.
lineIncrement
number
Height of each text row, in pixels.
NOTE: this property corresponds to the line-increment attribute in the XML declaration.
rows
number
Maximum number of rows that the text can span.
NOTE: this property corresponds to the rows attribute in the XML declaration.
textAnchor
"start" or "middle" or "end"
Horizontal alignment for the text, relative to the X coordinate of the element.
start: the start of the text is positioned at the X coordinate.middle: the middle of the text is positioned at the X coordinate.end: the end of the text is positioned at the X coordinate.
NOTE: this property corresponds to the text-anchor attribute in the XML declaration.
textContent
string
Text content of the element.
NOTE: since a TextElement represents an XML text property.
textOverflow
"clip" or "ellipsis"
Indicates how to render text that overflows its bounds.
clip: the text is clipped.ellipsis: the end of the text may be replaced with an ellipsis (...) in order to fit within the bounds of the element.
NOTE: this property corresponds to the text-overflow attribute in the XML declaration.
readonly textOverflowing
boolean
Indicates whether the text is overflowing due to the given rectangle bounds of this element.
If textOverflow is set to clip, textOverflowing indicates whether the text is clipping.
If textOverflow is ellipsis, textOverflowing indicates whether the end of text is being replaced
with an ellipsis (...).
writingMode
"lr" or "rl"
Writing mode for the text.
lr: the text is written from left to right.rl: the text is written from right to left.
NOTE: this property corresponds to the writing-mode attribute in the XML declaration.
Interface: TextElement
A Text element is a single line of text content.
Implemented by document.TextAreaElement
Properties
letterSpacing
number
Spacing between text characters, in pixels. The value may be negative to decrease the spacing, or positive to increase the spacing.
NOTE: this property corresponds to the letter-spacing attribute in the XML declaration.
textAnchor
"start" or "middle" or "end"
Horizontal alignment for the text, relative to the X coordinate of the element.
start: the start of the text is positioned at the X coordinate.middle: the middle of the text is positioned at the X coordinate.end: the end of the text is positioned at the X coordinate.
NOTE: this property corresponds to the text-anchor attribute in the XML declaration.
textContent
string
Text content of the element.
NOTE: since a TextElement represents an XML text property.
textOverflow
"clip" or "ellipsis"
Indicates how to render text that overflows its bounds.
clip: the text is clipped.ellipsis: the end of the text may be replaced with an ellipsis (...) in order to fit within the bounds of the element.
NOTE: this property corresponds to the text-overflow attribute in the XML declaration.
readonly textOverflowing
boolean
Indicates whether the text is overflowing due to the given rectangle bounds of this element.
If textOverflow is set to clip, textOverflowing indicates whether the text is clipping.
If textOverflow is ellipsis, textOverflowing indicates whether the end of text is being replaced
with an ellipsis (...).
writingMode
"lr" or "rl"
Writing mode for the text.
lr: the text is written from left to right.rl: the text is written from right to left.
NOTE: this property corresponds to the writing-mode attribute in the XML declaration.
Methods
getBBox()
Returns: DOMRect
Returns a DOMRect containing the element's calculated position and spatial extent at the time of being called.
Interface: GroupElement
A Group element is a container of children elements, with an optional affine transformation.
Properties
readonly groupTransform
Transform or undefined
Methods
getBBox()
Returns: DOMRect
Returns a DOMRect containing the element's calculated position and spatial extent at the time of being called.
Interface: AnimateElement
Properties
by
number
The increment to be used for each step of the animation. It only applies to animations on attributes that support addition.
NOTE: this property corresponds to the by attribute in the XML declaration.
readonly children
Element[]
New in SDK 4.1
Returns an array of the direct children of this element. If the element has no children, the array will be empty.
class
string
Class name of the element.
NOTE: this property corresponds to the class attribute in the XML declaration.
dur
number
The duration of the animation, in seconds.
NOTE: this property corresponds to the dur attribute in the XML declaration.
readonly firstChild
Element or null
First child element.
If the element has no children, the value is null.
from
number
The value to start the animation with.
NOTE: this property corresponds to the from attribute in the XML declaration.
readonly id
string
Identifier for the element.
NOTE: this property corresponds to the id attribute in the XML declaration.
image
string
Image file name or identifier for this element.
Note that the actual element (typically an ImageElement) that handles the setting or getting
of this property may be a descendant:
if this element isn't an ImageElement, the default behavior, if not overridden,
is to look for the first element with id=image within the descendants, and, if found,
set its image.
layer
number
Rendering display order.
NOTE: this property corresponds to the layer attribute in the XML declaration.
mode
number or number, number
Generic read/write property used by some elements for different purposes depending on the actual element type. It typically represents one or more modifiers for the element's behavior.
When getting this property, the value returned is always an integer. When setting this property, the value set may be an integer (when setting a simple value) or a two-element array where the first array element is an integer for the value and the second array element is an integer that may be used as a flags/modifier indicator for specialized purposes by some components (transition animation flags for example).
readonly nextSibling
Element or null
Next sibling element.
If the element has no next sibling, the value is null.
readonly parent
Element or null
Parent element.
If the element has no parent, the value is null.
repeatCount
number or "indefinite"
The number of times to repeat the animation.
NOTE: this property corresponds to the repeatCount attribute in the XML declaration.
repeatDur
number
The duration of each repetition of the animation.
NOTE: this property corresponds to the repeatDur attribute in the XML declaration.
NOTE: this attribute differs from the SVG specification as it specifies the length
of each repetition, rather than how long to repeat for.
state
Current state of the element.
text
string
Text content for this element.
Note that the actual element (typically a TextElement or TextAreaElement) that handles the setting or getting
of this property may be a descendant:
if this element isn't a TextElement or TextAreaElement, the default behavior, if not overridden,
is to look for the first element with id=text within the descendants, and, if found,
set its text.
to
number
The value to end the animation with.
NOTE: this property corresponds to the to attribute in the XML declaration.
readonly type
string
Type of the element.
The type of an element refers to the type XML attribute specified in the
document where the element is declared, not to the JavaScript type of the
element object.
value
number or number, number
Generic read/write property used by some elements for different purposes
depending on the actual element type. It typically represents a state variable for the
element.
For example, a panoramaview element's value is equal to the index of the current page.
When getting this property, the value returned is always an integer. When setting this property, the value set may be an integer (when setting a simple value) or a two-element array where the first array element is an integer for the value and the second array element is an integer that may be used as a flags/modifier indicator for specialized purposes by some components (transition animation flags for example).
Methods
animate()
animate(trigger: EventName)
Returns: void
Trigger the start of animations for this element, if any is defined.
Parameter: trigger Name of the animation trigger event.
sendEvent()
sendEvent(event: Event)
Returns: void
Send an event to the element. Events are typically generated by user action or by the system, but it may sometimes be necessary for an application to synthesize and send events directly.
Parameter: event Event to send.
Interface: ContainerElement
Base interface for elements that are containers.
Implemented by document.ScrollIndicatorElement, document.ComboButton, document.VirtualTileList, document.VirtualTileListItem, document.TileListItem
Properties
overflow
"inherit" or "visible" or "hidden"
Indicates whether the children are clipped or not when they overflow the bounds of the container.
When set to visible, the content is not clipped.
When set to hidden the content is clipped to the borders of the container element.
When set to inherit, the parent element's settings are inherited.
Methods
getBBox()
Returns: DOMRect
Returns a DOMRect containing the element's calculated position and spatial extent at the time of being called.
Interface: GraphicsElement
A Graphics element is an element than can have its position and spatial extent calculated.
Implemented by document.TileList, document.ImageElement, document.LineElement, document.ArcElement, document.CircleElement, document.RectElement, document.TextElement, document.GroupElement, document.ContainerElement
Properties
readonly children
Element[]
New in SDK 4.1
Returns an array of the direct children of this element. If the element has no children, the array will be empty.
class
string
Class name of the element.
NOTE: this property corresponds to the class attribute in the XML declaration.
readonly firstChild
Element or null
First child element.
If the element has no children, the value is null.
readonly id
string
Identifier for the element.
NOTE: this property corresponds to the id attribute in the XML declaration.
image
string
Image file name or identifier for this element.
Note that the actual element (typically an ImageElement) that handles the setting or getting
of this property may be a descendant:
if this element isn't an ImageElement, the default behavior, if not overridden,
is to look for the first element with id=image within the descendants, and, if found,
set its image.
layer
number
Rendering display order.
NOTE: this property corresponds to the layer attribute in the XML declaration.
mode
number or number, number
Generic read/write property used by some elements for different purposes depending on the actual element type. It typically represents one or more modifiers for the element's behavior.
When getting this property, the value returned is always an integer. When setting this property, the value set may be an integer (when setting a simple value) or a two-element array where the first array element is an integer for the value and the second array element is an integer that may be used as a flags/modifier indicator for specialized purposes by some components (transition animation flags for example).
readonly nextSibling
Element or null
Next sibling element.
If the element has no next sibling, the value is null.
readonly parent
Element or null
Parent element.
If the element has no parent, the value is null.
state
Current state of the element.
text
string
Text content for this element.
Note that the actual element (typically a TextElement or TextAreaElement) that handles the setting or getting
of this property may be a descendant:
if this element isn't a TextElement or TextAreaElement, the default behavior, if not overridden,
is to look for the first element with id=text within the descendants, and, if found,
set its text.
readonly type
string
Type of the element.
The type of an element refers to the type XML attribute specified in the
document where the element is declared, not to the JavaScript type of the
element object.
value
number or number, number
Generic read/write property used by some elements for different purposes
depending on the actual element type. It typically represents a state variable for the
element.
For example, a panoramaview element's value is equal to the index of the current page.
When getting this property, the value returned is always an integer. When setting this property, the value set may be an integer (when setting a simple value) or a two-element array where the first array element is an integer for the value and the second array element is an integer that may be used as a flags/modifier indicator for specialized purposes by some components (transition animation flags for example).
Methods
animate()
animate(trigger: EventName)
Returns: void
Trigger the start of animations for this element, if any is defined.
Parameter: trigger Name of the animation trigger event.
getBBox()
Returns: DOMRect
Returns a DOMRect containing the element's calculated position and spatial extent at the time of being called.
sendEvent()
sendEvent(event: Event)
Returns: void
Send an event to the element. Events are typically generated by user action or by the system, but it may sometimes be necessary for an application to synthesize and send events directly.
Parameter: event Event to send.
Interface: Element
Base interface for all element types. Elements are the fundamental building blocks for the user interface subsystem. Elements represent a combination of appearance and behavior. They are organized as a tree, where an element may have a parent and zero or more children.
Implemented by document.AnimateElement, document.GraphicsElement
Properties
readonly children
Element[]
New in SDK 4.1
Returns an array of the direct children of this element. If the element has no children, the array will be empty.
class
string
Class name of the element.
NOTE: this property corresponds to the class attribute in the XML declaration.
readonly firstChild
Element or null
First child element.
If the element has no children, the value is null.
readonly id
string
Identifier for the element.
NOTE: this property corresponds to the id attribute in the XML declaration.
image
string
Image file name or identifier for this element.
Note that the actual element (typically an ImageElement) that handles the setting or getting
of this property may be a descendant:
if this element isn't an ImageElement, the default behavior, if not overridden,
is to look for the first element with id=image within the descendants, and, if found,
set its image.
layer
number
Rendering display order.
NOTE: this property corresponds to the layer attribute in the XML declaration.
mode
number or number, number
Generic read/write property used by some elements for different purposes depending on the actual element type. It typically represents one or more modifiers for the element's behavior.
When getting this property, the value returned is always an integer. When setting this property, the value set may be an integer (when setting a simple value) or a two-element array where the first array element is an integer for the value and the second array element is an integer that may be used as a flags/modifier indicator for specialized purposes by some components (transition animation flags for example).
readonly nextSibling
Element or null
Next sibling element.
If the element has no next sibling, the value is null.
onactivate
((this: Element, event: Event) => any) or undefined
onanimationend
((this: Element, event: AnimationEvent) => any) or undefined
onanimationiteration
((this: Element, event: AnimationEvent) => any) or undefined
onanimationstart
((this: Element, event: AnimationEvent) => any) or undefined
onclick
((this: Element, event: MouseEvent) => any) or undefined
oncollapse
((this: Element, event: Event) => any) or undefined
ondisable
((this: Element, event: Event) => any) or undefined
onenable
((this: Element, event: Event) => any) or undefined
onexpand
((this: Element, event: Event) => any) or undefined
onhighlight
((this: Element, event: Event) => any) or undefined
onkeydown
((this: Element, event: KeyboardEvent) => any) or undefined
onkeypress
((this: Element, event: KeyboardEvent) => any) or undefined
onkeyup
((this: Element, event: KeyboardEvent) => any) or undefined
onlistbackward
((this: Element, event: ListScrollEvent) => any) or undefined
onlistforward
((this: Element, event: ListScrollEvent) => any) or undefined
onload
((this: Element, event: LoadEvent) => any) or undefined
onmousedown
((this: Element, event: MouseEvent) => any) or undefined
onmousemove
((this: Element, event: MouseEvent) => any) or undefined
onmouseout
((this: Element, event: MouseEvent) => any) or undefined
onmouseover
((this: Element, event: MouseEvent) => any) or undefined
onmouseup
((this: Element, event: MouseEvent) => any) or undefined
onpagescroll
((this: Element, event: PageScrollEvent) => any) or undefined
onreload
((this: Element, event: Event) => any) or undefined
onselect
((this: Element, event: Event) => any) or undefined
onunhighlight
((this: Element, event: Event) => any) or undefined
onunload
((this: Element, event: Event) => any) or undefined
onunselect
((this: Element, event: Event) => any) or undefined
readonly parent
Element or null
Parent element.
If the element has no parent, the value is null.
state
Current state of the element.
text
string
Text content for this element.
Note that the actual element (typically a TextElement or TextAreaElement) that handles the setting or getting
of this property may be a descendant:
if this element isn't a TextElement or TextAreaElement, the default behavior, if not overridden,
is to look for the first element with id=text within the descendants, and, if found,
set its text.
readonly type
string
Type of the element.
The type of an element refers to the type XML attribute specified in the
document where the element is declared, not to the JavaScript type of the
element object.
value
number or number, number
Generic read/write property used by some elements for different purposes
depending on the actual element type. It typically represents a state variable for the
element.
For example, a panoramaview element's value is equal to the index of the current page.
When getting this property, the value returned is always an integer. When setting this property, the value set may be an integer (when setting a simple value) or a two-element array where the first array element is an integer for the value and the second array element is an integer that may be used as a flags/modifier indicator for specialized purposes by some components (transition animation flags for example).
Methods
addEventListener()
addEventListener(type: K, listener: (this: Element, event: EventMap[K]) => any)
Returns: void
Add an event listener for events emitted by this element.
animate()
animate(trigger: EventName)
Returns: void
Trigger the start of animations for this element, if any is defined.
Parameter: trigger Name of the animation trigger event.
sendEvent()
sendEvent(event: Event)
Returns: void
Send an event to the element. Events are typically generated by user action or by the system, but it may sometimes be necessary for an application to synthesize and send events directly.
Parameter: event Event to send.
Interface: ElementSearch
Interface to look for elements in an element tree.
Methods
getElementById()
getElementById(id: string)
Returns: T or null
Get an descendant Element by ID. e.g. <element id="foo" />
When called on the document module itself, the entire element tree is searched.
When called on an individual element, the element subtree rooted at that element
is searched.
The first element with the requested ID, if any, is returned.
Parameter: id The ID of the element to look for.
getElementsByClassName()
getElementsByClassName(className: string)
Returns: Element[]
Get descendant Elements by their class name. e.g. <element class="foo" />
When called on the document module itself, the entire element tree is searched.
When called on an individual element, the element subtree rooted at that element
is searched.
All the elements with the requested class are returned.
Parameter: className Name of the class to look for.
getElementsByTagName()
getElementsByTagName(tagName: string)
Returns: Element[]
Get descendant Elements by tag name. e.g <svg>, <image>, <circle> etc.
When called on the document module itself, the entire element tree is searched.
When called on an individual element, the element subtree rooted at that element
is searched.
All the elements with the requested tag are returned.
Parameter: tagName Name of the tag to look for.
getElementsByTypeName()
getElementsByTypeName(typeName: string)
Returns: Element[]
Get descendant Elements by type name. e.g. <element type="foo" />
When called on the document module itself, the entire element tree is searched.
When called on an individual element, the element subtree rooted at that element
All the elements with the requested type are returned.
Parameter: typeName Name of the type to look for.
Interface: GlobalEvents
Event listeners.
Implemented by document.DocumentModule, document.Element
Properties
onactivate
((this: Element, event: Event) => any) or undefined
onanimationend
((this: Element, event: AnimationEvent) => any) or undefined
onanimationiteration
((this: Element, event: AnimationEvent) => any) or undefined
onanimationstart
((this: Element, event: AnimationEvent) => any) or undefined
onclick
((this: Element, event: MouseEvent) => any) or undefined
oncollapse
((this: Element, event: Event) => any) or undefined
ondisable
((this: Element, event: Event) => any) or undefined
onenable
((this: Element, event: Event) => any) or undefined
onexpand
((this: Element, event: Event) => any) or undefined
onhighlight
((this: Element, event: Event) => any) or undefined
onkeydown
((this: Element, event: KeyboardEvent) => any) or undefined
onkeypress
((this: Element, event: KeyboardEvent) => any) or undefined
onkeyup
((this: Element, event: KeyboardEvent) => any) or undefined
onlistbackward
((this: Element, event: ListScrollEvent) => any) or undefined
onlistforward
((this: Element, event: ListScrollEvent) => any) or undefined
onload
((this: Element, event: LoadEvent) => any) or undefined
onmousedown
((this: Element, event: MouseEvent) => any) or undefined
onmousemove
((this: Element, event: MouseEvent) => any) or undefined
onmouseout
((this: Element, event: MouseEvent) => any) or undefined
onmouseover
((this: Element, event: MouseEvent) => any) or undefined
onmouseup
((this: Element, event: MouseEvent) => any) or undefined
onpagescroll
((this: Element, event: PageScrollEvent) => any) or undefined
onreload
((this: Element, event: Event) => any) or undefined
onselect
((this: Element, event: Event) => any) or undefined
onunhighlight
((this: Element, event: Event) => any) or undefined
onunload
((this: Element, event: Event) => any) or undefined
onunselect
((this: Element, event: Event) => any) or undefined
EventName
String: "select" | "mousedown" | "mouseup" | "mousemove" | "click" | "keydown" | "keyup" | "keypress" | "activate" | "enable" | "disable" | "unselect" | "highlight" | "unhighlight" | ... 7 more ... | "listbackward"
Event name.
ElementState
String: "enabled" | "disabled" | "highlighted" | "unhighlighted" | "selected" | "unselected" | "expanded" | "collapsed"
State of an element.
Interface: DOMRect
Rectangle containing the calculated element position and spatial extent readonly properties with respect to the element's local coordinate system.
Properties
readonly bottom
number
Bottom coordinate value ([y] + height, or [y] if height is negative).
readonly height
number
Height of the bounding rectangle.
readonly left
number
Left coordinate value ([x], or [x] + width if width is negative).
readonly right
number
Right coordinate value ([x] + width, or [x] if width is negative).
readonly top
number
Top coordinate value ([y], or [y] + height if height is negative).
readonly width
number
Width of the bounding rectangle.
readonly x
number
X coordinate of the top-left corner of the bounding rectangle.
readonly y
number
Y coordinate of the top-left corner of the bounding rectangle.
Interface: Bounded
Trait interface for elements that have a position and a spatial extent (they have a bounding rectangle). The [x], [y], width and height are expressed in pixels and are relative to the element's local coordinate system.
Properties
height
number
Height of the bounding rectangle.
width
number
Width of the bounding rectangle.
x
number
X coordinate of the top-left corner of the bounding rectangle.
y
number
Y coordinate of the top-left corner of the bounding rectangle.
Interface: Styled
Trait interface for elements that have styled visual properties.
Properties
readonly style
Style of the element.
Interface: Gradient
Color gradient.
Properties
readonly colors
{ c1: string; c2: string; c3: string; c4: string; }
Gradient colors.
For linear and radial gradients, [c1] and [c2] are the start and end colors, respectively.
([c3] and [c4] are ignored)
For bilinear gradients, [c1] and [c2] are the same as for a linear gradient,
[c3] and [c4] are the two additional colors, in clockwise order.
opacity
{ o1: number or undefined; o2: number or undefined; o3: number or undefined; o4: number or undefined; }
Opacity for the gradient colors. The values [o1], [o2], [o3] and [o4] are the opacity coefficients for the gradient colors [c1], [c2], [c3], and [c4], respectively. The values are between 0.0 (fully transparent) and 1.0 (fully opaque). (values outside the range will be clamped).
type
"linear" or "radial" or "bilinear"
Gradient type.
x1
number
X coordinate of the first point of the gradient.
x2
number
X coordinate of the second point of the gradient.
Must be >= [x1] for linear and radial gradients, > [x1] for bilinear gradients.
y1
number
Y coordinate of the first point of the gradient.
y2
number
Y coordinate of the second point of the gradient.
Must be >= [y1] for linear and radial gradients, > [y1] for bilinear gradients.
Interface: Transform
2D affine transformation that may be applied to a GroupElement.
Properties
readonly rotate
{ angle: number; }
Rotation in the (X,Y) plane.
readonly scale
{ x: number; y: number; }
Scaling along the X and Y axes.
readonly translate
{ x: number; y: number; }
Translation along the X and Y axes.
Interface: Style
Attributes related to an element's visual appearance.
Styles set on an element of an inappropriate type are ignored.
Properties
display
"inherit" or "none" or "inline"
Determines if an element is part of the rendering process.
When set to inline, the element is rendered.
When set to none, the element and its children will not be rendered (but may still
receive events).
When set to inherit, the element's parent's property is used.
fill
string
Color of the interior of a graphical element. In the case of text element, this is the color of the text itself.
fillOpacity
number or undefined
Opacity of the element's interior, between 0.0 (fully transparent) and 1.0 (fully opaque). (values outside the range will be clamped)
fontFamily
string
Name of the font family to use to render text.
When set to inherit, the element's parent's property is used.
fontSize
number or undefined
Size of the font to use to render text.
fontWeight
"inherit" or "light" or "regular" or "bold"
Weight of the font to use to render text.
When set to inherit, the element's parent's property is used.
opacity
number or undefined
Opacity of the element, between 0.0 (fully transparent) and 1.0 (fully opaque). (values outside the range will be clamped)
strokeWidth
number
New in SDK 4.1
Sets the width of a line element. Minimum of 0, maximum of 31 allowed. Values outside this range will be clamped. Must be an integer, non-integer values will be rounded.
textDecoration
"inherit" or "none" or "underline"
Decoration added to the text.
When set to inherit, the element's parent's property is used.
none: no decoration is added to the textunderline: an underline is added to the text
visibility
"inherit" or "visible" or "hidden"
Determines if an element is visible.
When set to visible, the element is visible.
When set to hidden, the element is not visible, but it is still part of the
rendering process, so it is still accounted for in size and alignment calculations.
When set to inherit, the parent element's property is used.
InheritableNumber
String: number | undefined
Number value that may be inherited from an element's parent.
When undefined, the value should be inherited from the element's parent.
Color
String: string
Color identifier.
A color may be specified as
- an RGB (Red, Green, Blue) triplet as:
#RRGGBB, - an RGBA (Red, Green, Blue, Alpha) quad as:
#RRGGBBAAwhereRR,GG,BBandAAare the red, green, blue and alpha component values, respectively, in hexadecimal (range 00 to FF). - a color name for predefined colors.
- the special value
inheritto indicate that the color value should be inherited from the corresponding property of the element's parent.
EventHandler
String: (event: Event) => boolean
Event handler that may be used as a globally-registered event handler.
Interface: EventMap
Properties
activate
animationend
animationiteration
animationstart
click
collapse
disable
enable
expand
highlight
keydown
keypress
keyup
listbackward
listforward
load
mousedown
mousemove
mouseout
mouseover
mouseup
pagescroll
reload
select
unhighlight
unload
unselect
Interface: LoadEvent
Event details for loading-related events.
Properties
readonly defaultPrevented
boolean
Set to true when the default handling was prevented
readonly phase
1 or 2
The loading phase.
readonly target
EventTarget or undefined
Target of the event
readonly type
string
Type of the event
Interface: ListScrollEvent
Event details for list-scrolling-related events.
Properties
readonly defaultPrevented
boolean
Set to true when the default handling was prevented
readonly first
number
Index of the first visible item.
readonly last
number
Index of the last visible item.
readonly middle
number
Index of the middle visible item.
readonly target
EventTarget or undefined
Target of the event
readonly type
string
Type of the event
Interface: PageScrollEvent
Event details for page-scrolling-related events. All three properties are expressed in the same arbitrary measurement unit (which may or may not be pixels).
Properties
readonly defaultPrevented
boolean
Set to true when the default handling was prevented
readonly pageSize
number
Size of a page, in an arbitrary measurement unit.
readonly position
number
Current scroll position, in an arbitrary measurement unit.
readonly target
EventTarget or undefined
Target of the event
readonly type
string
Type of the event
readonly viewSize
number
Total view size (all pages combined), in an arbitrary measurement unit.
Interface: AnimationEvent
Event details for animation-related events.
Properties
readonly defaultPrevented
boolean
Set to true when the default handling was prevented
readonly elapsedTime
number
The amount of time the animation has been running, in seconds, as of the time the event fired.
readonly target
EventTarget or undefined
Target of the event
readonly type
string
Type of the event
Interface: KeyboardEvent
Event details for keyboard-related events.
Properties
readonly defaultPrevented
boolean
Set to true when the default handling was prevented
readonly key
string
Name of the key or button.
readonly target
EventTarget or undefined
Target of the event
readonly type
string
Type of the event
Interface: MouseEvent
Event details for pointer-related events, such as a touch screen event.
Properties
readonly defaultPrevented
boolean
Set to true when the default handling was prevented
readonly screenX
number
X coordinate of the pointer when the event fired.
readonly screenY
number
Y coordinate of the pointer when the event fired.
readonly target
EventTarget or undefined
Target of the event
readonly type
string
Type of the event
Interface: ActivateEvent
Event details for user actions, such as a button click or key press.
Properties
readonly command
"back" or "exit" or "home" or "ok" or "select"
Name of the command associated with the event.
readonly defaultPrevented
boolean
Set to true when the default handling was prevented
readonly screenX
number or undefined
X coordinate of the pointer when the event fired.
readonly screenY
number or undefined
Y coordinate of the pointer when the event fired.
readonly target
EventTarget or undefined
Target of the event
readonly type
string
Type of the event
