You do not normally need to create an instance of this tool because one already exists as the ToolManager.textEditingTool, which you can modify.
The Tool.name of this tool is "TextEditing".
Optionalinit: Partial<TextEditingTool>Gets or sets the default HTMLInfo that edits the text.
When TextEditingTool.doActivate is called, the currentTextEditor is set to this value by default. If a TextBlock.textEditor is specified on the TextBlock, that editor is used instead.
This tool will call HTMLInfo.show during doActivate, and HTMLInfo.hide during doDeactivate.
By default the value is an HTMLInfo, and the HTMLInfo.mainElement is an HTMLTextArea.
You can see the default implementation details here.
For typical operation, HTMLInfo implementations should have a way of calling TextEditingTool.acceptText.
Gets or sets whether this tool is started and is actively doing something.
You can set this to true after your tool is started (i.e. when it is the Diagram.currentTool and doStart had been called), but when it is not yet in a state that it is actually "doing" something, because it is waiting for the right circumstances. This is typically only important when the tool is used in a modal fashion.
The default value is false. This is normally set by doActivate and doDeactivate.
Gets or sets whether this tool can be started by a mouse event.
Set this to false to prevent canStart from returning true. Setting this property to false should prevent this tool from being used in a mode-less fashion by the ToolManager with a mouse down/move/up event. However, even when this property is false, this tool can still be used in a modal fashion: it can still be started by explicitly setting the Diagram.currentTool property to this tool.
The default value is true.
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".
This name is sometimes used by tools that use Adornments as the Part.category for their Adornments. It is also sometimes used by tools that conduct transactions as the transaction name.
Gets or sets whether to select (highlight) the editable text when the TextEditingTool is activated. The default is true.
Gets or sets how user gestures can start in-place editing of text.
Possible values are TextEditingStarting values.
The default is TextEditingStarting.SingleClickSelected
Gets or sets the state of the TextEditingTool. The only accepted values are TextEditingState values.
The starting value value is TextEditingState.None, TextEditingTool.doActivate sets the value to TextEditingState.Active. The default text editor receiving focus sets the value to TextEditingState.Editing. TextEditingTool.acceptText sets the value to TextEditingState.Validating. Once accepted and the tool begins the "TextEditing" transaction, the value is set to TextEditingState.Validated.
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.
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.
The function, if supplied, must not have any side-effects.
Gets or sets the name of the transaction to be committed by stopTransaction
If null, the transaction will be rolled back.
If this is non-null at the time of a call to stopTransaction, it calls Diagram.commitTransaction with this transaction name; if this is null at that time, it calls Diagram.rollbackTransaction.
The default value is null; startTransaction will also set this to null. Because a value of null when stopTransaction is called will rollback the transaction, it is important that your code sets this property to a non-null value when it thinks it has succeeded.
This property exists so that no matter what execution path occurs to end the usage of a tool, any ongoing transaction can be properly committed or rolled-back. Many tools call startTransaction and stopTransaction; thus they set this property for their transaction to be committed. doCancel also sets this property to null.
VirtualacceptFinish editing by trying to accept the new text.
Please read the Learn page on Extensions for how to override methods and how to call this base method.
The reason must be a TextEditingAccept value.
VirtualcancelThis is called to cancel any running "WaitAfter" timer.
This is called when a tool is stopped.
This method is rarely overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
Virtual OverridecanThis 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.
This method may be overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
VirtualcanThis method controls for some Tools whether canStart may return true depending on the button being used. Normally this returns true if InputEvent.left is true. This method may be overridden to consider other buttons, or to ignore which button by just returning true.
true, if the left mouse button is being held down
since4.0
VirtualcanAs of version 4, this predicate method is no longer called by the ToolManager. Most of the responsibility for pinch zooming has been moved to the PanningTool.
deprecatedOverridedoStart editing the text for a textBlock.
If TextEditingTool.textBlock is not already specified, this looks for one at the current mouse point. If none is found, this method does nothing.
This method sets currentTextEditor.
If TextBlock.textEditor is defined on the TextBlock it will use that as the value.
By default, it uses the value of defaultTextEditor, which is an HTMLInfo
showing an HTML textarea, with the CSS class goTXarea.
If the currentTextEditor is an HTMLInfo, this method calls HTMLInfo.show on that instance.
This sets Tool.isActive to true. Custom text editors should call TextEditingTool.acceptText to finish the edit by modifying the TextBlock and committing the edit transaction. Or call TextEditingTool.doCancel to abort the edit.
OverridedoAbort any text editing operation.
OverridedoRelease the mouse.
If the currentTextEditor is an HTMLInfo, this calls HTMLInfo.hide.
VirtualdoCall 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.
since2.1
VirtualdoThe 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.
This method may be overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
VirtualdoThe diagram will call this method upon a key up event. Implementations of this method can look at Diagram.lastInput to get the key.
By default this method does nothing. This method may be overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
OverridedoThis calls acceptText with the reason TextEditingAccept.MouseDown, if this tool Tool.isActive.
VirtualdoThe 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.
By default this method does nothing. This method may be overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
OverridedoA click (mouse up) calls TextEditingTool.doActivate if this tool is not already active and if TextEditingTool.canStart returns true.
VirtualdoThe 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.
By default this method does nothing. (But the ToolManager.doMouseWheel override will call Tool.standardMouseWheel.) This method may be overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
OverridedoThis calls TextEditingTool.doActivate if there is a textBlock set. doActivate attempts to set textBlock if it is null.
VirtualdoCall 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.
since2.1
VirtualdoThis 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.
By default this does nothing. This method may be overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
The event that caused standardWaitAfter.
VirtualfindThis 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.
This method is very infrequently overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
a Point in document coordinates.
the required Part.category of the Adornment.
VirtualisReturn 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.
This uses the value of ToolManager.dragSize. On touch devices the value is automatically increased to accommodate the unavoidable movement of fingers.
This method may be overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
Optionalfirst: PointPoint in view coordinates, defaults to Diagram.firstInput's InputEvent.viewPoint.
Optionallast: PointPoint in view coordinates, defaults to Diagram.lastInput's InputEvent.viewPoint.
VirtualisThis 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.
This method may be overridden, although usually it is sufficient to set textValidation. Please read the Learn page on Extensions for how to override methods and how to call this base method.
true if the new string is valid for the given TextBlock.
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.
Text editors can use the GraphObject.measuredBounds and TextBlock.lineCount to determine a reasonable size for their text areas.
the text to measure
VirtualstandardImplement the standard behavior for mouse clicks, searching for and calling click handler functions on GraphObjects or on Diagram, and raising the corresponding DiagramEvent.
A click on a GraphObject of the diagram will raise one of the following DiagramEvents: "ObjectSingleClicked", "ObjectDoubleClicked", or "ObjectContextClicked". This will also look at the corresponding click property: GraphObject.click, GraphObject.doubleClick, or GraphObject.contextClick. If the value is a function, this will call it, passing the current InputEvent and the GraphObject. If the value is null, it tries looking at the parent GraphObject.panel, and so on, walking up the visual tree until it finds the appropriate function to call. After calling the click function, if the value of InputEvent.handled is false, this method will continue walking up the visual tree looking for more click functions to call. Once it has looked at the top-level object (a Part) for a click function, this method stops.
A click in the background of the diagram will raise one of the following DiagramEvents: "BackgroundSingleClicked", "BackgroundDoubleClicked", or "BackgroundContextClicked". This will also look at the corresponding click property: Diagram.click, Diagram.doubleClick, or Diagram.contextClick. If the value is a function, this will call it, passing the current InputEvent.
This method is not responsible for selecting or deselecting any parts. Call standardMouseSelect for that functionality.
Note that this calls GraphObject.isEnabledObject on the target object; if it returns false, no click action will occur.
The ClickSelectingTool calls this method in its override of doMouseUp in order to raise "click" events. Note that by default GraphObjects in Layers that are Layer.isTemporary will not be "clicked". To change that behavior it is easiest to set GraphObject.isActionable to true on those objects for which you wish to handle "click" events. Then the ActionTool's doMouseUp override will raise the standard "click" events.
This method may be overridden, but you should consider calling this base method in order to get all of its functionality. Please read the Learn page on Extensions for how to override methods and how to call this base method.
Optionalnavig: ((a: GraphObject) => T | null) | nullAn optional custom navigation function to find target objects. This argument is passed to Diagram.findObjectAt.
Optionalpred: ((a: T) => boolean) | nullAn optional custom predicate function to find target objects. A null value is effectively the same as a function that always returns true. This argument is passed to Diagram.findObjectAt, unless the value is undefined, which means to use a predicate to consider only objects in layers holding permanent objects.
true if InputEvent.handled had been set to true on the Diagram.lastInput.
VirtualstandardImplement 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.
The GraphObject.mouseEnter property provides a function to call when the mouse first enters an object or any of its contained objects (if the object is actually a Panel).
The GraphObject.mouseLeave property provides a function to call when the mouse leaves an object and all of its contained objects (if the object is actually a Panel).
The GraphObject.mouseOver property and Diagram.mouseOver properties provide functions to call when the mouse moves but stays within the same GraphObject or when the mouse moves in the background of the Diagram.
This method is also responsible for updating the Diagram.currentCursor according to the value of GraphObject.cursor and Diagram.defaultCursor.
This method may be overridden, but you should consider calling this base method in order to get all of its functionality. Please read the Learn page on Extensions for how to override methods and how to call this base method.
VirtualstandardImplement the standard behavior for selecting parts with the mouse, depending on the control and shift modifier keys.
Control-clicking on a part will select it if it wasn't already, and will deselect if it had been selected. Shift-clicking on a part will add it to the selection (if it wasn't already). Otherwise, clicking on a part will select it (if it wasn't already).
Note that there are restrictions on selection. For example, a part cannot be selected in this manner if Part.selectable is false, or if Diagram.maxSelectionCount would be exceeded.
A left click in the background of the diagram with no modifier keys clears the selection.
This method does not implement any click event behavior -- that is implemented by standardMouseClick.
The ClickSelectingTool calls this method in its override of doMouseUp in order to change the selection.
This method may be overridden, but you should consider calling this base method in order to get all of its functionality. Please read the Learn page on Extensions for how to override methods and how to call this base method.
VirtualstandardImplement the standard behavior for mouse wheel events. ToolManager.doMouseWheel calls this method.
Turning the mouse wheel if Diagram.allowVerticalScroll is true causes the diagram to scroll up or down. If InputEvent.shift and Diagram.allowHorizontalScroll are true, the diagram scrolls left or right.
If InputEvent.control and Diagram.allowZoom are true, turning the mouse wheel changes the diagram's scale, zooming in or out while trying to keep the point in the model at the same point as the mouse.
The value of ToolManager.mouseWheelBehavior affects what operations might occur upon mouse wheel events.
This method may be overridden, but you should consider calling this base method in order to get all of its functionality. Please read the Learn page on Extensions for how to override methods and how to call this base method.
VirtualstandardAs of version 4, this method is no longer called by the ToolManager. Most of the responsibility for pinch zooming has been moved to the PanningTool.
deprecatedVirtualstandardAs of version 4, this method is no longer called by the ToolManager. Most of the responsibility for pinch zooming has been moved to the PanningTool.
deprecatedVirtualstandardThis 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.
This is normally used to implement mouse hover and mouse hold events. If the mouse has moved, it must not have moved beyond the distance as determined by Tool.isBeyondDragSize for it be considered "stationary". So the regular ToolManager.doMouseMove implementation only calls this method when the mouse has moved beyond the drag size.
This method is rarely overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
The delay, in milliseconds.
Optionalevent: InputEventAn optional event that caused this timer. Defaults to Diagram.lastInput. This gets passed on to doWaitAfter.
Call Diagram.startTransaction with the given transaction name. This always sets transactionResult to null.
This is normally called in an override of doActivate, if the tool modifies the model, along with a call to stopTransaction in an override of doDeactivate. Alternatively, you can surround a block of code that sets the transactionResult with calls to startTransaction and stopTransaction.
Optionaltname: stringa string describing the transaction.
the value of the call to Diagram.startTransaction.
VirtualstopIf 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.
If you want to stop the current tool and have it restore the original state, call doCancel. Please read the Learn page on Extensions for how to override methods and how to call this base method.
VirtualstopIf transactionResult is null, call Diagram.rollbackTransaction, otherwise call Diagram.commitTransaction.
This is normally called in an override of doDeactivate,
if startTransaction was called in doActivate.
Alternatively, you can surround a block of code that sets the transactionResult
with calls to startTransaction and stopTransaction.
This method may be overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
the result of the call to rollback or commit the transaction.
VirtualupdateThe 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.
By default this method does nothing. This method may be overridden. Please read the Learn page on Extensions for how to override methods and how to call this base method.
Static ReadonlyDoubledeprecated
Static ReadonlyEnterdeprecated
Static ReadonlyLostdeprecated
Static ReadonlyMousedeprecated
Static ReadonlySingledeprecated
Static ReadonlySingledeprecated
Static ReadonlyStatedeprecated
Static ReadonlyStatedeprecated
Static ReadonlyStatedeprecated
Static ReadonlyStatedeprecated
Static ReadonlyStatedeprecated
Static ReadonlyStatedeprecated
Static ReadonlyTabdeprecated
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: Learn page on Text Validation. For customizing the TextEditingTool, read about HTMLInfo and see Learn page on Text Editors.