CS11 Advanced Java Lab 5 - Boggle Client UI

This week you should be able to get the vast majority of the Boggle client UI finished up. There will be a few more tweaks necessary when we add the client-server interaction, but after this week almost everything should be done from a UI perspective.

Here is a picture of what your user interface might look like by the end of this week:

The major components are as follows:

• A "Start Game" button. This is at the top of the screen in the above UI layout. This button is used to start a new round of Boggle.

  This button should initially be enabled.

• A Boggle timer display. This is below the "Start Game" button, above the Boggle board display. When the user is playing a round of Boggle, this timer counts down from 3 minutes. When the timer ends, the round is over.
• The Boggle board display. This is below the timer. This is the component you created in Lab 3.
• A scrollable list of words that the user has found, along with a label. These components are to the left of the Boggle board. The label doesn't change - it simply says, in effect, "here are the words you have found."

• Below the Boggle board display, there are two buttons, "Add Word" and "Clear Word." Once the user has spelled out a word on the board, they can hit the "Add Word" button to append it to their word-list. If the user doesn't like the word they spelled, they can hit the "Clear Word" button and clear out the current letter-selection.

  Both of these buttons should initially be disabled.

Of course, all of this will be wrapped in an application class. You might call that JBoggleApp, or BoggleClient, or something like that. This class will contain the main() method for your application, and the main() method will of course start up your application's user interface.

The Model-View-Controller Design Pattern

This week you will have an opportunity to explore the Model-View-Controller (MVC) design pattern. The scrollable word-list should use a JList, and JLists are views into a model that implements the ListModel interface.

Unfortunately, your WordList class is almost certainly unsuitable for using directly as a JList model, since your word-list is a set of words, not a list of words, and thus the position of a specific word in the set is not well defined.

So, you have two choices for creating your word-list:

1. Take the easy way out. Your client application can have two fields, one being the WordList object, and the other being a javax.swing.DefaultListModel object. Then, you can use the WordList to make sure you don't add duplicate words, and if a word isn't already in the WordList, you can just append it to the DefaultListModel object.
2. Provide a cleaner implementation. Create a subclass of the AbstractListModel (which implements the ListModel interface) that contains a WordList field. Provide an accessor that returns the internal WordList. Provide "add word" and "clear words" methods that also fire the appropriate "list-data changed" events.

You can follow either of these choices for your implementation. (I took the easy way out in my implementation...)

The Boggle Timer

This week's lab is a little involved, so to save you some time, you will get to use a simple "Boggle timer" class (here is the file: JBoggleTimer.java). The Boggle timer derives from JLabel and includes an internal javax.swing.Timer object for performing its periodic updates.

There is one little problem with the Boggle timer, though: It is supposed to fire an ActionEvent when the Boggle timer hits 0, but it doesn't currently do this. The code for adding and removing ActionListener implementations is present, and there is even support for setting the Boggle timer's action-command. But, you need to provide the missing piece.

Implement the fireActionPerformed() method to actually fire the ActionEvent. This is easier than you might expect, since all Swing components use the same event-passing infrastructure, and you can use this same infrastructure to fire the action-event. Specifically, all Swing components have a protected listenerList member, which stores all event-listeners that have been registered on a particular Swing component.

Go to the Java API Documentation for the javax.swing.event.EventListenerList class, and follow the pattern outlined for the fireFooXXX() method. (Of course, in this case, "Foo" is "Action", and "XXX" is "Performed", but that's simple enough.) There is one caveat though: The example code shows the FooEvent as being a class field; this is wrong. Instead, make it a local variable in the fireActionPerformed() method. (Otherwise, bad stuff will happen. You can probably figure out what, if you eyeball the example code...)

Make sure to set the ActionEvent's ID to ActionEvent.ACTION_PERFORMED, and make sure to set the action-command as well. This way you can leverage these capabilities in your controller.

The Boggle-Client Controller

• "Start Game" Button

  • Generate a new random Boggle board, and set the Boggle Board display to show the new board.
  • Clear out the word-list model, so that the UI shows no words for the new board, and so that the internal WordList object is empty.
  • Enable the "Add Word" and "Clear Word" buttons.
  • Disable the "Start Game" button.
  • Set the Boggle timer to have 3 minutes left, and start the timer.

• "Add Word" Button

  • Get the current word from the Boggle board display component. Add it to the word-list model, but only if the word's length is at least 3 characters, and if the word isn't already in the word list. Otherwise, don't add the word to the model.
  • Clear the current selections on the Boggle board display.

• "Clear Word" Button

  • Clear the current selections on the Boggle board display.

• The Boggle Timer

  Remember that the timer will also fire an ActionEvent when time is expired. Here is the processing for the timer:

  • Disable the "Add Word" and "Clear Word" buttons.
  • Re-enable the "Start Game" button.

That should be it for the controller. Once you have this coded up, you should be able to play rounds of Boggle. Make sure that your client application operates correctly, then add all of your new files to your Subversion repository. You can figure out which files are new by typing this command in your working copy:

    svn status

This command will recursively scan your directories, and report all files that are either modified or unrecognized. If a file is unrecognized (a "?" next to the filename) then you can svn add it to your repository.

Once this is all done, make sure you have committed your work, and leave your efforts in your ~/cs11/advjava/lab5 directory.