Class TextBlock

Extends GraphObject. 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: 

var $ = go.GraphObject.make;  // for conciseness in defining GraphObjects

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

Constructor Summary Details

Returns Name Description
 
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.

Properties Summary Details

Returns Name Description
{boolean}
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. More... The default is false.

See also Part.textEditable.

{function(TextEditingTool, string, string) | null}
errorFunction
Gets or sets the function to call if a text edit made with the TextEditingTool is invalid. More... The default is null.
{string}
font
Gets or sets the current font settings. More... 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.

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

{boolean}
isMultiline
Gets or sets whether or not the text allows or displays multiple lines or embedded newlines. More... If this is false, all characters after the first newline will be omitted. Default is true.
{boolean}
isStrikethrough 1.2
Gets or sets whether or not the text has a strikethrough line (line-through). More... Default false.
{boolean}
isUnderline 1.2
Gets or sets whether or not the text is underlined. More... Default false.
{number}
lineCount
This read-only property returns the total number of lines in this TextBlock, including lines created from returns (\n) and wrapping. More...

This value may be meaningless before the TextBlock is measured.

{number}
maxLines 1.5
Gets or sets the maximum number of lines that this TextBlock can display. More... Value must be a greater than zero whole number or Infinity. 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.

{Rect}
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.
{EnumValue}
overflow 1.4
Gets or sets how text that is too long to display should be handled. More...

Possible values are TextBlock.OverflowClip and TextBlock.OverflowEllipsis. For OverflowEllipsis to work, you must also set wrap to TextBlock.None or limit the number of lines with maxLines.

The default value is TextBlock.OverflowClip.

{string|Brush}
stroke
Gets or sets the Brush or string that describes the stroke (color) of the font. More...

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.

{string}
text
Gets or sets the TextBlock's text string. More... 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.

{string}
textAlign
Gets or sets the alignment location in the TextBlock's given space. More... The 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 bounds (such as with desiredSize).

In left-to-right writing systems, "start" and "left" are synonymous, as are "end" and "right".

The default is "start".

{HTMLElement}
textEditor
Gets or sets the HTMLElement that this TextBlock uses as its text editor in the TextEditingTool. More... If null, the TextBlock will use the default text editor of the TextEditingTool. The default is null.
{function(TextBlock, string, string):boolean | null}
textValidation
Gets or sets the predicate that determines whether or not a string of text is valid. More... If this is non-null, the predicate is called in addition to any TextEditingTool.textValidation predicate. See TextEditingTool.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.

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

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

The default value is TextBlock.WrapDesiredSize.

Properties borrowed from class GraphObject:
actionCancel, actionDown, actionMove, actionUp, actualBounds, alignment, alignmentFocus, angle, areaBackground, background, click, column, columnSpan, contextClick, contextMenu, cursor, Default, desiredSize, diagram, doubleClick, Fill, fromEndSegmentDirection, fromEndSegmentLength, fromLinkable, fromLinkableDuplicates, fromLinkableSelfNode, fromMaxLinks, fromShortLength, fromSpot, height, Horizontal, isActionable, isPanelMain, layer, margin, maxSize, measuredBounds, minSize, mouseDragEnter, mouseDragLeave, mouseDrop, mouseEnter, mouseHold, mouseHover, mouseLeave, mouseOver, name, opacity, panel, part, pickable, portId, position, row, rowSpan, scale, segmentFraction, segmentIndex, segmentOffset, segmentOrientation, stretch, toEndSegmentDirection, toEndSegmentLength, toLinkable, toLinkableDuplicates, toLinkableSelfNode, toMaxLinks, toolTip, toShortLength, toSpot, Uniform, UniformToFill, Vertical, visible, width
Methods borrowed from class GraphObject:
bind, copy, getDocumentAngle, getDocumentPoint, getDocumentScale, getLocalPoint, isContainedBy, isVisibleObject, setProperties

Constants Summary Details

Returns Name Description
<constant> {EnumValue}
None
Used as a value for TextBlock.wrap, the TextBlock will not wrap its text.
<constant> {EnumValue}
OverflowClip 1.4
Used as the default value for TextBlock.overflow: if the width is too small to display all text, the TextBlock will clip.
<constant> {EnumValue}
OverflowEllipsis 1.4
Used as a value for TextBlock.overflow: if the width is too small to display all text, the TextBlock will display an ellipsis.
<constant> {EnumValue}
WrapDesiredSize
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.
<constant> {EnumValue}
WrapFit
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.