Class TextBlock

GoDiagram®
v10.0.8
by Northwoods Software®

A TextBlock is a GraphObject that displays a Text string in a given Font.

Inheritance
object
GraphObject
TextBlock
Namespace: Northwoods.Go
Assembly: Northwoods.GoDiagram.WinForms.dll
Syntax
public class TextBlock : GraphObject, IHasContextMenu, IHasToolTip
Remarks

The size and appearance of the text is specified by Font.

Text is drawn using the Stroke brush, which may be any CSS color string or a Brush.

A created TextBlock:

// A TextBlock with text and stroke properties set:
new TextBlock("Hello World") { Stroke = "gray" }

TextBlocks typically receive a natural size based on their text and font strings, but often a width is given in order to cause the text to wrap at a certain place. In order for wrapping to occur, the Wrap property must not be None.

TextBlocks can be edited by users using the TextEditingTool. The IHostInfo that a given TextBlock uses as its text editor can be customized by setting the TextEditor property.

For examples of TextBlock possibilities and functionality, see the Introduction page on TextBlocks.

Constructors

TextBlock()

Constructs a new TextBlock with no string to show; if it had a string, it would draw the text, wrapping if needed, in the default font using a black stroke.

Declaration
public TextBlock()

TextBlock(string)

Constructs a new TextBlock with the given text string; draws the text, wrapping if needed, in the default font using a black stroke.

Declaration
public TextBlock(string txt)
Parameters
Type Name Description
string txt

Properties

Choices

Gets or sets the an array of possible choices for a custom TextEditingTool.

Declaration
public IList<string> Choices { get; set; }
Property Value
Type Description
IList<string>
Remarks

The value must be an array of strings.

The default value is null.

Editable

Gets or sets whether or not this TextBlock allows in-place editing of the Text string by the user with the help of the TextEditingTool.

Declaration
public bool Editable { get; set; }
Property Value
Type Description
bool
Remarks

The default is false.

See also TextEditable.

ErrorFunction

Gets or sets the function to call if a text edit made with the TextEditingTool is invalid.

Declaration
public Action<TextEditingTool, string, string> ErrorFunction { get; set; }
Property Value
Type Description
Action<TextEditingTool, string, string>
Remarks

The default is null.

Flip

Gets or sets how the TextBlock is displayed: Either normally or with a Horizontal or Vertical flip or both.

Declaration
public Flip Flip { get; set; }
Property Value
Type Description
Flip
Remarks

Possible values are None, Horizontal, Vertical, or Both. The default is None.

Font

Gets or sets the current font settings.

Declaration
public Font Font { get; set; }
Property Value
Type Description
Font
Remarks

The default font is new Font("Segoe UI", 13).

Formatting

Gets or sets the policy for trimming whitespace on each line of text.

Declaration
public Format Formatting { get; set; }
Property Value
Type Description
Format
Remarks

Possible values are Trim, which trims whitespace before and after every line of text, or None, which will not trim any whitespace and may be useful for preformatted text.

The default value is Trim.

See Also

GraduatedFunction

Gets or sets the function to convert from a value along a "Graduated" Panel to a string.

Declaration
public Func<double, TextBlock, string> GraduatedFunction { get; set; }
Property Value
Type Description
Func<double, TextBlock, string>
Remarks

The default returns a string representing the value rounded to at most 2 decimals.

The function takes a number argument, a value between GraduatedMin and GraduatedMax, and this TextBlock. The function will return a string, the text that will appear at the value of the argument.

Note that the second argument is not a particular label that would be rendered at the given value. The function, if supplied, must not have any side-effects.

GraduatedSkip

Gets or sets the function to determine which values along a "Graduated" Panel will be skipped.

Declaration
public Func<double, GraphObject, bool> GraduatedSkip { get; set; }
Property Value
Type Description
Func<double, GraphObject, bool>
Remarks

The default is null and doesn't skip any text labels.

The function takes a number argument, a value between GraduatedMin and GraduatedMax, and this TextBlock. The function will return a bool, whether the text label will be skipped at the value of the argument.

Note that the second argument is not a particular label that would be rendered at the given value. The function, if supplied, must not have any side-effects.

Interval

Gets or sets how frequently this text should be drawn within a "Graduated" Panel, in multiples of the GraduatedTickUnit.

Declaration
public int Interval { get; set; }
Property Value
Type Description
int
Remarks

The default is 1. Any new value must be a positive integer.

IsMultiline

Gets or sets whether or not the text displays multiple lines or embedded newlines.

Declaration
public bool IsMultiline { get; set; }
Property Value
Type Description
bool
Remarks

If this is false, all characters including and after the first newline will be omitted. The default is true.

See Also

IsStrikethrough

Gets or sets whether or not the text has a strikethrough line (line-through).

Declaration
public bool IsStrikethrough { get; set; }
Property Value
Type Description
bool
Remarks

The default is false.

See Also

IsUnderline

Gets or sets whether or not the text is underlined.

Declaration
public bool IsUnderline { get; set; }
Property Value
Type Description
bool
Remarks

The default is false.

See Also

LineCount

This read-only property returns the total number of lines in this TextBlock, including lines created from embedded newlines (\n), Wrapping, and MaxLines.

Declaration
public int LineCount { get; }
Property Value
Type Description
int
Remarks

This value may be meaningless before the TextBlock is measured.

See Also

LineHeight

This read-only property returns the height of a line of text in this TextBlock, not including any Northwoods.Go.TextBlock.SpacingAbove or Northwoods.Go.TextBlock.SpacingBelow.

Declaration
public double LineHeight { get; }
Property Value
Type Description
double
See Also

MaxLines

Gets or sets the maximum number of lines that this TextBlock can display.

Declaration
public int MaxLines { get; set; }
Property Value
Type Description
int
Remarks

Value must be a greater than zero whole number or int.MaxValue. The default is int.MaxValue.

Modifying this value may modify the computed height of the TextBlock. If MaxLines is set, the value of LineCount will never be larger than MaxLines.

See Also

NaturalBounds

This read-only property returns the natural bounds of this TextBlock in local coordinates, as determined by its Font and Text string, and optionally its DesiredSize.

Declaration
public override Rect NaturalBounds { get; }
Property Value
Type Description
Rect
Overrides

Overflow

Gets or sets how text that is too long to display should be handled.

Declaration
public Overflow Overflow { get; set; }
Property Value
Type Description
Overflow
Remarks

Possible values are Clip and Ellipsis. For OverflowEllipsis to work, you must constrain the available size of the TextBlock in some way, such as setting Wrap to None, or limiting the number of lines with MaxLines or a height constraint.

The default value is Clip.

See Also

Stroke

Gets or sets the Brush that describes the stroke (color) of the text that is drawn.

Declaration
public Brush Stroke { get; set; }
Property Value
Type Description
Brush
Remarks

The default value is a solid black brush. Any valid CSS string can specify a solid color, and the Brush class can be used to specify a gradient or pattern. More information about the syntax of CSS color strings is available at: CSS colors (mozilla.org).

Text

Gets or sets the TextBlock's text string.

Declaration
public string Text { get; set; }
Property Value
Type Description
string
Remarks

The default is an empty string. The text of a TextBlock, along with the values of Font, Wrap, IsMultiline and sizing restrictions are what naturally determine the size of the TextBlock.

The text in textblocks can include manual line-breaks by using the character escape, \n.

Leading and trailing whitespace is eliminated in each line of TextBlock text.

If Editable is set to true, users can edit textblocks with the TextEditingTool.

TextAlign

Gets or sets the alignment location in the TextBlock's given space.

Declaration
public TextAlign TextAlign { get; set; }
Property Value
Type Description
TextAlign
Remarks

Possible values are Start, End, Left, Right, Center.

This property is most pertinent when the TextBlock has multiple lines of text, or when the TextBlock is given a size that differs from the text's natural size (such as with DesiredSize).

In left-to-right writing systems, Start and Left are synonymous, as are End and Right.

The default is Start.

See Also

TextEdited

Gets or sets the function that is called after the TextBlock's text has been edited by the TextEditingTool.

Declaration
public Action<TextBlock, string, string> TextEdited { get; set; }
Property Value
Type Description
Action<TextBlock, string, string>
Remarks

The first argument is a reference to this TextBlock. The second argument is the previous text, before editing. The third argument is the current text, which is also TextBlock.Text.

(textBlock, previousText, currentText) => { ... }

The default value is null -- no function is called.

TextEditor

Gets or sets the IHostInfo that this TextBlock uses as its text editor in the TextEditingTool.

Declaration
public IHostInfo TextEditor { get; set; }
Property Value
Type Description
IHostInfo
Remarks

If null, the TextBlock will use the default text editor of the TextEditingTool. The default is null. The value should be set to an instance of IHostInfo. Setting this property might not affect any ongoing text editing operation.

TextValidation

Gets or sets the predicate that determines whether or not a user-edited 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, the predicate is called in addition to any TextValidation predicate. See IsValidText(TextBlock, string, string) for more details.

(textBlock, oldString, newString) => { // return bool }

The default predicate is null, which is equivalent to simply returning true.

The function, if supplied, must not have any side-effects, and must return true or false.

See Also

VerticalAlignment

Gets or sets the vertical alignment Spot of this TextBlock, used when the TextBlock has more available vertical space than it needs to draw all lines.

Declaration
public Spot VerticalAlignment { get; set; }
Property Value
Type Description
Spot
Remarks

The default value is Top, which aligns the TextBlock to the top of its available space.

The TextAlign is often used along with this property to specify where the should be positioned in its available space.

This does not affect TextBlock coordinates or bounds, it only affects where text is drawn within the given area.

See Also

Wrap

Gets or sets whether the text should be wrapped if it is too long to fit on one line.

Declaration
public Wrap Wrap { get; set; }
Property Value
Type Description
Wrap
Remarks

Possible values are DesiredSize, Fit, BreakAll, and None.

The default value is DesiredSize.

See Also

Methods

GetBaseline()

Gets the function that, given the TextBlock and numerical text height, computes the position to draw the baseline of a line of text in all TextBlocks.

Declaration
public static Func<TextBlock, double, double> GetBaseline()
Returns
Type Description
Func<TextBlock, double, double>
Remarks

By default this is null and default behavior returns (textHeight * 0.75).

This computation affects drawing only, and does not change TextBlock measurement calculations.

GetUnderline()

Gets the function that, given the TextBlock and numerical text height, computes the position to draw the underline of a line of text in all TextBlocks.

Declaration
public static Func<TextBlock, double, double> GetUnderline()
Returns
Type Description
Func<TextBlock, double, double>
Remarks

By default this is null and default behavior returns (textHeight * 0.75).

This computation affects drawing only, and does not change TextBlock measurement calculations.

SetBaseline(Func<TextBlock, double, double>)

Sets the function that, given the TextBlock and numerical text height, computes the position to draw the baseline of a line of text in all TextBlocks.

Declaration
public static void SetBaseline(Func<TextBlock, double, double> value)
Parameters
Type Name Description
Func<TextBlock, double, double> value
Remarks

This computation affects drawing only, and does not change TextBlock measurement calculations. It is expected this method will be called before or during initialization of any Diagram. Diagrams will not redraw when this method has been called, and you should call Diagram.Redraw() if you are calling this method outside of your initialization.

SetUnderline(Func<TextBlock, double, double>)

Sets the function that, given the TextBlock and numerical text height, computes the position to draw the underline of a line of text in all TextBlocks.

Declaration
public static void SetUnderline(Func<TextBlock, double, double> value)
Parameters
Type Name Description
Func<TextBlock, double, double> value
Remarks

This computation affects drawing only, and does not change TextBlock measurement calculations. It is expected this method will be called before or during initialization of any Diagram. Diagrams will not redraw when this method has been called, and you should call Diagram.Redraw() if you are calling this method outside of your initialization.

Implements