Handles interactive editing and adding of labels.
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.
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.
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
EditLabelInputMode is installed as child mode of a GraphEditorInputMode and can be retrieved from the editLabelInputMode property.const editLabelInputMode = mode.editLabelInputModeRelated Reading in the Developer's Guide
Type Details
- yFiles module
- view
See Also
Constructors
Parameters
A map of options to pass to the method.
- priority - number
- enabled - boolean
- The enabled state of this input mode. This option sets the enabled property on the created object.
- textEditorInputMode - TextEditorInputMode
- The TextEditorInputMode which handles the actual text editing. This option either sets the value directly or recursively sets properties to the instance of the textEditorInputMode property on the created object.
- autoRemoveEmptyLabels - boolean
- 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. This option sets the autoRemoveEmptyLabels property on the created object.
- textEditorInputModeConfigurator - function(IInputModeContext, TextEditorInputMode, ILabel):void
- A handler which allows for configuring the textEditorInputMode during adding or editing labels. This option sets the textEditorInputModeConfigurator property on the created object.
Signature Details
function(context: IInputModeContext, mode: TextEditorInputMode, label: ILabel)Callback for configuring a TextEditorInputMode for editing a provided label instance.Parameters
- context - IInputModeContext
- The context in which the label is being edited or created.
- mode - TextEditorInputMode
- The mode that will be used for editing the label's text.
- label - ILabel
- The label that will be edited or created.
- hideLabelDuringEditing - boolean
- A property that determines whether the label should be hidden while it is being edited. This option sets the hideLabelDuringEditing property on the created object.
Properties
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.
Remarks
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.
Property Value
true if empty labels should be removed after text editing; otherwise, false.Gets or sets the enabled state of this input mode.
Remarks
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.
Gets or sets a property that determines whether the label should be hidden while it is being edited.
Remarks
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.
Retrieves the IInputModeContext this mode has been installed in.
Remarks
null if this mode is currently not installed. To obtain a context that has this IInputMode as the inputMode use createInputModeContext.Gets the priority of this input mode.
Remarks
Implements
Gets or sets the TextEditorInputMode which handles the actual text editing.
Remarks
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.
Throws
- Exception({ name: 'NotSupportedError' })
- If an attempt is made to change the instance while this mode is
. To exchange a mode, first , then to ensure that all data is initialized correctly.
Gets or sets a handler which allows for configuring the textEditorInputMode during adding or editing labels.
Remarks
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.
Signature Details
function(context: IInputModeContext, mode: TextEditorInputMode, label: ILabel)
Parameters
- context - IInputModeContext
- The context in which the label is being edited or created.
- mode - TextEditorInputMode
- The mode that will be used for editing the label's text.
- label - ILabel
- The label that will be edited or created.
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
Will be called to unconditionally cancel all ongoing edits.
Remarks
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
Creates an IInputModeContext based on parentInputModeContext but specific for this input mode.
Returns
- ↪IInputModeContext
- An IInputModeContext for this mode.
createLabel
(evt: LabelEditingEventArgs, helper: IEditLabelHelper) : Promise<yfiles.graph.ILabel|null>Uses the text editor to actually create a new label.
Remarks
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.
Parameters
A map of options to pass to the method.
- evt - LabelEditingEventArgs
- The information for label creation.
- helper - IEditLabelHelper
- An initialized IEditLabelHelper which handles adding the label.
Returns
- ↪Promise<yfiles.graph.ILabel|null>
- A task that represents the asynchronous label creation. The result of the task contains the new label or
nullif the creation was canceled.
editLabel
(label: ILabel, evt: LabelEditingEventArgs, helper: IEditLabelHelper) : Promise<yfiles.graph.ILabel|null>Uses the text editor to actually edit the given label.
Remarks
Parameters
A map of options to pass to the method.
- label - ILabel
- The label to edit.
- evt - LabelEditingEventArgs
- The information for label creation.
- helper - IEditLabelHelper
- An initialized IEditLabelHelper which handles adding the label.
Returns
- ↪Promise<yfiles.graph.ILabel|null>
- A task that represents the asynchronous label editing. The result of the task contains the updated label or
nullif editing was canceled.
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. 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
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 while the mode is installed.
- controller - ConcurrencyController
- The ConcurrencyController for this mode.
See Also
Implements
Raises the label-added event.
Parameters
A map of options to pass to the method.
- evt - InputModeItemEventArgs<ILabel>
- The InputModeItemEventArgs<TModelItem> instance that contains the ILabel that has been added.
Raises the label-deleted event.
Parameters
A map of options to pass to the method.
- evt - InputModeItemChangedEventArgs<ILabel,LabelEventArgs>
- The ItemChangedEventArgs<TItem,TValue> instance that contains the ILabel that has been deleted.
Raises the label-edited event.
Parameters
A map of options to pass to the method.
- evt - InputModeItemEventArgs<ILabel>
- The ItemEventArgs<T> instance that contains the ILabel that has changed the text.
Raises the label-editing-canceled event.
Parameters
A map of options to pass to the method.
- evt - InputModeItemEventArgs<ILabel>
- The InputModeItemEventArgs<TModelItem> instance containing the event data.
Raises the label-editing-started event.
Parameters
A map of options to pass to the method.
- evt - InputModeItemEventArgs<ILabel>
- The InputModeItemEventArgs<TModelItem> instance containing the event data.
Raises the query-label-adding event.
Remarks
evt as handled.Parameters
A map of options to pass to the method.
- evt - LabelEditingEventArgs
- The event arguments.
Raises the query-label-editing event.
Remarks
evt as handled.Parameters
A map of options to pass to the method.
- evt - LabelEditingEventArgs
- The event arguments.
Called when the textEditorInputMode property value changes and after initialization of the property.
Parameters
A map of options to pass to the method.
- oldMode - TextEditorInputMode
- the old value, which may be
nullthe first time - newMode - TextEditorInputMode
- the new value
Raises the validate-label-text event.
Parameters
A map of options to pass to the method.
- evt - LabelTextValidatingEventArgs
- The LabelTextValidatingEventArgs instance containing the event data.
openTextEditor
(label: ILabel, evt: LabelEditingEventArgs, helper: IEditLabelHelper) : Promise<string|null>Opens a new textEditorInputMode input field.
Remarks
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.
Parameters
A map of options to pass to the method.
- 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.
Returns
- ↪Promise<string|null>
- A future of the label's text that will be notified of the label text edit or a
nullif the text edit was canceled.
startLabelAddition
(owner: ILabelOwner, alwaysAdd?: boolean, initialNewText?: string) : Promise<yfiles.graph.ILabel|null>Interactively creates a new label for the provided label owner.
Remarks
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
A map of options to pass to the method.
- 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 theowner'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.
Returns
- ↪Promise<yfiles.graph.ILabel|null>
- A task that represents the asynchronous label creation. The result of the task contains the new label or
nullif the creation was canceled.
Starts editing the given label.
Remarks
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
A map of options to pass to the method.
- 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.
Returns
- ↪Promise<yfiles.graph.ILabel|null>
- A task that represents the asynchronous label edit. The result of the task contains the modified label or
nullif the edit was canceled.
Will be called to request a stop of the current editing progress.
Remarks
falseReturns
- ↪boolean
trueif and only if the editing has been stopped or there was no edit in progress
See Also
Implements
Uninstalls this mode from the given context.
Remarks
Parameters
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
Events
Occurs when this mode has triggered the addition of an ILabel, for instance, in response to startLabelAddition.
Occurs when this mode has triggered the removal an ILabel.
Remarks
true.Occurs when this mode has triggered the edit of an ILabel, for instance, in response to startLabelEditing.
Occurs when the actual label editing process is canceled.
Remarks
See Also
Occurs when the actual label editing process is about to start.
Remarks
See Also
Occurs when a label is about to be added.
Remarks
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.
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
}
},
)Occurs when a label is about to be edited.
Remarks
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.
Examples
graphEditorInputMode.editLabelInputMode.addEventListener(
'query-label-editing',
(evt) => {
if (evt.label?.tag === 'Non-Editable') {
// do not edit if forbidden
evt.cancel = true
}
},
)Occurs when a label that is about to be added or edited.
Remarks
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.
Examples
graphEditorInputMode.editLabelInputMode.addEventListener(
'validate-label-text',
(evt) => {
if (
evt.label.tag === 'int label' &&
Number.isNaN(parseInt(evt.newText))
) {
evt.validatedText = null
}
},
)