Virtual Keyboards
Typing math formulas require access to many special symbols. While keyboard shortcuts and inline shortcuts can help, mobile devices require another solution. A virtual keyboard is a keyboard displayed on screen that can be customized with specialized symbols for math input.
The mathfield virtual keyboard panel can display multiple keyboards. The default keyboards are numeric, functions, symbols, roman letters and greek letters.
These keyboards include the most common math symbols and they can be customized to fit your specific needs. For example you can remove some keyboards, or create new ones.
Touch and hold a key to display variants related to the key. Not all keys have variants, though.
Controlling when the virtual keyboard panel is displayed
The default behavior of the virtual keyboard panel is to only be displayed on touch-enabled devices (mobile phones, tablets, laptops with a touch-screen) when a matfield is focused.
This behavior can be changed with the virtualKeyboardMode
configuration property:
"auto"
: this is the default behavior: on touch-enabled devices, show the virtual keyboard panel when the mathfield is focused, otherwise, don’t show it."manual"
: a toggle button to control the virtual keyboard panel is displayed in the mathfield"onfocus"
: the virtual keyboard panel is displayed when the mathfield is focused"off"
: never show the virtual keyboard panel
There is only one virtual keyboard panel displayed at a time, but each mathfield can specify different virtual keyboard panel configurations.
Customizing the appearance of the virtual keyboard toggle
By specifying a CSS rule for the .ML__virtual-keyboard-toggle
selector the
appearance of the virtual keyboard toggle can be modified.
Make sure the rule has sufficient CSS specificity to be applied. Add a !important
directive or prefix the selector with the id of your mathfield.
The icon of the virtual keyboard toggle can be changed using the virtualKeyboardToggleGlyph
configuration property.
Changing the arrangement of alphabetical keys
By default, the layout of the alphabetic virtual keyboard is determined based on the locale (QWERTY for english speaking countries, AZERTY for french speaking countries, etc…).
To select a different alphabetic keyboard layouts, such as DVORAK and COLEMAK,
use the virtualKeyboardLayout
configuration property.
Customizing the appearance of the virtual keyboard keycaps
The appearance of keycaps can be controlled with the following CSS variables:
--keycap-height
--keycap-font-size
--keycap-small-font-size
(only if needed)--keycap-extra-small-font-size
(only if needed)--keycap-tt-font-size
(only if needed)
Sharing virtual keyboards amongst multiple instances
When there are multiple mathfield elements in a page, they usually each have their own virtual keyboard.
However, in some cases it might be desirable to have the virtual keyboard instance “detached” from the mathfield, and potentially shared by multiple mathfield elements.
That’s the case for example when mathfield elements are displayed in an iframe. Since an iframe is essentially a mini embedded document, the default virtual keyboard will not display correctly when use in an iframe, as it will be attached to the iframe instead of being attached to the main document.
This can be solved by using a “shared” virtual keyboard.
To use a shared virtual keyboard, call the makeSharedVirtualKeyboard()
function in the context of the main document.
makeSharedVirtualKeyboard({
virtualKeyboardLayout: 'dvorak',
});
In the iframe elements, use the use-shared-virtual-keyboard
attribute on
the math-field
elements.
<math-field use-shared-virtual-keyboard></math-field>
Controling which keyboards are displayed
The virtual keyboard panel displays multiple keyboards which can be
toggled using the keyboard switcher: numeric
, functions
, symbols
, roman
and greek
.
To choose which keyboards are available, use the virtualKeyboards
configuration property. The value of this property is a space-separated string
of the name of the keyboards that should be displayed.
Defining custom virtual keyboards
A virtual keyboard is made up of one or more “layers”. A keyboard layer is a
set of keys that can be toggled using another key. For example, the roman
keyboard has a regular layer and a layer for symbols. Most keyboards have a single layer.
Custom virtual keyboard layouts can be defined with an object literal.
Defining a layer
First, let’s define a layer, which we’ll call "college-layer"
.
A layer is an array of rows, a row is an array of keycaps.
Each keycap can have the following properties:
-
class
: the CSS classes to style this keycap. The classes can be custom defined (see below about thestyles
layer property), or be one of the default ones:keycap
: a standard-width keycap, using the system font for its labelkeycap tex
: a standard-width keycap, using the TeX font for its label. Using thetex
class is not necessary if using thelatex
property to define the label.modifier
: a modifier (shift/option, etc…) keycapkeycap small
: display the label in a smaller sizeaction
: an “action” keycap (for arrows, return, etc…)separator w5
: a half-width blank used as a separator. Other widths includew15
(1.5 width),w20
(double width) andw50
(five-wide, used for the space bar).bottom
,left
,right
: alignment of the label
-
label
: the HTML markup displayed for the keycap. If nolabel
is provided, thelatex
value is used. If nokey
,command
orinsert
property is provided, the label (stripped of any HTML markup) is what will be inserted when the keycap is pressed. -
latex
: a Latex fragment used as a label and as the content to insert when the keycap is pressed. -
key
: the keypress to emulate when the keycap is pressed, for example"5"
. -
aside
: an optional small label displayed below the keycap. This label may not be displayed if the space available is too small. -
insert
: a Latex fragment to insert when the keycap is pressed. Thelatex
property is usually sufficient, -
altKeys
: the name of a set of alternate keys to display when the keycap is long-pressed. -
command
: the command to perform when the keycap is pressed. -
shifted
: the HTML markup to display as the label of the keycap when the shift key is pressed -
shiftedCommand
: the command to perform when the keycap is pressed with the shift key.
The following properties, in order, are used to determine how to display
they keycap: latex
, label
, insert
.
When the keycap is pressed, the following properties are used, in order, to
determine the action to perform: command
, insert
, latex
, key
.
To associate a CSS stylesheet with this layer, use the styles
property of the
layer.
The appearance of the layer can be further customized by providing a CSS class
name for the backdrop
and container
properties of the layer.
const COLLEGE_KEYBOARD_LAYER = {
"college-layer": {
styles: "",
rows: [
[
{ class: "keycap tex", latex: "a" },
{ class: "keycap tex", latex: "x" },
{ class: "separator w5" },
{ class: "keycap", label: "7", key: "7" },
// Will display the label using the system font. To display
// with the TeX font, use:
// { class: "keycap tex", label: "7", key: "7" },
// or
// { class: "keycap", latex: "7"},
{ class: "keycap", label: "8", key: "8" },
{ class: "keycap", label: "9", key: "9" },
{ class: "keycap", latex: "\\div" },
{ class: "separator w5" },
{
class: "keycap tex small",
insert: "$$#@^{2}$$",
label: "<span><i>x</i> ²</span>"
},
{
class: "keycap tex small",
insert: "$$#@^{}$$",
label: "<span><i>x</i><sup> <i>n</i></sup></span>"
},
{
class: "keycap small",
insert: "$$\\sqrt{#0}$$",
latex: "\\sqrt{#0}"
}
],
[
{ class: "keycap tex", latex: "b" },
{ class: "keycap tex", latex: "y" },
{ class: "separator w5" },
{ class: "keycap", label: "4", latex:"4" },
{ class: "keycap", label: "5", key: "5" },
{ class: "keycap", label: "6", key: "6" },
{ class: "keycap", latex: "\\times" },
{ class: "separator w5" },
{ class: "keycap small", latex: "\\frac{#0}{#0}" },
{ class: "separator" },
{ class: "separator" }
],
[
{ class: "keycap tex", label: "<i>c</i>" },
{ class: "keycap tex", label: "<i>z</i>" },
{ class: "separator w5" },
{ class: "keycap", label: "1", key: "1" },
{ class: "keycap", label: "2", key: "2" },
{ class: "keycap", label: "3", key: "3" },
{ class: "keycap", latex: "-" },
{ class: "separator w5" },
{ class: "separator" },
{ class: "separator" },
{ class: "separator" }
],
[
{ class: "keycap", latex: "(" },
{ class: "keycap", latex: ")" },
{ class: "separator w5" },
{ class: "keycap", label: "0", key: "0" },
{ class: "keycap", latex: "." },
{ class: "keycap tex", latex: "\\pi" },
{ class: "keycap", latex: "+" },
{ class: "separator w5" },
{
class: "action",
command: ["performWithFeedback", "moveToPreviousChar"],
label: "<svg><use xlink:href='#svg-arrow-left' /></svg>"
},
{
class: "action",
command: ["performWithFeedback", "moveToNextChar"],
label: "<svg><use xlink:href='#svg-arrow-right' /></svg>"
},
{
class: "action font-glyph bottom right",
command: ["performWithFeedback", "deleteBackward"],
label: "⌫"
}
]
]
}
};
Defining a keyboard
Now, let’s define a new keyboard called "college-keyboard"
.
The keyboard has a label
which is displayed in the keyboard selector area
of the virtual keyboard. When hovering on this label, a tooltip
can be
displayed to further explain what the keyboard is about.
Finally, we must provide the layers that make up this keyboard.
In this example we have a single layer, so we can set the value of the
layer
property to the name of the layer.
If we had several layers, we could set the property layers
to an
array of their names.
const COLLEGE_KEYBOARD = {
"college-keyboard": {
"label": "College", // Label displayed in the Virtual Keyboard Switcher
"tooltip": "College Level", // Tooltip when hovering over the label
"layer": "college-layer"
}
};
Adding the layers and keyboards
Now, we just have to call setOptions()
with our custom layer and custom
keyboard.
The virtualKeyboards
option indicate which keyboards we want to be available.
Here we only want our keyboard, so we’ll just pass its name.
If we wanted multiple keyboards, we could provide a space-separated list, for
example "numeric college-keyboard symbols"
. If we wanted all the default
keyboards, plus ours, we could have used the "all"
shortcut:
"all college-keyboard"
.
mf.setOptions({
"customVirtualKeyboardLayers": COLLEGE_KEYBOARD_LAYER
"customVirtualKeyboards": COLLEGE_KEYBOARD,
"virtualKeyboards": "college-keyboard"
});
}
Next
- Web Component Lifecycle
- Understand in depth the lifecycle of a MathfieldElement: construction, interaction with the DOM and when can you communicate with it.