When a character such as ')' is typed, ShowMatchingCharCmd inserts this character at caret position and then highlights matching '(' for half a second.

When writing such command, a developer may be tempted to find the bounding box of the matching '(' using methods such as DocumentView.modelToView and to directly draw the highlight on the DocumentPane containing the DocumentView.

Commands should never do this. Commands should only deal with nodes and selection marks.

Nodes which are contained in a Document are rendered graphically using NodeViews created by a ViewFactory. Similarly, Marks which are attached to Nodes and which managed by a MarkManager are rendered graphically using Highlights created by a HighlightFactory.

Dot, mark, selected, selected2 are special marks only because standard commands operate on them. An application can create its own marks for any purpose.

A custom mark has an ID (any Object which implements hashCode() and equals() will do) and is attached to a Node. It is created using MarkManager.set(Object id, Node node) for NodeMarks and MarkManager.set(Object id, TextNode text, int offset) for TextLocations.

Standard commands completely ignore these custom marks. For example, standard command CancelSelection will leave these marks intact. The only way to get rid of them is either to remove them using MarkManager.remove or to delete the Nodes they are attached to.

Custom marks are rendered graphically using Highlights created by the HighlightFactory of the DocumentView. By default, the HighlightFactory of a DocumentView is a BasicHighlightFactory.

A BasicHighlightFactory creates Highlights which are:

Therefore, in order to highlight the matching '(', ShowMatchingCharCmd creates a TextLocation named "highlight.matchingCharN" before the matching '(' and a TextLocation named "highlight2.matchingCharN" after the matching '('. After half a second, ShowMatchingCharCmd automatically removes these marks.

public class ShowMatchingCharCmd extends CommandBase
                                 implements Traversal.Handler {
    private int highlightId = 0;

    private char matchingChar;
    private char insertedChar;
    private int charCount;
    
    public boolean prepare(DocumentView docView, 
                           String parameter, int x, int y) {
        if (parameter == null || parameter.length() != 1)
            return false;

        return docView.canInsertString();
    }
    ...

ShowMatchingCharCmd can be executed if:

All the above conditions are tested by DocumentView.canInsertString.

    ...
    public Object execute(DocumentView docView, 
                          String parameter, int x, int y) {
        String s = parameter.substring(0, 1);
        docView.insertString(s);

        insertedChar = s.charAt(0);
        switch (insertedChar) {
        case '}':
            matchingChar = '{';
            break;
        case ')':
            matchingChar = '(';
            break;
        case ']':
            matchingChar = '[';
            break;
        default:
            matchingChar = '\0';
        }
        if (matchingChar == '\0') {
            docView.getToolkit().beep();
            return null;
        }

        final MarkManager markManager = docView.getMarkManager();
        TextLocation dot = markManager.getDot();

        charCount = 0;
        TextOffset match = null;
        if (dot.getOffset() > 0)
            match = processTextNode(dot.getTextNode(), dot.getOffset() - 1);
        if (match == null)
            match = (TextOffset) Traversal.traverseBefore(dot.getTextNode(), 
                                                          this);
        if (match == null) {
            docView.getToolkit().beep();
            return null;
        }

        Rectangle r1 = docView.modelToView(match.text, match.offset);
        Rectangle r2 = docView.getVisibleRectangle();
        // r1 is null if the matching char is contained in a collapsed section.
        if (r1 == null || r1.height <= 0 || 
            r2.height <= 0 || !r1.intersects(r2)) {
            char[] chars = match.text.getTextChars();

            int count = 1;
            int boundary = match.offset - 1;
            loop: while (boundary >= 0) {
                switch (chars[boundary]) {
                case '\n': case '\r':
                    break loop;
                }

                ++count;
                if (count == 80)
                    break;

                --boundary;
            }
            
            String line = new String(chars, boundary+1, match.offset-boundary);
            line = XMLText.collapseWhiteSpace(line);
            if (boundary >= 0 && count == 80)
                line = "..." + line;

            ShowStatus.showStatus("Matches '" + line + "'");
            return null;
        }

        final String id1 = "highlight.matchingChar" + highlightId;
        final String id2 = "highlight2.matchingChar" + highlightId;
        ++highlightId;

        markManager.add(id2, match.text, match.offset+1);
        markManager.add(id1, match.text, match.offset);

        Timer timer = 
            new Timer(500 /*ms*/, new ActionListener() {
                public void actionPerformed(ActionEvent e) {
                    markManager.remove(id1);
                    markManager.remove(id2);
                }
            });
        timer.setRepeats(false);
        timer.start();

        return null;
    }
    ...

The following Traversal.Handler is used to find the matching '(' in nodes which precede the node where ')':

    ...
    private TextOffset processTextNode(TextNode textNode, int from) {
        char[] chars = textNode.getTextChars();

        if (from < 0)
            from = chars.length - 1;

        for (int i = from; i >= 0; --i) {
            char c = chars[i];

            if (c == insertedChar) {
                ++charCount;
            } else if (c == matchingChar) {
                --charCount;
                if (charCount == 0)
                    return new TextOffset(textNode, i);
            }
        }

        return null;
    }

    // ---------------------------------------
    // Traversal.Handler
    // ---------------------------------------

    public Object processText(Text text) {
        return processTextNode(text, -1);
    }

    public Object processPI(ProcessingInstruction pi) {
        return processTextNode(pi, -1);
    }

    public Object processComment(Comment comment) {
        return processTextNode(comment, -1);
    }

    public Object enterElement(Element element) {
        return null;
    }

    public Object leaveElement(Element element) {
        return null;
    }
}

WrapElementCmd is an example of a validating command, that is, a command which cannot make the document invalid by inserting, deleting or replacing nodes.

This kind of command often requires the user to specify which element is to be inserted in the document. In such case, the chooser dialog box should only display elements which, when inserted in the document, cannot make it invalid.

This kind of command always uses an ElementEditor.

An ElementEditor is a validating editor which operates on the child nodes of a given element.

In order to use an ElementEditor, you need to create it and then to specify which element is being edited:

ElementEditor myElementEditor = new ElementEditor(myDocumentType);
myElementEditor.setEditedElement(myElement);

It implements a number of editing operations: delete, insert, replace, convert, wrap, cut, paste, etc.

For each operation, there are 3 methods:

Validating commands operating on the text selection rather than on the node selection use a TextEditor rather than an ElementEditor.

public class WrapElementCmd extends CommandBase {
    private Element element;

    public boolean prepare(DocumentView docView, 
                           String parameter, int x, int y) {
        element = docView.getSelectedElement(/*implicit*/ true);
        if (element == null)
            return false;

        Element editedElement = element.getParentElement();
        if (editedElement == null)
            return false;
        ElementEditor elementEditor = docView.getElementEditor();
        elementEditor.editElement(editedElement);

        return elementEditor.canWrap(element, element);
    }
    ...

    ...
    public Object execute(DocumentView docView,
                          String parameter, int x, int y) {
        ElementEditor elementEditor = docView.getElementEditor();
        Element editedElement = element.getParentElement();

        ArrayList<Field> fieldList = new ArrayList<Field>();
        elementEditor.canWrap(element, element, fieldList);

        Field[] fields = new Field[fieldList.size()];
        fieldList.toArray(fields);

        String title = "Wrap Element";
        FieldChooserDialog dialog = 
            new FieldChooserDialog(docView.getPanel(), title);

        FieldChoice[] choices = 
            FieldChoice.list(fields, /*includingText*/ false, 
                             /*includingWildcards*/ true,
                             /*includingTemplates*/ false, editedElement);
        FieldChoice choice = dialog.chooseField(choices, editedElement);
        if (choice == null)
            return null;
        
        MarkManager markManager = docView.getMarkManager();
        markManager.beginMark();

        Element wrapper = elementEditor.wrap(element, element,
                                             choice.field, choice.name);

        docView.describeUndo(title);

        markManager.remove(Mark.MARK);
        markManager.remove(Mark.SELECTED2);
        markManager.set(Mark.SELECTED, wrapper);
        docView.moveDotInto(wrapper);

        markManager.endMark();

        return null;
    }
}

Authors often need to paste in their XML documents text blocks copied from a word processor.

Without a special command, doing so is tedious because:

A special command can do all this automatically. Such a command is a validating one because the author must not be allowed to insert captured paragraphs in places which would make the document invalid.

The Paste command can be passed plain text or an XML string (a string which starts with "<?xml ") as its parameter (see Section 48, “paste” in XMLmind XML Editor - Commands). So why not use this standard validating command to do the paragraph insertion?

The idea here is to write a simple command, MakeParagraphsCmd, which returns an XML string containing one or several paragraphs built using clipboard content. This string is then passed to the Paste command which inserts the paragraphs (if the XML Schema or the DTD constraining the document allows to do so).

Note that MakeParagraphsCmd cannot be used alone. It must be part of a macro-command such as the following one (DocBook example):

  <command name="insertAfterAsSimpara">
    <macro>
      <sequence>
        <command name="MakeParagraphsCmd" parameter="simpara" />
        <command name="paste" parameter="after[implicitElement] %_" />
      </sequence>
    </macro>
  </command>

public class MakeParagraphsCmd extends CommandBase {
    private Name elementName;
    private boolean systemSelection;
    private boolean blocks;
    private String pastable;

    public boolean prepare(DocumentView docView, 
                           String parameter, int x, int y) {
        elementName = null;
        pastable = null;

        if (docView.getDocument() == null)
            return false;
        
        if (parameter == null || parameter.length() == 0)
            return false;

        String name = null;
        int pos = parameter.lastIndexOf(']');
        if (pos < 0)
            name = parameter;
        else if (pos+1 < parameter.length())
            name = parameter.substring(pos+1);

        if (name != null)
            elementName = Name.fromString(name.trim());
        if (elementName == null)
            return false;

        systemSelection = (parameter.indexOf("[systemSelection]") >= 0);
        blocks = (parameter.indexOf("[blocks]") >= 0);

        if (systemSelection)
            pastable = SystemSelection.get(docView.getPanel());
        else
            pastable = Clipboard.get(docView.getPanel());
        if (pastable == null || pastable.length() == 0 || 
            pastable.startsWith("<?xml "))
            return false;

        return true;
    }
    ...

    ...
    public Object execute(DocumentView docView, 
                          String parameter, int x, int y) {
        ArrayList<String> textList = new ArrayList<String>();

        StringBuilder block = new StringBuilder();

        LineNumberReader lines = 
            new LineNumberReader(new StringReader(pastable));
        String line;
        while ((line = readLine(lines)) != null) {
            line = XMLText.collapseWhiteSpace(line);
            if (line.length() == 0) { 
                // Open line.
                if (blocks && block.length() > 0) {
                    textList.add(block.toString());
                    block = new StringBuilder();
                }

                continue;
            }

            line = XMLText.filterText(line);

            if (blocks) {
                if (block.length() > 0)
                    block.append(' ');
                block.append(line);
            } else {
                textList.add(line);
            }
        }

        if (blocks && block.length() > 0)
            textList.add(block.toString());

        int count = textList.size();
        if (count == 0)
            return EXECUTION_FAILED;

        // The content of the clipboard is fetched as a *Java String*. 
        // Therefore no need to specify encoding in the XML declaration.

        StringBuilder result = new StringBuilder();
        result.append("<?xml version='1.0'?>");

        openTag(ClipboardFormat.ENVELOPE_NAME, result);
        for (int i = 0; i < count; ++i) {
            String text = (String) textList.get(i);

            openTag(elementName, result);
            XMLText.escapeXML(text, result);
            closeTag(elementName, result);
        }
        closeTag(ClipboardFormat.ENVELOPE_NAME, result);
        
        return result.toString();
    }
    ...

<?xml version="1.0"?><p>Paragraph #1.</p>

<?xml version="1.0"?>
<ns:clipboard
xmlns:ns="http://www.xmlmind.com/xmleditor/namespace/clipboard">
  <p>Paragraph #1.</p>
  <p>Paragraph #2.</p>
</ns:clipboard>

Execute uses the following helper methods:

    ...
    private static final String readLine(LineNumberReader lines) {
        try {
            return lines.readLine();
        } catch (IOException cannotHappen) {
            cannotHappen.printStackTrace();
            return null;
        }
    }

    private static final void openTag(Name name, StringBuilder buffer) {
        buffer.append('<');
        buffer.append(name.localPart);
        buffer.append(" xmlns='");
        buffer.append(name.namespace.uri);
        buffer.append("'>");
    }

    private static final void closeTag(Name name, StringBuilder buffer) {
        buffer.append("</");
        buffer.append(name.localPart);
        buffer.append('>');
    }
}