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.

The editorContainer is using the yfiles-labeleditbox CSS class and provides additional classes for the enter and leave phase of the container.

Examples

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

Getting the TextEditorInputMode from its parent input mode

const textEditorInputMode = mode.editLabelInputMode.textEditorInputMode

Type Details

yFiles module: view

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.

stopEditingOnCommit - boolean

A property that determines whether the text editor should be closed on commit. This option sets the stopEditingOnCommit property on the created object.

autoCommitOnFocusLost - boolean

Whether the text edited should be committed or the editing should be canceled if the focus is lost. 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(EventArgs, unknown):boolean

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

Signature Details

function(evt: EventArgs, eventSource: unknown) : 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

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

Returns

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

cancelRecognizer - function(EventArgs, unknown):boolean

The event recognizer that detects when editing the text should be canceled. This option sets the cancelRecognizer property on the created object.

Signature Details

function(evt: EventArgs, eventSource: unknown) : 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

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

Returns

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

stopRecognizer - function(EventArgs, unknown):boolean

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

Signature Details

function(evt: EventArgs, eventSource: unknown) : 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

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

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.

selectContent - boolean

Whether the content of the text editor should be selected when the textbox gets shown. This option sets the selectContent 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 indicating 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.

textBoxMargins - Insets

The margins to use around the editorContainer when it comes near to the viewport borders and needs to be adjusted. This option sets the textBoxMargins 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 EditLabelInputMode, the value of this property is overridden by a value the EditLabelInputMode considers as best suitable for the currently edited label. It can be set, though, using the textEditorInputModeConfigurator on the EditLabelInputMode for global configurations or the textEditorInputModeConfigurator from the LabelEditingEventArgs for per-label changes.

Examples

mode.editLabelInputMode.textEditorInputModeConfigurator = (
  context: IInputModeContext,
  inputMode: TextEditorInputMode,
  label: ILabel,
) => {
  // 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.center
}

mode.editLabelInputMode.addEventListener(
  'query-label-editing',
  (evt: LabelEditingEventArgs) => {
    evt.textEditorInputModeConfigurator = (
      context: IInputModeContext,
      inputMode: TextEditorInputMode,
      label: ILabel,
    ) => {
      // 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.center
    }
  },
)

autoCommitOnFocusLost

: boolean

Gets or sets whether the text edited should be committed or the editing should be canceled if the focus is lost.

Remarks

The default behavior is to commit the edited text.

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.

Property Value

true if the text box should be flipped if necessary; false otherwise.

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(EventArgs, unknown):boolean

Gets or sets the event recognizer that detects when editing the text should be canceled.

Remarks

When the provided KeyEventArgs are recognized, cancel is called.

Property Value

The default recognizer checks for ESCAPE_DOWN.

Signature Details

function(evt: EventArgs, eventSource: unknown) : 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

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

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.

Property Value

The div element that contains the editor that is displayed on top of the CanvasComponent to the user for actually editing the text. By default this element contains a single textarea child with a CSS class of yfiles-labeleditbox.

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 editor-text-changed 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.editLabelInputMode.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.

lineBreakRecognizer

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that detects 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.

Property Value

The line break recognizer. The default recognizer checks for Key.Enter while CONTROL is pressed.

Signature Details

function(evt: EventArgs, eventSource: unknown) : 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

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

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

If this mode is used as a sub mode of EditLabelInputMode, the value of this property is overwritten by a value the EditLabelInputMode considers best suitable for the currently edited label. To set a location other than the one EditLabelInputMode considers best, the textEditorInputModeConfigurator from EditLabelInputMode for global configurations or the textEditorInputModeConfigurator from LabelEditingEventArgs for per-label changes may be used.

Examples

mode.editLabelInputMode.textEditorInputModeConfigurator = (
  context: IInputModeContext,
  inputMode: TextEditorInputMode,
  label: ILabel,
) => {
  // 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.center
}

mode.editLabelInputMode.addEventListener(
  'query-label-editing',
  (evt: LabelEditingEventArgs) => {
    evt.textEditorInputModeConfigurator = (
      context: IInputModeContext,
      inputMode: TextEditorInputMode,
      label: ILabel,
    ) => {
      // 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.center
    }
  },
)

parentInputModeContext

: IInputModeContext?

Retrieves the IInputModeContext this mode has been installed in.

Remarks

The value will be null if this mode is currently not installed.

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 CanvasComponent. The lower the priority value, the earlier it will be installed. If two modes are using the same priority value, the first one to be registered will be installed earlier.

Implements

IInputMode

rotateTextBox

: boolean

Gets or sets a value indicating 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.

selectContent

: boolean

Gets or sets whether the content of the text editor should be selected when the textbox gets shown.

Remarks

By default, this is enabled so that when the text editor is opened, typing will replace the content.

stopEditingOnCommit

: boolean

Gets or sets a property that determines whether the text editor should be closed on commit.

Remarks

If set to false, the text editor is kept open after commit and editing has to be stopped by the caller. This allows EditLabelInputMode to keep the editor open if label text validation fails. EditLabelInputMode always stops editing after successful validation.

If set to true, the label editor is closed on commit even if label text validation fails. The label text is not changed when the editor is closed with invalid text.

The default value is false.

stopRecognizer

: function(EventArgs, unknown):boolean

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

Remarks

When the provided KeyEventArgs are recognized, tryStop is called.

Property Value

The stop recognizer. The default recognizer checks for Key.Enter while CONTROL is not pressed.

Signature Details

function(evt: EventArgs, eventSource: unknown) : 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

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

Returns

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

textBoxMargins

: Insets

Gets or sets the margins 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 MOVE_TEXT_BOX.

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.editLabelInputMode.textEditorInputModeConfigurator = (
  context: IInputModeContext,
  inputMode: TextEditorInputMode,
  label: ILabel,
) => {
  // 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.center
}

mode.editLabelInputMode.addEventListener(
  'query-label-editing',
  (evt: LabelEditingEventArgs) => {
    evt.textEditorInputModeConfigurator = (
      context: IInputModeContext,
      inputMode: TextEditorInputMode,
      label: ILabel,
    ) => {
      // 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.center
    }
  },
)

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 editor-text-changed 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.

Remarks

The input box is not closed automatically afterward such that it can be kept open after failed validation, for example.

To close the input box afterward, either call tryStop or set stopEditingOnCommit to automatically close it after committing the gesture.

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.

initializeSelection

()

Helper method called by installTextBox that sets the initial caret location and selects the text.

Remarks

This implementation moves the caret to the end of the text and selects the text if selectContent is set to true.

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 editing-canceled event.

Parameters

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

evt - TextEventArgs: The event argument

onEditingStarted

(evt: TextEventArgs)

Raises the editing-started 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 text-edited 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 text-edited event.

Parameters

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

evt - TextEventArgs: The event arguments.

tryStop

() : boolean

Will be called to request a stop of the current editing progress.

Remarks

This should stop the current edit, if one is in progress, and possibly commit all pending changes. If stopping is not possible, this method can return false

Returns

↪boolean: true if and only if the editing has been stopped or there was no edit in progress

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

'editing-canceled'

: function(TextEventArgs, this):void

Occurs if the editing has not been finished.

'editing-started'

: function(TextEventArgs, this):void

Occurs when text editing is started.

'editor-text-changed'

: function(TextEventArgs, this):void

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.

'text-edited'

: function(TextEventArgs, this):void

Occurs once the text has been edited.

TextEditorInputMode

Remarks

Examples

Related Reading in the Developer's Guide

Type Details

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

Property Value

autoFocusCanvasOnEditorClosed

Remarks

autoStartEditing

Remarks

cancelRecognizer

Remarks

Property Value

Signature Details

Parameters

Returns

See Also

controller

editing

Remarks

editorContainer

Property Value

See Also

editorText

Remarks

enabled

Remarks

Examples

exclusive

Remarks

lineBreakRecognizer

Remarks

Property Value

Signature Details

Parameters

Returns

See Also

location

Remarks

Examples

parentInputModeContext

Remarks

priority

Remarks

Implements

rotateTextBox

Remarks

selectContent

Remarks

See Also

stopEditingOnCommit

Remarks

stopRecognizer

Remarks

Property Value

Signature Details

Parameters

Returns

See Also