Title Page

The Cloze Test Project

User's Manual

NLKRRG

Table of Contents

Overview
Platform
Definitions
Getting Started
User's Manual
    Using the Interface
    Using the Classes

Overview Back to Top

The Cloze Test programs' user interface is designed to enable the user to quickly create, load and save many different types of Cloze Tests.  Once a test is created, it can be used in other types of applications to test reading comprehension.  Users designing their own applications who wish to incorporate the Cloze Test will find the class, Cloze.java, to be particularly useful, making it so a cloze test can be incorporated in only about 8-10 lines of code.

Platform Back to Top

The Cloze Project is written in java, so as long as there is a Java runtime environment, it should be able to run on any platform.
NOTE: Use JDK 1.4.2 or above due to JTextField bug in earlier releases

Definitions  Back to Top

Cloze Test - a reading comprehension test that blanks out certain words.
Window Size - The number of words to be grouped together when deciding which word to take out.  For example, for the test type Every X, it is the x variable.  So     if the window size was five, it would take out every fifth word.  For the test type Low Frequency,  it is how many words it looks through to pick out a low                 frequency word.  So if the window size was 10, out of every 10 words, one low frequency word would be taken out.
Delimiter - one or more characters designating the start and end of the word to be tested.

Getting Started  Back to Top

Necessary Files:
Cloze.java - back end, logic class for administering a Cloze Test, serializable
Frequency.java - creates a hash table of frequency counts (used by Cloze.java for Low Frequency tests), serializable
GiveTest.java - class that implements the GUI for the Cloze Test (used by Cloze.java)
GradeTest.java - class that grades the Cloze Test (used by GiveTest.java)
ListDialog.java - dialog class to pick which words will be deleted (used by Cloze.java for Hand Pick Victims)
MainFrame.java - Front end GUI to test the Cloze class
Test.java - main method that creates an instance of MainFrame and calls the displayMainFrame() method

User's Manual

Using the Interface:  Back to Top

Used to test and try all of the different types of Cloze Tests available by looking at the delimited text and/or taking the test
 

File Menu:

 
New - creates a new test, clears the text box and resets the radio buttons in the Test menu to the defaults of Every X and 5
Open - opens a text file and displays it in the text area
Save Test - can only be used after a test has been created (after the Modify or Generate Buttons have been pressed), saves
       test to desired user defined directory
Open Test - opens an already created test; displays saved text in text box, radio buttons reflect saved test type and size
Exit - closes program

Test Menu:


Top set of radio buttons - list the different types of possible test:
    Every X - deletes every Xth word, where X is chosen in the bottom set of radio buttons
        - requires at least two sentences.  First sentence is left untouched and the length of the text after the first sentence
        needs to be longer than the window size selected
    Low Frequency - deletes a low frequency word within a window size whose length is chosen in the bottom set of radio buttons
        - requires at least two sentences.  First sentence is left untouched and the length of the text after the first sentence
        needs to be longer than the window size selected
    Hand Pick Victims - lets the user select which words will be deleted, dialog will pop up when Modify or Generate buttons are pressed
Bottom set of radio buttons - list the different sizes possible
    if the window size is larger than the text size after the first sentence, the original text will be returned unmodified
Modify Button - displays the text showing the delimited words (demarcated by '#')
Generate Button - creates and runs the test.  Fill in the empty text fields, press SUBMIT when done, 60 or above is passing

Hand Pick Victims Dialog:
 

Modify Button: An example with every 5th word deleted
 

Generate Button: And example with every 5th word deleted
 

Using the Classes:  Back to Top

**See JavaDoc File for API style method descriptions**

Cloze.java 
Important Usage Notes:
- The main file to the back end, to create a Cloze test of your own without using the front end GUI.
- Defaults:  When a new Cloze object is made, there are three different constructors.  The default constructor sets the test type to the first type of test in the TESTS array (originally "Every X"), sets the window size to 5 and the delimiter to "#".  The constructor which takes in a String argument defaults the test type and the window size the same as above, but sets the delimiter to the String that was passed in.  The last constructor takes in a file.  It sets all the defaults the same as the default constructor, and then uses the file to create one frequency count which will be used throughout the life of that object instead of frequency counts being made every time a low frequency test is called.
- To create a new kind of test, first make a private method implementing the test.  Then add the name of the test to the final String array TESTS.  Finally, add an else if clause to the makeModifiedText() method for the new kind of test, setting clozeString to the delimited string the new test made, returning true if was created successfully, false otherwise.  This should be all that needs to be done to add a new test.  The front end GUI should take care of the rest without any changes being made to it.  Make sure to set the answer vector with the delimited words in it to be used during grading.
- To give the users more choices of window size, modify the Object array CHOICES.  They must be Integers due to how swing is set up.  Add them in the order to be shown in the front end GUI.
- makeModifiedText() returns true if the a string was returned (whether or not it got modified) and false if the string couldn't be made.  For instance, if the user presses the cancel button on the "Hand Pick Victims" dialog, it would return false.
- displayText() will display whatever text is sent to it without any modifications onto a JFrame. 
- The removeChar() function will remove all the occurrences of the second string parameter from the first string parameter.  This is useful in getting rid of single quotes that could confuse the user.  For instance, if the word 'cat' with the quotes were to be tested, the user would have to know to include the quotes.
- makeModifiedText() needs to be called before adminTest() because adminTest() uses the clozeString that was created in makeModifiedText().

Restrictions:
- The window size needs to be an int between 3 and 20.  To change this, change the final variables MIN_SIZE and MAX_SIZE.  setNum() will return false if the number is not in this range.
- The test type needs to be one of the defined tests.  setType() will return false if the given type is not defined.
- setGrade() needs to be a double between 0.0 and 100.0.  This method is meant to be used by the grading class (GradeTest.java) so the Cloze object has access to the grade for that test.
- setText() does not restrict the text, but the individual tests do.  "Low Frequency" and "Every X" both need a string with at least two sentences (since the first sentence is used as the control).  The text after the first sentence needs to have at least as many words as the window size.  If either of these restrictions fail, the tests will return the text as given without any modification.  "Hand Pick Victims" does not limit the size of the text so that the user can have more freedom.

Example:
String str = "Once upon a time there was a girl.  This girl's name was Mary.  Mary liked sheep.  The end";
Cloze c = new Cloze();
c.setType("Low Frequency");
c.setNum("10");
str = str.removeChar(str, "/'");
c.setText(str);
c.makeModifiedText();
c.displayText(c.getClozeString());
c.adminTest();

Frequency.java  
Important Usage Notes:
- makeTable() creates and stores the hash table in the Frequency object.  The key is the word and the value is how many times it occurred in the given string.
- This method is used by the Cloze class when a "Low Frequency" test is being made.  To use it separately, make sure the given text doesn't have any extra punctuation (like single quotes) than the string in which you will be comparing it to or it will return a nullPointerException. 
- the makeTable() function also finds the average and the median frequencies.  To find out which number works best for the data, uncomment the print statements to see the numbers.  Whichever one works better, use in the Deletable() function in the if statement.
- The Deletable() function compares the frequency of the given word to the average or median (default is median) and if it is less than the average or median, it returns true signaling that the given word was a low frequency word and should thus be a tested word.

GiveTest.java 
Important Usage Notes:
- This class is a dialog which means that the program waits for user input before continuing.  The submit/cancel buttons move the flow back to where it was called.
- The action performed for the submit button gathers the user input answers and calls GradeTest to compare/grade the test.
- Sets the grade in the Cloze object after GradeTest has returned the number correct (turns it into a percentage first)
- Uses the delimiter to know where the text boxes are to be inserted, so needs to be called after makeModifiedText()

GradeTest.java
Important Usage Notes:
- gradeTest() is given 2 vectors, the first one being the user entered answers gathered in GiveTest.java after the submit button has been pressed and the second one being the one created in the Cloze object with the delimited words.  This method returns the number correct.
- getBlanks() returns the number of blanks that the user left which could be used to prompt them if they are done with the test if they left 1 or more blanks.

ListDialog.java  
Important Usage Notes:
- This class creates the "Hand Pick Victims" dialog, which requires user input before continuing.
- The left side is all the words in the text with a check box next to them, read from left to right.  The right side is the entire text so the words can be seen in context.
- The words on the left hand side are CheckableItem objects, which stores the string word and whether or not it is selected.
- When a check box is checked, class CheckBoxRenderer is called and takes care of marking the checked word and changing its selection state as a CheckableItem - CheckableItem and CheckBoxRenderer are both private classes in the ListDialog.java file

MainFrame.java 
Important Usage Notes:
- If a new test is added, or the window size options modified, mainframe should take care of that by itself, without any changes needed to be made to this class
- The menu bar is where most of the action occurs, so if something new needs to be added, add it to the menu bar
- Tries to catch all the user errors by presenting them with a dialog box informing them of their mistake (for instance, an empty text area when trying to create a test).