TextEditorInputMode

Show usages

An IInputMode implementation that displays a textarea in the CanvasComponent to let the user edit a text.

Inheritance Hierarchy

TextEditorInputMode

Implemented Interfaces

IInputMode

Remarks

Hitting escape or enter will cancel or stop editing.

This mode is exclusive by default.

Examples

Typically the TextEditorInputMode is installed as child mode of a GraphEditorInputMode and can be retrieved from the textEditorInputMode property.

Getting the TextEditorInputMode from its parent input mode

const textEditorInputMode = mode.textEditorInputMode

Type Details

yfiles module: view-component
yfiles-umd modules: All view modules
Legacy UMD name: yfiles.input.TextEditorInputMode

Constructors

TextEditorInputMode

(editorContainer?: HTMLDivElement)

Creates a new instance using a default text box or the provided editor.

ParametersOptions Overload

options - Object
A map of options to pass to the method.

editorContainer - HTMLDivElement

The editor to use as the text editor. If none is provided a default text editor will be used.

priority - number

exclusive - boolean

A value indicating whether this mode will be the only one running when it has the mutex. This option sets the exclusive property on the created object.

enabled - boolean

The enabled state of this input mode. This option sets the enabled property on the created object.

autoCommitOnFocusLost - boolean

A property that determines whether the text edited should be committed if the focus gets lost or the editing should be canceled. This option sets the autoCommitOnFocusLost property on the created object.

autoFocusCanvasOnEditorClosed - boolean

A property that determines whether this mode should try to focus the GraphComponent once the editor is closed via a keyboard gesture. This option sets the autoFocusCanvasOnEditorClosed property on the created object.

autoStartEditing - boolean

Whether this mode should automatically fire up the editor once it gets installed. This option sets the autoStartEditing property on the created object.

lineBreakRecognizer - function(Object, EventArgs):boolean

The event recognizer to detect the key gesture for new line breaks. This option sets the lineBreakRecognizer property on the created object.

Signature Details

function(eventSource: any, evt: EventArgs) : boolean

A callback that recognizes events.

Given a sender and an event argument, delegates decide whether the event is treated as a match depending on the context.

Parameters

eventSource - any: The source of the event.
evt - EventArgs: The arguments of the event to be decided to handle.

Returns

boolean: true if the evt is considered to be handled.

cancelRecognizer - function(Object, EventArgs):boolean

The event recognizer to detect when editing the text shall be canceled. This option sets the cancelRecognizer property on the created object.

Signature Details

function(eventSource: any, evt: EventArgs) : boolean

A callback that recognizes events.

Given a sender and an event argument, delegates decide whether the event is treated as a match depending on the context.

Parameters

eventSource - any: The source of the event.
evt - EventArgs: The arguments of the event to be decided to handle.

Returns

boolean: true if the evt is considered to be handled.

stopRecognizer - function(Object, EventArgs):boolean

The event recognizer to detect when editing the text shall be stopped. This option sets the stopRecognizer property on the created object.

Signature Details

function(eventSource: any, evt: EventArgs) : boolean

A callback that recognizes events.

Given a sender and an event argument, delegates decide whether the event is treated as a match depending on the context.

Parameters

eventSource - any: The source of the event.
evt - EventArgs: The arguments of the event to be decided to handle.

Returns

boolean: true if the evt is considered to be handled.

location - IPoint

The location of the text box in world coordinates. This option sets the location property on the created object.

upVector - IPoint

The point that describes the "up"-vector that will be used to determine the orientation of the text box in the world coordinate system. This option sets the upVector property on the created object.

anchor - IPoint

The anchor of the text box. This option sets the anchor property on the created object.

autoFlipTextBox - boolean

A value indicating whether to automatically flip the orientation of the text box if the upVector actually points downwards. This option sets the autoFlipTextBox property on the created object.

rotateTextBox - boolean

A value indiciating whether the text box should be rotated with the upVector. This option sets the rotateTextBox property on the created object.

textBoxPlacementPolicy - TextBoxPlacementPolicy

The textBoxPlacementPolicy to use when the editorContainer isn't completely visible in the current viewport. This option sets the textBoxPlacementPolicy property on the created object.

textBoxPadding - Insets

The padding to use around the editorContainer when it comes near to the viewport borders and needs to be adjusted. This option sets the textBoxPadding property on the created object.

Properties

anchor

: IPoint

Gets or sets the anchor of the text box.

Remarks

The anchor is the point inside the coordinate system of the text box that shall coincide with the location in the world coordinate system. The X and Y values are expressed as relative width/height ratios.

If this mode is used for label editing as a sub mode of GraphEditorInputMode the value of this property is overridden by a default value. It can be set, though, using the textEditorInputModeConfigurator.

Examples

mode.textEditorInputModeConfigurator = (context, inputMode, label) => {
  // anchor the text editor centered above the label
  inputMode.anchor = new Point(0.5, 1)
  // always place the editor horizontal
  inputMode.upVector = new Point(0, -1)
  // place the editor relative to the label's center
  inputMode.location = label.layout.orientedRectangleCenter
}mode.textEditorInputModeConfigurator = (
  context: IInputModeContext,
  inputMode: TextEditorInputMode,
  label: ILabel
): void => {
  // anchor the text editor centered above the label
  inputMode.anchor = new Point(0.5, 1)
  // always place the editor horizontal
  inputMode.upVector = new Point(0, -1)
  // place the editor relative to the label's center
  inputMode.location = label.layout.orientedRectangleCenter
}

autoCommitOnFocusLost

: boolean

Gets or sets a property that determines whether the text edited should be committed if the focus gets lost or the editing should be canceled.

Remarks

The default behavior is to cancel the editing process.

autoFlipTextBox

: boolean

Gets or sets a value indicating whether to automatically flip the orientation of the text box if the upVector actually points downwards.

Remarks

The default is true.

autoFocusCanvasOnEditorClosed

: boolean

Gets or sets a property that determines whether this mode should try to focus the GraphComponent once the editor is closed via a keyboard gesture.

Remarks

The default is true

autoStartEditing

: boolean

Gets or sets whether this mode should automatically fire up the editor once it gets installed.

Remarks

If this mode is permanently installed, set this flag to false and set the editing flag to true in order to start editing.

cancelRecognizer

: function(any, EventArgs):boolean

Gets or sets the event recognizer to detect when editing the text shall be canceled.

Remarks

When the provided KeyEventArgs are recognized, cancel is called.

Signature Details

function(eventSource: any, evt: EventArgs) : boolean

A callback that recognizes events.

Given a sender and an event argument, delegates decide whether the event is treated as a match depending on the context.

Parameters

eventSource - any: The source of the event.
evt - EventArgs: The arguments of the event to be decided to handle.

Returns

boolean: true if the evt is considered to be handled.

controller

: ConcurrencyController

Gets the installed controller.

editing

: boolean

Gets or sets the current editing state of the editor.

Remarks

Setting a new value will trigger the onBeginEditing and onCancelEditing methods respectively.

editorContainer

: HTMLDivElement

Gets the div-element that contains the text editor.

editorText

: string

Gets or sets the text that is displayed and edited.

Remarks

If customizations change the way the text is edited by providing a custom editor, this property can be overridden to return the current text contents and set the contents accordingly. Alternatively the EditorTextChanged event can be used for this task.

enabled

: boolean

Gets or sets the enabled state of this input mode.

Remarks

Clients can use this property to disable or reenable this instance. This will set the Enabled property of the installed controller so a disabled instance should never try to acquire the input mutex.

Examples

Disabling the TextEditorInputMode on its parent input mode

mode.textEditorInputMode.enabled = false

exclusive

: boolean

Gets or sets a value indicating whether this mode will be the only one running when it has the mutex.

Remarks

The value of this property will be delegated to the exclusive property of the controller.

If this mode is marked as exclusive and has the mutex, all other modes added to the same MultiplexingInputMode will be deactivated. Otherwise it will always run concurrently with all other modes.

inputModeContext

: IInputModeContext

Gets the context instance this mode is currently installed in or null if this instance is not installed.

Remarks

Note that this instance should not be passed down to subordinate modes or instances. Instead a corresponding context that has this instance set as the parentInputMode should be used.

Implements

IInputMode

lineBreakRecognizer

: function(any, EventArgs):boolean

Gets or sets the event recognizer to detect the key gesture for new line breaks.

Remarks

When the provided KeyEventArgs are recognized, a new line break is inserted at the current caret position.

Signature Details

function(eventSource: any, evt: EventArgs) : boolean

A callback that recognizes events.

Given a sender and an event argument, delegates decide whether the event is treated as a match depending on the context.

Parameters

eventSource - any: The source of the event.
evt - EventArgs: The arguments of the event to be decided to handle.

Returns

boolean: true if the evt is considered to be handled.

location

: IPoint

Gets or sets the location of the text box in world coordinates.

Remarks

Examples

mode.textEditorInputModeConfigurator = (context, inputMode, label) => {
  // anchor the text editor centered above the label
  inputMode.anchor = new Point(0.5, 1)
  // always place the editor horizontal
  inputMode.upVector = new Point(0, -1)
  // place the editor relative to the label's center
  inputMode.location = label.layout.orientedRectangleCenter
}mode.textEditorInputModeConfigurator = (
  context: IInputModeContext,
  inputMode: TextEditorInputMode,
  label: ILabel
): void => {
  // anchor the text editor centered above the label
  inputMode.anchor = new Point(0.5, 1)
  // always place the editor horizontal
  inputMode.upVector = new Point(0, -1)
  // place the editor relative to the label's center
  inputMode.location = label.layout.orientedRectangleCenter
}

priority

: number

Gets the priority of this input mode.

Remarks

The priority will influence the order in which the modes will be installed into the canvas control. The lower the priority value, the earlier it will be installed. If two modes are installed using the same priority value, the first one will be installed earlier.

Implements

IInputMode

rotateTextBox

: boolean

Gets or sets a value indiciating whether the text box should be rotated with the upVector.

Remarks

If the value is false (the default), the text box will always be horizontal.

stopRecognizer

: function(any, EventArgs):boolean

Gets or sets the event recognizer to detect when editing the text shall be stopped.

Remarks

When the provided KeyEventArgs are recognized, tryStop is called.

Signature Details

function(eventSource: any, evt: EventArgs) : boolean

A callback that recognizes events.

Given a sender and an event argument, delegates decide whether the event is treated as a match depending on the context.

Parameters

eventSource - any: The source of the event.
evt - EventArgs: The arguments of the event to be decided to handle.

Returns

boolean: true if the evt is considered to be handled.

textBoxPadding

: Insets

Gets or sets the padding to use around the editorContainer when it comes near to the viewport borders and needs to be adjusted.

Remarks

This is a value in view coordinates. Default is 20 on each side.

textBoxPlacementPolicy

: TextBoxPlacementPolicy

Gets or sets the textBoxPlacementPolicy to use when the editorContainer isn't completely visible in the current viewport.

Remarks

The default value is SCROLL_CANVAS.

upVector

: IPoint

Gets or sets the point that describes the "up"-vector that will be used to determine the orientation of the text box in the world coordinate system.

Remarks

The default is 0, -1.

Examples

mode.textEditorInputModeConfigurator = (context, inputMode, label) => {
  // anchor the text editor centered above the label
  inputMode.anchor = new Point(0.5, 1)
  // always place the editor horizontal
  inputMode.upVector = new Point(0, -1)
  // place the editor relative to the label's center
  inputMode.location = label.layout.orientedRectangleCenter
}mode.textEditorInputModeConfigurator = (
  context: IInputModeContext,
  inputMode: TextEditorInputMode,
  label: ILabel
): void => {
  // anchor the text editor centered above the label
  inputMode.anchor = new Point(0.5, 1)
  // always place the editor horizontal
  inputMode.upVector = new Point(0, -1)
  // place the editor relative to the label's center
  inputMode.location = label.layout.orientedRectangleCenter
}

Methods

adjustPosition

()

Adjusts the position of the text box in the CanvasComponent.

adjustSize

(maxSize: Size)

Adjusts the size of the text box in the editorContainer.

Parameters

options - Object
A map of options to pass to the method.

maxSize - Size: The suggested maximum size to use.

calculateMaxTextBoxSize

() : Size

Calculates the maximum size for this instance.

Remarks

The result is passed to adjustSize.

This implementation makes sure the textbox does not exceed the bounds of the canvas.

Returns

↪Size: The maximum size for the textbox.

cancel

()

Cancels editing of the text box.

Implements

IInputMode

clear

()

Resets the contents of the text box.

createEditorContainer

() : HTMLDivElement

Creates the default editor and it's container div element.

Remarks

This is called when no editor was provided to the constructor and populates editorContainer lazily on demand.

If custom code overrides this factory method to provide a custom editor, the following methods might need adjustment, too:

editorText - alternatively use the EditorTextChanged event.
adjustSize
adjustPosition

Returns

↪HTMLDivElement: The div that will be placed in the CanvasComponent for editing the text.

edit

() : Promise<string>

Starts interactive text editing.

Returns

↪Promise<string>: A Promise that will fulfill with the edited text or fulfill with null if editing is cancelled.

ensureVisible

()

Adjusts the viewport of the CanvasComponent such that the text box is in the visible area.

Remarks

Called once when the editing starts.

install

(context: IInputModeContext, controller: ConcurrencyController)

Installs this mode into the given context that is provided by the canvas.

Remarks

In general a mode can only be installed into a single canvas at all times.

This method is called to initialize this instance. Subclasses should override this method to register the corresponding event handler delegates for the various input events they need to register with.

Overriding implementations should call the base implementation, first.

Parameters

options - Object
A map of options to pass to the method.

context - IInputModeContext: The context that this instance shall be installed into. The same instance will be passed to this instance during uninstall. A reference to the context may be kept and queried during the time the mode is installed.
controller - ConcurrencyController: The controller for this mode.

Implements

IInputMode

installTextBox

()

Installs the editorContainer in the canvas and puts focus into it.

Remarks

The default implementation also selects all text in default text box and sets the caret to the end of the text.

onBeginEditing

()

Called when editing starts.

Remarks

Requests the input mutex, and installs the text box.

onCanceled

()

Called after cancel has been called.

Remarks

Can be overridden in subclasses to perform additional actions after the mode has been canceled.

This implementation does nothing.

onCancelEditing

()

Called when editing gets canceled.

Remarks

Removes the text box and releases the input mutex.

onConcurrencyControllerActivated

()

Called after the active property of the installed ConcurrencyController has been set to true.

Remarks

Can be overridden in subclasses to perform additional actions after the mode has been activated.

Overriding implementations should call the base implementation.

onConcurrencyControllerDeactivated

()

Called after the active property of the installed ConcurrencyController has been set to false.

Remarks

Can be overridden in subclasses to perform additional actions after the mode has been deactivated.

Overriding implementations should call the base implementation.

onEditingCanceled

(evt: TextEventArgs)

Raises the EditingCanceled event.

Parameters

options - Object
A map of options to pass to the method.

evt - TextEventArgs: The event argument

onEditingStarted

(evt: TextEventArgs)

Raises the EditingStarted event.

Parameters

options - Object
A map of options to pass to the method.

evt - TextEventArgs: The event argument.

onStopEditing

()

Called when editing is stopped.

Remarks

Triggers the TextEdited event, removes the box and releases the input mutex.

onStopped

()

Called after tryStop has been called.

Remarks

Can be overridden in subclasses to perform additional actions after the mode has been stopped.

This implementation does nothing.

onTextEdited

(evt: TextEventArgs)

Raises the TextEdited event.

Parameters

options - Object
A map of options to pass to the method.

evt - TextEventArgs: The event arguments.

tryStop

() : boolean

Stops editing and returns true.

Returns

↪boolean: base.Stop()

Implements

IInputMode

uninstall

(context: IInputModeContext)

Uninstalls this mode from the given context.

Remarks

This code should clean up all changes made to the canvas in the install method. After a mode has been uninstalled it can be installed again into the same or another canvas.

Overriding implementations should call the base implementation after their own code.

Parameters

options - Object
A map of options to pass to the method.

context - IInputModeContext: The context to deregister from. This is the same instance that had been passed to install during installation.

Implements

IInputMode

uninstallTextBox

()

Removes the text box.

Events

EditingCanceled

Occurs if the editing has not been finished.

Event Registration

addEditingCanceledListener(function(this, TextEventArgs):void)

Event Deregistration

removeEditingCanceledListener(function(this, TextEventArgs):void)

Signature Details

function(sender: this, evt: TextEventArgs)

Represents the method that will handle an event when the event provides data.

Parameters

sender - this: The source of the event.
evt - TextEventArgs: An object that contains the event data.

EditingStarted

Occurs when text editing is started.

Event Registration

addEditingStartedListener(function(this, TextEventArgs):void)

Event Deregistration

removeEditingStartedListener(function(this, TextEventArgs):void)

Signature Details

function(sender: this, evt: TextEventArgs)

Represents the method that will handle an event when the event provides data.

Parameters

sender - this: The source of the event.
evt - TextEventArgs: An object that contains the event data.

EditorTextChanged

Occurs when the editor's text should be changed.

Remarks

This event can be used by custom code that uses its own editor component. Listen to this event to update the text in the editor. Write changes in text back to the editorText property.

Event Registration

addEditorTextChangedListener(function(this, TextEventArgs):void)

Event Deregistration

removeEditorTextChangedListener(function(this, TextEventArgs):void)

Signature Details

function(sender: this, evt: TextEventArgs)

Represents the method that will handle an event when the event provides data.

Parameters

sender - this: The source of the event.
evt - TextEventArgs: An object that contains the event data.

TextEdited

Occurs once the text has been edited.

Event Registration

addTextEditedListener(function(this, TextEventArgs):void)

Event Deregistration

removeTextEditedListener(function(this, TextEventArgs):void)

Signature Details

function(sender: this, evt: TextEventArgs)

Represents the method that will handle an event when the event provides data.

Parameters

sender - this: The source of the event.
evt - TextEventArgs: An object that contains the event data.

TextEditorInputMode

Remarks

Examples

Type Details

See Also

Constructors

TextEditorInputMode

ParametersOptions Overload

Signature Details

Parameters

Returns

Signature Details

Parameters

Returns

Signature Details

Parameters

Returns

See Also

Properties

anchor

Remarks

Examples

autoCommitOnFocusLost

Remarks

autoFlipTextBox

Remarks

autoFocusCanvasOnEditorClosed

Remarks

autoStartEditing

Remarks

cancelRecognizer

Remarks

Signature Details

Parameters

Returns

See Also

controller

editing

Remarks

editorContainer

See Also

editorText

Remarks

enabled

Remarks

Examples

exclusive

Remarks

inputModeContext

Remarks

Implements

lineBreakRecognizer

Remarks

Signature Details

Parameters

Returns

See Also

location

Remarks

Examples

priority

Remarks

See Also

Implements

rotateTextBox

Remarks

stopRecognizer

Remarks

Signature Details

Parameters

Returns

See Also

textBoxPadding

Remarks

textBoxPlacementPolicy

Remarks

upVector

Remarks

Examples

See Also