Expand all

abstract ve.ui.Surface

Extends

Constructor

new ve.ui.Surface(target, dataOrDocOrSurface, [config])abstract #

A surface is a top-level object which contains both a surface model and a surface view.

Parameters:

Name Type Attributes Description
target ve.init.Target

Target the surface belongs to
dataOrDocOrSurface HTMLDocument | Array | ve.dm.ElementLinearData | ve.dm.Document | ve.dm.Surface

Document data, document model, or surface model to edit
config Object optional

Configuration options

Properties:
Name Type Attributes Default Description
attachedRoot ve.dm.BranchNode optional

Node to surface, if ve.dm.Document passed in
mode string

Editing mode, either "visual" or "source"
$scrollContainer jQuery optional

The scroll container of the surface
$scrollListener jQuery optional

The scroll listener of the surface
$overlayContainer jQuery optional

Clipping container for local overlays, defaults to surface view
overlayPadding number optional

Padding beween local overlays and clipping container
commandRegistry ve.ui.CommandRegistry optional

Command registry to use
sequenceRegistry ve.ui.SequenceRegistry optional

Sequence registry to use
dataTransferHandlerFactory ve.ui.DataTransferHandlerFactory optional

Data transfer handler factory to use
includeCommands Array.<string> | null optional

List of commands to include, null for all registered commands
excludeCommands Array.<string> optional

List of commands to exclude
importRules Object optional
 {}

Import rules
multiline boolean optional
 true

Multi-line surface
placeholder string optional

Placeholder text to display when the surface is empty
readOnly string optional
 false

Surface is read-only
nullSelectionOnBlur string optional
 true

Surface selection is set to null on blur
inDialog string optional
 ''

The name of the dialog this surface is in
inTargetWidget boolean optional
 false

The surface is in a target widget
Source:
A surface is a top-level object which contains both a surface model and a surface view.

Methods

adjustVisiblePadding() #

Adjust visible padding on the surface to allow the whole document to be scrolled to.

Source:

Adjust visible padding on the surface to allow the whole document to be scrolled to.

createContext(config) → {ve.ui.LinearContext} #

Create a context.

Parameters:

Name Type Description
config Object

Configuration options
Source:

Returns:

Type
ve.ui.LinearContext
Create a context.

createDialogWindowManager() → {ve.ui.WindowManager} #

Create a dialog window manager.

Source:

Returns:

Dialog window manager

Type
ve.ui.WindowManager
Create a dialog window manager.

createModel(doc, [attachedRoot]) → {ve.dm.Surface} #

Create a surface model

Parameters:

Name Type Attributes Description
doc ve.dm.Document

Document model
attachedRoot ve.dm.BranchNode optional

Node to surface
Source:

Returns:

Surface model

Type
ve.dm.Surface
Create a surface model

createProgress(progressCompletePromise, label, nonCancellable) → {jQuery.Promise} #

Create a progress bar in the progress dialog

Parameters:

Name Type Description
progressCompletePromise jQuery.Promise

Promise which resolves when the progress action is complete
label jQuery | string | function

Progress bar label
nonCancellable boolean

Progress item can't be cancelled
Source:

Returns:

Promise which resolves with a progress bar widget and fails if cancelled

Type
jQuery.Promise
Create a progress bar in the progress dialog

createView(model) → {ve.ce.Surface} #

Create a surface view

Parameters:

Name Type Description
model ve.dm.Surface

Surface model
Source:

Returns:

Surface view

Type
ve.ce.Surface
Create a surface view

destroy() → {ve.ui.Surface}chainable #

Destroy the surface, releasing all memory and removing all DOM elements.

Source:

Returns:

Type
ve.ui.Surface

Fires:

Destroy the surface, releasing all memory and removing all DOM elements.

execute(triggerOrAction, [method], […args]) → {boolean} #

Execute an action or command

This is a compatability wrapper for executeCommandWithSource.

Parameters:

Name Type Attributes Description
triggerOrAction ve.ui.Trigger | string

Trigger or symbolic name of action
method string optional

Action method name
args any optional
repeatable

Additional arguments for action
Source:

Returns:

Action or command was executed

Type
boolean

Execute an action or command

This is a compatability wrapper for executeCommandWithSource.

executeCommand(commandName) → {boolean} #

Execute a command by name

Parameters:

Name Type Description
commandName string

Command name
Source:

Returns:

The command was executed

Type
boolean
Execute a command by name

executeWithSource(triggerOrAction, [method], [source], […args]) → {boolean} #

Execute an action or command

Parameters:

Name Type Attributes Description
triggerOrAction ve.ui.Trigger | string

Trigger or symbolic name of action
method string optional

Action method name
source string optional

Action source, for logging
args any optional
repeatable

Additional arguments for action
Source:

Returns:

Action or command was executed

Type
boolean
Execute an action or command

focus() #

Give focus to the surface

Source:
Give focus to the surface

getBoundingClientRect() → {Object|null} #

Get the bounding rectangle of the surface, relative to the viewport.

Source:

Returns:

Object with top, bottom, left, right, width and height properties. Null if the surface is not attached.

Type
Object | null
Get the bounding rectangle of the surface, relative to the viewport.

getCommands() → {Array.<string>} #

Get list of commands available on this surface.

Source:

Returns:

Commands

Type
Array.<string>
Get list of commands available on this surface.

getContext() → {ve.ui.LinearContext} #

Get the context menu.

Source:

Returns:

Context user interface

Type
ve.ui.LinearContext
Get the context menu.

getDialogs() → {ve.ui.WindowManager} #

Get dialogs window set.

Source:

Returns:

Dialogs window set

Type
ve.ui.WindowManager
Get dialogs window set.

getDir() → {string} #

Surface 'dir' property (GUI/User-Level Direction)

Source:

Returns:

'ltr' or 'rtl'

Type
string
Surface 'dir' property (GUI/User-Level Direction)

getDom() → {HTMLDocument|string} #

Get the DOM representation of the surface's current state.

Source:

Returns:

HTML document (visual mode) or text (source mode)

Type
HTMLDocument | string
Get the DOM representation of the surface's current state.

getGlobalOverlay() → {ve.ui.Overlay} #

Get the global overlay.

Global overlays are attached to the top-most frame.

Source:

Returns:

Global overlay

Type
ve.ui.Overlay
Get the global overlay.

getHtml() → {string} #

Get the HTML representation of the surface's current state.

Source:

Returns:

HTML

Type
string
Get the HTML representation of the surface's current state.

getImportRules() → {Object} #

Get sanitization rules for rich paste

Source:

Returns:

Import rules

Type
Object
Get sanitization rules for rich paste

getInDialog() → {string} #

Get the name of the dialog this surface is in

Source:

Returns:

The name of the dialog this surface is in

Type
string
Get the name of the dialog this surface is in

getLocalOverlay() → {ve.ui.Overlay} #

Get the local overlay.

Local overlays are attached to the same frame as the surface.

Source:

Returns:

Local overlay

Type
ve.ui.Overlay
Get the local overlay.

getMode() → {string} #

Get the surface's editing mode

Source:

Returns:

Editing mode

Type
string
Get the surface's editing mode

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

Get the surface model.

Source:

Returns:

Surface model

Type
ve.dm.Surface
Get the surface model.

getPadding() → {ve.ui.Surface.Padding} #

Get the current content area padding

Padding in this context means areas of the surface which are rendered but are obsured by some other UI element, e.g. a floating toolbar (but not a static toolbar).

This can be used when deciding how to position other floating UI elements, e.g. to avoid rendering a context menu under a floating toolbar.

Source:

Returns:

Type
ve.ui.Surface.Padding

Get the current content area padding

Padding in this context means areas of the surface which are rendered but are obsured by some other UI element, e.g.

getTarget() → {ve.init.Target} #

Get the target the surface belongs to

Source:

Returns:

Type
ve.init.Target
Get the target the surface belongs to

getToolbarDialogs([position]) → {ve.ui.WindowManager} #

Get toolbar dialogs window set.

Parameters:

Name Type Attributes Default Description
position string optional
 'side'

Get the toolbar dialogs window set for a specific position
Source:

Returns:

Toolbar dialogs window set

Type
ve.ui.WindowManager
Get toolbar dialogs window set.

getView() → {ve.ce.Surface} #

Get the surface view.

Source:

Returns:

Surface view

Type
ve.ce.Surface
Get the surface view.

getViewportDimensions() → {Object|null} #

Get vertical measurements of the visible area of the surface viewport

Source:

Returns:

Object with top, left, bottom, and height properties. Null if the surface is not attached.

Type
Object | null
Get vertical measurements of the visible area of the surface viewport

initialize() → {ve.ui.Surface}chainable #

Initialize surface.

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

Source:

Returns:

Type
ve.ui.Surface

Fires:

Initialize surface.

isMultiline() → {boolean} #

Check if the surface is multi-line

Source:

Returns:

Surface is multi-line

Type
boolean
Check if the surface is multi-line

isReadOnly() → {boolean} #

Check if the surface is read-only

Source:

Returns:

Type
boolean
Check if the surface is read-only

onContextResize() #

Handle resize events from the context

Source:
Handle resize events from the context

onDocumentTransact(Transaction) #

Handle transact events from the document model

Parameters:

Name Type Description
Transaction ve.dm.Transaction
Source:
Handle transact events from the document model

onModelBlur() #

Handle surface model blur events

Source:
Handle surface model blur events

onModelFocus() #

Handle surface model focus events

Source:
Handle surface model focus events

onModelSelect() #

Handle select events from the model

Source:
Handle select events from the model

onViewActivation() #

Handle surface view activation events

Source:
Handle surface view activation events

onViewPosition([wasSynchronizing]) #

Handle position events from the view

Parameters:

Name Type Attributes Default Description
wasSynchronizing boolean optional
 false
Source:
Handle position events from the view

scrollSelectionIntoView([selectionModel], [scrollConfig]) #

Scroll the selection into view

Called in response to selection events.

This is done for all selections, even native ones, to account for the extra padding of the floating toolbar.

Parameters:

Name Type Attributes Description
selectionModel ve.dm.Selection optional

Optional selection model, defaults to current selection
scrollConfig Object optional

Scroll config options, passed to ve.scrollIntoView
Source:

Fires:

Scroll the selection into view

Called in response to selection events.

setDisabled() #

Source:

setPadding(padding) #

Set content area padding.

When UI components obscure the surface (e.g. the toolbar), set the appropriate amount of padding here so that scroll-into-view calculations can be adjusted.

Parameters:

Name Type Description
padding ve.ui.Surface.Padding

Padding object. Omit properties to leave unchanged.
Source:
Set content area padding.

setPlaceholder([placeholder]) #

Set placeholder text

Parameters:

Name Type Attributes Description
placeholder string optional

Placeholder text, clears placeholder if not set
Source:
Set placeholder text

setReadOnly(readOnly) #

Set the read-only state of the surface

Parameters:

Name Type Description
readOnly boolean

Make surface read-only
Source:

Fires:

Set the read-only state of the surface

setupDebugBar() #

Set up the debug bar and insert it into the DOM.

Source:
Set up the debug bar and insert it into the DOM.

updatePlaceholder() #

Update placeholder rendering

Source:
Update placeholder rendering

Type Definitions

Padding #

Type:

Properties:

Name Type Attributes Description
top number optional

Top padding
right number optional

Right padding
bottom number optional

Bottom padding
left number optional

Left padding
Source:

Events

cancel() #

The surface has been cancelled by user action, e.g. Escape

Source:
The surface has been cancelled by user action, e.g.

destroy() #

When a surface is destroyed.

Source:
When a surface is destroyed.

readOnly(readOnly) #

The surface read-only state has changed

Parameters:

Name Type Description
readOnly boolean

The surface is read-only
Source:
The surface read-only state has changed

ready() #

When a surface has been initialized

Source:
When a surface has been initialized

scroll() #

The surface was scrolled programmatically as a result of a native selection change

Source:

The surface was scrolled programmatically as a result of a native selection change

submit() #

The surface has been submitted by user action, e.g. Ctrl+Enter

Source:
The surface has been submitted by user action, e.g.