mathlive

The native keyboard event

A string descring the keystroke, for example `“Alt-KeyU”. See W3C UIEvents for more information on the format of the descriptor.

Support for Trusted Type.

This optional function will be called before a string of HTML is injected in the DOM, allowing that string to be sanitized according to a policy defined by the host.

A URL fragment pointing to the directory containing the fonts necessary to render a formula.

These fonts are available in the /dist/fonts directory of the SDK.

Customize this value to reflect where you have copied these fonts, or to use the CDN version.

The default value is ‘./fonts’.

Changing this setting after the mathfield has been created will have no effect.

{
     // Use the CDN version
     fontsDirectory: ''
}

{
     // Use a directory called 'fonts', located next to the
     // `mathlive.js` (or `mathlive.mjs`) file.
     fontsDirectory: './fonts'
}

{
     // Use a directory located at the top your website
     fontsDirectory: 'https://example.com/fonts'
}

Namespace that is added to data- attributes to avoid collisions with other libraries.

The namespace should be a string of lowercase letters.

It is empty by default.

A URL fragment pointing to the directory containing the optional sounds used to provide feedback while typing.

Some default sounds are available in the /dist/sounds directory of the SDK.

When true and the spacebar is pressed, no space is inserted.

When false, a space is inserted when the spacebar is pressed.

When true, the user cannot edit the mathfield.

If true, extra parentheses around a numerator or denominator are removed automatically.

This option controls how many levels of subscript/superscript can be entered. For example, if scriptDepth is “1”, there can be one level of superscript or subscript. Attempting to enter a superscript while inside a superscript will be rejected. Setting a value of 0 will prevent entry of any superscript or subscript (but not limits for sum, integrals, etc…)

This can make it easier to enter equations that fit what’s expected for the domain where the mathfield is used.

To control the depth of superscript and subscript independently, provide an array: the first element indicate the maximum depth for subscript and the second element the depth of superscript. Thus, a value of [0, 1] would suppress the entry of subscripts, and allow one level of superscripts.

When true and an open fence is entered via typedText() it will generate a contextually appropriate markup, for example using \left...\right if applicable.

When false, the literal value of the character will be inserted instead.

When true, during text input the field will switch automatically between ‘math’ and ‘text’ mode depending on what is typed and the context of the formula. If necessary, what was previously typed will be ‘fixed’ to account for the new info.

For example, when typing “if x >0”:

Smart Mode is off by default.

Manually switching mode (by typing alt/option+=) will temporarily turn off smart mode.

Examples

• slope = rise/run
• If x > 0, then f(x) = sin(x)
• x^2 + sin (x) when x > 0
• When x<0, x^{2n+1}<0
• Graph x^2 -x+3 =0 for 0<=x<=5
• Divide by x-3 and then add x^2-1 to both sides
• Given g(x) = 4x – 3, when does g(x)=0?
• Let D be the set {(x,y)|0<=x<=1 and 0<=y<=x}
• \int_{the unit square} f(x,y) dx dy
• For all n in NN

When true, when a digit is entered in an empty superscript, the cursor leaps automatically out of the superscript. This makes entry of common polynomials easier and faster. If entering other characters (for example “n+1”) the navigation out of the superscript must be done manually (by using the cursor keys or the spacebar to leap to the next insertion point).

When false, the navigation out of the superscript must always be done manually.

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 750 will indicate that the maximum interval between two characters to be considered part of the same inline shortcut sequence is 3/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.

Note that some operations, such as clicking to change the selection, or losing the focus on the mathfield, will automatically timeout the shortcuts.

The keys of this object literal indicate the sequence of characters that will trigger an inline shortcut.

string | {after?: string; mode?: ParseMode; value: string}

The command is a single selector, or a selector with arguments

If specified, this indicates in which mode this keybinding will apply. If none is specified, the keybinding apply in every mode.

If specified, this indicates the OS platform to which this keybinding apply.

For example, if set to !macos this key binding will apply to every platform, except macOS.

The pressed keys that will trigger this keybinding.

The key is made up of modifiers and the key itself.

The following modifiers can be used:

If the cmd modifier is used, the keybinding will only apply on macOS. If the win modifier is used, the keybinding will only apply to Windows. If the meta modifier is used, the keybinding will apply to platforms other than macOS or Windows.

The alt key is the option key on Apple keyboards.

The following values for keys can be used:

• a–z, 0–9
• `, -, =, [, ], \, ;, ', ,, ., /
• left, up, right, down, pageup, pagedown, end, home
• tab, enter, escape, space, backspace, delete
• f1–f19
• pausebreak, capslock, insert
• numpad0–numpad9, numpad_multiply, numpad_add, numpad_separator
• numpad_subtract, numpad_decimal, numpad_divide

The values will be remapped based on the current keyboard layout. So, for example if a is used, on a French AZERTY keyboard the keybinding will be associated with the key labeled ‘A’ (event though it corresponds to the key labeled ‘Q’ on a US QWERTY keyboard).

To associate keybindings with physical keys independent of the keyboard layout, use the following keycodes:

• [KeyA]–[KeyZ], [Digit0]–[Digit9]
• [Backquote], [Minus], [Equal], [BracketLeft], [BracketRight], [Backslash], [Semicolon], [Quote], [Comma], [Period], [Slash]
• [ArrowLeft], [ArrowUp], [ArrowRight], [ArrowDown], [PageUp], [PageDown], [End], [Home]
• [Tab], [Enter], [Escape], [Space], [Backspace], [Delete]
• [F1]–[F19]
• [Pause], [CapsLock], [Insert]
• [Numpad0]–[Numpad9], [NumpadMultiply], [NumpadAdd], [NumpadComma]
• [NumpadSubtract], [NumpadDecimal], [NumpadDivide]

For example, using [KeyQ] will map to the the key labeled ‘Q’ on a QWERTY keyboard, and to the key labeled ‘A’ on an AZERTY keyboard.

As a general guideline, it is preferable to use the key values a–z for keybinding that are pseudo-mnemotechnic. For the other, it is generally preferable to use the keycodes.

Consider the key combination: alt+2. With an AZERTY (French) layout, the digits (i.e. ‘2’) are only accessible when shifted. The ‘2’ key produces ‘é’ when not shifted. It is therefore impossible on an AZERTY keyboard to produce the alt+2 key combination, at best it would be alt+shift+2. To indicate that the intended key combination should be alt and the key on the keyboard which has the position of the 2 key on a US keyboard, a key code should be used instead: alt+[Digit2]. This will correspond to a key combination that can be generated on any keyboard.

If a keybinding is invalid (impossible to produce) with the current keyboard layout, an error will be generated, and the onError listener will be called with a invalid-keybinding error code.

Scaling factor to be applied to horizontal spacing between elements of the formula. A value greater than 1.0 can be used to improve the legibility.

Control the letter shape style:

(it) = italic (up) = upright

The default letter shape style is auto, which indicates that french should be used if the locale is “french”, and tex otherwise.

A dictionary of LaTeX macros to be used to interpret and render the content.

For example, to add a new macro to the default macro dictionary:

mf.setConfig({
macros: {
...mf.getOption('macros'),
smallfrac: '^{#1}\\!\\!/\\!_{#2}',
},
});

Note that getOption() is called to keep the existing macros and add to them. Otherwise, all the macros are replaced with the new definition.

The code above will support the following notation:

\smallfrac{5}{16}

The locale (language + region) to use for string localization.

If none is provided, the locale of the browser is used.

An object whose keys are a locale string, and whose values are an object of string identifier to localized string.

Example

{
"fr-CA": {
"tooltip.undo": "Annuler",
"tooltip.redo": "Refaire",
}
}

This will override the default localized strings.

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 speech example

Sets the speed of the selected voice.

One of x-slow, slow, medium, fast, x-fast or a value as a percentage.

Range is 20% to 200% For example 200% to indicate a speaking rate twice the default rate.

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

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, i.e. [[ltr]].

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.

See speech example

A set of key/value pairs 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

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.

See virtual keyboard example

When a key on the virtual keyboard is pressed, produce a short audio feedback.

If the property is set to a string or HTMLAudioElement, the same sound is played in all cases. Otherwise, a distinct sound is played:

• delete a sound 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.

The value of the properties should be either a string, the name of an audio file in the soundsDirectory directory, or an HTMLAudioElement.

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

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

The property is either a string, the name of an audio file in the soundsDirectory directory, or an HTMLAudioElement.

• '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.

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).

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

The right hand side toolbar configuration.

Use none to disable right hand side toolbar of virtual keyboard.

A space separated list of the keyboards that should be available. The keyboard 'all' is synonym with 'numeric', 'functions'``,‘symbols’`` 'roman' and 'greek',

The keyboards will be displayed in the order indicated.