Developing User Interfaces
CMSC 498B
Spring 2002
Prof. Ben Bederson
Project #2
Due March 21, 2002

Purpose

The purpose of this program is to gain familiarity with Java's event facilities, including the ability to generate your own application-specific events. This is also a continued exercise in rendering your own graphics.

The Problem

You are going to create a simple text editing program with selection.  You should create a new component that provides basic functionality similar to JTextArea.  When your component has keyboard focus, it should accept keyboard events and let users type in text.  It should show a blinking text cursor that the user can manipulate with arrow keys and some simple keyboard bindings.  Furthermore, the widget should support contiguous selection with either the mouse or keyboard, and finally, the user should be able to cut, copy, and paste the text within the widget.   Finally, you should generate a custom "Selection" event that gets triggered whenever the selection is changed.  You should test this by creating a Selection listener that prints to the console a short message showing the current selection whenever it changes.  You do not need to worry about scrolling.

The requirements are:

• Implement this project entirely in Java.
• Create your custom text component by extending JComponent.  It should not have any children components.
• Your demonstration application should start in a window of dimensions 600 (width) x 400 (height) with a single component which is your custom text editor.
• You should carefully define an API for your new component.  All internal methods should be private or protected except for the methods which a user of your widget might want to use, and those methods should be declared public.  You should define javadoc style API comments for those public methods, and write the API documentation in such a way that a user of your component should be able to understand how to use your component (including at least a definition, input parameters and output results).  The public API must include methods for supporting programmatically accessing and modifying the text, and accessing and modifying the selection.  You can define what the API actually looks like.  We will run javadoc on your program and look at the generated documentation.  As with the compilation of your program, there should be no errors or warnings from javadoc.
• You should render the text simply with no automatic wrapping, and you don't have to worry about scrolling at all.  You can assume that the text will fit entirely within the window.  You may force the background color of the component is white, and the text color to black, and assume that the user of your component does not change this.  The complexity comes in representing the selection.  You should draw the selection as is standard in commercial widgets, where the selected characters are represented with white text on a black background.  Thus, you will have to carefully calculate the positions of characters in order to calculate where to render the text and background in different colors.  You will also have to understand exact character positions in order to know where in the text the user clicks and drags the mouse.
• Your text editor should respond to the following keys:
• All "regular" alphanumeric keys should enter that character
• The Enter key should start a new line
• The 4 arrow keys should move the cursor appropriately.  You do not need to worry about how the cursor should move vertically if you go from a long to a short, and then to a long line.  That is, you should always try and keep the cursor at approximately the same horizontal location, but if there is a short line, you should just move the cursor to the end of that line.
• The Home key should move the cursor to the beginning of the line
• The End key should move the cursor to the end of the line
• Holding down the Shift key while pressing any of the cursor movement keys (arrows, Home, or End) should create or extend the selection, as appropriate.
• Pressing any alphanumeric key when there is a selection active should replace the selection with that key.
• Pressing any cursor movement key when there is a selection active should move the cursor and unselect all the selected text.
• Pressing the Backspace, Delete or the ctrl-x key should delete the currently selected text (if any).  If there is no selected text, pressing the Delete key should delete the character after the cursor (if one), and pressing the Backspace key should delete the character before the cursor (if one).   Pressing the Delete key at end of line should join next line.  Pressing the Backspace key at the beginning of a line should join it with the previous one.
• Pressing the ctrl-x key should also copy the currently selected text (if any) into the "copy buffer".
• Pressing the ctrl-c key should copy the currently selected text (if any) into the "copy buffer".
• Pressing the ctrl-v key should paste (insert) the contents of the copy buffer (if any) to the point the cursor is at.  The cursor should be moved to the end of the pasted text.  If there was any selected text when ctrl-v was pressed, the selected text should be replaced with the inserted text.
• Clicking the mouse should move the cursor to the legal position nearest to the point the mouse was clicked.  If there was any selected text, it should be unselected.
• Click and dragging the mouse should dynamically select the text under the cursor, and move the cursor to the point the mouse is released at.  If there was some selected text when the mouse is dragged, the original text should be unselected.
• You should create a custom interface called SelectionListener that defines the method:
  public void selectionChanged(SelectionEvent)
• You should create a custom event called SelectionEvent that contains a string that represents the result of the selection after the change that generated this event.
• Your custom component should support addSelectionListener and removeSelectionListener methods, and should fire the selectionChanged event whenever the selection changes.
• Your test application should create a selection listener and add it to your custom component, and print the contents of the selection after every change with output of the form: "new selection: xxx" where 'xxx' is replaced with the actual selection.
• For efficiency, don't draw unselected text under selected text.  You must draw each character only once.
• You may use any font you want, including a fixed-width font such as "courier new" if you like.

This is a hard project.  I strongly recommend that you start immediately, as you will need the full two weeks to do a good job.

Java Hints

You can learn about javadoc at http://java.sun.com/j2se/javadoc/index.html

Submitting

Submit your program the same way you submitted project #1, by creating a zip file of all the source code files related to your project, login to a Unix WAM computer, and run the WAM submit program.  This is course CMSC 498B, Section 0101, Project #2.