Main ideas

The MathFlow Editor interface includes two input/display modes, Design view and Source view.

  • Design view is the standard mode for creating and editing your equations. In this view, the input is displayed as it will be seen in your document.
  • Source view is an alternate mode which displays the exact MathML syntax and structure and operates just like a text editor, allowing you to directly edit equation content within the MathML itself.

After you have added the templates in the Design view, you can view and edit the MathML in the Source view. Click the Design view or Source view tab just below the editor window to switch modes. Changes made in either mode are immediately reflected in the other. The Editor will always open into the view used in the last editing session. Most of the MathFlow Editor documentation is based on the standard Design view. We describe Source view later in the Source editing section and in the MathFlow tutorials.

Equation templates

The editor is based on the idea of an equation template. There are templates for fractions, subscripts, superscripts, matrices, etc. To build an equation, you insert templates and fill in the blanks.

equation templates in the MathFlow Editor

To fill in the blanks, enter letters and numbers from the keyboard, select symbols from a palette, or replace a blank with another template. If you select something before inserting a template from the toolbar, the symbol or expression you've selected will automatically be inserted into the first blank in the template. Some people describe this as "wrapping" a template around a selection.

By nesting equation templates inside one another, you can build up almost any equation. Navigate around an equation using the mouse and arrow keys. You can also cut and paste sub-expressions to build up more complex expressions.

nesting templates inside another

The editor templates and symbols are directly based on MathML. MathML is the markup language for encoding math on the Web standardized by the World Wide Web Consortium (W3C). You can certainly use the editor without knowing much (if anything) about MathML.

Example: MathML source code for a very simple expression x + 4.

<math><mi>x</mi><mo>+</mo><mn>4</mn></math>

MathFlow Editor allows you to customize many typesetting and style properties to fine-tune visual appearances. You edit properties by selecting an expression and opening a property dialog box from the editor menu bar. Typesetting and style properties mostly correspond directly to MathML concepts. That is, changing properties corresponds to setting MathML attributes. In most cases, MathFlow can process the full range of valid MathML attribute values.

The possible values for each style property are discussed in MathFlow Editor: Controlling style properties, and in the Editor online help.

For simple equations, you may only need the letters, symbols, and digits available on the keyboard. However, in many situations, you will want to enter special mathematical symbol characters. You can enter a symbol in an equation by clicking it on the toolbar, or by selecting it from one of the symbol palettes, also on the toolbar.

Alternatively, if you know the symbol's name or numerical code, you can enter it directly, using the Insert Symbol submenu.

Can insert symbol with Unicode value

The standard toolbar configuration contains many commonly used symbol characters. However, there is a very large number of MathML symbols (around 1300), and although MathFlow doesn't support all 1300, it supports more than what appears in the standard toolbar.

Note: It's common for the hex value for a Unicode character to be displayed with the leading characters 0x. In the Insert Symbol dialog, if you lead the value with 0x, you will get an error. Thus the correct entry for the example above is 2135 as shown, and not 0x2135.

MathFlow Editor has customizable toolbars and by changing toolbar palettes, you can access most of the MathML symbols MathFlow supports. However, some rare characters don't appear in the built-in toolbars, so if you need to use these characters frequently, you will probably want to make a custom toolbar containing them.

Moving the cursor

Most of the time, cursor movement in MathFlow Editor works as you would expect, and you don't need to think too hard about it. However, as the cursor moves through your equation, its shape changes to give you extra information about the equation structure. Spending a few minutes learning about the subtleties of cursor movement will have a big payoff in the long run.

MathFlow Editor tries to make cursor movement as natural and intuitive as possible. In general, the left, right, up and down arrows move the cursor to the next valid insertion point in the corresponding direction. Similarly, clicking the mouse anywhere in an equation moves the cursor to the closest valid location to the click.

Behind the scenes, the MathFlow Editor is negotiating a potentially complicated nested structure of MathML templates. Moving the cursor to the right on the screen can involve jumping in and out of MathML structures behind the scenes.

The cursor may occasionally not move exactly as you would expect on account of the nesting of the MathML structure. In these cases, the cursor movement is giving you additional information about the structure of your equation.

To help you follow where the cursor is in the MathML structure of the equation, the MathFlow Editor gives two visual cues. The cursor position is represented by a blinking red vertical bar. However, note that there is a faint gray rectangle as well. This gray rectangle is outlining the equation template containing the cursor location and is the first cue about the MathML structure near the cursor.

To illustrate, consider stepping through the following equation with the right arrow.

The expression is x plus one-half. Cursor is outside the fraction, to the left of the fraction.

As the cursor moves to the right, note that when it moves into the fraction, the gray rectangle shifts to the fraction, instead of the entire equation.

Same expression, x plus one-half. Cursor now has moved to the right, and is in the numerator, to the left of the numeral one.

The second visual cue about the location of the cursor in the nested MathML template structure is the MathML Ancestry panel. As you move the cursor, you can see the nesting of MathML templates, with the innermost template or symbol that the cursor is on at the far right of the Ancestry panel, and the outermost ‹math› template on the left.

In more complicated situations, one might have several nested rows, where the right edges all align. When this happens, hitting the right arrow will move the cursor from an inner template to an outer template in the nesting. Although you will see the gray rectangle outlining the parent template and MathML Ancestry panel change, the actual cursor position stays the same.

The expression is x to the y power to the m power to the n power. The cursor is located in the innermost exponent -- which is the variable en. Clicking the right arrow moves to the next outer level, and so on.

By spending a few minutes playing with cursor movement and nested templates, you will rapidly get the hang of navigating around in a structured MathML equation.

Cursor shapes

Math cursor

When you start a new equation, the cursor automatically starts as a blinking vertical red line. When the Editor window loses focus, the cursor changes to gray and stops blinking. The vertical line is the normal cursor in MathFlow editor.

As you type, the editor will begin inserting the characters into the equation, and the cursor will move to show the insertion point. Also, a faint gray box will appear, outlining the template in which the cursor is currently located. As you move around in an equation, the gray outline shifts, giving you a visual cue about the nesting structure of the underlying MathML, as illustrated here:

See next paragraph for explanation of the screen shot.

In the first two illustrations, the cursor is located in the numerator and denominator of a fraction, and the outlined parent is the row template containing the entire numerator and denominator respectively. In the third illustration, the cursor is on the left edge of the fraction itself, and the outlined parent is a "wrapper" row containing the fraction itself.

Token cursor

The Editor will automatically put characters into special MathML templates called tokens. There are tokens for variables (called an <mi> template in MathML, for math identifier), numbers (<mn>), operators (<mo>), and so on.

The right and left arrow keys generally move the cursor between the tokens in the row. However, when you move the cursor over a token that contains several characters together, the cursor will take an upside-down T-shape to show the extent of the grouped items by underlining them, as shown here.

In the expression ex plus one two three, the cursor is between two and three, and is an upside-down T shape.

Within a token, the arrow keys will move the cursor between the individual characters in the token. You can also position the cursor within a multi-character token with the mouse.

In MathML, identifier tokens with more than one character, e.g. "sin", are rendered in an upright font by default, while single character tokens are rendered in italics. If you move two alphabetic tokens together, say by deleting an intervening space, the editor will automatically merge the characters together into a single token. Similar behavior applies to numbers. By noticing the cursor shape, you can easily keep track of what characters are being grouped into tokens.

Text cursor

The MathFlow editor also supports the MathML text template. Within a text template, characters appear in an upright font by default, and the spacebar always inserts a space. Outside a text template, the spacebar may not insert a space. See Keyboard input for details.

When the cursor is inside a text template, it changes to an "I-beam" shape.

Screen shot shows the I-beam cursor inside a text template.

You can insert a text template either from the layout templates palette on the toolbar (it looks like a T inside a dashed box) or from the Insert menu or by using the keyboard shortcut Ctrl+T.

Cursor embellishment for non-MathML elements

As the cursor moves through the equation, a small triangle may appear below the cursor, as seen in this image:

In the expression, a small red triangle appears beneath the cursor, described in the next paragraph.

This triangle is used to indicate the presence of non-MathML markup somewhere within a given element. The example image above was created with the following MathML:

<math>
   <mrow>
      <mfrac>
         <mrow>
            <mi>a</mi>
         </mrow>
         <?foo?>
         <!-- comment --!>
         <atag/>
         <mrow>
            <mi>b</mi>
         </mrow>
      </mfrac>
   </mrow>
</math>

Notice the non-MathML elements between the numerator and denominator elements of the mfrac. Technically, these non-MathML elements should be displayed in Design view in the same location as the fraction bar, which would be very confusing. Since there are many situations where this kind of problem can occur, all such situations will be displayed with the upward facing triangle below the text cursor, whenever the text cursor is "on" an element with non-MathML elements inside. If you place your mouse cursor over the triangle, the status bar will show you the name of the element that contains the non-MathML markup.

Template blanks

When you insert a new template into an equation, small squares indicate the empty slots, or template blanks, where data should be inserted. The cursor will automatically jump to the first template blank. If you want to fill in the template blank later, you can move the cursor out of the template without entering characters. Just reposition the cursor in the template when you are ready to fill it in. Also be aware that if you close the MathFlow Editor and add the expression to XMetaL without filling in the template, the template will be converted to a square, and you'll have to delete the square and add the originally-intended content when you come back to fill in the template later.

You can verify that the cursor is on the template blank by looking at the MathML ancestry.

MathML ancestry

This is an important aid in avoiding a common confusion: when a template blank appears at the end of an <mrow> or other template, it can be difficult to tell whether the cursor is actually on the template, or on the <mrow>:

Right:   Cursor is inside the template, and the "template" element is the far-right element listed in the MathML ancestry.
Wrong: Cursor is outside the template, and the "mrow" element is the far-right element listed in the MathML ancestry.

Thus it is a good habit to check the ancestry to make sure the cursor is really on the template. The gray rectangle will confirm what you see in the ancestry.

Moving directly to template blanks

Because selecting a template blank is such a common task, there are two kinds of shortcuts. Hitting the Tab key will cycle between all open template blanks. You can also move the cursor to a template blank by clicking it with the mouse.

At times you may find that a symbol or a character is not available. However, you may be able to create it by combining symbols with other symbols or characters from the keyboard. The symbols that are available for combinations are contained within the standard toolbar.

To create the combined character, place the cursor to the right of the symbol or character you want to combine with another symbol. Select the appropriate symbol under the "Common combining mark templates", "", or the "Other combining mark symbols", "".

For example, you can combine a tilde with the character 'c'.

First place the cursor to the right of "see".
Then choose the tilde from the other combining mark symbols palette.

You can also strike through a character by combining it with a slash.

First place the cursor to the right of the character you're applying the slash to.
Then choose the slash from the common combining mark templates palette.

Only one symbol can be combined with another symbol or character at a time.

Non-MathML elements are valid markup which can be found anywhere within MathML elements but do not belong to the MathML standard. There are three different types of non-MathML elements you can use in the MathFlow Editor:

  • Processing Instructions
  • Comments
  • Elements from non-MathML namespaces

Such non-MathML elements are retained by the MathFlow editor.

Here is a sample MathML equation containing each element listed above:

<math>
   <mrow>
      <?foo?>
      <!--comment--!>
      <atag/>
      <mi>d</mi>
   </mrow>
</math>

The element <?foo?> is called a processing instruction, where "foo" can be additional information that can be used to display the content in a way that is user-specific.

The element <!--comment--!> is a standard XML comment.

The element <atag/> is a valid XML element where "atag" is the element name. This could also be of the form <atag></atag>, where the text between those two tags could be anything (including MathML elements).

Safe mode

MathFlow Editor includes an option called safe mode that prevents the user from accidentally changing non-MathML elements contained within an equation. When safe mode is engaged for a given type of non-MathML, the Design view within the editor will display non-MathML as a downward pointing triangle within token elements (such as mi, mn, mtext) and container elements (such as mrow and mstyle). The editor will also prevent certain actions from occurring, such as deleting portions of an equation that contain non-MathML elements. Depending on the circumstances, you will either be warned of the presence of non-MathML elements in the status line or prompted for permission to delete the non-MathML elements. When you disable safe mode for any type of non-MathML element, you will not see the non-MathML element in Design view, nor will you be prompted or warned when deleting the non-MathML element. Disabling safe mode will be useful for experienced users who are aware of the presence of non-MathML elements and do not need the additional safety provided by this mode.

To illustrate what non-MathML looks like in Design view, consider the following MathML:

<math>
   <mrow>
      <!--comment 1--!>
      <mi><?pi1?>a<?pi2?>b<?pi3?>c<?pi4?></mi>
      <!--comment 2--!>
   </mrow>
</math>

Notice that there are four processing instructions surrounding the letters "abc", plus the two comments that are to the far left and right of the letters. Viewing this equation in Design view will show red markers above the content at the location of the non-MathML elements as seen here.

Non-MathML elements

Since the comments were placed inside the container element mrow, these triangles are slightly lower than the processing instructions that are contained within the mi. This may be helpful in determining where the non-MathML elements reside. You can also determine what the contents of the non-MathML element are by moving your cursor over the triangle, which will cause the status line to display as much of the non-MathML element as possible.

Non-MathML that is not within a token or container element is displayed as an upward facing triangle just below the current cursor position. Examples of this are shown under "Cursor Embellishment for Non-MathML Elements" in Cursor shapes.

While it is useful to enable safe mode to display non-MathML in token and container elements, it is possible to turn off portions of safe mode or to turn it off entirely. For full details, see Customizing editing behavior.

By default, MathFlow will warn you when the equation contains non-MathML by displaying a dialog box. This is done whenever there are major changes to the equation such as doing the following:

  • Opening the editor
  • Switching from Source view to Design view
  • Pasting an equation into the editor

Since this warning can become tedious, you have the option to disable it. This can be done from within the warning dialog box by checking the "Don't show this dialog again" checkbox:

Disabling the "non-MathML elements" warning.

It is also possible to disable the warning through General Editing Preferences. See Customizing editing behavior.