EditLabelInputMode

Handles interactive editing and adding of labels.

Implements

I
IInputMode

Inheritance Hierarchy

Remarks

Label adding or editing using the text editor can be triggered from code by calling startLabelAddition, startLabelEditing, or the respective methods on GraphEditorInputMode or TableEditorInputMode. This input mode also handles label adding or editing triggered by commands.

The actual text editor is opened using the textEditorInputMode.

This input mode relies on the IEditLabelHelper implementation found in a ILabel's or ILabelOwner's lookup. By default, all labels and label owners provide a suitable implementation. Custom implementations may be provided by decorators.

Using a custom edit label helper for nodes

graph.decorator.nodes.editLabelHelper.addConstant(new EditLabelHelper())

At the beginning of a label adding or editing operation, IEditLabelHelper's initialize is called for preparations but also for optional information, like styles. Custom implementations might also keep state. It is guaranteed that for each initialized helper either cancel or finish is called.

It is possible to validate new label text before the editor is closed and the label's text is changed or a new label is added.

Validating the label text

graphEditorInputMode.editLabelInputMode.addEventListener(
  'validate-label-text',
  (evt) => {
    if (
      evt.label.tag === 'int label' &&
      Number.isNaN(parseInt(evt.newText))
    ) {
      evt.validatedText = null
    }
  },
)

If label editing was successful, EditLabelInputMode delegates to IEditLabelHelper's finish method which takes care of actually setting the label text or adding a new label or removing the edited label.

Examples

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

Getting the EditLabelInputMode from its parent input mode

const editLabelInputMode = mode.editLabelInputMode

Members

Show:

protected

Constructors

EditLabelInputMode

()

Parameters

Show options overload

Properties

autoRemoveEmptyLabels

: boolean

Gets or sets a value indicating whether this mode should automatically remove labels from the graph when a label text has been edited and the label text is empty.

true if empty labels should be removed after text editing, false otherwise. label-deleted is dispatched after a label has been removed.

The default value is true.

final

Property Value

true if empty labels should be removed after text editing; otherwise, false.

enabled

: boolean

Gets or sets the enabled state of this input mode.

Clients can use this property to disable or reenable this instance.

If the text editor is open when enabled is set to false, editing will be cancelled immediately.

hideLabelDuringEditing

: boolean

Gets or sets a property that determines whether the label should be hidden while it is being edited.

If enabled, any selection, focus, and highlight visualizations of the label are hidden along with the label visualization itself.

Even if enabled, the label text is still visible in the editorText.

The default value is true.

final

parentInputModeContext

: IInputModeContext

protectedreadonly

Retrieves the IInputModeContext this mode has been installed in.

The value will be null if this mode is currently not installed. To obtain a context that has this IInputMode as the inputMode use createInputModeContext.

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

Implements

IInputMode.priority

textEditorInputMode

: TextEditorInputMode

Gets or sets the TextEditorInputMode which handles the actual text editing.

Upon change, the onTextEditorInputModeChanged method will be called.

The EditLabelInputMode mode uses the TextEditorInputMode to open the text box for the currently handled label. The TextEditorInputMode class opens the actual text box and informs this caller about the text being edited or the text editing being canceled.

final

Throws

Exception ({ name: 'NotSupportedError' }): If an attempt is made to change the instance while this mode is installed. To exchange a mode, first uninstall, then reinstall to ensure that all data is initialized correctly.

textEditorInputModeConfigurator

: function(IInputModeContext, TextEditorInputMode, ILabel): void

Gets or sets a handler which allows for configuring the textEditorInputMode during adding or editing labels.

The location, anchor, or upVector of the text editor is configured when the EditLabelInputMode opens the editor to position it at the label's location.

This handler, if set, is called during adding or editing labels after the text box is positioned for the currently edited label, allowing you to override these values and place the label at a custom position. It is called, though, before a textEditorInputModeConfigurator which is obtained from query-label-adding, query-label-editing, or an IEditLabelHelper is called. Therefore, the settings which are done in this handler override the defaults but might be overridden themselves by a subsequently called handler.

Note that only the positional properties location, anchor, or upVector are changed during label editing. All other properties of TextEditorInputMode are not changed and therefore can be set directly on the textEditorInputMode.

final

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
}

Methods

cancel

()

Will be called to unconditionally cancel all ongoing edits.

This will be called prior to the uninstalling of this instance and when other input modes temporarily acquire the mutex.

In order to stop an active input mode manually, client code should use the following idiom:

if (!mode.tryStop()) {
  mode.cancel()
}

Implements

IInputMode.cancel

createInputModeContext

(): IInputModeContext

protected

Creates an IInputModeContext based on parentInputModeContext but specific for this input mode.

createLabel

(evt: LabelEditingEventArgs, helper: IEditLabelHelper): any

protected

Uses the text editor to actually create a new label.

The label is added to the evt's owner.

This method is only called when label creation is not forbidden after querying query-label-adding and the label owner's IEditLabelHelper.

protected

Parameters

evt: LabelEditingEventArgs: The information for label creation.
helper: IEditLabelHelper: An initialized IEditLabelHelper which handles adding the label.

Return Value

any: A task that represents the asynchronous label creation. The result of the task contains the new label or null if the creation was canceled.

editLabel

(

label: ILabel

evt: LabelEditingEventArgs

helper: IEditLabelHelper

): any

protected

Uses the text editor to actually edit the given label.

This method is only called when label creation is not forbidden after querying query-label-adding and the label owner's IEditLabelHelper.

protected

Parameters

label: ILabel: The label to edit.
evt: LabelEditingEventArgs: The information for label creation.
helper: IEditLabelHelper: An initialized IEditLabelHelper which handles adding the label.

Return Value

any: A task that represents the asynchronous label editing. The result of the task contains the updated label or null if editing was canceled.

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. Implement this method to register the corresponding event handlers for the various input events this mode will listen to.

When this instance gets uninstalled from the context the same context instance will be passed to it.

Implementations may hold a reference to the context instance and use it while installed.

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 while the mode is installed.
controller: ConcurrencyController: The ConcurrencyController for this mode.

protected

Parameters

evt: LabelEditingEventArgs: The event arguments.

onQueryLabelEditing

(evt: LabelEditingEventArgs)

protected

Raises the query-label-editing event.

Invoking the event handlers stops once one event marks the evt as handled.

protected

Parameters

evt: LabelEditingEventArgs: The event arguments.

onTextEditorInputModeChanged

(oldMode: TextEditorInputMode, newMode: TextEditorInputMode)

protected

Called when the textEditorInputMode property value changes and after initialization of the property.

protected

Parameters

oldMode: TextEditorInputMode: the old value, which may be null the first time
newMode: TextEditorInputMode: the new value

onValidateLabelText

(evt: LabelTextValidatingEventArgs)

protected

Raises the validate-label-text event.

protected

Parameters

evt: LabelTextValidatingEventArgs: The LabelTextValidatingEventArgs instance containing the event data.

openTextEditor

(

label: ILabel

evt: LabelEditingEventArgs

helper: IEditLabelHelper

): any

protected

Opens a new textEditorInputMode input field.

Called for both adding a new label and editing an existing label. Opens the text editor and asynchronously returns a string with the edited text or null if text editing has been canceled.

This method is only called if label editing has not been forbidden after querying query-label-editing or the label's or the label owner's IEditLabelHelper.

protected

Parameters

label: ILabel: The label to edit.
evt: LabelEditingEventArgs: Additional information about the label to edit, e.g. a custom layoutParameter or a textEditorInputModeConfigurator callback to configure the textEditorInputMode before the label is edited.
helper: IEditLabelHelper: An initialized IEditLabelHelper which can apply the editing results on the label.

Return Value

any: A future of the label's text that will be notified of the label text edit or a null if the text edit was canceled.

startLabelAddition

(

owner: ILabelOwner

alwaysAdd?: boolean

initialNewText?: string

): any

Interactively creates a new label for the provided label owner.

This method will invoke the text editor that will let the user edit the text of the label. If the user commits the label text, the label will be added to the label owner.

The text that the user enters may be validated before the label is actually added.

If either a handler for query-label-adding or the owner's IEditLabelHelper set a new label, that label will be edited instead of adding a new one. This behavior can be suppressed by setting alwaysAdd to true.

Parameters

Show options overload

owner: ILabelOwner: The item to create a new label for.
alwaysAdd?: boolean: If set to false, a label provided with label set in a handler for query-label-adding or the owner's IEditLabelHelper will be edited. Otherwise, a new label will always be added.
initialNewText?: string: An optional additional string that should be appended to the new text. This can be used to support features like allowEditLabelOnTyping.

Return Value

any: A task that represents the asynchronous label creation. The result of the task contains the new label or null if the creation was canceled.

startLabelEditing

(label: ILabel, initialNewText?: string): any

Starts editing the given label.

This implementation uses the TextEditorInputMode to display an editor to edit the label. The text that the user enters may be validated before the label is actually edited.

This method will raise the query-label-editing event and query the IEditLabelHelper for the label and its owner, but will ignore the result except for the textEditorInputModeConfigurator property on the LabelEditingEventArgs. Thus editing a label via this method cannot be prevented by event handlers or IEditLabelHelpers.

Parameters

label: ILabel: The label to edit.
initialNewText?: string: An optional additional string that should be appended to the new text. This can be used to support features like allowEditLabelOnTyping.

Return Value

any: A task that represents the asynchronous label edit. The result of the task contains the modified label or null if the edit was canceled.

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

Implements

IInputMode.tryStop

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.

Parameters

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

Implements

IInputMode.uninstall

Events

'label-added'

: InputModeItemEventArgs<ILabel>

Occurs when this mode has triggered the addition of an ILabel, for instance, in response to startLabelAddition.

Properties of

InputModeItemEventArgs<ILabel>

context: IInputModeContext: Gets the context for the current event.
item: TModelItem: Gets the item which has been created or changed.

'label-deleted'

: InputModeItemChangedEventArgs<ILabel, LabelEventArgs>

Occurs when this mode has triggered the removal an ILabel.

This can only happen when an empty label text is set in response to startLabelEditing and autoRemoveEmptyLabels is true.

Properties of

InputModeItemChangedEventArgs<ILabel, LabelEventArgs>

context: IInputModeContext: Gets the context for the current event.
details: TDetail: Gets additional information about the state of the item, before it has been deleted.
item: TItem: Gets the item which has been created or changed.

'label-edited'

: InputModeItemEventArgs<ILabel>

Occurs when this mode has triggered the edit of an ILabel, for instance, in response to startLabelEditing.

Properties of

InputModeItemEventArgs<ILabel>

context: IInputModeContext: Gets the context for the current event.
item: TModelItem: Gets the item which has been created or changed.

'label-editing-canceled'

: InputModeItemEventArgs<ILabel>

Occurs when the actual label editing process is canceled.

This offers the possibility to clean up temporary customizations for the actual label editing process.

Properties of

InputModeItemEventArgs<ILabel>

context: IInputModeContext: Gets the context for the current event.
item: TModelItem: Gets the item which has been created or changed.

'label-editing-started'

: InputModeItemEventArgs<ILabel>

Occurs when the actual label editing process is about to start.

This offers the possibility to customize the label editing process.

Properties of

InputModeItemEventArgs<ILabel>

context: IInputModeContext: Gets the context for the current event.
item: TModelItem: Gets the item which has been created or changed.

'query-label-adding'

: LabelEditingEventArgs

Occurs when a label is about to be added.

Event handlers for this event can customize the behavior for adding a new label extensively. Adding a label can be forbidden entirely, or the properties of the added label can be changed, by setting the appropriate properties on the LabelEditingEventArgs. It is even possible to forbid adding a label, but edit an existing one instead.

If developers want to be sure that their settings will be adopted, they have to set handled to true.

This event is not raised if a IEditLabelHelper for the label owner has already handled or canceled the label editing.

Properties of

LabelEditingEventArgs

cancel: boolean writable: Gets or sets a value indicating whether the action (adding or editing a label) should be canceled.
context: IInputModeContext: Gets the context for the current event.
handled: boolean writable: Gets or sets a value indicating whether this event has been handled.
label: ILabel writable: Gets or sets the label to edit.
layoutParameter: ILabelModelParameter writable: Gets or sets the layoutParameter of the label to add.
owner: ILabelOwner writable: Gets or sets the owner of the label.
preferredSize: Size writable: Gets or sets the preferredSize of the label to add.
style: ILabelStyle writable: Gets or sets the style of the label to add.
tag: ILabel['tag'] writable: Gets or sets the tag of the label to add.
text: string writable: Gets or sets the text to set for the label.
textEditorInputModeConfigurator: function(IInputModeContext, TextEditorInputMode, ILabel): void writable: Gets or sets the configurator for the TextEditorInputMode for editing the provided label instance.

Examples

graphEditorInputMode.editLabelInputMode.addEventListener(
  'query-label-adding',
  (evt) => {
    if (evt.owner!.labels.size >= 1) {
      // do not add a second label
      evt.cancel = true
    } else {
      // the new label should be red
      evt.style = new LabelStyle({ backgroundFill: Color.RED })
      evt.handled = true
    }
  },
)

'query-label-editing'

: LabelEditingEventArgs

Occurs when a label is about to be edited.

Event handlers for this event can customize the behavior for editing an existing label. Editing can be forbidden entirely, or redirected to a different label, even on a different owner. In case editing existing labels is unwanted, event handlers can also specify that instead of editing a label, a new one should be added.

If developers want to be sure that their settings will be adopted, they have to set handled to true.

This event is not raised if a IEditLabelHelper for the label or owner has already handled or canceled the label editing.

Properties of

LabelEditingEventArgs

cancel: boolean writable: Gets or sets a value indicating whether the action (adding or editing a label) should be canceled.
context: IInputModeContext: Gets the context for the current event.
handled: boolean writable: Gets or sets a value indicating whether this event has been handled.
label: ILabel writable: Gets or sets the label to edit.
layoutParameter: ILabelModelParameter writable: Gets or sets the layoutParameter of the label to add.
owner: ILabelOwner writable: Gets or sets the owner of the label.
preferredSize: Size writable: Gets or sets the preferredSize of the label to add.
style: ILabelStyle writable: Gets or sets the style of the label to add.
tag: ILabel['tag'] writable: Gets or sets the tag of the label to add.
text: string writable: Gets or sets the text to set for the label.
textEditorInputModeConfigurator: function(IInputModeContext, TextEditorInputMode, ILabel): void writable: Gets or sets the configurator for the TextEditorInputMode for editing the provided label instance.

Examples

graphEditorInputMode.editLabelInputMode.addEventListener(
  'query-label-editing',
  (evt) => {
    if (evt.label?.tag === 'Non-Editable') {
      // do not edit if forbidden
      evt.cancel = true
    }
  },
)

'validate-label-text'

: LabelTextValidatingEventArgs

Occurs when a label that is about to be added or edited.

This event that can be used to validate the label text before inserting/updating the actual label. Set validatedText to null to reject the currently edited label's newText or set a (possibly asynchronously) validatedText.

Note that in the case of startLabelAddition the label is not part of the current graph but only a helper instance.

If validation fails the text editor is kept open until a valid text is entered or text editing is canceled. This behavior can be changed by setting stopEditingOnCommit to true. With that setting, the editor is closed immediately after commit. If validation fails in that case, the label will not be changed or created.

Properties of

LabelTextValidatingEventArgs

context: IInputModeContext: Gets the context for the current event.
label: ILabel: Gets the label that is being edited.
newText: string: Gets the new text to use for the label.
validatedText: any writable: Gets or sets the validated text, or a Promise<T> resolving with the new text to use for the label.

Examples

Labels with tag "int label" should be rejected if their text cannot be parsed into an integer value:

graphEditorInputMode.editLabelInputMode.addEventListener(
  'validate-label-text',
  (evt) => {
    if (
      evt.label.tag === 'int label' &&
      Number.isNaN(parseInt(evt.newText))
    ) {
      evt.validatedText = null
    }
  },
)

EditLabelInputMode

Remarks

Examples

See Also

Developer's Guide

API

Members

Constructors

EditLabelInputMode

Parameters

Properties

autoRemoveEmptyLabels

Property Value

See Also

Developer's Guide

enabled

hideLabelDuringEditing

parentInputModeContext

priority

Implements

textEditorInputMode

Throws

textEditorInputModeConfigurator

Examples

Methods

cancel

Implements

createInputModeContext

createLabel

Parameters

Return Value

editLabel

Parameters

Return Value

install

Parameters

Implements

onLabelAdded

Parameters

onLabelDeleted

Parameters

onLabelEdited

Parameters

onLabelEditingCanceled

Parameters

onLabelEditingStarted

Parameters

onQueryLabelAdding

Parameters

onQueryLabelEditing

Parameters

onTextEditorInputModeChanged

Parameters

onValidateLabelText

Parameters

openTextEditor

Parameters

Return Value

startLabelAddition

Parameters

Return Value

startLabelEditing

Parameters

Return Value

tryStop

Return Value

Implements

uninstall

Parameters

Implements

Events

'label-added'

Properties of

See Also

Developer's Guide

'label-deleted'

Properties of

'label-edited'

Properties of

See Also