Project 6: Android App for Manual Operation of Maze 

To Deliver: release 9.0

To Download: 

Due date for submission:    Nov 18, at 5 AM 

Drop out date:                     Nov 20, at 5 AM

Motivation

We want to port our maze java application to Android. This requires us to redesign the user interface and to port the Falstad package into the new Android project.

Since the new UI from Project 5 handles the different screens, we do not need particular classes from the Falstad package anymore, for example MazeApplication.java are not used anymore.

We also need to reorganize Maze.java since the different screens and states it currently manages are now handled by the new UI activities. In consequence, Maze.java will loose some of its responsibilities. 

As  Java AWT and Swing  packages are not supported on Android, we need to recode the MazePanel.java implementation in our Android project (if you did the refactoring HW that encapsulated all AWT graphics in MazePanel.java).

What to learn from this project:

- Experience in the differences between the general Java environment and the specific Android Java environment. 

- Working with threads (the maze generation operates in a separate thread to keep the UI responsive)

- Working with simple graphics in Android

- How Android handles graphics and screen updates in its UI thread with a message queue

Notes

When porting Falstad's code to Android, several issues come up:

• Temporary feedback on what the program is doing: Use the Log.v(), Log.e()… methods and LogCat to obtain output from the Maze program. 
• Maze.java: this class looses quite a bit if its complexity and its responsibilities. Organizing the generation of a maze according to the user given parameter settings moves into the StateGenerating activity class such that MazeBuilder will interact with the State Generating Activity. Maze.java's main responsibility is reduced to handle the maze visualization with notifications to registered viewers in state Play where the maze is on display and either the user manually navigates the robot through the maze or the robot driver and robot explore the maze.
• State Generating: Generating the maze takes place in a separate thread to retain an UI the responds to user input. 
• There are different design options on how the MazeBuilder thread may deliver the cells, distance matrix and other data to the StatePlay activity. One can serialize the data and communicate it within an intent. One can transfer the data into the applications preferences. One can make the Maze class subclass Application. There may be even more.
• The MazeBuilder thread updates a visualization for the progress that it makes in the Generating activity. One possible visualization is a progress bar. This may require a Handler to handle messages being sent between the MazeBuilder thread and the main thread to inform the main thread about the progress being made in the MazeBuilder thread.
• Communication between threads can be handled with a so-called Handler, another example with a handler and discussion on possible issues with a handler.
• State  Play:  
• We also need to support other keyboard input as in Falstad, e.g. + and - to  zoom in our out of the map view. There are different ways to establish this. A gesture for scaling is one way or a zoomcontrols as for maps. In case you want to use a hardware key, consider an OnKeyListener for this. 
• To handle the Maze graphics, there are different options, among others one can draw on a Canvas using a View as described here. 
• In this case, drawing the graphics is implemented in an OnDraw method and one can cause the Android environment to call OnDraw by a call to the invalidate method. 
• The main UI thread has a so-called looper and handles requests for redrawing  a view in a queue. For the manual operation of the maze, where the user clicks buttons, the integration of the maze graphics and controlling when an update is necessary is reasonably straightforward. 
• Outlook for Project 7: For the automated exploration with the RobotDriver, it is advisable to consider using a Handler for the UI thread and feeding runnable tasks for robot steps into the handler such that the UI thread faithfully performs all requested updates (check method postdelayed). The UI thread otherwise may bundle invalidate requests and skip some updates. Note that slowing doing the UI thread with sleep commands is NOT a good idea. 

As a general advice: do not attempt a big bang integration, identify individual steps, e.g. the integration of the maze generation and make this one work before integrating the graphics part etc. For the reimplementation of the MazePanel code: reimplement the individual functions and test them before you attempt to port the FirstPersonDrawer and the MapDrawer into the Android project.

To do list:

• Refine the AMaze app from Project 5 into a working maze application for the manual operation mode that runs on Android with similar functionality as the maze application worked as a Java application on a PC before. 
• Update the repository and deliver a release 9.0 to submit your results to the grader. 
• Grading
• You will receive points for a subversion release 9.0 that includes source code that can be checked out by the grader. 
• You will receive points if your Android app can be executed and a manual exploration works at least for a small skill level. 
• You will receive points for feedback produced at runtime with Log.v / Log.e etc commands such that one can see the app internally works.