Project 5: Android App for Maze 

To Deliver: release 8.0

To Download: 

Due date for submission:    Nov 11, at 5 AM

Drop out date:                     Nov 13, at 5 AM

Motivation

We want to port our maze java application to Android. This requires us to redesign the user interface for a start.

User interface design is very important for a successful app. It needs to be intuitive and self explanatory as you cannot expect a user being willing to ever read a manual page on how to use your wonderful software. 

Porting the falstad package and making it work with the new Android user interface is subject to the next project P6. If for some reason you want to go ahead, please note that Java AWT and Swing  packages are not supported on Android. These need to be replaced and Homework 5 is supposed to prepare for this.

What to learn from this project:

- Experience in user interface design. 

- Working with Activities and Intents in Android

Design decision

It is up to you to decide on the particular design, however as minimum requirements we will follow the 4-stage automaton implemented in Falstad's maze program:

• State Title (class name: AMazeActivity): 
• Displays the welcome page and takes parameter settings to start with the maze generation. Your design can follow the design you developed for Homework 4. Parameters include: 
• the complexity (size) of the maze. Use a SeekBar for this. Pick a meaningful, commonly used default value.
• the maze generation algorithm (Backtracking, Prim's, and Eller's algorithm). Use a Spinner  for this, pick a commonly used default value
• the selection of one of the following ways to operate the robot: a) Manual, b) Gambler, c) Curious Gambler, d) Wall Follower, e) Wizard. Pick manual as a default value.
• the selection of either generating a random maze or loading a maze from file.  Pick random generation as a default value.
• a start button to start with either the random generation of a maze or loading a maze from file (needs 1 previously stored maze for each size). The action bar may be a good location for a start button.
• Possible transitions are to state Generating (via parameter settings and clicking on the start button). 
• State Generating (class name GeneratingActivity): 
• Intermediate page that shows progress of the maze generation algorithm and informs a user. 
• Once the generation algorithm is finished the display switches to State Play.
• Pressing the back button will stop the maze generation and return to State Title.
• State  Play (class name PlayActivity): 
• Displays the maze and lets the user either watch a robot exploring the maze or allows the user to manually navigate the robot through the maze. 
• As an intermediate step only for this project introduce a Button "Shortcut" to directly move the UI to State Finish (possibly enhanced with a selection mechanism for: success, failure due to an accident or due to lack of energy).
• Displays the remaining energy, use a ProgressBar for this.
• Provides a feature to toggle visibility of the map plus functionality to toggle visibility of the solution on the map. Consider a split action bar and/or floating action bar (overlay) for this. Similar to state title above:
• show the whole maze from top or not (toggle).
• show the solution in the maze or not (toggle).
• show the currently visible walls or not (toggle)
• Pressing the back button returns to State Title to allow the user to choose different parameter settings and restart. 
• If in manual exploration mode: screen provides navigation buttons (up, down, left, right), consider a split action bar and/or floating action bar (overlay). 
• If in robot exploration mode: screen provides a start/pause button to start the exploration and a pause the animation, consider a split action bar and/or floating action bar (overlay).
• If the robot stops (no energy, accident, at exit) the screen switches to the finish screen.
• State Finish (class name FinishActivity): 
• Displays the finish page and informs the user what happened and how to restart the game. 
• Shows the overall energy consumption and length of path.
• Visualizes if robot stopped for lack of energy, or if it is broken, or if it reached the exit (consider using audio or vibrations to enhance the user experience).
• Pressing the back button returns to State Title.

As we do not use the maze code at this point, you need to imitate the behavior of the final app at certain points: 

• In general: have your user interface respond to any user input by a corresponding message (with a so-called toast) and a Log.v() output into the Eclipse Logcat window such that you can recognize that the bits and pieces of your app correctly communicate.
• State Generating: imitate the delay in state generating and the update to the progress visualization by some simple code that does not generate a maze. 
• State Play:  you should represent the graphics part for the maze in your layout by a simple button (the Shortcut button) that when it is clicked, the display moves on to state Finish. Also prepare for a user interface in state Play that allows a user to navigate the robot.  Check if buttons for right, left, top, bottom are pressed.  

To retain a reasonably uniform design, I would like to fix some further naming conventions for classes:

Call your new Android project AMazeBy<YourName> and use a path edu.wm.cs.cs301.<yourname> and create two packages: UI for user interface and falstad for the falstad code that we will incorporate at a later point in time.

To do list:

• Use your existing Java implementation to generate and store at least one maze for each skill level. We will use these to allow the user to load a predefined maze from file.
• Do a paper prototype of the design
• Draw each individual screen, button etc on paper. Simulate common usage scenarios to convince yourself that the design works and is convenient & appealing.
• For information on paper prototyping see e.g. Scott Klemmer's lecture 3.1.
• Perform a class design with CRC cards for the different Android activities in your user interface. 
• Pick one activity per state and use the class names as suggested above, e.g. AMazeActivity.java for the title screen.
• Put your crc design in writing, simply list each class, its responsibilities and collaborators. Email this to the grader.
• Create a new Android project in Eclipse. 
• Follow the Getting Started Guide on developer.android.com with sections "Building your first app" and "Adding the action bar".
• On Lab machines:
• the Android plugin for Eclipse and the emulator are already installed. No additional installation is necessary.
• Do not try to update the SDK as the installation is shared and the directory requires administrator rights to modify it.
• You need to tell your Eclipse configuration where the Android SDK is located 
• Eclipse->Preferences->Android: set SDK location to /usr/remote/cs301/android-sdk-linux_x86
• You have to create an Abstract Virtual Device (AVD) with the Android Virtual Device Manager 
• see Eclipse->Window->Android Virtual Device Manager
• On your own laptop/PC:
• follow the installation instructions on the wiki or developer.android.com
• Note that an Android project is not(!) a common Java project in Eclipse! 
• A new Android project is always generated as a HelloWorld sample application. 
• To get more familiar with Android projects, there are different ways to go from here.
• You can follow the Getting Started Guide on developer.android.com with sections "Building your first app" and "Adding the action bar".
• You can follow the steps described in Tutorial 2 and 5, Mark Murphy's book "The Busy Coder's Guide to Android Development" to build a small sample application and run it. 
• Other alternative tutorials are for instance this one developing a simple UI and starting another activity or this one by Lars Vogel.  
• Work through Mark Murphy's book "The Busy Coder's Guide to Android Development" (no, not all 2500 pages at once!) to familiarize yourself with the different bits and pieces that go into an Android project.
• With the a HelloWorld that actually works, purposely add code that is faulty to see what error messages this creates. Try some syntax errors. Try calling a method on a variable with value null to see how a null pointer runtime exception is reported and so forth. This makes it easier to recognize what is wrong if your code has errors.
• Define each activity:
• Follow the naming conventions for classes and UI elements (like buttons) listed under "Design Decisions" above. 
• Check on the use of the action bar: design concepts and how to work with the action bar.
• Check tutorials on how to add more activities (e.g. Tutorial 8 in Murphy's book) and how to make a switch from one activity to another with an intent and parameter settings (e.g. described here or here). 
• Serialization: A tutorial that particularly deals with the communication of data from serializable objects is this. Serialization in a general Java setting is also discussed in Horstmann's book, Chapter 7.
• Add a corresponding layout xml file and specify its content in directory res/layout. For the first activity you can refine the pregenerated file main.xml there but for others you need to add a new file for each new activity. 
• All strings that you use need to be defined in file res/values/strings.xml. 
• Basic widgets are for instance described here and in Chapter 9 and 10 of Murphy's book.
• Update file AndroidManifest.xml to take the new activities into account. 
• Add a corresponding java file to src/edu.wm.cs.cs301/UI/ for each activity. Each activity will need its own java class file there. 
• Connect your new project to your subversion repository, update the repository and deliver a release 6.0 in the tags directory to submit your results to the grader. 
• Send CRC design description by email to the grader. 
• Grading
• You will receive points for the CRC design description.
• You will receive points for a subversion release 8.0 that includes source code and that can be checked out by the grader. 
• You will receive points for implementing each of the 4 activities such that the Eclipse project does not show any syntactical or configuration errors. 
• You will receive points for each activity that the grader is able to run on the emulator and by moving from the starting main activity. 
• You will receive points for feedback that your implementation correctly demonstrates with the help of Log.v() message in the Eclipse Logcat window in response to individual (and correct) user input.