### Hierarchy

- GraphObject
  - TextBlock

A TextBlock is a GraphObject that displays a text string in a given font.

The size and appearance of the text is specified by font, which takes a well-formed CSS string as its value. The order of the CSS properties given is important for cross-browser compatibility, and should be given in this order:

"font-style font-variant font-weight font-size font-family"

For example, "Italic small-caps bold 32px Georgia, Serif" is a valid font string using every CSS font property. Note that not all browsers may support every property.

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

Some created TextBlocks:

    // A TextBlock with text and stroke properties set:
    new go.TextBlock({ text: "Hello World", stroke: "gray" })
    // Alternatively:
    new go.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 TextBlock.None.

TextBlocks can be edited by users using the TextEditingTool. The HTMLInfo that a given TextBlock uses as its text editor can be customized by setting the textEditor property. For an example of custom text editing tool use, see the Custom TextEditingTool Sample.

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

## Index

### Constructors

- constructor

### Properties

- choices
- editable
- errorFunction
- flip
- font
- formatting
- graduatedEnd
- graduatedFunction
- graduatedSkip
- graduatedStart
- interval
- isMultiline
- isOverflowed
- isStrikethrough
- isUnderline
- lineCount
- lineHeight
- maxLines
- naturalBounds
- overflow
- spacingAbove
- spacingBelow
- stroke
- text
- textAlign
- textEdited
- textEditor
- textValidation
- verticalAlignment
- wrap

### Methods

- getBaseline
- getUnderline
- setBaseline
- setUnderline

### Constants

- FormatNone
- FormatTrim
- None
- OverflowClip
- OverflowEllipsis
- WrapBreakAll
- WrapDesiredSize
- WrapFit

## Inherited Members

### Properties

- GraphObject.actionCancel
- GraphObject.actionDown
- GraphObject.actionMove
- GraphObject.actionUp
- GraphObject.actualBounds
- GraphObject.alignment
- GraphObject.alignmentFocus
- GraphObject.angle
- GraphObject.background
- GraphObject.click
- GraphObject.column
- GraphObject.columnSpan
- GraphObject.contextClick
- GraphObject.contextMenu
- GraphObject.cursor
- GraphObject.desiredSize
- GraphObject.diagram
- GraphObject.doubleClick
- GraphObject.enabledChanged
- GraphObject.fromEndSegmentLength
- GraphObject.fromLinkable
- GraphObject.fromLinkableDuplicates
- GraphObject.fromLinkableSelfNode
- GraphObject.fromMaxLinks
- GraphObject.fromShortLength
- GraphObject.fromSpot
- GraphObject.height
- GraphObject.isActionable
- GraphObject.isPanelMain
- GraphObject.layer
- GraphObject.margin
- GraphObject.maxSize
- GraphObject.measuredBounds
- GraphObject.minSize
- GraphObject.mouseDragEnter
- GraphObject.mouseDragLeave
- GraphObject.mouseDrop
- GraphObject.mouseEnter
- GraphObject.mouseHold
- GraphObject.mouseHover
- GraphObject.mouseLeave
- GraphObject.mouseOver
- GraphObject.name
- GraphObject.opacity
- GraphObject.panel
- GraphObject.part
- GraphObject.pickable
- GraphObject.portId
- GraphObject.position
- GraphObject.row
- GraphObject.rowSpan
- GraphObject.scale
- GraphObject.segmentFraction
- GraphObject.segmentIndex
- GraphObject.segmentOffset
- GraphObject.segmentOrientation
- GraphObject.shadowVisible
- GraphObject.stretch
- GraphObject.toEndSegmentLength
- GraphObject.toLinkable
- GraphObject.toLinkableDuplicates
- GraphObject.toLinkableSelfNode
- GraphObject.toMaxLinks
- GraphObject.toShortLength
- GraphObject.toSpot
- GraphObject.toolTip
- GraphObject.visible
- GraphObject.width

### Methods

- GraphObject.apply
- GraphObject.attach
- GraphObject.bind
- GraphObject.copy
- GraphObject.findBindingPanel
- GraphObject.getDocumentAngle
- GraphObject.getDocumentBounds
- GraphObject.getDocumentPoint
- GraphObject.getDocumentScale
- GraphObject.getLocalPoint
- GraphObject.isContainedBy
- GraphObject.isEnabledObject
- GraphObject.isVisibleObject
- GraphObject.set
- GraphObject.setProperties
- GraphObject.trigger

## Constructors

### constructor

- new TextBlock(text?: string, init?: Partial<TextBlock>): TextBlock
- new TextBlock(init?: Partial<TextBlock>): TextBlock

- Constructs a TextBlock, which by default has no string to show; if it did, it would draw the text, wrapping if needed, in the default font using a black stroke.

  Typical usage:

      new go.TextBlock("Hello World", { font: "12px sans-serif", stroke: "gray" })

  It is common to data-bind the text:

      // A Node used as the node template, holding a single TextBlock
      myDiagram.nodeTemplate =
        new go.Node()
        .add(
          new go.TextBlock({ font: "12px sans-serif", stroke: "darkgray" })
          .bind("text"));

      // It could be used with model data like this:
      myDiagram.model = new go.GraphLinksModel(
        [
           { key: "1", text: "First TextBlock" },
           { key: "2", text: "Second TextBlock" }
        ]);

  #### Parameters

  - ##### Optional text: string

    The textblock's text.

  - ##### Optional init: Partial<TextBlock>

    Optional initialization properties.

  #### Returns TextBlock

- A newly constructed TextBlock has no string to show; if it did, it would draw the text, wrapping if needed, in the default font using a black stroke.

  #### Parameters

  - ##### Optional init: Partial<TextBlock>

    Optional initialization properties.

  #### Returns TextBlock

## Properties

### choices: string[]

- Gets or sets the an array of possible choices for a custom TextEditingTool. The value must be an array of strings.

  The default value is null. For example usage, see the Custom TextEditingTool Sample.

  since

    1.7

### editable: boolean

- 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. The default is false.

  See also Part.textEditable.

### errorFunction: (tool: TextEditingTool, oldString: string, newString: string) => void

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

### flip: EnumValue

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

  Possible values are GraphObject.None, GraphObject.FlipHorizontal, GraphObject.FlipVertical, or GraphObject.FlipBoth. The default is GraphObject.None.

  since

    2.0

### font: string

- Gets or sets the current font settings. The font property must be a valid CSS string describing a font. The font string can accept several CSS properties but they must be in a specific order in order to render correctly across all browsers:

  `"font-style font-variant font-weight font-size font-family"`

  For example, `"Italic small-caps bold 32px Georgia, Serif"` is a valid font string using every CSS font property. Not every browser can render every font option. For more information about CSS font syntax, see CSS fonts (mozilla.org).

  If your Node sizes depend on TextBlocks, it is best to ensure any custom fonts you are using are finished loading before you load your Diagram. This will ensure nodes are sized appropriately for the initial Diagram layout.

  The default font is "13px sans-serif".

### formatting: EnumValue

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

  Possible values are TextBlock.FormatTrim, which trims whitespace before and after every line of text, or TextBlock.FormatNone, which will not trim any whitespace and may be useful for preformatted text. The default is TextBlock.FormatTrim.

  since

    2.2

### graduatedEnd: number

- Gets or sets the fractional distance along the main shape of a "Graduated" Panel at which this kind of tick text should end. The default is 1; the value should range from 0 to 1.

  since

    1.7

### graduatedFunction: (val: number, tb: TextBlock) => string

- Gets or sets the function to convert from a value along a "Graduated" Panel to a string. The default returns a string representing the value rounded to at most 2 decimals.

  The function takes a number argument, a value between Panel.graduatedMin and Panel.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 the TextBlock, not a particular label that would be rendered at the given value. The function, if supplied, must not have any side-effects.

  since

    1.7

### graduatedSkip: (val: number, tb: TextBlock) => boolean

- Gets or sets the function to determine which values along a "Graduated" Panel will be skipped. The default is null and doesn't skip any text labels.

  The function takes a number argument, a value between Panel.graduatedMin and Panel.graduatedMax, and this TextBlock. The function will return a boolean, whether the text label will be skipped at the value of the argument.

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

  since

    2.0

### graduatedStart: number

- Gets or sets the fractional distance along the main shape of a "Graduated" Panel at which this text should start. The default is 0; the value should range from 0 to 1.

  since

    1.7

### interval: number

- Gets or sets how frequently this text should be drawn within a "Graduated" Panel, in multiples of the Panel.graduatedTickUnit. The default is 1. Any new value must be a positive integer.

  since

    1.7

### isMultiline: boolean

- Gets or sets whether or not the text displays multiple lines or embedded newlines. If this is false, all characters including and after the first newline will be omitted. The default is true.

  see

    maxLines

### Read-only isOverflowed: boolean

- Gets whether the TextBlock text is truncated (overflowed) or not. This value is set during a TextBlock's measurement.

  As with all read-only properties, using this property as a binding source is unlikely to be useful.

  since

    2.3

  see

    overflow

### isStrikethrough: boolean

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

  see

    isUnderline

  since

    1.2

### isUnderline: boolean

- Gets or sets whether or not the text is underlined. The default is false.

  see

    isStrikethrough

  since

    1.2

### Read-only lineCount: number

- This read-only property returns the computed number of lines in this TextBlock, including lines created from embedded newlines (`\n`), wrapping, and maxLines.

  This value may be meaningless before the TextBlock is measured.

  see

    lineHeight

### Read-only lineHeight: number

- This read-only property returns the height of a line of text in this TextBlock, not including any spacingAbove or spacingBelow.

  This value may be meaningless before the TextBlock is measured.

  since

    2.2

  see

    lineCount

### maxLines: number

- Gets or sets the maximum number of lines that this TextBlock can display. Value must be a greater than zero whole number or `Infinity`. The default is `Infinity`.

  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

    isMultiline

  since

    1.5

### Override Read-only naturalBounds: Rect

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

### overflow: EnumValue

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

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

  The default value is TextBlock.OverflowClip.

  see

    wrap

  since

    1.4

### spacingAbove: number

- Gets or sets additional spacing above each line of text. The default is zero. The value may be negative.

  This can be useful when you need to adjust the font spacing on custom fonts or monospace fonts to suit your needs.

  since

    2.2

### spacingBelow: number

- Gets or sets additional spacing below each line of text. The default is zero. The value may be negative.

  This can be useful when you need to adjust the font spacing on custom fonts or monospace fonts to suit your needs.

  since

    2.2

### stroke: BrushLike

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

  The default value is `"black"`. 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: string

- Gets or sets the TextBlock's text string. 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: "left" | "right" | "center" | "end" | "start"

- Gets or sets the alignment location in the TextBlock's given space. The only possible values are `"start"`, `"end"`, `"left"`, `"right"`, and `"center"`. Any other value is invalid.

  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

    verticalAlignment

### textEdited: (thisTextBlock: TextBlock, oldString: string, newString: string) => void

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

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

      function(textBlock, previousText, currentText)

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

  since

    1.7

### textEditor: HTMLInfo

- Gets or sets the HTMLInfo that this TextBlock uses as its text editor in the TextEditingTool. 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 HTMLInfo. Setting this property might not affect any ongoing text editing operation.

  As of 2.0 setting this to an HTML Element is no longer supported.

  For example usage, see the Custom TextEditingTool Sample.

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

- Gets or sets the predicate that determines whether or not a user-edited string of text is valid. If this is non-null, the predicate is called in addition to any TextEditingTool.textValidation predicate. See TextEditingTool.isValidText for more details.

      function(textBlock, oldString, newString)

  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

    TextEditingTool.textValidation

### verticalAlignment: Spot

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

  The default value is Spot.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

    textAlign

  since

    1.7

### wrap: EnumValue

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

  Possible values are TextBlock.WrapDesiredSize, TextBlock.WrapFit, TextBlock.WrapBreakAll, and TextBlock.None.

  The default value is TextBlock.WrapDesiredSize.

  see

    overflow

## Methods

### Static getBaseline

- getBaseline(): (textBlock: TextBlock, textHeight: number) => number

- 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. By default this is null and default behavior returns `(textHeight * 0.75)`.

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

  since

    2.0

  #### Returns (textBlock: TextBlock, textHeight: number) => number

  - - (textBlock: TextBlock, textHeight: number): number

    - #### Parameters

      - ##### textBlock: TextBlock

      - ##### textHeight: number

      #### Returns number

### Static getUnderline

- getUnderline(): (textBlock: TextBlock, textHeight: number) => number

- 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. By default this is null and default behavior returns `(textHeight * 0.75)`.

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

  since

    2.0

  #### Returns (textBlock: TextBlock, textHeight: number) => number

  - - (textBlock: TextBlock, textHeight: number): number

    - #### Parameters

      - ##### textBlock: TextBlock

      - ##### textHeight: number

      #### Returns number

### Static setBaseline

- setBaseline(value: (textBlock: TextBlock, textHeight: number) => number): void

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

  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.

  since

    2.0

  #### Parameters

  - ##### value: (textBlock: TextBlock, textHeight: number) => number

    - - (textBlock: TextBlock, textHeight: number): number

      - #### Parameters

        - ##### textBlock: TextBlock

        - ##### textHeight: number

        #### Returns number

  #### Returns void

### Static setUnderline

- setUnderline(value: (textBlock: TextBlock, textHeight: number) => number): void

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

  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.

  since

    2.0

  #### Parameters

  - ##### value: (textBlock: TextBlock, textHeight: number) => number

    - - (textBlock: TextBlock, textHeight: number): number

      - #### Parameters

        - ##### textBlock: TextBlock

        - ##### textHeight: number

        #### Returns number

  #### Returns void

## Constants

### Static FormatNone: EnumValue

Used as a value for TextBlock.formatting: the TextBlock will not trim any whitespace at the start or end of each line of text. This can be useful if your text is preformatted.

since

  2.2

### Static FormatTrim: EnumValue

Used as the default value for TextBlock.formatting: the TextBlock will automatically trim any whitespace at the start or end of each line of text.

since

  2.2

### Static Override None: EnumValue

Used as a value for TextBlock.wrap, the TextBlock will not wrap its text.

### Static OverflowClip: EnumValue

Used as the default value for TextBlock.overflow: if the width is too small to display all text, the TextBlock will clip.

since

  1.4

### Static OverflowEllipsis: EnumValue

Used as a value for TextBlock.overflow: if the width is too small to display all text, the TextBlock will display an ellipsis.

since

  1.4

### Static WrapBreakAll: EnumValue

Used a a value for TextBlock.wrap, the TextBlock will attempt to wrap at each character, allowing breaks within "words."

since

  2.0

### Static WrapDesiredSize: EnumValue

Used as the default value for TextBlock.wrap, the TextBlock will wrap text and the width of the TextBlock will be the desiredSize's width, if any.

### Static WrapFit: EnumValue

Used as a value for TextBlock.wrap, the TextBlock will wrap text, making the width of the TextBlock equal to the width of the longest line.

Copyright © 1998-2022 by Northwoods Software Corporation.