Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/workers
Class: TextSymbol

require(["esri/symbols/TextSymbol"], function(TextSymbol) { /* code goes here */ });

Description

(Added at v1.0)
Text symbols are used to add text on the graphics layer.

Samples

Search for samples that use this class.

Class hierarchy

esri/symbols/Symbol
|_esri/symbols/TextSymbol

Constructors

NameSummary
new TextSymbol(text)Creates a new TextSymbol object that includes only the text.
new TextSymbol(text, font, color)Creates a new TextSymbol object.
new TextSymbol(json)Creates a new TextSymbol object using a JSON object.

Constants

NameDescription
ALIGN_ENDThe end of the text string is aligned with the point.
ALIGN_MIDDLEThe center of the text string is aligned with the point.
ALIGN_STARTThe beginning of the text string is aligned with the point.
DECORATION_LINETHROUGHText has a lined striked through it.
DECORATION_NONEText has no decoration.
DECORATION_OVERLINEText has a line along the top.
DECORATION_UNDERLINEText is underlined.

Properties

NameTypeSummary
alignStringThe text alignment in relation to the point.
angleNumberText angle.
colorColorSymbol color.
decorationStringThe decoration on the text.
fontFontFont for displaying text.
haloColorColorThe halo color used for the text symbol.
haloSizeNumberThe size (in pixel units) used if setting a halo on a text symbol.
horizontalAlignmentStringHorizontal alignment of the text with respect to the graphic.
kerningBooleanDetermines whether to adjust the spacing between characters in the text string.
rotatedBooleanDetermines whether every character in the text string is rotated.
textStringText string for display in the graphics layer.
typeStringThe type of symbol.
verticalAlignmentStringVertical alignment of the text with respect to the graphic.

Vertical alignment is not supported in Internet Explorer versions 7-10.
xoffsetNumberThe offset on the x-axis in pixels from the point.
yoffsetNumberThe offset on the y-axis in pixels from the point.

Methods

NameReturn typeSummary
setAlign(align)TextSymbolSets the alignment of the text.
setAngle(angle)TextSymbolSets the angle of the text.
setColor(color)SymbolSets the symbol color.
setDecoration(decoration)TextSymbolSets the decoration for the text.
setFont(font)TextSymbolSets the text font.
setHaloColor(color)TextSymbolSets a halo color for the text symbol.

NOTE: Known limitations when working with the text symbol halo:
  • IE 9 and below not supported.
  • Sub-pixel halo (i.e.
setHaloSize(size)TextSymbolSets the size of the halo (in pixels) used for the text symbol.

NOTE: Known limitations when working with the text symbol halo:
  • IE 9 and below not supported.
  • Sub-pixel halo (i.e.
setHorizontalAlignment(alignment)TextSymbolUpdates the horizontal alignment of the text symbol.
setKerning(kerning)TextSymbolSets whether to adjust the spacing between characters in the text string.
setOffset(x, y)TextSymbolSets the x and y offset of the text.
setRotated(rotated)TextSymbolSets whether every character in the text string is rotated.
setText(text)TextSymbolSets the text string.
setVerticalAlignment(alignment)TextSymbolUpdates the vertical alignment of the text symbol.
toJson()ObjectConverts object to its ArcGIS Server JSON representation.
Constructor Details

new TextSymbol(text)

Creates a new TextSymbol object that includes only the text.
Parameters:
<String> text Required Text string for display in the graphics layer.
Sample:

Create a new text symbol using the default values for color, size, etc.

require([
  "esri/symbols/TextSymbol", ... 
], function(TextSymbol, ... ) {
  var textSym = new TextSymbol("Hello World");
  ...
});

Create a new text symbol and set new values for color, weight, font and angle.

require([
  "esri/symbols/TextSymbol", "esri/Color", "esri/symbols/Font", ... 
], function(TextSymbol, Color, Font, ... ) {
  var textSymbol =  new TextSymbol("Hello World").setColor(
    new Color([128,0,0])).setAlign(Font.ALIGN_START).setAngle(45).setFont(
    new Font("12pt").setWeight(Font.WEIGHT_BOLD)) ;
  ...
});

new TextSymbol(text, font, color)

Creates a new TextSymbol object.
Parameters:
<String> text Required Text string for display in the graphics layer.
<Font> font Required Font for displaying text.
<Color> color Required Symbol color.

new TextSymbol(json)

Creates a new TextSymbol object using a JSON object.
Parameters:
<Object> json Required

JSON object representing the TextSymbol. View the REST API Reference for Symbol Objects for details on creating a JSON symbol. Note that when specifying symbol width and height using JSON the values should be entered in points, the JavaScript API then converts the point values to pixels. The TextSymbol does not support backgroundColor, borderLineColor, verticalAlignment or horizontalAlignment properties.

Property Details

<String> align

The text alignment in relation to the point. See the Constants table for valid values. Deprecated at v3.8. Use horizontalAlignment and verticalAlignment instead.
Default value: ALIGN_MIDDLE
See also: setAlign()

<Number> angle

Text angle. 0 is horizontal and the angle moves clockwise.
Default value: 0
See also: setAngle()

<Color> color

Symbol color.

<String> decoration

The decoration on the text. See the Constants table for valid values. Deprecated at v3.8. Use Font.decoration instead.
Default value: DECORATION_NONE
See also: setDecoration()

<Font> font

Font for displaying text.
See also: setFont()

<Color> haloColor

The halo color used for the text symbol.

Known limitations:
  • IE 9 and below not supported.
  • Sub-pixel halo (i.e. fractional size such as 1.25px) renders inconsistently in various browsers.
(Added at v3.15)

<Number> haloSize

The size (in pixel units) used if setting a halo on a text symbol.

Known limitations:
  • IE 9 and below not supported.
  • Sub-pixel halo (i.e. fractional size such as 1.25px) renders inconsistently in various browsers.
(Added at v3.15)

<String> horizontalAlignment

Horizontal alignment of the text with respect to the graphic. (Added at v3.8)
Known values: "left" | "right" | "center" | "justify"
Default value: "center"

<Boolean> kerning

Determines whether to adjust the spacing between characters in the text string.
Known values: true | false
Default value: true
See also: setKerning()

<Boolean> rotated

Determines whether every character in the text string is rotated.
Known values: true | false
Default value: false
See also: setRotated()

<String> text

Text string for display in the graphics layer.
See also: setText()

<String> type

The type of symbol.
Known values: simplemarkersymbol | picturemarkersymbol | simplelinesymbol | cartographiclinesymbol | simplefillsymbol | picturefillsymbol | textsymbol

<String> verticalAlignment

Vertical alignment of the text with respect to the graphic.

Vertical alignment is not supported in Internet Explorer versions 7-10. Also, it is not supported when the graphics layer uses HTML Canvas to draw graphics. (Added at v3.8)
Known values: "baseline" | "top" | "middle" | "bottom"
Default value: "baseline"

<Number> xoffset

The offset on the x-axis in pixels from the point.
Default value: 0
See also: setOffset()

<Number> yoffset

The offset on the y-axis in pixels from the point.
Default value: 0
See also: setOffset()
Method Details

setAlign(align)

Sets the alignment of the text. Deprecated at v3.8. Use setHorizontalAlignment and setVerticalAlignment instead.
Return type: TextSymbol
Parameters:
<String> align Required The text alignment. See the Constants table for valid values.
Sample:
require([
  "esri/symbols/TextSymbol", ... 
], function(TextSymbol, ... ) {
  var textSymbol = new TextSymbol();
  textSymbol.setAlign(TextSymbol.ALIGN_START);
  ...
});
See also: align

setAngle(angle)

Sets the angle of the text.
Return type: TextSymbol
Parameters:
<Number> angle Required Angle value between 0 and 359.
Sample:

textSymbol.setAngle(15);

See also: angle

setColor(color)

Sets the symbol color.
Return type: Symbol
Parameters:
<Color> color Required Symbol color.
Sample:
require([
  "esri/Color", ... 
], function(Color, ... ) {
  symbol.setColor(new Color([255,255,0,0.5]));
  ...
});

setDecoration(decoration)

Sets the decoration for the text. Many browsers including Internet Explorer 7, Firefox and Opera 9 do not support the decoration properties for text symbols. Deprecated at v3.8. Use Font.setDecoration instead.
Return type: TextSymbol
Parameters:
<String> decoration Required The decoration on the text. See the Constants table for valid values.
See also: decoration

setFont(font)

Sets the text font.
Return type: TextSymbol
Parameters:
<Font> font Required Text font.
Sample:
require([
  "esri/symbols/TextSymbol", "esri/symbols/Font", ... 
], function(TextSymbol, Font, ... ) {
  var textSymbol = new TextSymbol( ... );
  var font  = new Font();
  font.setSize("12pt");
  font.setWeight(Font.WEIGHT_BOLD);
  textSymbol.setFont(font);
  ...
});
See also: font

setHaloColor(color)

Sets a halo color for the text symbol.

NOTE: Known limitations when working with the text symbol halo:
  • IE 9 and below not supported.
  • Sub-pixel halo (i.e. fractional size such as 1.25px) renders inconsistently in various browsers.
(Added at v3.15)
Return type: TextSymbol
Parameters:
<Color> color Required The color used for the text symbol halo.
Sample:
ts.setHaloColor(new Color([255, 0, 0]));

setHaloSize(size)

Sets the size of the halo (in pixels) used for the text symbol.

NOTE: Known limitations when working with the text symbol halo:
  • IE 9 and below not supported.
  • Sub-pixel halo (i.e. fractional size such as 1.25px) renders inconsistently in various browsers.
(Added at v3.15)
Return type: TextSymbol
Parameters:
<Number> size Required The size (in pixels) of the text symbol halo.
Sample:
ts.setHaloSize(1);

setHorizontalAlignment(alignment)

Updates the horizontal alignment of the text symbol. (Added at v3.8)
Return type: TextSymbol
Parameters:
<String> alignment Required Horizontal alignment of the text with respect to the graphic. See horizontalAlignment property for the list of supported options.

setKerning(kerning)

Sets whether to adjust the spacing between characters in the text string.
Return type: TextSymbol
Parameters:
<Boolean> kerning Required Set to true for kerning.
See also: kerning

setOffset(x, y)

Sets the x and y offset of the text.
Return type: TextSymbol
Parameters:
<Number> x Required X offset value in pixels.
<Number> y Required Y offset value in pixels.
See also: xoffsetyoffset

setRotated(rotated)

Sets whether every character in the text string is rotated. Many browsers including Internet Explorer 7, Firefox and Opera 9 do not support rotated for text symbols.
Return type: TextSymbol
Parameters:
<Boolean> rotated Required Set to true to rotate all characters in the string.
See also: rotated

setText(text)

Sets the text string.
Return type: TextSymbol
Parameters:
<String> text Required The text string.
See also: text

setVerticalAlignment(alignment)

Updates the vertical alignment of the text symbol. (Added at v3.8)
Return type: TextSymbol
Parameters:
<String> alignment Required Vertical alignment of the text with respect to the graphic. See verticalAlignment property for the list of supported options.

toJson()

Converts object to its ArcGIS Server JSON representation.
Return type: Object