CSE143 Winter 2003

Project 3

The Multi-Lingual Ouija Board

Due dates: Electronic parts are due on Wednesday evening, Feb. 12.  Paperwork and written parts may be handed in on Feb. 13 in quiz section or Feb. 14 in lecture.

Overview

February is the month for urgent questions.  What kind of chocolate is just right for that special someone?  What is my grade in CSE143 going to be?  Who will marry Joe Millionaire?  Fortunately, a coffin maker named E.C. Reiche discovered a simple way to channel spirits of the dead into answering such questions.  By 1890 the concept had developed into the Ouija board, still in everyday use by decision-makers everywhere.  Visit Ghosts of the Prairie Haunted Museum for more information Now, for the first time ever, the Ouija board is poised for two major breakthroughs -- and you are part of this history-making adventure.  First -- the Ouija board enters the electronic age, by being reborn as a computer application.  Every time you tap on the board, it spits out the next letter of the answer.  Second, and most amazing -- the electronic Ouija board is totally multilingual.  It can generate answers in any alphabet or writing system the human race has yet to create, from ancient Runes to modern Devanagari.

This project is intended largely as a warm-up to a later project.  In both of them, you will get practice with various development tools; with a bit of Swing; with Unicode; with reading and writing invariants; and with data structures using Java collections.  The amount of code you actually have to write in this project is small.  The challenge is understanding how the pieces fit together.  On the other hand, there are a fair amount of written questions.  There is no Part A/Part B.  The follow-up project will have a separate number and a somewhat different theme, but a similar structure.

Here is a snapshot of the program in operation.  The upper panel is the Ouija board.  When you click on it, one more character appears.  That's about all there is to it.

The characters are to be generated randomly, from a range of characters.  The range is specified by two characters passed to the constructor of the controlling class.  These should be the first and last characters from some interesting Unicode block.  You can find the hexadecimal codes for Unicode characters on the official Unicode site.  To allow for non-Latin characters, Java lets you give character constants in hex.  For example, Braille patterns have codes from 2800 to 28FF.

Starting Code

(Code links at top of page).  To start with, you have two packages this time.  MDUtils contains some utilities which you might not even need to look at.  You won't be able to hand in any files of this package.  The other package, "randchars", will contain source files for the random characters application. 

The application itself is structured as three .java files.  Their names are chosen to suggest the MVC (Model-View-Controller) architecture that we will be talking about in class.  You have starter code for all of them.  RandCharController.java shouldn't need to be modified, but it will have to be turned in.  It sets up the other classes and handles the user interaction (which is simply mouse clicks).   If you do modify it, don't add constructors or modify the existing constructor signature.

OuijaViewer needs modification in order to compile and run.  Comments in the code should help you get there.   This is where your graphics code will go. 

RandCharModel is most in need of completion.  The class holds the actual data of the application, that is, the list of characters generated.  You will have to choose an appropriate data structure.  You may not use any arrays in this class.

Additional requirements

One of the rules of the assignment (which is a general MVC design rule), is the Model must not perform viewer functions (like painting the Ouija board), and the Viewer must not contain model data.  In the present circumstance, it means that the permanent list of generated characters must reside in the Model.  The viewer can request a copy as a local variable, but may not keep it around.  (This may seem strange and inefficient, but it has many design advantages, which we'll be discussing).  The methods outlined in the starter classes are designed to lead to a simple and well-structured solution, but you are not required to adhere to them.  Before adopting a different approach, however, spend sometime understanding the suggested structure.

Your results will be more interesting if you have a nice, complete Unicode font on your computer.  Many Windows systems have "Arial Unicode MS", but it may be missing some of the more exotic code blocks.  If you discover some good downloadable fonts, please share the information.

Written part

1. Debugger.  Get familiar with the Debugger in Bluej and/or DrJava.  (In DrJava, you have to explictly enable it, and even then the command from which you DrJava has to be set up just right.  See the program's Help file for more information).  To show us that you have a basic grashp on the Debugger, do the following: set a breakpoint in the method that repaints the Ouija Board panel.  Run the program and when it hits the breakpoint, exam the values of the local and instance variables.  Run the program until there are about four randomly chosen characters on the screen.  At this point, arrange the debugger window so that all (if possible) of the instance variables of the class are visible.  Then capture a screen snapshot, and print it to hand it.
2. Run the program and get some interesting characters on the board.  Then capture a snapshot of the entire screen.  Print it (color would be nice, but not required!) to hand in.
3. Javadoc. Comment all of your classes and methods with appropriate and information Javadoc comments.  Then extract the comments using the Javadoc tool, for all the classes in the randchars package (whether or not you modified them).  Print out the result, staple, and hand in.
4. Invariants.  As you browse the Sun documentation in the course of doing your project, be on the lookout for good and bad examples of documenting invariants.  In particular, find one good and one poor example each of a) pre and post conditions b) class or data invariants.  This is four cases altogether.  Print out the documentation pages for these examples; write on them to explain why cases they illustrate and why, and turn them in.
5. In one of the starter classes, there is a method called updatePosition.  Write out the important invariants for the method.  Include invariants for any instance variables  and local variables that the method might use.  Include the information as comments directly in the .java file that you turn in.  On the printed listing for that file, highlight or circle in some very visible way all the comments which make up the answer to this question.
6. Swing components are frequently composed of other components, which themselves might have a nested structure.  The components can be said to form a "containment hierarchy".  This is complete separate from the inheritance hierarchy of the classes involved.
   1. Draw the complete containment hierarchy for the components in this project.
   2. Start with the OuijaView class; discover and draw its complete inheritance hierarchy (classes and interfaces), all the way back to Object.

Some rules (for this project):

• As a matter of robustness, the program should operate correctly even if the two characters supplied are not the first and last characters of a Unicode block.
• All turned-in .java files must be in package "randchars".  This time you may not change any program file names, or add any .java files.
• You should at least attempt to turn in your files as a .zip or .jar this time.  At some future point, that will be required.  If you use a .zip or jar, be sure your files have the proper package statements.  Zip them all together in one directory.
• This project is to be done by each student individually, with no code sharing or code viewing.
• Use your best style and programming practice.

Some advice:

• Keep it simple.  You won't get extra points for being complex or elaborate (although you might win your TA's admiration, or mine!). 
• Read the assignment through carefully, word for word, before beginning to work.  Your reading should include all the starter code, especially the comments at the beginning of each class and method.
• Before writing any code of your own, study all of the given code, and the sample solution code for Project 1 2.
• Read the assignment through carefully again, word for word, before turning in the program. 
• Continue to use the Message Board to ask questions -- or to answer them if you have something figured out.  Just don't post any actual code, please.
• Start early.

Buona Fortuna!

Hints, Tips, and Corrections

1. RandCharDriver.java should be in the randchars package.

2. [2/10/2003].  A file named FontUtils.java has been dropped into the starter code area, within MDUtils.  It has a couple of groups of methods that might help you find and manage the Unicode fonts on your system.  You aren't required to use it.  It will be on the turn-in server.  You can't modify it to turn in.

The methods with names like setUnicodeFont might be useful in the OuijaPanel.  The method will choose a font from a list of names preferred fonts and use the first one it comes to that is available.  It will never fail ("never" is tempting the gods, of course...).  You can also supply a font name or list of font names to be tried before any of the defaults are tried.  Once you have the font, you can do a g.setFont().  Although it's too late to require you to use this method, it's strongly encouraged, because it will make our testing easier (it makes the program more portable between machines).

The methods with names like testFontsAndReport might be useful for seeing what characters can be rendered in the fonts installed on your computer.  You can give it a character or a string of weird Unicode characters, and it will print out all the fonts on your system which are capable of rending those characters.  Look at main to see how to use it.  Modifying main might be the easiest way to experiment with it.

In experimenting, I've found that Code2000 has far and away the most weird characters -- far more than Arial Unicode MS, which seems to be second-best.  Bitstream Cyberbit is pretty good, too.