CIT 591 Assignment 8: Study
Fall 2005, David Matuszek

Purposes of this assignment:

General idea of the assignment:

People often have to learn pairs of things that go together (in psychological jargon, paired associates). Given one of them (the stimulus), the person has to come up with the other (the response). For example:

As your customer, I want a program to help me memorize lists of things--for example, German vocabulary words. In addition, I want a program to help me construct these lists in the first place.

Details:

The Item class

An item is a single pair of things to learn (for example, Pennsylvania and Harrisburg). In addition to the stimulus and response, an item keeps track of how many times in a row it has been answered correctly (as a rough measure of how well the item has been "learned.") The Item class should have the following capabilities:

Method Purpose
public Item(String stimulus, String response) Constructor; the number of times correct will be initialized to zero.
public void setStimulus(String stimulus)
public void setResponse(String response)
public void setTimesCorrect(int)
public String getStimulus()
public String getResponse()
public int getTimesCorrect()		 Setter and getter methods; timesCorrect returns the number of times in a row that this item has been answered correctly.
public void mark(Boolean correct) Keeps track of the number of times in a row that this item was answered correctly (true indicates a correct answer, false an incorrect answer).

The StudyList class

The most important component of the StudyList class is a list of items to be studied. Your class will keep these items in an ArrayList (java.util.ArrayList), which has the important feature that it can grow as you add items. Declare and define your array list with the following somewhat unusual syntax:

ArrayList<Item> studyList = new ArrayList<Item>();

Except for constructing the list, you do not need any unusual syntax. You can explore the API for methods to use with an ArrayList, but most or all of your work will be done with the ListIterator (see below).

Your StudyList class should have the following capabilities:

Method Purpose
public StudyList() Constructor
public void load(File file)

Read in a list of items from the given File.The file should have one Item per line, with the syntax:
     stimulus | response | timesCorrect
Vertical bars (and optional spaces) separate the parts. When you read in items, discard the vertical bars (you can use the split(" *\\| *") method of the String class) and trim spaces from the beginning and end of the stimulus and the response.

You can assume that the file being read in has the correct syntax.
public void save(File file) Save the item list to the given File, one Item per line, with " | " separating the parts.
public ListIterator listIterator() Simply gets and returns a ListIterator for the underlying ArrayList. The returned iterator has operations add(Item), remove(), hasNext(), next(), hasPrevious(), and previous(), among others; you can use this iterator to directly manipulate the items in the study list. See the Java API for java.util.ListIterator for details.

The StudyListEditor class

The StudyListEditor is a Swing-based application (with a main method) for editing study lists. Only one study is edited at a time. The StudyListEditor GUI should have the following controls:

A Load menu item
The Load command calls up a JFileChooser that enables the user to choose a file containing a study list, then reads it in. If a study list is currently being edited and the changes have not been saved, Load should first bring up a warning dialog box from which the user may cancel loading.

The Save, and Save As... menu items
The Save and Save As... commands each call up a JFileChooser that enables the user to choose a file; the Save command should just save to the same file as was most recently loaded. (Save and Save As... should be disabled--grayed out--if no file has previously been loaded.)

A New Study List menu item
The New Study List command will create a new, empty StudyList, which you can then add items to and otherwise edit. If a study list is currently being edited and the changes have not been saved, New Study List should first bring up a warning dialog box from which the user may cancel this operation.

Text fields for displaying/editing the stimulus and response for the current item
These fields should be clearly labeled and should be editable. If edited, the changes should be made to the Item being displayed (do this when the user moves to a different item or saves the file).

A JComboBox for choosing the number of times (0 to 5) in a row that the item has been answered correctly.
This combo box should be clearly labeled and should be zero for new items.

Next and Previous buttons
These buttons move to the next item and the previous item in the study list, respectively.They should be disabled--grayed out--if there is no such item. When clicked, any changes made in the stimulus, response, and number of times correct should be copied to that Item. However, if either stimulus or response is blank, these buttons should bring up a warning (message) dialog and not move to another item until the problem is corrected.

New button
Creates a new item, setting the stimulus and response display to blank and the number of times correct to zero.

Delete button
Removes the currently displayed item from the study list.

Quit button
If all changes have been saved to a file, simply quits the program. If there are unsaved changes, this button brings up a warning dialog box from which the user may save, quit anyway, or cancel quitting.

It is important for the programmer to realize that there can be a difference between the item information displayed on the screen and what is actually in the Item. The user should not have to know about this. Hence, almost any action (except typing into a text field) should cause the program to check the inputs and update items appropriately, before the action is taken.

Stimulus and response values should be trimmed (use String method trim()) before being stored in the Item. An "empty" stimulus or response field (one that is zero length after being trimmed) should, in most cases, cause a warning message to be displayed and the requested operation to be aborted. (It should be OK to delete an item with empty fields.) To minimize code duplication, I suggest the use of a private boolean method to do this checking.

The Study class

Study is a Swing-based application (with a main method) for helping the user memorize study lists. The display should be as follows:

Menu items Load, Save, and Save As...
These commands behave exactly as in the StudyListEditor class. (We need to save the item list because the number of times correct for each item may have changed.)

A JLabel for displaying the stimulus
The text in a JLabel can be changed at any time with the setText(String) method.

A text field in which the user enters the response
This field should have an ActionListener so that the user can enter the response simply by hitting the Enter (or Return) key; having to click a button would just be a nuisance. The response is then evaluated and scored, and feedback is given (see below). When an incorrect response is entered, the background of this field is set to Color.PINK, and remains pink until the user enters the correct response.

A JLabel field for feedback
This field should display Correct! after a correct response, and the stimulus of the next item should be displayed in the above JLabel.
After an incorrect response, however, the background of the response text field should be set to Color.PINK, and this JLabel should be set to show the correct response. The user must then type in the correct response (this may take several tries) before going on to the next item; when she does, this JLabel is set to Correct! and the color of the response text field is reset to white.

Quit button
If all changes have been saved to a file, simply quits the program. If there are unsaved changes, this button brings up a warning dialog box from which the user may save, quit anyway, or cancel quitting.

An item is considered to be "learned" when the user gets it correct a certain number of times (say, 3) in a row. Learned items are kept in the study list, but are not ever presented to the user.

When all items have been learned and there is nothing more to display, the program should bring up a dialog box to so inform the user. The user should be given an opportunity to save the study list. The program does not quit automatically at this point, because the user may wish to use a different study list.

Testing:

Do JUnit testing on the Item class. The StudyListEditor and Study classes are basically GUI classes, and must be tested by hand. The StudyList class reads and saves files, and returns a ListIterator for the internal ArrayList; again, nothing much to test.

Division of labor:

One member of your team should write the StudyListEditor class and the other member should write the Study class (these are both basically GUI classes, of roughly comparable difficulty.) If you have no partner, you can omit the StudyListEditor class. Use @author tags to specify who did which class.

One member of your team should write the load method and the other the save method, so that each of you gets some experience with file I/O. @author tags do not apply to individual methods, but you can put your name in an ordinary comment.

Due date:

Thursday, November 17, before midnight. As usual, please submit one zip file, via Blackboard, containing all necessary files.