# mathlive

The functions in this module are the main entry points to the MathLive public API.

To invoke these functions, use the global MathLive object. For example:

const markup = MathLive.toMarkup('e^{i\\pi}+1=0');

### Methods

#### latexToAST(latex: string) → Object

Convert a LaTeX string to an Abstract Syntax Tree

See: MASTON

latex string

A string of valid LaTeX. It does not have to start with a mode token such as a $$ or \(. Object The Abstract Syntax Tree as a JavaScript object. #### latexToMarkup(text: string, displayMode: string, formatopt: string) → string Convert a LaTeX string to a string of HTML markup. text string A string of valid LaTeX. It does not have to start with a mode token such as $$ or \(.

displayMode string

If 'displaystyle' the "display" mode of TeX is used to typeset the formula. Most appropriate for formulas that are displayed in a standalone block. If 'textstyle' is used, the "text" mode of TeX is used, which is most appropriate when displaying math "inline" with other text.

format string optional = 'html'

For debugging purposes, this function can also return a text representation of internal data structures used to construct the markup. Valid values include 'mathlist' and 'span'

string

#### latexToMathML(latex: string, options: object) → string

Convert a LaTeX string to a string of MathML markup.

latex string

A string of valid LaTeX. It does not have to start with a mode token such as a  or \(.

options object
options.generateID boolean optional = false

If true, add an extid attribute to the MathML nodes with a value corresponding with the a matching atomID.

string

#### makeMathField(element: HTMLElement,string, configopt: Object.<string, *>) → MathField

Convert a DOM element into an editable math field.

element HTMLElement | string

An HTML DOM element, for example as obtained by .getElementById(), or a string representing the ID of a DOM element.

config Object.<string, *> optional
config.horizontalSpacingScale number optional = 1.0

Scaling factor to be applied to horizontal spacing between elements.

config.namespace string optional = ''

Namespace that is added to data- attributes to avoid collisions with other libraries. It is empty by default. The namespace should be a string of lowercase letters.

config.substituteTextArea function optional

A function that returns a focusable element that can be used to capture text input. This can be useful when a <textarea> element would be undesirable. Note that by default on mobile devices the TextArea is automatically replaced with a <span> to prevent the device virtual keyboard from being displayed.

config.onFocus function optional

Invoked when the mathfield has gained focus

config.onBlur function optional

Invoked when the mathfield has lost focus

config.onKeystroke function optional

Invoked when a keystroke is about to be processed.

• keystroke is a string describing the keystroke
• ev is the keyboard event.

Return false to stop handling of the event.

config.overrideDefaultInlineShortcuts boolean optional = false

If true the default inline shortcuts (e.g. 'p' + 'i' = 'π') are ignored.

config.inlineShortcuts Object.<string, string> optional

A map of shortcuts → replacement value. For example { 'pi': '\\pi'}. If overrideDefaultInlineShortcuts is false, these shortcuts are applied after any default ones, and can therefore override them.

config.inlineShortcutTimeout number optional = 0

Maximum time, in milliseconds, between consecutive characters for them to be considered part of the same shortcut sequence.

A value of 0 is the same as infinity: any consecutive character will be candidate for an inline shortcut, regardless of the interval between this character and the previous one.

A value of 250 will indicate that the maximum interval between two characters to be considered part of the same inline shortcut sequence is 1/4 of a second.

This is useful to enter "+-" as a sequence of two characters, while also supporting the "±" shortcut with the same sequence. The first result can be entered by pausing slightly between the first and second character if this option is set to a value of 250 or so.

config.inlineShortcutConversionDelay number | string optional = 0

Time, in milliseconds, before an inline shortcut is converted.

If the value is 0, the inline shortcut is converted as soon as it is recognized. This can cause issues if there are overlapping shortcuts. For example, if there is a 'del' shortcut, the 'delta' shortcut would never get triggered.

Setting a small value, for example 250 ms, ensures that the longer shortcut can be typed without triggering the first one.

The value can also be set to 'auto', in which case the delay is 0 if the shortcut sequence is unambiguous and a small delay otherwise.

config.smartFence boolean optional = true

If true, when an open fence is entered via typedText() it will generate a contextually appropriate markup, for example using \left...\right if applicable. If false, the literal value of the character will be inserted instead.

config.ignoreSpacebarInMathMode boolean optional = true

If true, when the spacebar is pressed, no space is inserted. If false, a space is inserted when the spacebar is pressed.

config.virtualKeyboardToggleGlyph string optional

If specified, the markup to be used to display the virtual keyboard toggle glyph. If none is specified a default keyboard icon is used.

config.virtualKeyboardMode string optional = ''

• 'manual': pressing the virtual keyboard toggle button will show or hide the virtual keyboard. If hidden, the virtual keyboard is not shown when the field is focused until the toggle button is pressed.
• 'onfocus': the virtual keyboard will be displayed whenever the field is focused and hidden when the field loses focus. In that case, the virtual keyboard toggle button is not displayed.
• 'off': the virtual keyboard toggle button is not displayed, and the virtual keyboard is never triggered.

If the setting is empty, it will default to 'onfocus' on touch-capable devices and to 'off' otherwise.

config.virtualKeyboards string optional = 'all'

A space separated list of the keyboards that should be available. The keyboard 'all' is synonym with:

• 'numeric', 'roman', 'greek', 'functions' and 'command'

The keyboards will be displayed in the order indicated.

config.virtualKeyboardRomanLayout string optional = 'qwerty'

The arrangement of the keys for the layers of the roman virtual keyboard. One of 'qwerty', 'azerty', 'qwertz', 'dvorak' or 'colemak'.

config.customVirtualKeyboardLayers Object optional

Some additional custom virtual keyboard layers. A keyboard is made up of one or more layers (think of the main layer and the shift layer on a hardware keyboard). Each key in this object define a new keyboard layer (or replace an existing one). The value of the key should be some HTML markup.

config.customVirtualKeyboards Object optional

An object describing additional keyboards. Each key in the object is an ID for a separate keyboard. The key should have a value made up of an object with the following keys:

• tooltip: a string label describing the keyboard.
• label: a string, displayed in the keyboard switcher to identify this keyboard
• layers: an array of strings, the ID of the layers used by this keyboard. These layers should be defined using customVirtualKeyboardLayers.
• classes: a string, the classes to be added to the label for this keyboard Possible values are 'tex' to use a TeX font to display the label.
• layer: optional, the ID of the layer to switch to when the label of this keyboard is clicked on in the keyboard switcher.
• command: optional, a selector to perform when the label is clicked. Either the command or layer key must be present.

config.virtualKeyboardTheme boolean optional = ''

The visual theme used for the virtual keyboard. If empty, the theme will switch automatically based on the device it's running on. The two supported themes are 'material' and 'apple' (the default).

config.keypressVibration boolean optional = 'on'

When a key on the virtual keyboard is pressed, produce a short haptic feedback, if the device supports it.

config.keypressSound boolean optional = ''

When a key on the virtual keyboard is pressed, produce a short audio feedback. The value should be either a URL to a sound file or an object with the following keys:

• delete URL to a sound file played when the delete key is pressed
• return ... when the return/tab key is pressed
• spacebar ... when the spacebar is pressed
• default ... when any other key is pressed. This key is required, the others are optional. If they are missing, this sound is played as well.

config.plonkSound string optional = ''

Path to a URL to a sound file which will be played to provide feedback when a command has no effect, for example when pressing the spacebar at the root level.

config.textToSpeechRules string optional = 'mathlive'

Specify which set of text to speech rules to use. A value of mathlive indicates that the simple rules built into MathLive should be used. A value of sre indicates that the Speech Rule Engine from Volker Sorge should be used. Note that SRE is not included or loaded by MathLive and for this option to work SRE should be loaded separately.

config.textToSpeechMarkup string optional = ''

The markup syntax to use for the output of conversion to spoken text. Possible values are ssml for the SSML markup or mac for the MacOS markup (e.g. [[ltr]])

config.textToSpeechRulesOptions * optional = {}

A set of value/pair that can be used to configure the speech rule engine. Which options are available depends on the speech rule engine in use. There are no options available with MathLive's built-in engine. The options for the SRE engine are documented [here]{@link:https://github.com/zorkow/speech-rule-engine}

config.speechEngine string optional = 'local'

Indicates which speech engine to use for speech output. Use local to use the OS-specific TTS engine. Use amazon for Amazon Text-to-Speech cloud API. You must include the AWS API library and configure it with your API key before use. See the 'speech' example project for more details.

config.speechEngineVoice string optional = ''

Indicates the voice to use with the speech engine. This is dependent on the speech engine. For Amazon Polly, see here: https://docs.aws.amazon.com/polly/latest/dg/voicelist.html

config.speechEngineRate string optional = ''

Sets the speed of the selected voice. One of x-slow, slow, medium, fast,x-fast or a value as a percentage. For example 200% to indicate a speaking rate twice the default rate. Range is 20% to 200%

config.onMoveOutOf function optional

A handler invoked when keyboard navigation would cause the insertion point to leave the mathfield.

The argument indicates the direction of the navigation, either "forward" or "backward".

Return false to prevent the move, true to wrap around to the start of the field.

By default, the insertion point will wrap around.

config.onTabOutOf function optional

A handler invoked when pressing tab (or shift-tab) would cause the insertion point to leave the mathfield.

The argument indicates the direction of the navigation, either "forward" or "backward".

By default, the insertion point jumps to the next/previous focussable element.

config.onContentWillChange function optional

A handler invoked just before the content is about to be changed.

config.onContentDidChange function optional

A handler invoked just after the content has been changed.

config.onSelectionWillChange function optional

A handler invoked just before the selection is about to be changed.

config.onSelectionDidChange function optional

A handler invoked just after the selection has been changed.

config.onUndoStateWillChange function optional

A handler invoked before a change in the undo stack state. The command argument is a string indication what caused the state change: "undo", "redo" or "snapshot".

config.onUndoStateDidChange function optional

A handler invoked after a change in the undo stack state. The command argument is a string indication what caused the state change: "undo", "redo" or "snapshot".

config.onVirtualKeyboardToggle function optional

A handler invoked after the virtual keyboard visibility has changed.

The visible argument is true if the virtual keyboard is visible.

The second argument is a DOM element containing the virtual keyboard, which can be used to determine its size, and therefore the portion of the screen it obscures.

config.onReadAloudStatus function optional

A handler invoked when the status of read aloud changes.

The status argument is a string denoting the status:

• "playing" when reading begins
• "done" when reading has been completed,
• "paused" when reading has been temporarily paused by the user

config.handleSpeak function optional

A callback invoked to produce speech from a string.

config.handleReadAloud * optional

A callback invoked to produce speech and highlight the relevant atoms in an equation. The input is SSML markup with appropriate <mark> tags.

If a Read Aloud operation is in progress, stop it.

#### playReadAloud(token: string, countnullable: number)

If a Read Aloud operation is in progress, read from a specified token

token string
count number nullable

#### readAloud(element: DOMElement, text: string, config: object)

Start a Read Aloud operation (reading with synchronized highlighting).

element DOMElement

The DOM element to highlight

text string

The text to speak

config object

Return the status of a Read Aloud operation (reading with synchronized highlighting). Possible values include:

• ready
• playing
• paused

#### renderMathInDocument(optionsopt: Object)

Transform all the elements in the document body that contain LaTeX code into typeset math.

See: Usage Guide

options Object optional

See renderMathInElement() for details

#### renderMathInElement(element: Element,string, optionsopt: Object)

Transform all the children of element, recursively, that contain LaTeX code into typeset math.

See: Usage Guide

element Element | string

An HTML DOM element, or a string containing the ID of an element.

options Object optional
options.namespace string optional = ''

Namespace that is added to data- attributes to avoid collisions with other libraries. It is empty by default. The namespace should be a string of lowercase letters.

options.macros Array.<object> optional = {}

Custom macros

options.skipTags Array.<string>

an array of tag names whose content will not be scanned for delimiters

options.ignoreClass string optional = 'tex2jax_ignore'

a string used as a regular expression of class names of elements whose content will not be scanned for delimiters

options.processClass string optional = 'tex2jax_process'

a string used as a regular expression of class names of elements whose content will be scanned for delimiters, even if their tag name or parent class name would have prevented them from doing so.

options.preserveOriginalContent boolean optional = true

if true, store the original textual content of the element in a data-original-content attribute. This value can be accessed for example to restore the element to its original value:

     elem.innerHTML = elem.dataset.originalContent;

options.readAloud boolean optional = false

if true, generate markup that can be read aloud later using MathLive.readAloud()

options.TeX.processEnvironments boolean

if false, math expression that start with \begin{ will not automatically be rendered. (true by default)

options.TeX.delimiters.inline Array
options.TeX.delimiters.display Array

TeX.delimiters.display arrays of delimiters that will trigger a render of the content in 'textstyle' or 'displaystyle', respectively.

If a Read Aloud operation is paused, resume it

#### revertToOriginalContent(element: string,Element,MathField, optionsopt: Object)

element string | Element | MathField
options Object optional = {}
options.namespace string

The namespace used for the data- attributes. If you used a namespace with renderMathInElement, you must use the same namespace here.

#### revertToOriginalContent(element: string,Element,MathField, optionsopt: Object) → string

element string | Element | MathField
options Object optional = {}
options.namespace string

The namespace used for the data- attributes. If you used a namespace with renderMathInElement, you must use the same namespace here.

string

the original content of the element.

#### highlightAtomID(atomID: string)inner

Highlight the span corresponding to the specified atomID This is used for TTS with synchronized highlighting (read aloud)

atomID string