C

TextEditorInputMode

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

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

See Also

The CSS styling options for the editor container are presented in detail in the section CSS Transition or Animation for the Input Element .

Developer's Guide

Members

Show:

Constructors

TextEditorInputMode

(editorContainer?: HTMLDivElement)
Creates a new instance using a default text box or the provided editor.

Parameters

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

See Also

API
createEditorContainer

Properties

anchor

: IPoint
Gets or sets the anchor of the text box.

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.

conversionfinal

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
    }
  },
)

See Also

Developer's Guide

autoCommitOnFocusLost

: boolean
Gets or sets whether the text edited should be committed or the editing should be canceled if the focus is lost.
The default behavior is to commit the edited text.
final

autoFlipTextBox

: boolean
Gets or sets a value indicating whether to automatically flip the orientation of the text box if the upVector actually points downwards.
The default is true.
final

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.
The default is true
final

autoStartEditing

: boolean
Gets or sets whether this mode should automatically fire up the editor once it gets installed.
If this mode is permanently installed, set this flag to false and set the editing flag to true in order to start editing.
final

cancelRecognizer

: function(EventArgs, unknown): boolean
Gets or sets the event recognizer that detects when editing the text should be canceled.
When the provided KeyEventArgs are recognized, cancel is called.
final

Property Value

The default recognizer checks for ESCAPE_DOWN.

See Also

API
lineBreakRecognizer, stopRecognizer

controller

: ConcurrencyController
protectedreadonly
Gets the installed controller.
protectedreadonlyfinal

editing

: boolean
Gets or sets the current editing state of the editor.
Setting a new value will trigger the onBeginEditing and onCancelEditing methods respectively.
final

editorContainer

: HTMLDivElement
readonly
Gets the HTMLDivElement that contains the text editor.
readonlyfinal

Property Value

The HTMLDivElement 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.

See Also

Developer's Guide
API
createEditorContainer

editorText

: string
Gets or sets the text that is displayed and edited.
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.
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.

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.

final

lineBreakRecognizer

: function(EventArgs, unknown): boolean
Gets or sets the event recognizer that detects the key gesture for new line breaks.
When the provided KeyEventArgs are recognized, a new line break is inserted at the current caret position.
final

Property Value

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

See Also

API
cancelRecognizer, stopRecognizer

location

: IPoint
Gets or sets the location of the text box in world coordinates.
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.
conversionfinal

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
    }
  },
)

See Also

Developer's Guide

parentInputModeContext

: IInputModeContext
protectedreadonly
Retrieves the IInputModeContext this mode has been installed in.
The value will be null if this mode is currently not installed.
protectedreadonlyfinal

priority

: number
Gets the priority of this input mode.
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.
final

rotateTextBox

: boolean
Gets or sets a value indicating whether the text box should be rotated with the upVector.
If the value is false (the default), the text box will always be horizontal.
final

selectContent

: boolean
Gets or sets whether the content of the text editor should be selected when the textbox gets shown.
By default, this is enabled so that when the text editor is opened, typing will replace the content.
final

See Also

API
initializeSelection

stopEditingOnCommit

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

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.

final

stopRecognizer

: function(EventArgs, unknown): boolean
Gets or sets the event recognizer to detect when editing the text should be stopped.
When the provided KeyEventArgs are recognized, tryStop is called.
final

Property Value

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

See Also

API
lineBreakRecognizer, cancelRecognizer

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.
This is a value in view coordinates. Default is 20 on each side.
conversionfinal

textBoxPlacementPolicy

: TextBoxPlacementPolicy
Gets or sets the textBoxPlacementPolicy to use when the editorContainer isn't completely visible in the current viewport.
The default value is MOVE_TEXT_BOX.
conversionfinal

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.

The default is 0, -1.

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.

conversionfinal

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
    }
  },
)

See Also

Developer's Guide
API
rotateTextBox

Methods

adjustPosition

()
protected
Adjusts the position of the text box in the CanvasComponent.

adjustSize

(maxSize: Size)
protected
Adjusts the size of the text box in the editorContainer.
protected

Parameters

maxSize: Size
The suggested maximum size to use.

calculateMaxTextBoxSize

(): Size
protected
Calculates the maximum size for this instance.

The result is passed to adjustSize.

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

protected

Return Value

Size
The maximum size for the textbox.

See Also

API
adjustSize

cancel

()
Cancels editing of the text box.

clear

()
Resets the contents of the text box.

createEditorContainer

(): HTMLDivElement
protected
Creates the default editor and it's container HTMLDivElement.

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:

protected

Return Value

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

edit

(): Promise<string>
Starts interactive text editing.

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.

final

Return Value

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

ensureVisible

()
protected
Adjusts the viewport of the CanvasComponent such that the text box is in the visible area.
Called once when the editing starts.
protected

See Also

API
textBoxPlacementPolicy

initializeSelection

()
protected
Helper method called by installTextBox that sets the initial caret location and selects the text.
This implementation moves the caret to the end of the text and selects the text if selectContent is set to true.
protected

install

(context: IInputModeContext, controller: ConcurrencyController)
Installs this mode into the given context that is provided by the canvas.

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

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.

See Also

API
uninstall

installTextBox

()
protected
Installs the editorContainer in the canvas and puts focus into it.
The default implementation also selects all text in default text box and sets the caret to the end of the text.
protected

onBeginEditing

()
protected
Called when editing starts.
Requests the input mutex, and installs the text box.
protected

onCanceled

()
protected
Called after cancel has been called.

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

This implementation does nothing.

protected

onCancelEditing

()
protected
Called when editing gets canceled.
Removes the text box and releases the input mutex.
protected

onConcurrencyControllerActivated

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

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

Overriding implementations should call the base implementation.

protected

onConcurrencyControllerDeactivated

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

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

Overriding implementations should call the base implementation.

protected

onEditingCanceled

(evt: TextEventArgs)
protected
Raises the editing-canceled event.
protected

Parameters

evt: TextEventArgs
The event argument

onEditingStarted

(evt: TextEventArgs)
protected
Raises the editing-started event.
protected

Parameters

evt: TextEventArgs
The event argument.

onStopEditing

()
protected
Called when editing is stopped.
Triggers the text-edited event, removes the box, and releases the input mutex.
protected

onStopped

()
protected
Called after tryStop has been called.

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

This implementation does nothing.

protected

onTextEdited

(evt: TextEventArgs)
protected
Raises the text-edited event.
protected

Parameters

evt: TextEventArgs
The event arguments.

tryStop

(): boolean
Will be called to request a stop of the current editing progress.
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

Return Value

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

uninstall

(context: IInputModeContext)
Uninstalls this mode from the given context.

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

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

uninstallTextBox

()
protected
Removes the text box.

Events

'editing-canceled'

: TextEventArgs
Occurs if the editing has not been finished.

Properties of

TextEventArgs
context: IInputModeContext
Gets the context for the current event.
text: string
Gets the text that was or will be edited.

See Also

Developer's Guide

'editing-started'

: TextEventArgs
Occurs when text editing is started.

Properties of

TextEventArgs
context: IInputModeContext
Gets the context for the current event.
text: string
Gets the text that was or will be edited.

See Also

Developer's Guide

'editor-text-changed'

: TextEventArgs
Occurs when the editor's text should be changed.
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.

Properties of

TextEventArgs
context: IInputModeContext
Gets the context for the current event.
text: string
Gets the text that was or will be edited.

'text-edited'

: TextEventArgs
Occurs once the text has been edited.

Properties of

TextEventArgs
context: IInputModeContext
Gets the context for the current event.
text: string
Gets the text that was or will be edited.

See Also

Developer's Guide