Cango Text Utilities User Guide

Cango text utilities extension

The CangoTextUtils extension module provides the Cango graphics library with additional methods to simplify drawing Text on a canvas.

The extension requires Cango canvas graphics library Version 26 or later. Download the source code from CangoTextUtils-4v04.js and the minified version at CangoTextUtils-4v04-min.js

The module adds these Global object to assist drawing various specialty text styles:

HTMLMathText
MathText
TextOnPath
VectorText
ExpNotationText
SciNotationText

Also added are these wrapper methods which create and render the Text objects:

drawHTMLText
drawMathText
drawTextOnPath
drawVectorText
drawExpNotationText
drawSciNotationText

Global objects added

HTMLText

Syntax:

const txt = new HTMLText(str [, options]);

Description:

HTMLText is a Cango Extension Object that takes a string containing text and CSS formatting rules in HTML paragraph syntax and returns a Cango Img of the paragraph as it would be laid out by a browser. This Img element may be translated, rotated etc just as any other Img object and then rendered to the canvas.

All the required CSS formatting should included inline in the 'style' attribute eg.
"</p style="font-size:14px; padding: 1em">This is sample text</p>".

Parameters:

str: String - The text string in HTML paragraph text with CSS styling included inline.If the text string is just plain text ie. the '<p>' tags and any CCS rules are absent, then the text will be formatted using the Cango default font size, font family and fill color and it will wrap at the width set by the 'imgWidth' optional property.

options: Object - The key-value pairs are used to set the various optional properties of the Img object as it is rendered to the canvas. All key-value pairs are processed as for a normal Cango Img object, see the Cango User Guide section Object Optional Properties.

Note 1:

Special characters: Most keyboard characters may be inserted unencoded eg: !@#$%^*()_+[]{}|:;,./? special characters may be encoded with the unicode eg: deg = \u00B0 alpha = \u03B1 | = \u007C etc. The exceptions are & and < these must be encoded with a preceding backslash so '&' needs \& and '<' needs \<. Encoding any other characters with a backslash will not be recognized or throw an error eg. \° or \| each throw an error.

Note 2:

How to determine width: The HTML text will be formatted in a block with lines wrapping at the minimum of inline style "width" rule (in pixels, em, etc) and then the Img returned will have its width set by the optional "imgWidth" property (world coordinate units) which will have the effect of scaling the Img. If imgWidth is undefined then the Img will have width set by the natural width of the paragraph as it would be laid out by the browser.

Example:

function drawHTML(cvsID)
{
  const gc = new Cango(cvsID),
        xmin = -50, xmax = 250,
        ymin = 0, ymax = 100;
  gc.setWorldCoordsRHC(xmin, ymin, xmax-xmin, ymax-ymin);

  const t = "HTML text test multi-line and special chars too < & etc.";
  gc.drawHTMLText(t, {x:-25, y:80, 
                      fontSize:16, fontWeight:"bold", bgFillColor:"lightgreen", 
                      fillColor:"brown"});

  const r = "Test rotation rot:30°";
  gc.drawHTMLText(r, {rot:30, x:170, y:70, 
                      fontsize:18, fontWeight:400, 
                      fillcolor:"navy", 
                      lorg:5});

  // test the MathJax access to the HTML overlay text
  const s = "MathJax and KaTeX work$$ v = \\sqrt{\\frac{p}{m+\\tfrac{1}{3}p}ln(\\frac{L}{c})}$$";

  gc.drawHTMLText(s, {x:-25, y:40, fillColor:"red", fontSize:20, fontWeight:800});
}

Figure 1. Example of 'drawHTMLText' and drawMathText methods.

MathText

Syntax:

const txt = new MathText(lateXstr [, options]);

Description:

MathText is a Cango Extension Object which takes a text string in LaTeX syntax for mathematical formula. The string is formatted as a Image of the corresponding math expression as it would be laid out by 'CodeCogs' utility and this image is used as the descriptor for the Cango Img object that is returned.

Parameters:

lateXstr: String - The text string in LaTeX syntax representing math expressions.

options: Object - Various optional properties may be passed as key-value pairs in this object. The math formatting uses only the 'fillColor' property set the foreground color of the text. The background of the image is always transparent. All other key-value pairs are processed as for a normal Cango Img object, see the Cango User Guide section Object Optional Properties.

Note 1:

The '\' character: Most LaTeX formatting option begin with 'backslash' character, but this single backslash is a special character within JavaScript and redefines the subsequent character in a string. To avoid this all LaTeX strings used in drawMathText must have a double backslash '\\' wherever a single '\' is required.

Note 2:

Text Colors: The 'fillColor' optional property must be in the format a named color string eg, 'blue'. Only a small set of colors are supported, they are:
"red", "green", "blue", "yellow", "cyan", "magenta", "teal", "purple", "darkblue",
"darkred", "orange", "darkorange", "golden", "pink", "darkgreen", "orchid", "emerald".

Note 3:

Multi-line equations: Multi-line equation formatting is supported in LatTex by adding '\\' to indicate a newline. As seen in Note 1 this should be replaced with '\\\\'.
The formatted math expressions are center aligned by default, but multi-line equations usually have '=' signs aligned which is difficult with each line individually center aligned. To align equations and enforce left aligned text, add the LaTeX command \hspace*{length} at the start of the lines to be indented.

Example:

function drawMath(cvsID)
{
  const g = new Cango(cvsID);
  g.setWorldCoordsRHC(0,0,280);

  const m = "v=\\sqrt{\\frac{p}{m + \\frac{1}{3}p} ln(\\frac{L}{c})}";
  g.drawMathText(m, {x:50, y:170, lorg:1, fillColor:"blue"});

  const r = 
  "\\vspace{2ex} v^2 = \\int_{c}^{L} {\\frac{1}{x}dx} \\\\ \
    \\vspace{2ex} \\hspace*{5ex}=\\frac{2\\times 45.8}{0.9} \\int_{2.6}^{45} \\frac{1}{x}dx \\\\ \
                  \\hspace*{5ex}=\\frac{2\\times 45.8}{0.9} \\times (ln(45) - ln(2.625))";
  g.drawMathText(r, {x:30, y:60, lorg:4, imgHeight:70});
}

Figure 2. Examples of the drawMathText method.

TextOnPath

Syntax:

var pthTxt = new TextOnPath(str, pth, options);

Description:

TextOnPath is a sub-class of Group it breaks the 'str' argument into a group of single character Text objects and assigns transforms to position them along the path specified by the 'pth' argument

The Text will be drawn in the same direction that the path descriptor is traversed. If the Text appears reversed transform the PathSVG direction with the revWinding method (see example below).

Parameters:

str: String - The text string to be drawn with each letter's drawing origin position to lie along the path.

pth: PathSVG object - An PathSVG object defining the path along which the text is to be drawn. The path may have discontinuous sections.

options: Object - The key-value pairs of the 'options' object describe set the various properties of the text such as fontSize, fillColor etc. For details of the other properties see Cango User Guide section Object Optional Properties

In addition to the set of options supported by the standard Text object there are two keys specific to this method:

charSpacing - Number specifying the pixel spacing between the individual characters.
offset - Number specifying the percentage of the total path length at which the first character will be drawn. If the offset means that some characters will not fit before the end of the path is reached then these characters will wrap around and be drawn at the start of the path.

Example:

function textOnCircle(cvsID)
{
  const g = new Cango(cvsID);
  g.setWorldCoordsRHC(-12, -12, 30);

  const trk = PathSVG.circle(15);
  g.drawPath(trk, {strokeColor:"grey"});

  g.drawTextOnPath("HULLO WORLD (lorg 5)", trk, { 
    offset: 15, fontSize: 18, lorg:5, fillColor:"green"});

  g.drawTextOnPath("Clockwise Text", segment(trk).revWinding(), 
            {offset: 5, fontSize: 18, lorg:8, fillColor:"blue"});
}

Figure 3. Example of 'TextOnPath' object.

VectorText

Syntax:

var vTxt = new VectorText(str, options);

Description:

VectorText is a Cango Extension Object that converts the text 'str' to a Path object. The font used is the Hershey vector font. The character set comprises 96 printable ASCII characters and the full Greek alphabet.

Special characters within the string may be specified by Unicode escapes. These are six characters long, \u followed by exactly four hexadecimal characters. If the hex character code is only one, two or three characters long, then the code must be padded with leading zeroes, eg. the Greek letter 'Π' has character code '\u03A0'. The hexadecimal part of this kind of character escape is not case sensitive ie. '\u03A0' and '\u03a0' are equivalent. The lower case 'π' has character code '\u03C0' or ''\u03c0'.

Parameters:

str: String - The text string to be written.

options: Object - The values for the various optional properties may be passed as key-value pairs in this object. For details of the other properties see the Cango User Guide section Object Optional Properties.

NOTE: Since the string is drawn as a stroked Path, the color is set by the options property "strokeColor" rather than "fillColor" which sets the color of Text objects.

Example:

function vectorText(cvsID)
{
  var g = new Cango(cvsID);

  g.setWorldCoordsRHC(-15, -15, 40);

  g.drawVectorText("abcd \u0026 ABCD", {x:0, y:10, fontSize: 30});
  g.drawVectorText("Greek Letters: \u03B1\u03B2\u03B3\u03B4 \u0391\u0392\u0393\u0394",
    {x:0, y:5, fontSize: 15});
  g.drawVectorText("strokeColor:'blue', lorg=7",
    {x:0, y:0, strokeColor:"blue", fontSize:20, fontWeight:200, lorg:7});
  g.drawVectorText("bgFillColor: lime, lorg 3",
    {rot: 30, x:0, y:0, fontSize:15, fontWeight:700, lorg:3, bgFillColor:'lime'});
}

Figure 4. Example of 'drawVectorText' method.

Vector Text character set

To generate the characters shown, insert the character (or its Unicode) into the string.

ASCII characters
sp \u0020	! \u0021	" \u0022	# \u0023	$ \u0024	% \u0025	& \u0026	' \u0027	( \u0028	) \u0029	* \u002A	+ \u002B	, \u002C	- \u002D	. \u02E	/ \u002F
0 \u0030	1 \u0331	2 \u0332	3 \u0333	4 \u0334	5 \u0335	6 \u0336	7 \u0337	8 \u0338	9 \u0339	: \u033A	; \u033B	< \u033C	= \u033D	> \u033E	? \u033F
@ \u0040	A \u0041	B \u0042	C \u0043	D \u0044	E \u0045	F \u0046	G \u0047	H \u0048	I \u0049	J \u004A	K \u004B	L \u004C	M \u004D	N \u004E	O \u004F
P \u0050	Q \u0051	R \u0052	S \u0053	T \u0054	U \u0055	V \u0056	W \u0057	X \u0058	Y \u0059	Z \u005A	[ \u005B	\ \u005C	] \u005D	^ \u005E	_ \u005F
` \u0060	a \u0061	b \u0062	c \u0063	d \u0064	e \u0065	f \u0066	g \u0067	h \u0068	i \u0069	j \u006A	k \u006B	l \u006C	m \u006D	n \u006E	o \u006F
p \u0070	q \u0071	r \u0072	s \u0073	t \u0074	u \u0075	v \u0076	w \u0077	x \u0078	y \u0079	z \u007A	{ \u007B	\| \u007C	} \u007D	~ \u007E

To generate the symbols shown, insert the Unicode shown below the symbol into the string.

Special characters
Α \u0391	Β \u0392	Γ \u0393	Δ \u0394	Ε \u0395	Ζ \u0396	Η \u0397	Θ \u0398	Ι \u0399	Κ \u039A	Λ \u039B	Μ \u039C	Ν \u039D	Ξ \u039E	Ο \u039F	Π \u03A0
Ρ \u03A1	Σ \u03A3	Τ \u03A4	ϒ \u03A5	Φ \u03A6	Χ \u03A7	Ψ \u03A8	Ω \u03A9	α \u03B1	β \u03B2	γ \u03B3	δ \u03B4	ε \u03B5	ζ \u03B6	η \u03B7	θ \u03B8
ι \u03B9	κ \u03BA	λ \u03BB	μ \u03BC	ν \u03BD	ξ \u03BE	ο \u03BF	π \u03C0	ρ \u03C1	σ \u03C3	τ \u03C4	υ \u03C5	φ \u03C6	χ \u03C7	ψ \u03C8	ω \u03C9
° \u00B0	· \u00B7	× \u00D7	÷ \u00F7

ExpNotationText

Syntax:

const txt = new ExpNotationText(mantissa, exponent [, options]);

Description:

ExpNotationText is a Cango Extension Object that takes mantissa and exponent values and returns an object which has two Text child elements with the exponent text positioned as a superscript to the upper right of the mantissa in a smaller font.

Parameters:

mantissa: Number or String- The mantissa of the number to be drawn.

exponent: Number or String - The exponent of the number to be drawn.

Note:

In addition to the set of Text options there are two keys specific to this method:

preText - defines a string that will be draw in front of the scientific notation Text.
postText - defines a string that will be draw immediately following the scientific notation Text.

Example:

  function expNotation(cvsID)
  {
    const g = new Cango(cvsID);
    g.clearCanvas();
    g.setWorldCoordsRHC(-12, -10, 35);

    const man = 2.36;
    const exp = 4;

    g.drawExpNotationText(man, exp, {
      x: 2, y: 12, fontSize: 18,
      bgFillColor:'lime',
      postText: " kg"
    });

    g.drawExpNotationText("\u03B2", "-7.5"+"\u03BB", {
      x: 2, y: 4, fontSize: 18
    });

    g.drawExpNotationText(9876.54, {
      x: 7, rot:-20, 
      preText: "~",
      fillColor:'red', 
      fontSize: 24, 
      fontWeight:800, 
      lorg:3});
  }

Figure 5. Example of 'SciNotationText'.

SciNotationText

Syntax:

const txt = new SciNotationText(value [, options]);

Description:

SciNotationText is a Cango Extension Object that takes a value and returns an object which has two Text child elements, the mantissa of the value in the range 1 .. 10 and its exponent of the power of 10. The exponent text is positioned as a superscript to the upper right of the "×10" in a smaller font.

Parameters:

mantissa: Number or String- The mantissa of the number to be drawn.

exponent: Number or String - The exponent of the number to be drawn.

Note:

In addition to the set of Text options there are two keys specific to this method:

preText - defines a string that will be draw in front of the scientific notation Text.
postText - defines a string that will be draw immediately following the scientific notation Text.

Example:

function sciNotation(cvsID)
{
  const g = new Cango(cvsID);
  g.clearCanvas();
  g.setWorldCoordsRHC(-12, -10, 35);

  // drawSciNotationText will accept numbers or strings 
  g.drawSciNotationText(2.0030000, {
    x: 1.2, y: 9, fontSize: 24,
    bgFillColor:'white',
    postText: " kg"
  });

  g.drawSciNotationText(0.0000450812, { 
    x: 2, y: 4, fontSize: 18, decPlaces: 4
  });

  g.drawSciNotationText("456", {
    preText: "~",
    fillColor:'red', 
    fontSize: 24, 
    fontWeight:800, 
    lorg:3});
}

Figure 6. Example of 'SciNotationText'.

Cango methods added

drawHTMLText

Syntax:

cgo.drawHTMLText(str [, options]);

Description:

A Cango method that creates an HTMLText object and renders it to the canvas.

Parameters:

str: String - The text string to be formatted as HTML text.

options: Object - The key-value pairs are used to set the various optional properties of the Img object as it is rendered to the canvas.

drawMathText

Syntax:

cgo.drawMathText(lateXstr [, options]);

Description:

The drawMathText method is a wrapper method that creates a MathText object from a text string in LaTeX syntax for mathematical formula na drendered the object to the canvas.

Parameters:

lateXstr: String - The text string in LaTeX syntax representing math expressions.

options: Object - Various optional properties may be passed as key-value pairs in this object. The math formatting uses only the 'fillColor' property set the foreground color of the text. The background of the image is always transparent. All other key-value pairs are processed as for a normal Cango Img object, see Cango User Guide section Object Optional Properties.

drawTextOnPath

Syntax:

cgo.drawTextOnPath(str, pth [, options]);

Description:

A Cango method that creates a TextOnPath object and renders it to the canvas.

Parameters:

str: String - The text string to be drawn with each letter's drawing origin position to lie along the path.

pth: PathSVG object - An PathSVG object defining the path along which the text is to be drawn. The path may have discontinuous sections.

options: Object - The key-value pairs of the 'options' object describe set the various properties of the text such as fontSize, fillColor etc. For details of the other properties see the Cango User Guide section Object Optional Properties

In addition to the set of options supported by the standard Text object there are two keys specific to this method:

charSpacing - Number specifying the pixel spacing between the individual characters.
offset - Number specifying the percentage of the total path length at which the first character will be drawn. If the offset means that some characters will not fit before the end of the path is reached then these characters will wrap around and be drawn at the start of the path.

drawVectorText

Syntax:

cgo.drawVectorText(str[, options]);

Description:

A Cango method creates a VectorText object with text defined by the 'str' argument and sets any of its properties as specified in the 'options' object then renders the VectorText object onto the canvas.

Parameters:

str: String - The text string to be written.

drawExpNotationText

Syntax:

cgo.drawExpNotationText(mantissa, exponent [, options]);

Description:

A Cango method that creates a ExpNotationText object and renders it to the canvas.

Parameters:

mantissa: Number or String- The mantissa of the expression to be drawn.

exponent: Number or String - The exponent of the expression to be drawn.

Note:

In addition to the set of Text options there are two keys specific to this method:

preText - defines a string that will be draw in front of the scientific notation Text.
postText - defines a string that will be draw immediately following the scientific notation Text.

drawSciNotationText

Syntax:

cgo.drawSciNotationText(value [, options]);

Description:

A Cango method that creates a SciNotationText object and renders it to the canvas.

Parameters:

value: Number - The value to be expressed as a power of 10 displaying mantissa and the exponent of the power of 10.

Note:

In addition to the set of Text options there are two keys specific to this method:

preText - defines a string that will be draw in front of the scientific notation Text.
postText - defines a string that will be draw immediately following the scientific notation Text.