# 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

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 mathfieldCallback optional

Invoked when the mathfield has gained focus

config.onBlur mathfieldCallback optional

Invoked when the mathfield has lost focus

config.onKeystroke mathfieldCallback optional

Invoked when a keystroke is about to be processed. First argument is a string describing the keystroke, the second 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.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.virtualKeyboardToggleGlyph string optional

If specified, the markup to be used to display the virtual keyboard toggle glyph.

config.virtualKeyboardMode string optional = ''

If 'manual', pressing the command bar toggle will display a virtual keyboard instead of the command bar. If 'onfocus', the virtual keyboard will be displayed whenever the field is focused. In that case, the command bar toggle is not displayed. When this setting is not empty, config.overrideDefaultCommands and config.commands are ignored.

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.

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 mathfieldWithDirectionCallback optional

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

By default, the insertion point will wrap around.

config.onTabOutOf mathfieldWithDirectionCallback optional

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

By default, the insertion point jumps to the next point of interest.

config.onDeleteOutOf mathfieldWithDirectionCallback optional

A handler called when deleting an item would cause the insertion point to leave the mathfield.

By default, nothing happens. @todo Not implemented yet.

config.onSelectOutOf mathfieldWithDirectionCallback optional

A handler called when the selection is extended so that it would cause the insertion point to leave the mathfield.

By default, nothing happens. @todo Not implemented yet.

config.onUpOutOf mathfieldCallback optional

A handler called when the up arrow key is pressed with no element to navigate to.

By default, nothing happens. @todo Not implemented yet.

config.onDownOutOf mathfieldCallback optional

A handler called when the up down key is pressed with no element to navigate to.

By default, nothing happens. @todo Not implemented yet.

config.onEnter mathfieldCallback optional

A handler called when the enter/return key is pressed and it is not otherwise handled. @todo

config.onContentWillChange mathfieldCallback optional

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

config.onContentDidChange mathfieldCallback optional

A handler called just after the content has been changed.

config.onSelectionWillChange mathfieldCallback optional

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

config.onSelectionDidChange mathfieldCallback optional

A handler called just after the selection has been changed.

config.onVirtualKeyboardToggle mathfieldCallback optional

A handler
called after the virtual keyboard visibility has changed. The first 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 mathfieldCallback optional

A handler called when the status of read aloud changes. The first argument is a string denoting the status, one of playing sent when reading begins, done when reading has been completed, paused when reading has been temporarily paused by the user.

config.handleSpeak * 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.

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)

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.

### Type Definitions

#### mathfieldWithDirectionCallback(direction: number) → boolean

Mathfield
Mathfield
direction number
boolean

False to suppress default behavior.