MathFlow Structure Editor

Contents of this section:

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.

Use symbols and templates to build equations in MathFlow.

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 copy and paste sub-expressions to build up more complex expressions.

Shot shows a superscript template nested inside a fraction template.

The editor templates and symbols are directly based on MathML. It's not necessary to know much, about MathML in order to use the MathFlow editor effectively, but it does help to understand how equations are structured.

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

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

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

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, it must be before you click OK to insert the equation into the document but if you do, you can move the cursor out of the template without entering characters. Just reposition the cursor into the template and fill it in before you close the Editor.

Warning: If you have empty template(s) in the equation and subsequently close the MathFlow Editor to add the expression to oXygen without filling in the template, you will get an error and you will not be able to recover the equation without going to oXygen's Text edit mode and editing the MathML manually.

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

MathML Ancestry     <math> : <mrow> : <template>

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>, operator, or other template:

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 into a template blank by clicking it with the mouse.

The MathML Ancestry is the status area displayed just below the Tabbed Toolbar, adjacent to the Mini Toolbar. The Ancestry is there to show you at a glance the nesting of the MathML structure at the cursor location, and to give you an easy way to select parts of the equation containing the cursor.

MathML Ancestry   …   <mrow> : <mrow> : <mfrac> : <mrow> : <mi>

Since all MathML equations consist of templates nested inside a ‹math› element, the Ancestry always shows the ‹math› element on the left. Intermediate MathML templates are listed in order of nesting, with the innermost MathML template at the cursor location indicated on the far right.

When there are too many levels of nesting to display all at once, the Ancestry shows dots on the right and/or left edge of the display. Clicking the dots scrolls the display in the corresponding direction.

As you move the mouse, the Ancestry automatically updates to reflect the nesting at the current cursor position. Also, when you select part of an equation in the editing area, the corresponding template label in the Ancestry will be highlighted.

Ancestry selections

When you mouse over one of the MathML templates labels in the Ancestry, it will become highlighted in red. Clicking a label in the Ancestry selects the corresponding part of the equation in the editor window.

A label in the ancestry becomes red when you mouse over it, and if you click it, MathFlow selects the corresponding part of the equation.

By double-clicking an Ancestry label, you can highlight the corresponding area of the current equation and simultaneously open the default Properties panel for that selection. Each kind of MathML template has a default Properties panel, depending on what MathML properties it supports. Changes to a Properties panel only affect the current selection. Sometimes a selection applies to several Properties. When this occurs, only the default panel is opened by double-clicking.

The editor interface includes two input/display modes: Design view and Source view. Design view is the standard mode for creating and editing your equations discussed in other sections of this documentation. 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 source itself. Source view also includes commands for checking the syntax of the MathML and formatting the text itself. The Editor will always open into the view used in the last editing session.

Click on the 'Source view' tab just below the editor window to edit the MathML source. Changes made to equation content in Source view are immediately reflected in Design view.

Edit MathML directly in MathFlow's Source view.

Editing the MathML in Source view is just like working in any text editor. All standard text, space, and line break characters are recognized. In addition, pressing Shift+Tab will tab blocks of text. This can be useful for isolating or formatting sections of the MathML to aid with editing.

The Source view toolbar is fixed (non-configurable) and includes commands for Cut, Copy, Paste, Undo, Redo, Format Source, Validate, and Help.

Edit menu, Source view

This menu contains the actions for exporting to and importing data from the system clipboard, as well as undoing actions, selecting content, and performing a find & replace.

Source view's Edit menu includes some basic, but useful, commands.

The Source view editor acts as a standard text editor, therefore selection, cut/copy, and paste operations only utilize text data and add no special formatting.

The clipboard can be used in two ways. First, the clipboard is useful for cutting and pasting within the Editor. Second, the clipboard is useful for pasting data into other applications. Equation data targeted for other applications in general requires additional formatting. For example, some XML applications may require a namespace prefix for MathML markup.

There are several commands in the Edit menu. Details follow, including shortcut keys:

Undo (Ctrl+Z)

This command reverses the last cut, paste, or text editing operation. You can undo the last 100 operations.

Redo (Ctrl+Y)

This command reapplies the last cut, paste, or text editing operation that was undone. You can redo operations up to the point of the first undo.

Cut (Ctrl+X)

This deletes the selected MathML or text from the editor, and places it in the system clipboard (so it can be pasted into other applications).

Copy (Ctrl+Ctrl)

This copies the selected MathML or text from the editor, and places it in the system clipboard (so it can be pasted into other applications) without removing the selection from the current equation.

Paste (Ctrl+V)

This command pastes the contents of the system clipboard into the editor window at the current cursor location. Only text content will be accepted.

If the MathML on the clipboard was placed there by the MathFlow Editor, it can always be pasted back into the Editor regardless of how it is formatted. Although Source view will allow any text to be placed into the editor, the data/equation must be in valid MathML format, and it MUST be enclosed by ‹math› tags. It will not paste clipboard data as MathML unless it begins and ends with ‹math› tags. It is recommended to use the Validate command after a paste to check for any MathML errors (see the next section, Source menu, for details). Also, the editor will ignore any data on the clipboard before the opening math tag, and after the ending math tag.

Select All (Ctrl+Alt)

This selects the entire MathML source currently in the editor.

Find/Replace (Ctrl+F)

This option operates just like most any text editor Find & Replace feature. The command will find instances of the specified text in the selection or entire document and if needed, replace any or all instances with specified text.

Source menu

This menu contains the actions for formatting and validating the MathML source; it is only available in Source view.

There are two commands in the Source menu:

Format

This command will format the MathML, nicely positioning the syntax into an easily readable form. Format affects the entire document (equation), whether any or all MathML text is selected or not. Format can also be accessed via a right-click in the editing window itself or by clicking the Format Source toolbar button (document icon).

Format command in the Source menu

Validate

This command (also known as the syntax checker) will check the MathML for proper syntax and structure. If the MathML passes validation, 'Validation completed successfully' will appear. If there are problems, the first error found will display in the status bar and the offending syntax will display as red text; a warning that reads 'The MathML is invalid, please see the status line for details' will also appear. As long as there are errors, the editor will be prevented from closing or switching to Design view. Validate can also be accessed by clicking the Validate toolbar button (checkmark icon).

Validate command in Source Menu

Context highlighting

Source view is designed with some clear visual cues to assist in viewing and editing the structure. To this end, the Editor uses four colors to differentiate the major components:

  • MathML data and regular text is displayed black, such as the number 355, the entity &beta; or the function sin.
  • MathML tags and edited data before re-formatting are displayed blue, such as </mo> or <mfrac>.
  • MathML attribute values display in purple, such as the 2 mathcolor and linebreak attribute values red, yellow, and badbreak, respectively.
  • MathML syntax errors reported after running the Validate command display in red, such as </row> when </mrow> is expected

Context highlighting in MathFlow's Source view