For the Fun of It: Writing Your Own Text Editor, Part 2

The buffer primitives and command handling were the focus of the previous article. In this article, I focus on the GUI. The two main Java GUI packages these days are Swing and JavaFX. I chose Swing because it’s more familiar to most readers; I suspect the logic within the code would not be much different for JavaFX.

Swing and the GUI Bits

For those who don’t know Swing, here’s a brief overview. The main parts of the GUI code are in the javax.swing package, and many are subclassed from JComponent. You use a JFrame for an application’s main window; JPanel and other composite components for layouts; and JButton, JLabel, JList, JTextArea, and so on for individual components.

For most of these items, there is not much to think about. There’s a menu bar at the top with the familiar File/Edit/View menus, a large panel in the middle to display the current in-memory file, and, in this case, a place to type commands from the command-line editor. This facility should include a recall mechanism so you don’t have to retype a command if you make an error or if you simply want to rerun something.

Finally, you should also be able to make changes to the text by selecting a range of text. This range may be anything from one character, to a word, to multiple lines, including parts of lines at the beginning and end, up to the whole file. Once text is selected, you should be able to cut or copy it for later pasting, type new text to replace it, or click Delete to discard it. This is the area that causes the most work when this type of GUI is layered on top of a line-oriented editor.

The main panel could be implemented in several ways in Swing. You could use a JList or a JTextArea to get some functionality. Or you could use a blank canvas and do all the work yourself. Each approach has some benefits. The JList approach allows each line to be a separate object, which would map well to my previous BufferPrims implementation (which used a List<String> to control the lines). However, it does not allow the selection of partial lines without some complicated mouse coordinate-to-character mapping. And selecting partial lines is a fairly basic function of a screen-based text editor. Writing that capability would significantly increase the size of the code, be complex, and be error-prone.

The JTextArea approach has more flexibility, but it requires care in handling the interaction between the logic in JTextArea and the logic in this application. The JCanvas class doesn’t actually exist, so the choice would probably be a JPanel or a JComponent. Here, I would draw the lines of text directly from the buffer in a paint-type method and handle the complexity of text selections and keyboard events entirely in the editor.

I started implementing several of these approaches. In the end, I went with a JTextArea and a custom implementation of BufferPrims called BufferPrimsJText to handle the mapping between the two views of the text buffer. JTextArea basically holds the text as a long String, but a helper class, Swing’s Document class, knows where the line boundaries are. The code in this editor doesn’t use the Document interface directly, but a full word processor would.

The BufferPrimsJText code moves text between the line-oriented buffer and the JTextArea. I rely on the JTextArea to maintain the text buffer contents. Almost all state information (even getting the line count) is obtained dynamically by querying the JTextArea.

To illustrate the general working of this interface, here is the replace() method from BufferPrimsJText. This method would be invoked when the user types a substitute command such as s/Hello/Goodbye/g in the command window. This example says to replace all (g at the end stands for global) Hello strings with Goodbye in the current line. Without the g the method would replace only the first occurrence in each line.

public void replace(String oldRE, 
                    String replacement, boolean all) {
    try {
        final int adjustedLineNum = 
            lineNumToIndex(getCurrentLineNumber());
        int startRange = 
            textView.getLineStartOffset(adjustedLineNum);
        int endRange = 
            textView.getLineEndOffset(adjustedLineNum) - 1;
        String line = 
            textView.getText(startRange, 
                             endRange - startRange);
        String str = all ?
            line.replaceAll(oldRE, replacement) :
            line.replaceFirst(oldRE, replacement);
        textView.replaceRange(str, startRange, endRange);
    } catch (BadLocationException e) {
        throw new RuntimeException(e.toString(), e);
    }
}

This code starts by calling my lineNumToIndex() method to map the line number from the one-based lines in the editor’s view of the text buffer (as discussed in the previous article) to the zero-based lines of the JTextArea Document. Then the JTextArea methods are used to compute the character index of the text in the current line (subtracting one so I don’t get the \n character at the line end). This information is used to grab the actual string representing the current line. Then one of the standard String methods, replaceAll() or replaceFirst(), is chosen, based on the all parameter (which in turn comes from the presence or absence of the g at the end of the command). Finally, the modified string is pushed back into the JTextArea by the latter’s replaceRange() method.

The other BufferPrimsJText methods work similarly: Compute a range, and then tell the JTextArea to perform the required operation on it.

What About Undo?

At first, I thought I would need to do some complicated mapping involving selection events to handle events such as the user selecting part of a line and then deleting it. However, it turned out to be easier: My BufferPrimsJText simply calls code in the JTextArea to do the work. And if my code updates the buffer (as my replace() method does), Swing still considers that an undoable event, and it calls my UndoableEventListener. I merely pass that along to an instance of Swing’s own UndoManager, which provides all the undo/redo capability. I had to provide only a pair of Swing Action classes to interface with my code and keep the Undo/Redo menu items enabled at the appropriate time.

One minor glitch is that a JTextArea.replaceRange() operation is recorded as two actions: a deletion followed by an insertion. As a result, the user would have to select Undo twice to undo what seems like a single action. Otherwise, it just works.

Test Early and Often

Every treatise on testing GUI code basically says not to test, meaning don’t test the GUI code but instead, keep it so simple that it doesn’t need testing. That is, of course, the purpose of my BufferPrims interface and the Commands class, which keep line-manipulation logic separate from the user interface code. There are, as you now know from the section “Swing and the GUI Bits” above, several different BufferPrims implementations. When you have multiple implementations of an interface, it’s usually best to test all of them against the same set of tests. But please don’t do that by copying and pasting tests from one test class into another! This is a perfect use case for automation.

For this project, I used JUnit 4’s Parameterized test runner. Test classes so annotated provide a @Parameters-annotated method that returns a list of arrays of Object and a constructor method that accepts the contents of one of those arrays. When there is only one parameter to the constructor, as here, the annotated method just returns an array of the parameter values. JUnit will call the constructor and then run all the test methods in the constructed test class, mapping the objects in one row to the constructor.

@RunWith(Parameterized.class)
public class BufferPrimsTest {

    protected BufferPrims target;

    // Constructor
    public BufferPrimsTest(Class<? extends BufferPrims> clazz)
        throws Exception {

        if (clazz == BufferPrimsJText.class) {
            target = new BufferPrimsJText(new JTextArea(24, 80));
            return;
        }
        target = clazz.getConstructor().newInstance();
    }

    @Parameters(name = "{0}")
    public static Class<BufferPrims>[] params() {
        return (Class<BufferPrims>[]) new Class<?>[] {
            BufferPrimsStringBuffer.class,
            BufferPrimsNoUndo.class,
            BufferPrimsWithUndo.class,
            BufferPrimsJText.class,
            };
    }

    // Some number of @Test methods testing the buffer primitives

The BufferPrimsTest class uses reflection (that is, Class.getConstructor().newInstance()) to create the target BufferPrims implementation being tested. However, the JTextArea version of BufferPrims has a different constructor argument than all the rest (it needs access to its JTextArea). So I handle that one specially; see the if statement inside the BufferPrimsTest constructor. The name parameter on the @Parameters annotation specifies which column to show as the name of the test. Omitting it leads to boring names such as 0, 1, 2, and so on.

I also test the line parsing code with a @Parameterized test. There are so many possible command input variations that it’s not possible to test them exhaustively, but I think I have a reasonably good selection. The LineParserTest constructor takes a boolean (based on whether the line should parse successfully or not), the input string to try parsing, the expected line numbers, and any arguments such as the filename for a read command or the old and new text for a substitution.

public class LineParserTest {

    @Parameters(name="{1}")
    public static List<Object[]> data() {
        final int current = buffHandler.getCurrentLineNumber();
        final int size = buffHandler.size();
        return Arrays.asList(new Object[][] {
            // exp-bool, input-str, line1, line2, arguments
            { true, "1,2p", 1, 2, null  },
            { true, "2p", 2, 2, null },
            { true, "3s/Line/Foo/", 3, 3, "/Line/Foo/" },
            { true, "3,3s/Line/Foo/", 3, 3, "/Line/Foo/" },
            { true, "3,6s/Line/Foo/", 3, 6, "/Line/Foo/" },
            { true, ",p", 1, buffHandler.size(), null  },   // print all
            ... more tests ...
            // Test some failure modes
            { false,  "?", 0, 0, null  },   // ?patt? not implemented
            ... more ...
        });
    }

You won’t find any place in the test where I prove the functionality of JButton, JTextArea, and friends. These are both well-tested before release and also very widely used. You also won’t find tests of simple lambdas that bind action code to events in my SwingEditor.java file, for example:

JButton goButton = new JButton("Go");
goButton.addActionListener(e -> doCommand(e));

This is trivial enough that I am fairly sure it won’t fail. The doCommand() method calls LineParser.parse(), which is extensively unit tested, and if all’s well, it calls the execute() method of the returned ParsedCommand. If doCommand() fails, no commands will work, and this would be discovered quite early. Even so, in the interest of completeness, there is a unit test in SwingEditorTest.java for doCommand().

I’m not a big fan of automated testing of UI code, but there may be times when you need it. There are several options for automated GUI testing, such as jimmy (which is currently maintained as part of the OpenJDK project) and Marathon, (which offers both free and commercial versions).

A good alternative is manual testing of just the GUI code. This consists of writing a very detailed test plan stating what the tester should do and what the tester should see.

Start the application, with a filename argument of 9lines.txt
    You should see a new window appear, containing 9 lines of 
     text such as "Line 1", "Line 2", etc.
In the text box at the bottom, type the text *7d*, 
     then press the Go button.
    You should see line 7 disappear, so that "Line 6" is 
     now followed by "Line 8".
Press the Go button again.
    You should see the current line 7 disappear, so that 
     "Line 6" is now followed by "Line 9".
In the text box, select the existing text and 
    hit Backspace or Delete.
     The text box should be empty.
In the text box, enter the command *3,5s/Line/Slime/*  
Press the Go button.
    You should see:
    Line 1
    Line 2
    Slime 3
    Slime 4
    Slime 5
    Line 6
    ...