### Hierarchy

- Tool
  - TextEditingTool

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.

## Index

### Constructors

- constructor

### Properties

- currentTextEditor
- defaultTextEditor
- selectsTextOnActivate
- starting
- state
- textBlock
- textValidation

### Methods

- acceptText
- canStart
- doActivate
- doCancel
- doDeactivate
- doError
- doMouseDown
- doMouseUp
- doStart
- doSuccess
- isValidText
- measureTemporaryTextBlock

### Constants

- DoubleClick
- Enter
- LostFocus
- MouseDown
- SingleClick
- SingleClickSelected
- StateActive
- StateEditing
- StateInvalid
- StateNone
- StateValidated
- StateValidating
- Tab

## Inherited Members

### Properties

- Tool.diagram
- Tool.isActive
- Tool.isEnabled
- Tool.name
- Tool.transactionResult

### Methods

- Tool.canStartMultiTouch
- Tool.cancelWaitAfter
- Tool.doKeyDown
- Tool.doKeyUp
- Tool.doMouseMove
- Tool.doMouseWheel
- Tool.doWaitAfter
- Tool.findToolHandleAt
- Tool.isBeyondDragSize
- Tool.standardMouseClick
- Tool.standardMouseOver
- Tool.standardMouseSelect
- Tool.standardMouseWheel
- Tool.standardPinchZoomMove
- Tool.standardPinchZoomStart
- Tool.standardWaitAfter
- Tool.startTransaction
- Tool.stopTool
- Tool.stopTransaction
- Tool.updateAdornments

## Constructors

### constructor

- new TextEditingTool(): TextEditingTool

- 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".

  #### Returns TextEditingTool

## Properties

### currentTextEditor: HTMLInfo

- Gets or sets the HTMLInfo that is editing the text.

### defaultTextEditor: HTMLInfo

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

### selectsTextOnActivate: boolean

- Gets or sets whether to select (highlight) the editable text when the TextEditingTool is activated. The default is true.

  since

    1.5

### starting: EnumValue

- Gets or sets how user gestures can start in-place editing of text.

  Possible values are TextEditingTool.SingleClickSelected, TextEditingTool.SingleClick, and TextEditingTool.DoubleClick.

  The default is TextEditingTool.SingleClickSelected

### state: EnumValue

- Gets or sets the state of the TextEditingTool. The only accepted values are listed as constant properties of TextEditingTool, including:

  - TextEditingTool.StateNone
  - TextEditingTool.StateActive
  - TextEditingTool.StateEditing
  - TextEditingTool.StateValidating
  - TextEditingTool.StateValidated

  The starting value value is TextEditingTool.StateNone, TextEditingTool.doActivate sets the value to TextEditingTool.StateActive. The default text editor receiving focus sets the value to TextEditingTool.StateEditing. TextEditingTool.acceptText sets the value to TextEditingTool.StateValidating. Once accepted and the tool begins the "TextEditing" transaction, the value is set to TextEditingTool.StateValidated.

  since

    1.7

### textBlock: TextBlock

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

### textValidation: (aTextBlock: TextBlock, oldString: string, newString: string) => boolean

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

## Methods

### Virtual acceptText

- acceptText(reason: EnumValue): void

- Finish editing by trying to accept the new text.

  Please read the Introduction page on Extensions for how to override methods and how to call this base method.

  #### Parameters

  - ##### reason: EnumValue

    The reason must be either TextEditingTool.LostFocus, TextEditingTool.MouseDown, TextEditingTool.Tab, or TextEditingTool.Enter.

  #### Returns void

### Override Virtual canStart

- canStart(): boolean

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

  This method may be overridden. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

  #### Returns boolean

### Override doActivate

- doActivate(): void

- Start 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.

  #### Returns void

### Override doCancel

- doCancel(): void

- Abort any text editing operation.

  #### Returns void

### Override doDeactivate

- doDeactivate(): void

- Release the mouse.

  If the currentTextEditor is an HTMLInfo, this calls HTMLInfo.hide.

  #### Returns void

### Virtual doError

- doError(oldstring: string, newstring: string): void

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

  since

    2.1

  #### Parameters

  - ##### oldstring: string

  - ##### newstring: string

  #### Returns void

### Override doMouseDown

- doMouseDown(): void

- This calls acceptText with the reason TextEditingTool.MouseDown, if this tool Tool.isActive.

  #### Returns void

### Override doMouseUp

- doMouseUp(): void

- A click (mouse up) calls TextEditingTool.doActivate if this tool is not already active and if TextEditingTool.canStart returns true.

  #### Returns void

### Override doStart

- doStart(): void

- This calls TextEditingTool.doActivate if there is a textBlock set. doActivate attempts to set textBlock if it is null.

  #### Returns void

### Virtual doSuccess

- doSuccess(oldstring: string, newstring: string): void

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

  since

    2.1

  #### Parameters

  - ##### oldstring: string

  - ##### newstring: string

  #### Returns void

### Virtual isValidText

- isValidText(textblock: TextBlock, oldstr: string, newstr: string): boolean

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

  This method may be overridden, although usually it is sufficient to set textValidation. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

  #### Parameters

  - ##### textblock: TextBlock

    the TextBlock that is being edited.

  - ##### oldstr: string

    the previous string value.

  - ##### newstr: string

    the proposed new string value.

  #### Returns boolean

  true if the new string is valid for the given TextBlock.

### measureTemporaryTextBlock

- measureTemporaryTextBlock(text: string): 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.

  since

    1.7

  #### Parameters

  - ##### text: string

    the text to measure

  #### Returns TextBlock

## Constants

### Static 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.

### Static Enter: EnumValue

A possible value for TextEditingTool.acceptText, the user has typed ENTER.

### Static LostFocus: EnumValue

A possible value for TextEditingTool.acceptText, the text editing control has lost focus.

### Static MouseDown: EnumValue

A possible value for TextEditingTool.acceptText, the user has clicked somewhere else in the diagram.

### Static 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.

### Static 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.

### Static StateActive: EnumValue

A possible value for state, TextEditingTool.doActivate sets the value of state to this.

### Static StateEditing: EnumValue

A possible value for state, The default text editor receiving focus sets the value of state to this.

### Static StateInvalid: EnumValue

A possible value for state, If validation fails, TextEditingTool.acceptText sets the value of state to this.

### Static StateNone: EnumValue

A possible value for state, this is the starting value before the tool is activated.

### Static StateValidated: EnumValue

A possible value for state, Once accepted and the tool begins the "TextEditing" transaction, the value of state is set to this.

### Static StateValidating: EnumValue

A possible value for state, TextEditingTool.acceptText sets the value of state to this.

### Static Tab: EnumValue

A possible value for TextEditingTool.acceptText, the user has typed TAB.

Copyright © 1998-2022 by Northwoods Software Corporation.