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.LinearData | 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 between 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
allowTabFocusChange boolean optional
 false

Allow changing focus from target surfaces with tab/shift+tab
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

Returns:

Type
ve.ui.LinearContext
Source:
Create a context.

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

Create a dialog window manager.

Returns:

Dialog window manager

Type
ve.ui.WindowManager
Source:
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

Returns:

Surface model

Type
ve.dm.Surface
Source:
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

Returns:

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

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

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

Create a sidebar window manager.

Returns:

Sidebar window manager

Type
ve.ui.WindowManager
Source:
Create a sidebar window manager.

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

Create a surface view

Parameters:

Name Type Description
model ve.dm.Surface

Surface model

Returns:

Surface view

Type
ve.ce.Surface
Source:
Create a surface view

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

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

Returns:

Type
ve.ui.Surface

Fires:

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

doesAllowTabFocusChange() → {boolean} #

Does the surface allow changing focus from target surfaces with tab/shift+tab

Returns:

Type
boolean
Source:
Does the surface allow changing focus from target surfaces with tab/shift+tab

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

Execute an action or command

This is a compatibility 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

Returns:

Action or command was executed

Type
boolean
Source:

Execute an action or command

This is a compatibility wrapper for executeCommandWithSource.

executeCommand(commandName) → {boolean} #

Execute a command by name

Parameters:

Name Type Description
commandName string

Command name

Returns:

The command was executed

Type
boolean
Source:
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

Returns:

Action or command was executed

Type
boolean
Source:
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.

Returns:

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

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

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

Get list of commands available on this surface.

Returns:

Commands

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

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

Get the context menu.

Returns:

Context user interface

Type
ve.ui.LinearContext
Source:
Get the context menu.

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

Get dialogs window set.

Returns:

Dialogs window set

Type
ve.ui.WindowManager
Source:
Get dialogs window set.

getDir() → {string} #

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

Returns:

'ltr' or 'rtl'

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

getDom() → {HTMLDocument|string} #

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

Returns:

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

Type
HTMLDocument | string
Source:
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.

Returns:

Global overlay

Type
ve.ui.Overlay
Source:
Get the global overlay.

getHtml() → {string} #

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

Returns:

HTML

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

getImportRules() → {Object} #

Get sanitization rules for rich paste

Returns:

Import rules

Type
Object
Source:
Get sanitization rules for rich paste

getInDialog() → {string} #

Get the name of the dialog this surface is in

Returns:

The name of the dialog this surface is in

Type
string
Source:
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.

Returns:

Local overlay

Type
ve.ui.Overlay
Source:
Get the local overlay.

getMode() → {string} #

Get the surface's editing mode

Returns:

Editing mode

Type
string
Source:
Get the surface's editing mode

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

Get the surface model.

Returns:

Surface model

Type
ve.dm.Surface
Source:
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 obscured 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.

Returns:

Type
ve.ui.Surface.Padding
Source:

Get the current content area padding

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

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

Get sidebar dialogs window set.

Returns:

Sidebar dialogs window set

Type
ve.ui.WindowManager
Source:
Get sidebar dialogs window set.

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

Get the target the surface belongs to

Returns:

Type
ve.init.Target
Source:
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

Returns:

Toolbar dialogs window set

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

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

Get the surface view.

Returns:

Surface view

Type
ve.ce.Surface
Source:
Get the surface view.

getViewportDimensions() → {Object|null} #

Get measurements of the visible area of the surface viewport

The bounding box returned is relative the viewport, e.g. a top value of 50 means the top 50px of the surface is outside the viewport.

Returns:

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

Type
Object | null
Source:

Get measurements of the visible area of the surface viewport

The bounding box returned is relative the viewport, e.g.

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

Initialize surface.

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

Returns:

Type
ve.ui.Surface

Fires:

Source:
Initialize surface.

isMultiline() → {boolean} #

Check if the surface is multi-line

Returns:

Surface is multi-line

Type
boolean
Source:
Check if the surface is multi-line

isReadOnly() → {boolean} #

Check if the surface is read-only

Returns:

Type
boolean
Source:
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([passive]) #

Handle position events from the view

Parameters:

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

recalculatePadding([scrollSelection]) #

Recalculate the content area padding based on the current state of the surface and visible components.

This should be called when the surface is resized or when UI components are toggled.

Parameters:

Name Type Attributes Description
scrollSelection boolean optional

Scroll selection into view after recalculating padding
Source:
Recalculate the content area padding based on the current state of the surface and visible components.

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

Fires:

Source:

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.
Deprecated:
  • The surface should calculate its own padding in recalculatePadding
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

Fires:

Source:
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.

suppressScrollPadding(scrollPaddingSuppressed) #

Suppress or unsuppress scroll padding adjustments.

This is set by the sticky toolbar when it is focussed to prevent a bug in Chromium browsers (https://issues.chromium.org/issues/40749247)

Parameters:

Name Type Description
scrollPaddingSuppressed boolean
Source:
Suppress or unsuppress scroll padding adjustments.

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.

padding() #

The surface padding has changed

Source:
The surface padding has changed

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.