Class TextEditingTool

GoDiagram®
v10.0.8
by Northwoods Software®

The TextEditingTool is used to let the user interactively edit text in place. This sets the 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.

Inheritance

object

Tool

TextEditingTool

Namespace: Northwoods.Go.Tools

Assembly: Northwoods.GoDiagram.WinForms.dll

Syntax

public class TextEditingTool : Tool

Remarks

Typically this is used by setting the 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 EditTextBlock(TextBlock) command, this tool is started and it uses an HTMLTextArea to perform in-place text editing. (For more details see the description for DoActivate().)

The TextBlock is accessible as the TextBlock property. The text editor is accessible as the 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 TextBlock property.

You can disable mouse clicking from starting this text editing tool by setting IsEnabled to false. You can disable the F2 key from starting this text editing tool by making sure CanEdit() returns false, by either setting AllowTextEdit to false or by setting TextEditable to false.

If you want to programmatically start the user editing a particular TextBlock, call EditTextBlock(TextBlock). 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 IHostInfo and see Introduction to Text Editors.

Constructors

TextEditingTool()

You do not normally need to create an instance of this tool because one already exists as the TextEditingTool, which you can modify.

The Name of this tool is "TextEditing".

Declaration

public TextEditingTool()

Properties

CurrentTextEditor

Gets or sets the IHostInfo that is editing the text.

Declaration

public IHostInfo CurrentTextEditor { get; set; }

Property Value

Type	Description
IHostInfo

DefaultTextEditor

Gets or sets the default IHostInfo that edits the text.

Declaration

public IHostInfo DefaultTextEditor { get; set; }

Property Value

Type	Description
IHostInfo

Remarks

When DoActivate() is called, the CurrentTextEditor is set to this value by default. If a TextEditor is specified on the TextBlock, that editor is used instead.

This tool will call Show(GraphObject, Diagram, Tool) during DoActivate(), and Hide(Diagram, Tool) during DoDeactivate().

By default the value is an IHostInfo.

For typical operation, IHostInfo implementations should have a way of calling AcceptText(TextEditingAccept).

SelectsTextOnActivate

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

Declaration

public bool SelectsTextOnActivate { get; set; }

Property Value

Type	Description
bool

Remarks

The default is true.

Starting

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

Declaration

public TextEditingStarting Starting { get; set; }

Property Value

Type	Description
TextEditingStarting

Remarks

Possible values are SingleClickSelected, SingleClick, and DoubleClick.

The default is SingleClickSelected

State

Gets or sets the state of the TextEditingTool.

Declaration

public TextEditingState State { get; set; }

Property Value

Type	Description
TextEditingState

Remarks

The only accepted values are listed as constant properties of TextEditingTool, including:

• None
• Active
• Editing
• Validating
• Validated

The starting value value is None, DoActivate() sets the value to Active. The default text editor receiving focus sets the value to Editing. AcceptText(TextEditingAccept) sets the value to Validating. Once accepted and the tool begins the "TextEditing" transaction, the value is set to Validated.

TextBlock

Gets or sets the TextBlock that is being edited.

Declaration

public TextBlock TextBlock { get; set; }

Property Value

Type	Description
TextBlock

Remarks

This property is initially null and is set in DoActivate() as the TextBlock at the mouse click point. However, if you set this property beforehand, DoActivate() will not set it, and this tool will edit the given TextBlock.

TextValidation

Gets or sets the predicate that determines whether or not a string of text is valid.

Declaration

public Func<TextBlock, string, string, bool> TextValidation { get; set; }

Property Value

Type	Description
Func<TextBlock, string, string, bool>

Remarks

If this is non-null, this predicate is called in addition to any TextValidation predicate. See IsValidText(TextBlock, string, string) 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

AcceptText(TextEditingAccept)

Finish editing by trying to accept the new text.

Declaration

public virtual void AcceptText(TextEditingAccept reason)

Parameters

Type	Name	Description
TextEditingAccept	reason	The reason must be either LostFocus, MouseDown, Tab, or Enter.

Remarks

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

CanStart()

This may run when there is a mouse-click on a TextBlock for which the Editable property is true in a Part that IsSelected.

Declaration

public override bool CanStart()

Returns

Type	Description
bool

Overrides

Tool.CanStart()

Remarks

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

DoActivate()

Start editing the text for a TextBlock.

Declaration

public override void DoActivate()

Overrides

Tool.DoActivate()

Remarks

If 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 TextEditor is defined on the TextBlock it will use that as the value. By default, it uses the value of DefaultTextEditor, which is an IHostInfo showing a context-dependent text editor.

If the CurrentTextEditor is an IHostInfo, this method calls Show(GraphObject, Diagram, Tool) on that instance.

This sets IsActive to true. Custom text editors should call AcceptText(TextEditingAccept) to finish the edit by modifying the TextBlock and committing the edit transaction. Or call DoCancel() to abort the edit.

DoCancel()

Abort any text editing operation.

Declaration

public override void DoCancel()

Overrides

Tool.DoCancel()

DoDeactivate()

Release the mouse.

If the CurrentTextEditor is an IHostInfo, this calls Hide(Diagram, Tool).

Declaration

public override void DoDeactivate()

Overrides

Tool.DoDeactivate()

DoError(string, string)

Call the TextBlock's ErrorFunction, if there is one, and then show the text editor again.

Declaration

public virtual void DoError(string oldstring, string newstring)

Parameters

Type	Name	Description
string	oldstring
string	newstring

Remarks

This is called only when the IsValidText(TextBlock, string, string) method returned false. The value of State will be Invalid. This method may be overridden. You may wish to override this method in order to not continue showing the editor.

DoMouseDown()

This calls AcceptText(TextEditingAccept) with the reason MouseDown, if this tool IsActive.

Declaration

public override void DoMouseDown()

Overrides

Tool.DoMouseDown()

DoMouseUp()

A click (mouse up) calls DoActivate() if this tool is not already active and if CanStart() returns true.

Declaration

public override void DoMouseUp()

Overrides

Tool.DoMouseUp()

DoStart()

This calls DoActivate() if there is a TextBlock set. DoActivate() attempts to set TextBlock if it is null.

Declaration

public override void DoStart()

Overrides

Tool.DoStart()

DoSuccess(string, string)

Call the TextBlock's TextEdited event handler, if there is one.

Declaration

public virtual void DoSuccess(string oldstring, string newstring)

Parameters

Type	Name	Description
string	oldstring
string	newstring

Remarks

This is called just after the 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.

IsValidText(TextBlock, string, string)

This predicate checks any TextValidation predicate and this tool's TextValidation predicate to make sure the Text property may be set to the new string.

Declaration

public virtual bool IsValidText(TextBlock textblock, string oldstr, string newstr)

Parameters

Type	Name	Description
TextBlock	textblock	the TextBlock that is being edited.
string	oldstr	the previous string value.
string	newstr	the proposed new string value.

Returns

Type	Description
bool	true if the new string is valid for the given TextBlock.

Remarks

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.

MeasureTemporaryTextBlock(string)

This method returns a temporary TextBlock used for measuring text during editing.

Declaration

public TextBlock MeasureTemporaryTextBlock(string text)

Parameters

Type	Name	Description
string	text	the text to measure

Returns

Type	Description
TextBlock

Remarks

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 MeasuredBounds and LineCount to determine a reasonable size for their text areas.