Homework 4: Extending the Graphical User Interface

To Deliver:         Release 4.0

To Download: 

Due date for submission:    October 12, at noon (12.00 PM), before fall break

Drop out date:                     October 17, at 5 AM (early morning), after fall break

Motivation

One step in learning a new programming language is always to figure out how to interact with a user. This often means programming a graphical user interface (GUI). In the near future this will include natural language processing, and a bit further on this will include a brain-machine interface. For this homework, we will restrict ourselves to some modest extensions of the Maze GUI. In particular we want to support some of the more recent features that are currently not accessible for a user. 

A GUI is an example of a reactive program where a program reacts to an ongoing user interaction. This is different to the common point of view where a program is started with a given set of parameter and then follows through a sequence of operations till it delivers the results and terminates. With a GUI, a user may trigger and influence the program behavior at any point in time. One way to think of it is as a finite automaton or an I/O automaton: the program reacts to user input and its reactions may depend on the usage history as it is stored in the internal state information of the automaton. In more practical terms, GUI programming requires you to 

• learn about different graphical components that are available to design a GUI
• learn how to integrate a graphical component into a GUI and how to connect the event when the user  operates the component with your code that describes the reaction of your program 

When it comes to GUI programming, there are multiple toolkits to choose from, see e.g. Feigenbaum's comparison between SWT, Swing and AWT (as of Feb 2006).

We will focus on Swing and AWT.  The Java Swing and AWT classes provide support for GUI programming in Java, you may want to consult a wiki page and the Java Swing API documentation  with its tutorial.

As far as testing is concerned, GUI development and testing requires further efforts which I feel exceeds what we can cover in this class, see e.g. announcements for GUI testing tools  and Tools in general at Junit.org, which include JFCUnit, Jemmy, Abbot, Marathon, and UISpec4J. So for this part of the project, we will restrict ourselves to manual tests and you are NOT asked to write Junit tests first. 

Requirements

1. MazeApplication.main() is and shall remain the main method to start the maze application. Besides that you can modify the Maze.java class and add further classes if you like. 
2. The Maze application supports 4 screens: the welcome screen, the generating screen, the playing screen, and the finish screen. The four screens may change in appearance and may provide more functionality, but having those four screens seems reasonable and should stay. They are currently implemented with 3 viewer classes: MazeView.java, MapDrawer.java, FirstPersonDrawer.java.
3. We will need a separate area close to the current screen to offer buttons and other graphical means for user input.
4. On the welcome/starting screen: The selection of the skill level currently is the only input necessary, it is combined with an immediate switch to the generating screen. This will need to change, if a user can choose/configure the settings of several, different parameters. Extend the GUI to support the following features:
• Feature: Generate and play the generation maze. A graphical feature such that the user tells the program to read parameter settings given in the welcome screen and to switch to the generating screen. Suggestion: a button. In many GUIs, any button that allows you to proceed is accompanied by a button to go back or to cancel. 
• Feature: Read a previously stored maze from a file. Suggested implementation: a button that starts a JFileChooser dialog. Is there a way to have the dialog start in a convenient directory?
• Feature: Generate and write the generated maze to a file. Suggested implementation: similar to the read feature but of course it needs to provide a "save file" dialog. Maze generation and file selection may run concurrently such that a user does not need to wait longer than necessary. Is there a way to have the dialog start in a convenient directory? Hint: check maze code for classes MazeFileReader.java and MazeFileWriter.java.
• Feature: Selection of one of the three implemented maze generation algorithms: Original, Prim, Eller. Suggested implementation: Radio buttons or anything that supports a selection of 1 out of n options. 
• Feature: Selection of the size of the maze in a more intuitive manner.  Suggested implementation: a slider or spinner.
5. On the generating screen: 
• Feature: A graphical feature  to stop the generation and to return to the welcome screen. Suggested implementation: a button. 
• Feature: A graphical visualization of the progress that has been made (something more visual than the current percentage counter). Suggested implementation: progress bar.
6. On the playing screen:
• Feature: A graphical feature  to toggle between a visible and invisible map. Suggested implementation: a toggle button, or a check box
• Feature: A graphical feature  to toggle that a solution is visible or not. Similar as for the map. Of course a solution can only be displayed if the map is displayed.
• Feature: A graphical feature  to finish the game and to return to the welcome screen. Suggested implementation: a button. 
7. On the finish screen: 
• Feature: Graphical feature to terminate the game. Suggested implementation: button. 
• Feature: Graphical feature to continue the game by switching to the welcome screen. Suggested implementation: button. 

There is a visual guide to Swing Components. Note that there is also the AWT library. 

To do list:

• Extend the current display to have a separate area for buttons and other graphical features of your GUI. 
• Let's break this done into a few steps: 
• Add the basics of the new control functionality first, i.e. "generate and play" on the welcome screen, "stop" on the generating screen, the playing screen and the finish screen.
• add the visual elements and check if you can see them when the program runs and if they react to a mouse click
• add code that is triggered by those events
• add code that provides the promised reaction to the user input
• Add other features, like the read and write dialogs etc. 
• Add another directory "data" next to src and test that you can use store mazes to files and load mazes from.
• Clean up your code, refine the Javadoc documentation.   
• Update your Java maze project in your svn repository. 
• Produce a tag release 4.0  

Grading: 

You will receive points 

• for a subversion repository that allows the grader to check out tags/rel4.0 which in turn delivers a complete project that compiles and can be executed in the grader's eclipse environment.
• if your Maze has a display with a separate new area for your new graphical elements
• if your Maze program can be executed and on each of the four screen, graphical elements are visible for the required features.
• if the progress visualization on the generating screen works
• if Javadoc works on your Maze program and your code is reasonably documented with Javadoc 
• for each of the following usage scenarios your Maze application supports (is able to perform)
1. user picks "generate and play" on a small maze, does not interrupt the generation, plays the game with the help of the map and solution, finishes and terminates the game with the "finish" button at the last screen.
2. same as #1 but user decides to continue with the game on the finish screen
3. same as #1 but user selects Prim's algorithm on a small maze
4. same as #1 but user selects Eller's algorithm on a small maze
5. user picks "generate and play" on large maze, stops the generation
6. same as #5 but user does not stop the generation but stops on the playing screen. 
7. same as #6 but user toggles map and solution view multiple times before going back to the welcome screen
8. same as #1 but user loads a particular maze from file
9. user picks "generate and save" and stores a generated maze to a file
10. same as #9 plus the user then reloads the maze and plays it successfully to the end (will be tested on a small maze).