Expand all

ve.ce.Surface

Extends

Constructor

new ve.ce.Surface(model, ui, [config]) #

ContentEditable surface.

Parameters:

Name Type Attributes Description
model ve.dm.Surface

Surface model to observe
ui ve.ui.Surface

Surface user interface
config Object optional

Configuration options
Mixes in:
Source:
ContentEditable surface.

Properties

cursorHolderTemplatestatic #

Cursor holder template

Properties:

Type Description
HTMLElement
Source:
Cursor holder template

inputTypeCommands :Object.<string, (string|null)>static #

Values of InputEvent.inputType which map to a command

Currently these are triggered when the user selects undo/redo from the context menu in Chrome, or uses the selection formatting tools on iOS.

See https://w3c.github.io/input-events/

Values of null will perform no action and preventDefault.

Type:

  • Object.<string, (string|null)>
Source:

Values of InputEvent.inputType which map to a command

Currently these are triggered when the user selects undo/redo from the context menu in Chrome, or uses the selection formatting tools on iOS.

unsafeAttributes :Array.<string>static #

Attributes considered 'unsafe' for copy/paste

These attributes may be dropped by the browser during copy/paste, so any element containing these attributes will have them JSON encoded into data-ve-attributes on copy.

Type:

Source:

Attributes considered 'unsafe' for copy/paste

These attributes may be dropped by the browser during copy/paste, so any element containing these attributes will have them JSON encoded into data-ve-attributes on copy.

Methods

activate() #

Reactivate the surface and restore the native selection

Source:

Fires:

Reactivate the surface and restore the native selection

afterDocumentKeyDown(e) #

Deferred until after document key down event

Parameters:

Name Type Description
e jQuery.Event

keydown event
Source:
Deferred until after document key down event

afterDocumentMouseDown(e, selectionBefore) #

Deferred until after document mouse down

Parameters:

Name Type Description
e jQuery.Event

Mouse down event
selectionBefore ve.ce.Selection

Selection before the mouse event
Source:
Deferred until after document mouse down

afterDocumentMouseUp(e, selectionBefore) #

Deferred until after document mouse up

Parameters:

Name Type Description
e jQuery.Event

Mouse up event
selectionBefore ve.ce.Selection

Selection before the mouse event
Source:
Deferred until after document mouse up

afterMutations(mutationRecords) #

Handler for mutation observer

Identifies deleted DOM nodes, and finds and deletes corresponding model structural nodes. Mutation observers run asynchronously (on the microtask queue) so the current document state may differ from when the mutations happened. Therefore this handler rechecks node attachment, document ranges etc.

Parameters:

Name Type Description
mutationRecords Array.<MutationRecord>

Records of the mutations observed
Source:

Handler for mutation observer

Identifies deleted DOM nodes, and finds and deletes corresponding model structural nodes.

afterPaste(e) → {jQuery.Promise} #

Handle post-paste events.

Parameters:

Name Type Description
e jQuery.Event

Paste event
Source:

Returns:

Promise which resolves when the content has been pasted

Type
jQuery.Promise
Handle post-paste events.

afterPasteAddToFragmentFromExternal(clipboardKey, $clipboardHtml, fragment, targetFragment, [isMultiline], [forceClipboardData]) → {jQuery.Promise} #

After paste handler for pastes from the another document

Parameters:

Name Type Attributes Description
clipboardKey string | undefined

Clipboard key for pasted data
$clipboardHtml jQuery | undefined

Clipboard HTML, if used to find the key
fragment ve.dm.SurfaceFragment

Current fragment
targetFragment ve.dm.SurfaceFragment

Fragment to insert into
isMultiline boolean optional

Pasting to a multiline context
forceClipboardData boolean optional

Ignore the paste target, and use only clipboard html
Source:

Returns:

Promise which resolves when the content has been inserted

Type
jQuery.Promise
After paste handler for pastes from the another document

afterPasteAddToFragmentFromInternal(slice, fragment, targetFragment, isMultiline) → {jQuery.Promise} #

After paste handler for pastes from the same document

Parameters:

Name Type Description
slice ve.dm.DocumentSlice

Slice of document to paste
fragment ve.dm.SurfaceFragment

Current fragment
targetFragment ve.dm.SurfaceFragment

Fragment to insert into
isMultiline boolean

Pasting to a multiline context
Source:

Returns:

Promise which resolves when the content has been inserted

Type
jQuery.Promise
After paste handler for pastes from the same document

afterPasteExtractClipboardData() → {ve.ce.ClipboardData} #

Extract the clipboard key and other relevant data from beforePasteData / the paste target

Source:

Returns:

Data

Type
ve.ce.ClipboardData
Extract the clipboard key and other relevant data from beforePasteData / the paste target

afterPasteFromExternalContextRange(pastedDocumentModel, isMultiline, forceClipboardData) → {ve.Range|boolean} #

Helper to work out the context range for an external paste

Parameters:

Name Type Description
pastedDocumentModel ve.dm.Document

Model for pasted data
isMultiline boolean

Whether pasting to a multiline context
forceClipboardData boolean

Whether the current attempted paste is the result of forcing use of clipboard data
Source:

Returns:

Context range, or false if data appeared corrupted

Type
ve.Range | boolean
Helper to work out the context range for an external paste

afterPasteImportRules(isMultiline) → {Object.<string, Object>} #

Helper to build import rules for pasted data

Parameters:

Name Type Description
isMultiline boolean

Get rules for a multiline context
Source:

Returns:

Import rules

Type
Object.<string, Object>
Helper to build import rules for pasted data

afterPasteInsertExternalData(targetFragment, pastedDocumentModel, contextRange) → {jQuery.Promise} #

Insert some pasted data from an external source

Parameters:

Name Type Description
targetFragment ve.dm.SurfaceFragment

Fragment to insert into
pastedDocumentModel ve.dm.Document

Model generated from pasted data
contextRange ve.Range

Range of data in generated model to consider
Source:

Returns:

Promise which resolves when the content has been inserted

Type
jQuery.Promise
Insert some pasted data from an external source

afterPasteInsertInternalData(targetFragment, data) → {jQuery.Promise} #

Insert some pasted data from an internal source

Parameters:

Name Type Description
targetFragment ve.dm.SurfaceFragment

Fragment to insert into
data Array

Data to insert
Source:

Returns:

Promise which resolves when the content has been inserted

Type
jQuery.Promise
Insert some pasted data from an internal source

afterPasteSanitize(linearData, isMultiline, isExternal) #

LinearData sanitize helper, for pasted data

Parameters:

Name Type Description
linearData ve.dm.LinearData

Data to sanitize
isMultiline boolean

Sanitize for a multiline context
isExternal boolean

Treat as external content
Source:
LinearData sanitize helper, for pasted data

afterPasteSanitizeExternal($element) #

Helper to clean up externally pasted HTML (via pasteTarget).

Parameters:

Name Type Description
$element jQuery

Root element containing pasted stuff to sanitize
Source:
Helper to clean up externally pasted HTML (via pasteTarget).

afterRenderLock(callback) #

Escape the current render lock

Parameters:

Name Type Description
callback function

Function to run after render lock
Source:
Escape the current render lock

annotationsAtFocus([filter]) → {Array.<ve.ce.Annotation>} #

Get the annotation views containing the cursor focus

Parameters:

Name Type Attributes Description
filter function optional

Function to filter view nodes by.
Source:

Returns:

Annotation views

Type
Array.<ve.ce.Annotation>
Get the annotation views containing the cursor focus

annotationsAtModelSelection([filter], [offset]) → {Array.<ve.ce.Annotation>} #

Get the annotation views at the current model selection

TODO: This doesn't work for annotations that span fewer than one character, as getNodeAndOffset will never return an offset inside that annotation.

Parameters:

Name Type Attributes Description
filter function optional

Function to filter view nodes by.
offset number optional

Model offset. Defaults to start of current selection.
Source:

Returns:

Annotation views

Type
Array.<ve.ce.Annotation>

Get the annotation views at the current model selection

TODO: This doesn't work for annotations that span fewer than one character, as getNodeAndOffset will never return an offset inside that annotation.

annotationsAtNode(node, [filter]) → {Array.<ve.ce.Annotation>} #

Get the annotation views containing the cursor focus

Only returns annotations which can be active.

Parameters:

Name Type Attributes Description
node Node

Node at which to search for annotations
filter function optional

Function to filter view nodes by. Takes one argument which is the view node and returns a boolean.
Source:

Returns:

Annotation views

Type
Array.<ve.ce.Annotation>

Get the annotation views containing the cursor focus

Only returns annotations which can be active.

appendHighlights($highlights, focused) #

Append passed highlights to highlight container.

Parameters:

Name Type Description
$highlights jQuery

Highlights to append
focused boolean

Highlights are currently focused
Source:
Append passed highlights to highlight container.

beforePaste(e) #

Handle pre-paste events.

Parameters:

Name Type Description
e jQuery.Event

Paste event
Source:
Handle pre-paste events.

blur() #

Blur the surface

Source:
Blur the surface

changeModel(transactions, selection) #

Change the model only, not the CE surface

This avoids event storms when the CE surface is already correct

Parameters:

Name Type Description
transactions ve.dm.Transaction | Array.<ve.dm.Transaction> | null

One or more transactions to process, or null to process none
selection ve.dm.Selection

New selection
Source:

Throws:

If calls to this method are nested

Type
Error

Change the model only, not the CE surface

This avoids event storms when the CE surface is already correct

cleanupUnicorns(fixupCursor) → {boolean} #

Check whether the DOM selection has moved out of the unicorned area (i.e. is not currently between two unicorns) and if so, set the model selection from the DOM selection, destroy the unicorns and return true. If there are no active unicorns, this function does nothing and returns false.

If the unicorns are destroyed as a consequence of the user moving the cursor across a unicorn with the left/rightarrow keys, the cursor will have to be moved again to produce the cursor movement the user expected. Set the fixupCursor parameter to true to enable this behavior.

Parameters:

Name Type Description
fixupCursor boolean

If destroying unicorns, fix up left/rightarrow cursor position
Source:

Returns:

Whether unicorns have been destroyed

Type
boolean
Check whether the DOM selection has moved out of the unicorned area (i.e.

clearKeyDownState() #

Clear a stored state snapshot from a key down event

Source:
Clear a stored state snapshot from a key down event

createSlug(element) #

Create a slug out of a DOM element

Parameters:

Name Type Description
element HTMLElement

Slug element
Source:

Fires:

Create a slug out of a DOM element

deactivate([showAsActivated], [noSelectionChange], [hideSelection]) #

Deactivate the surface, stopping the surface observer and replacing the native range with a fake rendered one.

Used by dialogs so they can take focus without losing the original document selection.

Parameters:

Name Type Attributes Default Description
showAsActivated boolean optional
 true

Surface should still show as activated
noSelectionChange boolean optional

Don't change the native selection.
hideSelection boolean optional

Completely hide the selection
Source:

Fires:

Deactivate the surface, stopping the surface observer and replacing the native range with a fake rendered one.

decRenderLock() #

Remove a single render lock

Source:
Remove a single render lock

destroy() #

Destroy the surface, removing all DOM elements.

Source:
Destroy the surface, removing all DOM elements.

drawSelections(name, selections, [options]) #

Draw selections.

Parameters:

Name Type Attributes Description
name string

Unique name for the selection being drawn
selections Array.<ve.ce.Selection>

Selections to draw
options Object optional
Properties:
Name Type Description
color string

CSS color for the selection. Should usually be set in a stylesheet using the generated class name.
wrapperClass string

Additional CSS class string to add to the $selections wrapper. mapped to the same index.
label string

Label shown above each selection
Source:
Draw selections.

endRelocation() #

Complete a relocation action.

Source:

Fires:

Complete a relocation action.

executeSequences(sequences) #

Execute matched sequences

Parameters:

Name Type Description
sequences Array.<ve.ui.SequenceRegistry.Match>
Source:
Execute matched sequences

findAdjacentUneditableBranchNode(direction) → {Node|null} #

Find a ce=false branch node that a native cursor movement from here might skip

If a node is returned, then it might get skipped by a single native cursor movement in the specified direction from the closest branch node at the current cursor focus. However, if null is returned, then any single such movement is guaranteed not to skip an uneditable branch node.

Note we cannot predict precisely where/with which cursor key we might step out of the current closest branch node, because it is difficult to predict the behaviour of left/rightarrow (because of bidi visual cursoring) and up/downarrow (because of wrapping).

Parameters:

Name Type Description
direction number

1 for before the cursor, +1 for after
Source:

Returns:

Potentially cursor-adjacent uneditable branch node, or null

Type
Node | null

Find a ce=false branch node that a native cursor movement from here might skip

If a node is returned, then it might get skipped by a single native cursor movement in the specified direction from the closest branch node at the current cursor focus.

findAndExecuteDelayedSequences() #

Check if any of the previously delayed sequences no longer match with current offset, and therefore should be executed.

Source:

Check if any of the previously delayed sequences no longer match with current offset, and therefore should be executed.

findAndExecuteSequences([isPaste], [isDelete]) #

Find sequence matches at the current surface offset and execute them

Parameters:

Name Type Attributes Description
isPaste boolean optional

Whether this in the context of a paste
isDelete boolean optional

Whether this is after content being deleted
Source:
Find sequence matches at the current surface offset and execute them

findBlockSlug(range) → {HTMLElement|null} #

Find the block slug a given range is in.

Parameters:

Name Type Description
range ve.Range

Range to check
Source:

Returns:

Slug, or null if no slug or if range is not collapsed

Type
HTMLElement | null

Throws:

If range is inside internal list

Type
Error
Find the block slug a given range is in.

findFocusedNode(range) → {ve.ce.Node|null} #

Find the focusedNode at a specified range

Parameters:

Name Type Description
range ve.Range

Range to search at for a focusable node
Source:

Returns:

Focused node

Type
ve.ce.Node | null
Find the focusedNode at a specified range

findMatchingSequences([isPaste], [isDelete]) → {Array.<ve.ui.SequenceRegistry.Match>} #

Find sequence matches at the current surface offset

Parameters:

Name Type Attributes Description
isPaste boolean optional

Whether this in the context of a paste
isDelete boolean optional

Whether this is after content being deleted
Source:

Returns:

Type
Array.<ve.ui.SequenceRegistry.Match>
Find sequence matches at the current surface offset

fixShiftClickSelect(selectionBefore) #

Fix shift-click selection

Support: Chrome When shift-clicking on links Chrome tries to collapse the selection so check for this and fix manually.

This can occur on mousedown or, if the existing selection covers the link, on mouseup.

https://code.google.com/p/chromium/issues/detail?id=345745

Parameters:

Name Type Description
selectionBefore ve.ce.Selection

Selection before the mouse event
Source:

Fix shift-click selection

Support: Chrome When shift-clicking on links Chrome tries to collapse the selection so check for this and fix manually.

fixupChromiumNativeEnter() #

Remove unwanted DOM elements from the CE view, inserted by Chromium's native Enter handling. We preventDefault an Enter keydown event, but the native handling can still happen with some IME combinations, e.g. Gboard on Android Chromium in many languages including English when there is candidate text (T312558).

Source:
Remove unwanted DOM elements from the CE view, inserted by Chromium's native Enter handling.

fixupCursorPosition(direction, extend) #

Move cursor if it is between annotation nails

Parameters:

Name Type Description
direction number

Direction of travel, 1=forwards, -1=backwards, 0=unknown
extend boolean

Whether the anchor should stay where it is

TODO: Improve name
Source:
Move cursor if it is between annotation nails

focus() #

Give focus to the surface, reapplying the model selection, or selecting the first visible offset if the model selection is null.

This is used when switching between surfaces, e.g. when closing a dialog window. Calling this function will also reapply the selection, even if the surface is already focused.

Source:

Give focus to the surface, reapplying the model selection, or selecting the first visible offset if the model selection is null.

forceShowModelSelection() → {boolean} #

Apply a DM selection to the DOM, even if the old DOM selection is different but DM-equivalent

Source:

Returns:

Whether the selection actually changed

Type
boolean
Apply a DM selection to the DOM, even if the old DOM selection is different but DM-equivalent

getActiveNode() → {ve.ce.Node|null} #

Get the active node

Source:

Returns:

Active node

Type
ve.ce.Node | null
Get the active node

getBeforePasteAnnotationSet() → {ve.dm.AnnotationSet} #

Get the annotation set that was a the user focus before a paste started

Source:

Returns:

Annotation set

Type
ve.dm.AnnotationSet
Get the annotation set that was a the user focus before a paste started

getDocument() → {ve.ce.Document} #

Get the document view.

Source:

Returns:

Document view

Type
ve.ce.Document
Get the document view.

getDrawnSelection(name, selection, [options]) → {jQuery} #

Get an already drawn selection from the cache

Parameters:

Name Type Attributes Description
name string

Name of selection group
selection ve.dm.Selection

Selection model
options Object optional

Selection options
Source:

Returns:

Drawn selection

Type
jQuery
Get an already drawn selection from the cache

getDrawnSelectionCacheKey(name, selection, [options]) → {string} #

Get a cache key for a drawn selection

Parameters:

Name Type Attributes Description
name string

Name of selection group
selection ve.dm.Selection

Selection model
options Object optional

Selection options
Source:

Returns:

Cache key

Type
string
Get a cache key for a drawn selection

getFocusedNode([range]) → {ve.ce.Node|null} #

Get the focused node (optionally at a specified range), or null if one is not present

Parameters:

Name Type Attributes Description
range ve.Range optional

Optional range to check for focused node, defaults to current selection's range
Source:

Returns:

Focused node

Type
ve.ce.Node | null
Get the focused node (optionally at a specified range), or null if one is not present

getFocusedNodeDirectionality() → {string} #

Get the directionality at the current focused node

Source:

Returns:

'ltr' or 'rtl'

Type
string
Get the directionality at the current focused node

getModel() → {ve.dm.Surface} #

Get the surface model.

Source:

Returns:

Surface model

Type
ve.dm.Surface
Get the surface model.

getNativeRange([range]) → {Range|null} #

Get a native range object for a specified ve.Range

Native ranges are only used by linear selections. They don't show whether the selection is backwards, so they should be used for measurement only.

Parameters:

Name Type Attributes Description
range ve.Range optional

Optional range to get the native range for, defaults to current selection's range
Source:

Returns:

Native range object, or null if there is no suitable selection

Type
Range | null

Get a native range object for a specified ve.Range

Native ranges are only used by linear selections.

getOffsetFromCoords(x, y) → {number} #

Get linear model offset from absolute coords

Parameters:

Name Type Description
x number

X offset
y number

Y offset
Source:

Returns:

Linear model offset, or -1 if coordinates are out of bounds

Type
number
Get linear model offset from absolute coords

getOffsetFromEventCoords(e) → {number} #

Get linear model offest from a mouse event

Parameters:

Name Type Description
e Event
Source:

Returns:

Linear model offset, or -1 if coordinates are out of bounds

Type
number
Get linear model offest from a mouse event

getRelativeSelectableContentOffset(startOffset, direction, [endOffset]) → {number} #

Place the selection at the next content offset which is selectable.

For the purposes of this method, offsets within ve.ce.ActiveNode's are not considered selectable when they are not active.

Parameters:

Name Type Attributes Description
startOffset number

Offset to start from
direction number

Search direction, -1 for left and 1 for right
endOffset number optional

End offset to stop searching at
Source:

Returns:

Content offset, or -1 of not found

Type
number
Place the selection at the next content offset which is selectable.

getSelectedContentBranchNode() → {ve.ce.ContentBranchNode|null} #

Get the ContentBranchNode containing the selection focus, if any

Source:

Returns:

ContentBranchNode containing selection focus, or null

Type
ve.ce.ContentBranchNode | null
Get the ContentBranchNode containing the selection focus, if any

getSelectedModels([all]) → {Array.<ve.dm.Model>} #

Get list of selected nodes and annotations.

Exclude active annotations unless the CE focus is inside a link

Parameters:

Name Type Attributes Description
all boolean optional

Include nodes and annotations which only cover some of the fragment
Source:

Returns:

Selected models

Type
Array.<ve.dm.Model>
Get list of selected nodes and annotations.

getSelection([selection]) → {ve.ce.Selection} #

Get selection view object

Parameters:

Name Type Attributes Description
selection ve.dm.Selection optional

Optional selection model, defaults to current selection
Source:

Returns:

Selection view

Type
ve.ce.Selection
Get selection view object

getSelectionDirectionality() → {string} #

Get block directionality at selection

Source:

Returns:

'rtl' or 'ltr'

Type
string
Get block directionality at selection

getSelectionState(range) → {ve.SelectionState} #

Get a SelectionState corresponding to a ve.Range.

If either endpoint of the ve.Range is not a cursor offset, adjust the SelectionState endpoints to be at cursor offsets. For a collapsed selection, the adjustment preserves collapsedness; for a non-collapsed selection, the adjustment is in the direction that grows the selection (thereby avoiding collapsing or reversing the selection).

Parameters:

Name Type Description
range ve.Range | null

Range to get selection for
Source:

Returns:

The selection

Type
ve.SelectionState
Get a SelectionState corresponding to a ve.Range.

getSurface() → {ve.ui.Surface} #

Get the top-level surface.

Source:

Returns:

Type
ve.ui.Surface
Get the top-level surface.

getViewportRange([covering], [padding]) → {ve.Range|null} #

Get an approximate range covering data visible in the viewport

It is assumed that vertical offset increases as you progress through the DM. Items with custom positioning may throw off results given by this method, so it should only be treated as an approximation.

If the document doesn't contain any content offsets (e.g. it only contains a transclusion), the returned range will cover the entire document. If the single element is particularly large this might be very distinct from the visible content.

Parameters:

Name Type Attributes Default Description
covering boolean optional

Get a range which fully covers the viewport, otherwise get a range which is full contained within the viewport.
padding number optional
 0

Increase computed size of viewport by this amount at the top and bottom
Source:

Returns:

Range covering data visible in the viewport, null if the surface is not attached

Type
ve.Range | null

Get an approximate range covering data visible in the viewport

It is assumed that vertical offset increases as you progress through the DM.

handleDataTransfer(dataTransfer, isPaste, [targetFragment]) → {boolean} #

Handle the insertion of a data transfer object

Parameters:

Name Type Attributes Description
dataTransfer DataTransfer

Data transfer
isPaste boolean

Handlers being used for paste
targetFragment ve.dm.SurfaceFragment optional

Fragment to insert data items at, defaults to current selection
Source:

Returns:

One more items was handled

Type
boolean
Handle the insertion of a data transfer object

handleDataTransferItems(items, isPaste, [targetFragment]) → {boolean} #

Handle the insertion of data transfer items

Parameters:

Name Type Attributes Description
items Array.<ve.ui.DataTransferItem>

Data transfer items
isPaste boolean

Handlers being used for paste
targetFragment ve.dm.SurfaceFragment optional

Fragment to insert data items at, defaults to current selection
Source:

Returns:

One more items was handled

Type
boolean
Handle the insertion of data transfer items

handleInsertion() #

Handle insertion of content.

Source:
Handle insertion of content.

handleObservedChanges(oldState, newState) #

Handle changes observed from the DOM

These are normally caused by the user interacting directly with the contenteditable.

Parameters:

Name Type Description
oldState ve.ce.RangeState | null

The prior range state, if any
newState ve.ce.RangeState

The changed range state
Source:

Handle changes observed from the DOM

These are normally caused by the user interacting directly with the contenteditable.

hasNativeCursorSelection() → {boolean} #

Check if the surface has a native cursor selection

On mobile platforms, this means it is likely the virtual keyboard is visible.

Source:

Returns:

Surface has a native cursor selection

Type
boolean

Check if the surface has a native cursor selection

On mobile platforms, this means it is likely the virtual keyboard is visible.

incRenderLock() #

Add a single render lock (to disable rendering)

Source:
Add a single render lock (to disable rendering)

initialize() #

Initialize surface.

This should be called after the surface has been attached to the DOM.

Source:

Fires:

Initialize surface.

isBlockedTrigger(trigger) → {boolean} #

Check if a trigger event is blocked from performing its default behaviour

If any of these triggers can't execute on the surface, (e.g. the underline command has been disabled), we should still preventDefault so ContentEditable native commands don't occur, leaving the view out of sync with the model.

Parameters:

Name Type Description
trigger ve.ui.Trigger

Trigger to check
Source:

Returns:

Trigger should preventDefault

Type
boolean

Check if a trigger event is blocked from performing its default behaviour

If any of these triggers can't execute on the surface, (e.g.

isDeactivated() → {boolean} #

Check if the surface is deactivated.

Source:

Returns:

Surface is deactivated

Type
boolean
Check if the surface is deactivated.

isFocused() → {boolean} #

Check if surface is focused.

Source:

Returns:

Surface is focused

Type
boolean
Check if surface is focused.

isReadOnly() → {boolean} #

Check if the surface is read-only

Source:

Returns:

Type
boolean
Check if the surface is read-only

isRenderingLocked() → {boolean} #

Check whether there are any render locks

Source:

Returns:

Render is locked

Type
boolean
Check whether there are any render locks

isShownAsDeactivated() → {boolean} #

Check if the surface is visibly deactivated.

Only true if the surface was decativated by the user in a way that is expected to change the rendering.

Source:

Returns:

Surface is visibly deactivated

Type
boolean
Check if the surface is visibly deactivated.

maybeSetBreakpoint() #

See if the just-entered content fits our criteria for setting a history breakpoint

Source:
See if the just-entered content fits our criteria for setting a history breakpoint

moveModelCursor(offset) #

Move the DM surface cursor

Parameters:

Name Type Description
offset number

Distance to move (negative = toward document start)
Source:
Move the DM surface cursor

onCopy(e, selection) #

Handle copy (including cut) and dragstart events.

Parameters:

Name Type Description
e jQuery.Event

Copy event
selection ve.dm.Selection

Optional selection to simulate a copy on
Source:
Handle copy (including cut) and dragstart events.

onCut(e) #

Handle cut events.

Parameters:

Name Type Description
e jQuery.Event

Cut event
Source:
Handle cut events.

onDocumentBeforeInput(e) #

Handle beforeinput events.

Parameters:

Name Type Description
e jQuery.Event

The input event
Source:
Handle beforeinput events.

onDocumentBlur() #

Handle document blur events.

This is triggered by a global focusin/focusout event noticing no selection on the document.

Source:

Fires:

Handle document blur events.

onDocumentCompositionStart(e) #

Handle compositionstart events. Note that their meaning varies between browser/OS/IME combinations

Parameters:

Name Type Description
e jQuery.Event

The compositionstart event
Source:
Handle compositionstart events.

onDocumentDragLeave(e) #

Handle document drag leave events.

Parameters:

Name Type Description
e jQuery.Event

Drag leave event
Source:
Handle document drag leave events.

onDocumentDragOver(e) #

Handle document drag over events.

Parameters:

Name Type Description
e jQuery.Event

Drag over event
Source:
Handle document drag over events.

onDocumentDragStart(e) #

Handle document drag start events.

Parameters:

Name Type Description
e jQuery.Event

Drag start event
Source:

Fires:

Handle document drag start events.

onDocumentDrop(e) #

Handle document drop events.

Limits native drag and drop behaviour.

Parameters:

Name Type Description
e jQuery.Event

Drop event
Source:

Fires:

Handle document drop events.

onDocumentFocus() #

Handle document focus events.

This is triggered by a global focusin/focusout event noticing a selection on the document.

Source:

Fires:

Handle document focus events.

onDocumentFocusInOut(e) #

Handler for focusin and focusout events. Filters events and debounces to #onFocusChange.

Parameters:

Name Type Description
e jQuery.Event

focusin/out event
Source:
Handler for focusin and focusout events.

onDocumentInput(e) #

Handle input events.

Parameters:

Name Type Description
e jQuery.Event

The input event
Source:
Handle input events.

onDocumentKeyDown(e) #

Handle document key down events.

Parameters:

Name Type Description
e jQuery.Event

Key down event
Source:
Handle document key down events.

onDocumentKeyPress(e) #

Handle document key press events.

Parameters:

Name Type Description
e jQuery.Event

Key press event
Source:
Handle document key press events.

onDocumentKeyUp(e) #

Handle document key up events.

Parameters:

Name Type Description
e jQuery.Event

Key up event
Source:

Fires:

Handle document key up events.

onDocumentMouseDown(e) #

Handle document mouse down events.

Parameters:

Name Type Description
e jQuery.Event

Mouse down event
Source:
Handle document mouse down events.

onDocumentMouseUp(e) #

Handle document mouse up events.

Parameters:

Name Type Description
e jQuery.Event

Mouse up event
Source:
Handle document mouse up events.

onDocumentSelectionChange(e) #

Handle document selection change events.

Parameters:

Name Type Description
e jQuery.Event

Selection change event
Source:
Handle document selection change events.

onFocusChange() #

Handle global focus change.

Source:
Handle global focus change.

onInsertionAnnotationsChange(insertionAnnotations) #

Handle insertionAnnotationsChange events on the surface model.

Parameters:

Name Type Description
insertionAnnotations ve.dm.AnnotationSet
Source:
Handle insertionAnnotationsChange events on the surface model.

onModelDocumentUpdate() #

Handle documentUpdate events on the surface model.

Source:

Fires:

Handle documentUpdate events on the surface model.

onModelSelect() #

Handle model select events.

Source:
See:
Handle model select events.

onPaste(e) → {boolean|undefined} #

Handle native paste event

Parameters:

Name Type Description
e jQuery.Event

Paste event
Source:

Returns:

False if the event is cancelled

Type
boolean | undefined
Handle native paste event

onPosition() #

Respond to a position event on this surface

Source:
Respond to a position event on this surface

onSynchronizerAuthorDisconnect(authorId) #

Called when the synchronizer receives a remote author disconnect

Parameters:

Name Type Description
authorId number

The author ID
Source:
Called when the synchronizer receives a remote author disconnect

onSynchronizerAuthorUpdate(authorId) #

Called when the synchronizer receives a remote author selection or name change

Parameters:

Name Type Description
authorId number

The author ID
Source:
Called when the synchronizer receives a remote author selection or name change

onSynchronizerPause() #

Handle pause events from the synchronizer

Drops the opacity of the surface to indicate that no updates are being received from other users.

Source:

Handle pause events from the synchronizer

Drops the opacity of the surface to indicate that no updates are being received from other users.

onSynchronizerWrongDoc() #

Called when the synchronizer reconnects and their is a server doc ID mismatch

Source:
Called when the synchronizer reconnects and their is a server doc ID mismatch

onWindowResize(e) #

Handle window resize event.

Parameters:

Name Type Description
e jQuery.Event

Window resize event
Source:

Fires:

Handle window resize event.

paintAuthor(authorId) #

Paint a remote author's current selection, as stored in the synchronizer

Parameters:

Name Type Description
authorId number

The author ID
Source:
Paint a remote author's current selection, as stored in the synchronizer

preparePasteTargetForCopy(force) #

Prepare the paste target for a copy event by selecting some text

Parameters:

Name Type Description
force boolean

Force a native selection, even on mobile (used for click-to-copy)
Source:
Prepare the paste target for a copy event by selecting some text

redrawSelections() #

Redraw selections

This is triggered by a surface 'position' event, which fires when the surface changes size, or when the document is modified. The drawnSelectionCache is cleared as these two things will cause any previously calculated rectangles to be incorrect.

Source:

Redraw selections

This is triggered by a surface 'position' event, which fires when the surface changes size, or when the document is modified.

removeCursorHolderAfter() #

Remove cursorHolderAfter, if it exists

Source:
Remove cursorHolderAfter, if it exists

removeCursorHolderBefore() #

Remove cursorHolderBefore, if it exists

Source:
Remove cursorHolderBefore, if it exists

removeCursorHolders() #

Remove cursor holders, if they exist

Source:
Remove cursor holders, if they exist

removeRangesAndBlur() #

Remove all native selection ranges, and blur any active element

This should hide all virtual keyboards when present.

Source:

Remove all native selection ranges, and blur any active element

This should hide all virtual keyboards when present.

renderSelectedContentBranchNode() → {boolean} #

Re-render the ContentBranchNode containing the selection focus, if any

Source:

Returns:

Whether a re-render actually happened

Type
boolean
Re-render the ContentBranchNode containing the selection focus, if any

restoreActiveNodeSelection() → {boolean} #

Restore the selection from the model if expands outside the active node

This is only useful if the DOM selection and the model selection are out of sync.

Source:

Returns:

Whether the selection was restored

Type
boolean

Restore the selection from the model if expands outside the active node

This is only useful if the DOM selection and the model selection are out of sync.

selectAll() #

Select all the contents within the current context

Source:
Select all the contents within the current context

selectAnnotation([filter]) #

Select the inner contents of the closest annotation

Parameters:

Name Type Attributes Description
filter function optional

Function to filter view nodes by.
Source:
Select the inner contents of the closest annotation

selectFirstSelectableContentOffset() #

Select the first content offset which is selectable.

See #selectRelativeSelectableContentOffset for the definition of selectable.

Source:
Select the first content offset which is selectable.

selectFirstVisibleStartContentOffset([fallbackToFirst]) #

Move the selection to the first visible "start content offset" in the viewport

Where "start content offset" is the first offset within a content branch node.

The following are used as fallbacks when such offsets can't be found:

  • The first visible content offset (at any position in the CBN)
  • The first selectable content offset in the doc (if fallbackToFirst is set)

Parameters:

Name Type Attributes Description
fallbackToFirst boolean optional

Whether to select the first content offset if a visible offset can't be found
Source:

Move the selection to the first visible "start content offset" in the viewport

Where "start content offset" is the first offset within a content branch node.

selectLastSelectableContentOffset() #

Select the last content offset which is selectable.

See #selectRelativeSelectableContentOffset for the definition of selectable.

Source:
Select the last content offset which is selectable.

selectNodeContents(node, [collapse]) → {boolean} #

Update the selection to contain the contents of a node

Parameters:

Name Type Attributes Description
node HTMLElement
collapse string optional

Collaspse to 'start' or 'end'
Source:

Returns:

Whether the selection changed

Type
boolean
Update the selection to contain the contents of a node

selectRelativeSelectableContentOffset(startOffset, direction, [endOffset]) #

Select the offset returned by #getRelativeSelectableContentOffset

Parameters:

Name Type Attributes Description
startOffset number
direction number
endOffset number optional
Source:
Select the offset returned by #getRelativeSelectableContentOffset

selectionSplitsNailedAnnotation() → {boolean} #

Tests whether the selection covers part but not all of a nailed annotation

Source:

Returns:

True if a nailed annotation is split either at the focus or at the anchor (or both)

Type
boolean
Tests whether the selection covers part but not all of a nailed annotation

setActiveNode(node) #

Set the active node

Parameters:

Name Type Description
node ve.ce.Node | null

Active node
Source:
Set the active node

setContentBranchNodeChanged() #

Inform the surface that one of its ContentBranchNodes' rendering has changed.

Source:
See:
Inform the surface that one of its ContentBranchNodes' rendering has changed.

setDragging(dragging) #

Set a flag when the user is dragging a selection

Parameters:

Name Type Description
dragging boolean

Dragging (mouse is down)
Source:
Set a flag when the user is dragging a selection

setNotUnicorning(node) #

Release the current unicorn held by a given node, without rerendering

If the node doesn't hold the current unicorn, nothing happens.

Parameters:

Name Type Description
node ve.ce.ContentBranchNode

The node releasing the unicorn
Source:

Release the current unicorn held by a given node, without rerendering

If the node doesn't hold the current unicorn, nothing happens.

setNotUnicorningAll(node) #

Ensure that no node has a unicorn.

If the given node currently has the unicorn, it will be released and no rerender will happen. If another node has the unicorn, that node will be rerendered to get rid of the unicorn.

Parameters:

Name Type Description
node ve.ce.ContentBranchNode

The node releasing the unicorn
Source:
Ensure that no node has a unicorn.

setReadOnly(readOnly) #

Set the read-only state of the surface

Parameters:

Name Type Description
readOnly boolean

Make surface read-only
Source:
Set the read-only state of the surface

setReviewMode(reviewMode, highlightNodes) #

Set the review mode state of the surface

In review mode the surface can't be interacted with by the user (unlike the read-only mode where the user can select text and inspect nodes).

Review mode does not restrict changes to the model by other means, so programmatic changes can still be made from other tools.

Parameters:

Name Type Description
reviewMode boolean

Set surface to review mode
highlightNodes Array.<ve.ce.Node>

Nodes to highlight while in review mode
Source:

Set the review mode state of the surface

In review mode the surface can't be interacted with by the user (unlike the read-only mode where the user can select text and inspect nodes).

setUnicorning(node) #

Set the node that has the current unicorn.

If another node currently has a unicorn, it will be rerendered, which will cause it to release its unicorn.

Parameters:

Name Type Description
node ve.ce.ContentBranchNode | null

The node claiming the unicorn, null to release (by rerendering) without claiming
Source:
Set the node that has the current unicorn.

showModelSelection([force]) → {boolean} #

Apply a DM selection to the DOM

Parameters:

Name Type Attributes Description
force boolean optional

Replace the DOM selection if it is different but DM-equivalent
Source:

Returns:

Whether the selection actually changed

Type
boolean
Apply a DM selection to the DOM

showSelectionState(selection) → {boolean} #

Apply a selection state to the DOM

If the browser cannot show a backward selection, fall back to the forward equivalent

Parameters:

Name Type Description
selection ve.SelectionState

The selection state to show
Source:

Returns:

Whether the selection actually changed

Type
boolean

Apply a selection state to the DOM

If the browser cannot show a backward selection, fall back to the forward equivalent

startRelocation() #

Start a relocation action.

Source:

Fires:

Start a relocation action.

storeDrawnSelection($selection, name, selection, [options]) → {string} #

Store an already drawn selection in the cache

Parameters:

Name Type Attributes Description
$selection jQuery

Drawn selection
name string

Name of selection group
selection ve.dm.Selection

Selection model
options Object optional

Selection options
Source:

Returns:

Cache key

Type
string
Store an already drawn selection in the cache

storeKeyDownState(e) #

Store a state snapshot at a keydown event, to be used in an after-keydown handler

A ve.SelectionState object is stored, but only when the key event is a cursor key. (It would be misleading to save selection properties for key events where the DOM might get modified, because anchorNode/focusNode are live and mutable, and so the offsets may come to point confusingly to different places than they did when the selection was saved).

Parameters:

Name Type Description
e jQuery.Event | null

Key down event; must be active when this call is made
Source:

Store a state snapshot at a keydown event, to be used in an after-keydown handler

A ve.SelectionState object is stored, but only when the key event is a cursor key.

updateActiveAnnotations([fromModelOrNode]) #

Update the activeAnnotations property and apply CSS classes accordingly

An active annotation is one containing the DOM cursor, which may not be well defined at annotation boundaries, except for links which use nails.

Also the order of .activeAnnotations may not be well defined.

Parameters:

Name Type Attributes Description
fromModelOrNode boolean | Node optional

If true, gather annotations from the model, instead of the cusor focus point. If a Node is passed, gather annotations from that node.
Source:

Fires:

Update the activeAnnotations property and apply CSS classes accordingly

An active annotation is one containing the DOM cursor, which may not be well defined at annotation boundaries, except for links which use nails.

updateCursorHolderAfter() #

Insert cursor holder between selection focus and preceding ce=false node, if required as a cursor target

Source:
Insert cursor holder between selection focus and preceding ce=false node, if required as a cursor target

updateCursorHolderBefore() #

Insert cursor holder between selection focus and subsequent ce=false node, if required as a cursor target

Source:
Insert cursor holder between selection focus and subsequent ce=false node, if required as a cursor target

updateCursorHolders() #

Insert cursor holders, if they might be required as a cursor target

Source:
Insert cursor holders, if they might be required as a cursor target

updateDeactivatedSelection() #

Update the fake selection while the surface is deactivated.

While the surface is deactivated, all calls to showModelSelection will get redirected here.

Source:
Update the fake selection while the surface is deactivated.

getClipboardHash($elements, [beforePasteData]) → {string}static #

When pasting, browsers normalize HTML to varying degrees. This hash creates a comparable string for validating clipboard contents.

Parameters:

Name Type Attributes Description
$elements jQuery

Clipboard HTML
beforePasteData Object optional

Paste information, including leftText and rightText to strip
Source:

Returns:

Hash

Type
string
When pasting, browsers normalize HTML to varying degrees.

Events

activation() #

Surface activation state has changed (i.e. on activate or deactivate)

Source:
Surface activation state has changed (i.e.

blur() #

Note that it's possible for a focus event to occur immediately after a blur event, if the focus moves to or from a FocusableNode. In this case the surface doesn't lose focus conceptually, but a pair of blur-focus events is emitted anyway.

Source:

Note that it's possible for a focus event to occur immediately after a blur event, if the focus moves to or from a FocusableNode.

focus() #

Note that it's possible for a focus event to occur immediately after a blur event, if the focus moves to or from a FocusableNode. In this case the surface doesn't lose focus conceptually, but a pair of blur-focus events is emitted anyway.

Source:

Note that it's possible for a focus event to occur immediately after a blur event, if the focus moves to or from a FocusableNode.

keyup() #

Source:

position([wasSynchronizing]) #

When the surface or its contents changes position (only after initialize has already been called).

Parameters:

Name Type Attributes Description
wasSynchronizing boolean optional

The surface was positioned due to synchronization (ve.dm.SurfaceSynchronizer)
Source:

When the surface or its contents changes position (only after initialize has already been called).

relocationEnd() #

Source:

relocationStart() #

Source: