EditContext API

The Text Input Service and Text Edit Context are abstractions representing the common aspects of text input across many operating systems. An EditContext is a JavaScript reflection of the Text Edit Context. When changes are made to the Text Edit Context by the Text Input Service, those changes are reflected to the author asynchronously in the form of events which are dispatched against the active EditContext. When the author makes changes to the active EditContext, those changes will be reflected in the Text Edit Context during the next lifecycle update.

WebIDLpartial interface HTMLElement {
     attribute EditContext? editContext;
};

An HTMLElement has an internal slot [[EditContext]], which is a reference to an EditContext and is intially null.

editContext

The editContext getter steps are to return the value of this's internal [[EditContext]] slot.

The editContext setter must follow these steps:

Input

editContext

Output

None

1. If this's local name is neither a valid shadow host name nor "canvas", then throw a "NotSupportedError" DOMException.
2. If editContext is not null, then:
   1. If editContext's associated element is equal to this, then terminate these steps.
   2. If editContext's associated element is not null, then throw a "NotSupportedError" DOMException.
3. Let oldEditContext be the value of this's internal [[EditContext]] slot.
4. If oldEditContext is not null and oldEditContext is this's node document's active EditContext, then:
   1. Run the steps to deactivate an EditContext with oldEditContext.
   2. If oldEditContext's associated element is not equal to this, then terminate these steps.
   3. If editContext is not null, editContext's associated element is not null and editContext's associated element is not equal to this, then throw a "NotSupportedError" DOMException.
5. If oldEditContext is not null, set oldEditContext's associated element to null.
6. If editContext is not null, then set editContext's associated element to this.
7. Set this's internal [[EditContext]] slot to be editContext.

WebIDLdictionary EditContextInit {
    DOMString text;
    unsigned long selectionStart;
    unsigned long selectionEnd;
};
[Exposed=Window]
interface EditContext : EventTarget {
    constructor(optional EditContextInit options = {});
    undefined updateText(unsigned long rangeStart, unsigned long rangeEnd,
        DOMString text);
    undefined updateSelection(unsigned long start, unsigned long end);
    undefined updateControlBounds(DOMRect controlBounds);
    undefined updateSelectionBounds(DOMRect selectionBounds);
    undefined updateCharacterBounds(unsigned long rangeStart, sequence<DOMRect> characterBounds);
    sequence<HTMLElement> attachedElements();
    readonly attribute DOMString text;
    readonly attribute unsigned long selectionStart;
    readonly attribute unsigned long selectionEnd;
    readonly attribute unsigned long characterBoundsRangeStart;
    sequence<DOMRect> characterBounds();
    attribute EventHandler ontextupdate;
    attribute EventHandler ontextformatupdate;
    attribute EventHandler oncharacterboundsupdate;
    attribute EventHandler oncompositionstart;
    attribute EventHandler oncompositionend;
};

text

The text getter steps are to return this's text.

selectionStart

The selectionStart getter steps are to return this's selection start.

selectionEnd

The selectionEnd getter steps are to return this's selection end.

characterBounds

The characterBounds getter steps are to return this's codepoint rects.

characterBoundsRangeStart

The characterBoundsRangeStart getter steps are to return this's codepoint rects start index.

updateText() method

The method must follow these steps:

Input

rangeStart, an unsigned long

rangeEnd, an unsigned long

newText, a DOMString

Output

None

1. Replace the substring of text in the range of rangeStart and rangeEnd with newText
   Note

   It's permissible that rangeStart > rangeEnd. The substring between the indices should be replaced in the same way as when rangeStart <= rangeEnd.

updateSelection() method

The method must follow these steps:

Input

start, an unsigned long

end, an unsigned long

Output

None

1. set selection start to start
2. set selection end to end

updateSelectionBounds() method

The method must follow these steps:

Input

selectionBounds, a DOMRect

Output

None

1. set selection bounds to selectionBounds

updateControlBounds() method

The method must follow these steps:

Input

controlBounds, a DOMRect

Output

None

1. set control bounds to controlBounds

updateCharacterBounds() method

The method must follow these steps:

Input

rangeStart, an unsigned long

characterBounds, an array of DOMRect

Output

None

1. set codepoint rects start index to rangeStart.
2. set codepoint rects to characterBounds.

attachedElements() method

The method returns a list with one item which is the the EditContext's associated element, or an empty list if the EditContext's associated element is null.

Note

This method returns a list instead of a single element for forward compatibility if EditContext is ever granted the ability to have multiple associated elements.

ontextupdate

The event handler for TextUpdateEvent.

oncharacterboundsupdate

The event handler for CharacterBoundsUpdateEvent.

ontextformatupdate

The event handler for TextFormatUpdateEvent.

oncompositionstart

The event handler for the compositionstart event.

oncompositionend

The event handler for the compositionend event.

WebIDLdictionary TextUpdateEventInit : EventInit {
    unsigned long updateRangeStart;
    unsigned long updateRangeEnd;
    DOMString text;
    unsigned long selectionStart;
    unsigned long selectionEnd;
    unsigned long compositionStart;
    unsigned long compositionEnd;
};
[Exposed=Window]
interface TextUpdateEvent : Event {
    constructor(DOMString type, optional TextUpdateEventInit options = {});
    readonly attribute unsigned long updateRangeStart;
    readonly attribute unsigned long updateRangeEnd;
    readonly attribute DOMString text;
    readonly attribute unsigned long selectionStart;
    readonly attribute unsigned long selectionEnd;
};

updateRangeStart, of type unsigned long, readonly

The start position of the range that is to be replaced.

updateRangeEnd, of type unsigned long, readonly

The end position of the range that is to be replaced.

text, of type DOMString, readonly

The new string that is to replace the old string in the range.

selectionStart, of type unsigned long, readonly

The start position of the selection after the text replacement.

selectionEnd, of type unsigned long, readonly

The end position of the selection after the text replacement.

WebIDLenum UnderlineStyle { "none", "solid", "dotted", "dashed", "wavy" };
enum UnderlineThickness { "none", "thin", "thick" };
dictionary TextFormatInit {
    unsigned long rangeStart;
    unsigned long rangeEnd;
    UnderlineStyle underlineStyle;
    UnderlineThickness underlineThickness;
};
[Exposed=Window]
interface TextFormat {
    constructor(optional TextFormatInit options = {});
    readonly attribute unsigned long rangeStart;
    readonly attribute unsigned long rangeEnd;
    readonly attribute UnderlineStyle underlineStyle;
    readonly attribute UnderlineThickness underlineThickness;
};
dictionary TextFormatUpdateEventInit : EventInit {
    sequence<TextFormat> textFormats;
};
[Exposed=Window]
interface TextFormatUpdateEvent : Event {
    constructor(DOMString type, optional TextFormatUpdateEventInit options = {});
    sequence<TextFormat> getTextFormats();
};

rangeStart, of type unsigned long, readonly

An offset that respresents the position before the first codepoint that should be decorated.

rangeEnd, of type unsigned long, readonly

An offset that respresents the position after the last codepoint that should be decorated.

underlineStyle, of type UnderlineStyle, readonly

The preferred underline style of the decorated text range.

underlineThickness, of type UnderlineThickness, readonly

The preferred underline thickness of the decorated text range.

getTextFormats method

Returns this's text format list.

A TextFormatUpdateEvent has an associated text format list, a list of zero or more text formats.

WebIDLdictionary CharacterBoundsUpdateEventInit : EventInit {
    unsigned long rangeStart;
    unsigned long rangeEnd;
};
[Exposed=Window]
interface CharacterBoundsUpdateEvent : Event {
    constructor(DOMString type, optional CharacterBoundsUpdateEventInit options = {});
    readonly attribute unsigned long rangeStart;
    readonly attribute unsigned long rangeEnd;
};

rangeStart, of type unsigned long, readonly

The start position of the range where the character bounds are needed by Text Input Service

rangeEnd, of type unsigned long, readonly

The end position of the range where the character bounds are needed by Text Input Service