TextEditingTool class

The TextEditingTool is used to let the user interactively edit text in place. This sets the TextBlock#text property; you may want to save the changed text to the model by using a TwoWay Binding on the "text" property of editable TextBlocks.

Typically this is used by setting the TextBlock#editable property to true on a particular TextBlock in a part. When the part is selected and the user clicks on the TextBlock or invokes the CommandHandler#editTextBlock command, this tool is started and it uses an HTMLTextArea to perform in-place text editing. (For more details see the description for TextEditingTool#doActivate.)

The TextBlock is accessible as the TextEditingTool#textBlock property. The text editor is accessible as the TextEditingTool#currentTextEditor property. From the text editor control one can access the TextBlock being edited via the 'textEditingTool' property to get to this tool, from which one can use the TextEditingTool#textBlock property.

You can disable mouse clicking from starting this text editing tool by setting Tool#isEnabled to false. You can disable the F2 key from starting this text editing tool by making sure Part#canEdit returns false, by either setting Diagram#allowTextEdit to false or by setting Part#textEditable to false.

If you want to programmatically start the user editing a particular TextBlock, call CommandHandler#editTextBlock. That command method is also invoked by the F2 key on the keyboard.

For a general discussion of text editing validation, see: Introduction to Text Validation. For customizing the TextEditingTool, read about HTMLInfo and see Introduction to Text Editors.

Implemented types

Tool

Available extensions

Annotations

@JS()
@staticInterop

Constructors

TextEditingTool(): factory

Properties

currentTextEditor ↔ HTMLInfo?: Available on TextEditingTool, provided by the TextEditingTool$Typings extension
Gets or sets the HTMLInfo that is editing the text.
getter/setter pair
defaultTextEditor ↔ HTMLInfo: Available on TextEditingTool, provided by the TextEditingTool$Typings extension
Gets or sets the default HTMLInfo that edits the text.
getter/setter pair
diagram ↔ Diagram: Available on Tool, provided by the Tool$Typings extension
This read-only property returns the Diagram that owns this tool and for which this tool is handling input events.
getter/setter pair
hashCode → int: The hash code for this object.
no setterinherited
isActive ↔ bool: Available on Tool, provided by the Tool$Typings extension
Gets or sets whether this tool is started and is actively doing something.
getter/setter pair
isEnabled ↔ bool: Available on Tool, provided by the Tool$Typings extension
Gets or sets whether this tool can be started by a mouse event.
getter/setter pair
name ↔ String: Available on Tool, provided by the Tool$Typings extension
Gets or sets the name of this tool. The default name is an empty string, but the constructor for each instance of a subclass of Tool will initialize it appropriately. For example, the name of the DragSelectingTool is "DragSelecting".
getter/setter pair
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
selectsTextOnActivate ↔ bool: Available on TextEditingTool, provided by the TextEditingTool$Typings extension
Gets or sets whether to select (highlight) the editable text when the TextEditingTool is activated. The default is true.
getter/setter pair
starting ↔ EnumValue: Available on TextEditingTool, provided by the TextEditingTool$Typings extension
Gets or sets how user gestures can start in-place editing of text.
getter/setter pair
state ↔ EnumValue: Available on TextEditingTool, provided by the TextEditingTool$Typings extension
Gets or sets the state of the TextEditingTool. The only accepted values are listed as constant properties of TextEditingTool, including:
getter/setter pair
textBlock ↔ TextBlock?: Available on TextEditingTool, provided by the TextEditingTool$Typings extension
Gets or sets the TextBlock that is being edited. This property is initially null and is set in TextEditingTool#doActivate as the TextBlock at the mouse click point. However, if you set this property beforehand, TextEditingTool#doActivate will not set it, and this tool will edit the given TextBlock.
getter/setter pair
textValidation ↔ bool Function(TextBlock, String, String)?: Available on TextEditingTool, provided by the TextEditingTool$Typings extension
Gets or sets the predicate that determines whether or not a string of text is valid. If this is non-null, this predicate is called in addition to any TextBlock#textValidation predicate. See #isValidText for more details. The default predicate is null, which is equivalent to simply returning true.
getter/setter pair
transactionResult ↔ String?: Available on Tool, provided by the Tool$Typings extension
Gets or sets the name of the transaction to be committed by #stopTransaction
getter/setter pair

Methods

acceptText(EnumValue reason) → void: Available on TextEditingTool, provided by the TextEditingTool$Typings extension
Finish editing by trying to accept the new text.
cancelWaitAfter() → void: Available on Tool, provided by the Tool$Typings extension
This is called to cancel any running "WaitAfter" timer.
canStart() → bool: Available on TextEditingTool, provided by the TextEditingTool$Typings extension
This may run when there is a mouse-click on a TextBlock for which the TextBlock#editable property is true in a Part that Part#isSelected.
canStart() → bool: Available on Tool, provided by the Tool$Typings extension
This predicate is used by the ToolManager to decide if this tool can be started mode-lessly by mouse and touch events. Implementations of this method can look at Diagram#lastInput to get the mouse event and input state.
canStartMultiTouch() → bool: Available on Tool, provided by the Tool$Typings extension
Called by ToolManager#doMouseDown and ToolManager#doMouseMove, this method determines whether or not to allow pinch zooming from a multi-touch event. By default this predicate just returns true. This method may be overridden. Please read the Introduction page on Extensions for how to override methods and how to call this base method. @expose @return {boolean} @see #standardPinchZoomStart @see #standardPinchZoomMove @since 1.5
doActivate() → void: Available on TextEditingTool, provided by the TextEditingTool$Typings extension
Start editing the text for a #textBlock.
doActivate() → void: Available on Tool, provided by the Tool$Typings extension
The Diagram calls this method after setting Diagram#currentTool, to make the new tool active. This should set #isActive to true. Overrides of this method might call #startTransaction, if this tool's activity involves modification of the model. Implementations of this method can look at Diagram#lastInput to get the mouse event and input state.
doCancel() → void: Available on TextEditingTool, provided by the TextEditingTool$Typings extension
Abort any text editing operation.
doCancel() → void: Available on Tool, provided by the Tool$Typings extension
The diagram will call this method when the user wishes to cancel the current tool's operation. Typically this is called when the user hits the ESCAPE key. This should restore the original state of what was modified by this tool, and then it should call #stopTool. This method is not responsible for cleaning up any side-effects that should be performed by #doDeactivate and/or #doStop, which will always be called whether the tool stops normally or abnormally.
doDeactivate() → void: Available on TextEditingTool, provided by the TextEditingTool$Typings extension
Release the mouse.
doDeactivate() → void: Available on Tool, provided by the Tool$Typings extension
The Diagram calls this method on the old tool when Diagram#currentTool is set to a new tool. This needs to set #isActive to false. Overrides of this method might call #stopTransaction, if this tool's activity involves modification of the model.
doError(String oldstring, String newstring) → void: Available on TextEditingTool, provided by the TextEditingTool$Typings extension
Call the #textBlock's TextBlock#errorFunction, if there is one, and then show the text editor again. This is called only when the #isValidText method returned false. The value of #state will be StateInvalid. This method may be overridden. You may wish to override this method in order to not continue showing the editor. @expose @param oldstring @param newstring @since 2.1
doKeyDown() → void: Available on Tool, provided by the Tool$Typings extension
The diagram will call this method upon a key down event. By default this just calls #doCancel if the key is the ESCAPE key. Implementations of this method can look at Diagram#lastInput to get the key.
doKeyUp() → void: Available on Tool, provided by the Tool$Typings extension
The diagram will call this method upon a key up event. Implementations of this method can look at Diagram#lastInput to get the key.
doMouseDown() → void: Available on TextEditingTool, provided by the TextEditingTool$Typings extension
This calls #acceptText with the reason TextEditingTool.MouseDown, if this tool Tool#isActive.
doMouseDown() → void: Available on Tool, provided by the Tool$Typings extension
The diagram will call this method upon a mouse down event. This is normally overridden for mouse-down tools; it is not called for mouse-move or mouse-up tools. However it may also be called when the tool is run in a modal fashion, when code explicitly sets the diagram's Diagram#currentTool. Implementations of this method can look at Diagram#lastInput to get the mouse event and input state.
doMouseMove() → void: Available on Tool, provided by the Tool$Typings extension
The diagram will call this method upon a mouse move event. This is normally overridden for mouse-move tools; it is not called for mouse-up tools. However it may also be called when the tool is run in a modal fashion, when code explicitly sets the diagram's Diagram#currentTool. An override of this method usually does nothing when #isActive is false. Implementations of this method can look at Diagram#lastInput to get the mouse event and input state.
doMouseUp() → void: Available on TextEditingTool, provided by the TextEditingTool$Typings extension
A click (mouse up) calls TextEditingTool#doActivate if this tool is not already active and if TextEditingTool#canStart returns true.
doMouseUp() → void: Available on Tool, provided by the Tool$Typings extension
The diagram will call this method upon a mouse up event. This is normally overridden for mouse-up tools. An override of this method usually does nothing when #isActive is false, except for calling #stopTool. Tools normally stop upon a mouse up, by calling #stopTool. If you want to handle multiple mouse down-up gestures in one tool activation, you will need to override this method to only stop the tool when you want. Implementations of this method can look at Diagram#lastInput to get the mouse event and input state.
doMouseWheel() → void: Available on Tool, provided by the Tool$Typings extension
The diagram will call this method as the mouse wheel is rotated. Implementations of this method can look at Diagram#lastInput to get the mouse event and input state.
doStart() → void: Available on TextEditingTool, provided by the TextEditingTool$Typings extension
This calls TextEditingTool#doActivate if there is a #textBlock set. #doActivate attempts to set #textBlock if it is null.
doStart() → void: Available on Tool, provided by the Tool$Typings extension
The Diagram calls this method when this tool becomes the current tool; you should not call this method. Tool implementations should perform their per-use initialization here, such as setting up internal data structures, or capturing the mouse. Implementations of this method can look at Diagram#lastInput to get the mouse event and input state.
doStop() → void: Available on Tool, provided by the Tool$Typings extension
The Diagram calls this method when this tool stops being the current tool; you should not call this method. Tool implementations should perform their per-use cleanup here, such as releasing mouse capture.
doSuccess(String oldstring, String newstring) → void: Available on TextEditingTool, provided by the TextEditingTool$Typings extension
Call the #textBlock's TextBlock#textEdited event handler, if there is one. This is called just after the TextBlock#text has been set to the new string value. When this method returns, this tool raises the "TextEdited" DiagramEvent and commits the transaction. This method may be overridden. @expose @param oldstring @param newstring @since 2.1
doWaitAfter(InputEvent event) → void: Available on Tool, provided by the Tool$Typings extension
This is called a certain delay after a call to #standardWaitAfter if there has not been any call to #cancelWaitAfter. The ToolManager overrides this method in order to implement support for mouse-hover behavior and tooltips.
findToolHandleAt(Point p, String category) → GraphObject?: Available on Tool, provided by the Tool$Typings extension
This convenience function finds the front-most GraphObject that is at a given point and that is an element of an Adornment that is of a given category. The tool handle must be an immediate element of the Adornment, not a GraphObject that is nested within Panels within the Adornment.
isBeyondDragSize([Point? first, Point? last]) → bool: Available on Tool, provided by the Tool$Typings extension
Return true when the last mouse point is far enough away from the first mouse down point to constitute a drag operation instead of just a potential click.
isValidText(TextBlock textblock, String oldstr, String newstr) → bool: Available on TextEditingTool, provided by the TextEditingTool$Typings extension
This predicate checks any TextBlock#textValidation predicate and this tool's #textValidation predicate to make sure the TextBlock#text property may be set to the new string.
measureTemporaryTextBlock(String text) → TextBlock: Available on TextEditingTool, provided by the TextEditingTool$Typings extension
This method returns a temporary TextBlock used for measuring text during editing. The TextBlock.text is set to the parameter's value, and the TextBlock is measured with the last available width of the #textBlock.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
standardMouseClick<T extends GraphObject>([T? navig(GraphObject)?, bool pred(T)?]) → bool: Available on Tool, provided by the Tool$Typings extension
Implement the standard behavior for mouse clicks, searching for and calling click handler functions on GraphObjects or on Diagram, and raising the corresponding DiagramEvent.
standardMouseOver() → void: Available on Tool, provided by the Tool$Typings extension
Implement the standard behavior for mouse enter, over, and leave events, where the mouse is moving but no button is pressed. This should be called by mouse move event handlers when wanting to detect and invoke mouse enter/over/leave event handlers.
standardMouseSelect() → void: Available on Tool, provided by the Tool$Typings extension
Implement the standard behavior for selecting parts with the mouse, depending on the control and shift modifier keys.
standardMouseWheel() → void: Available on Tool, provided by the Tool$Typings extension
Implement the standard behavior for mouse wheel events. ToolManager#doMouseWheel calls this method.
standardPinchZoomMove() → void: Available on Tool, provided by the Tool$Typings extension
Continues pinch-zooming (started by #standardPinchZoomStart on multi-touch devices.
standardPinchZoomStart() → void: Available on Tool, provided by the Tool$Typings extension
Initiates pinch-zooming on multi-touch devices.
standardWaitAfter(num delay, [InputEvent? event]) → void: Available on Tool, provided by the Tool$Typings extension
This is called to start a new timer to call #doWaitAfter after a given delay. It first cancels any previously running "WaitAfter" timer, by calling #cancelWaitAfter.
startTransaction([String? tname]) → bool: Available on Tool, provided by the Tool$Typings extension
Call Diagram#startTransaction with the given transaction name. This always sets #transactionResult to null.
stopTool() → void: Available on Tool, provided by the Tool$Typings extension
If the Diagram#currentTool is this tool, stop this tool and start the Diagram#defaultTool by making it be the new current tool. The implementation of various tool methods can call this method to stop the current tool. This will call #doStop -- you should not call that method directly.
stopTransaction() → bool: Available on Tool, provided by the Tool$Typings extension
If #transactionResult is null, call Diagram#rollbackTransaction, otherwise call Diagram#commitTransaction.
toString() → String: A string representation of this object.
inherited
updateAdornments(Part part) → void: Available on Tool, provided by the Tool$Typings extension
The diagram asks each tool to update any adornments the tool might use for a given part. If the tool uses its own tool handles, this should display them or hide them as appropriate. Typically this should only show them if the part is selected.

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Properties

doubleClick ↔ EnumValue: A possible value for TextEditingTool#starting, A double click on a TextBlock with TextBlock#editable property set to true will start in-place editing.
getter/setter pair
enter ↔ EnumValue: A possible value for TextEditingTool#acceptText, the user has typed ENTER.
getter/setter pair
lostFocus ↔ EnumValue: A possible value for TextEditingTool#acceptText, the text editing control has lost focus.
getter/setter pair
mouseDown ↔ EnumValue: A possible value for TextEditingTool#acceptText, the user has clicked somewhere else in the diagram.
getter/setter pair
singleClick ↔ EnumValue: A possible value for TextEditingTool#starting, A single click on a TextBlock with TextBlock#editable property set to true will start in-place editing.
getter/setter pair
singleClickSelected ↔ EnumValue: A possible value for TextEditingTool#starting, A single click on a TextBlock with TextBlock#editable property set to true will start in-place editing, but only if the Part that the TextBlock is in is already selected.
getter/setter pair
stateActive ↔ EnumValue: A possible value for #state, TextEditingTool#doActivate sets the value of #state to this.
getter/setter pair
stateEditing ↔ EnumValue: A possible value for #state, The default text editor receiving focus sets the value of #state to this.
getter/setter pair
stateInvalid ↔ EnumValue: A possible value for #state, If validation fails, TextEditingTool.acceptText sets the value of #state to this.
getter/setter pair
stateNone ↔ EnumValue: A possible value for #state, this is the starting value before the tool is activated.
getter/setter pair
stateValidated ↔ EnumValue: A possible value for #state, Once accepted and the tool begins the "TextEditing" transaction, the value of #state is set to this.
getter/setter pair
stateValidating ↔ EnumValue: A possible value for #state, TextEditingTool.acceptText sets the value of #state to this.
getter/setter pair
tab ↔ EnumValue: A possible value for TextEditingTool#acceptText, the user has typed TAB.
getter/setter pair