To Deliver: 1. Release 6.0 in your new GitLab repository AMazeBy<yourname>

2. New GitLab issue tracker board with issues tracked for assignment

4. Upload file P6By<Yourname>.pdf document to BB assignment

Learning Objectives :

-   Experience in designing a user interface .

-   Learn to work with a UI design in XML and connecting it with Java code

-   Experience in software development on an Android platform: working with activities and intents

Motivation/Background information

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.

Design decision

It is up to you to decide on the particular design, however as minimum requirements we will translate the 4-state automaton implemented in the maze program (shown in the figure above) into one with 6 states namely for Title, Generating, PlayManually, PlayAnimation, Winning, and

Losing. The following text describes this for a design with one activity per state. You can alternatively use the Android Navigation Component which will most likely lead to a design with only one base activity and then one fragment per state . This is ok and one can make this work as well, the grader will consider a fragment in lieu of an activity. Consider creating a narrative for your app such efforts will be recognized for Bonus points in P7. The corn maze above may serve as an example what is meant by “theme” or “narrative".

State Title (required class name: AMazeActivity):

1.    Displays the welcome page and takes parameter settings to start with the maze generation .

2.    Your code should include options to set the following parameters:

2.1. The complexity (size) of the maze . Consider using a SeekBar for this . Pick a meaningful, commonly used default value (0 may be a good choice during development) .

2.2. The option to include rooms (yes/no), and the default setting is yes . Pick wording that is intuitive for a user.

2.3. The option to select a maze generation algorithm   (DFS, Prim's, and Boruvka’s algorithm) . Consider using a Spinner for this to show the selection of generation algorithms, for the default value you can pick Boruvka’s if you are proud of your implementation and it works well or otherwise DFS as default setting .

2.4. The selection of either generating a new maze or playing a maze again that a user played before . One possibility is to have two buttons “Revisit” and “Explore” .

•    If the user clicks “Explore”, take into account what is selected for the maze generation algorithm (DFS, Prim's, and Boruvka’s algorithm), the size, the presence/absence of rooms etc . The idea is create a new random maze, you need to draw a random number for the seed . Communicate all these pieces of information with an intent to start the GeneratingActivity.

•    If the user clicks “Revisit”, in this assignment, simply proceed the same way as for “Explore” . Outlook for the final project: Each time the user plays a new maze with “Explore", you need to store the seed value that is used with the selected combination of (Size, Algorithm, Rooms y/n) . If the user clicks “revisit” you need to look up the seed value from persistent storage (a file) and communicate the configuration to the Generating Activity such that the corresponding old maze is computed again . For revisiting a maze, it does not matter how the user played it last time or this time (manually or with a driver) . Revisiting can be also useful for you for manual testing & debugging .

2.5. Navigation :

•    Possible transitions are to state Generating . The transition is triggered by the explore or revisit button . The user selections for Size, Algorithm, Rooms y/n, and the Seed value are communicated to the generating activity.

•    Note, the latest and greatest Android versions use a Jetpack navigation component . You can go down that rabbit hole if you want to, but for this class it is not necessary.

•  Note: The emulator for the Pixel 6 API level 32 has a back button on a separate side bar.

3.    Hint: check slides for   lecture “Android User Interface Basics” for an example . Please note that this example is not the only possibility, feel free to do your own design but you need to support the functionality described above.

State Generating (class name GeneratingActivity):

1.    Displays an intermediate page where the user can select the driver and robot settings while a maze is generated with a background thread . The page informs the user on the progress that is made on the preparation of a maze . The design idea is to keep the user engaged while the game computes the maze to reduce the perceived wait time .

2.    Your code should include options to set the following parameters :

2.1. The selection of a driver: a) Manual, b) Wall Follower, c) Wizard . Do not pick a default value, the user must actively select a driver. If your UI component requires default selection, invent an artificial value such as “Select:” that is preset. Design suggestion: use image buttons for fun visualizations or radio buttons . The user can pick one out of the three options .

2.2. The selection of one of a robot configuration: a) Premium, b) Mediocre, c) Soso d) Shaky. Premium has 4 reliable sensors, mediocre has reliable front & back sensors, unreliable left and right sensors, Soso has reliable left & right sensors, unreliable front and back sensors, Shaky has 4 unreliable sensors . The user can pick one out of the four options . The robot selection does not matter for the Manual driver, so you can either have a static design that shows it no matter what driver is selected or you only show the robot configuration selection if the wall follower or wizard is selected for the driver.

3.    There is a progress bar, where the visual representations shows an explicit quantity of progress that has been made by the maze generation background thread . You can achieve by using the progress bar in the determinate mode , or by adding a separate view that you implement yourself that shows the percentage completed over time .

3.1. Later in project 7: Whatever generating algorithm the user chose on the title screen, we need to perform the maze generation in a background thread . If the user chose to generate a new maze, we randomly pick a seed value . If the user chose to revisit a previously played game, we need to load the stored seed value for that game configuration (size & generation algorithm) from file and then generate the maze . This is all in project 7 .

3.2. For this project 6, we will only simulate the maze generation with some background thread/async task or alike that delays execution, slowly counts to 100 and provides the counter information to update the progress bar. The point is to learn how to have something computed in the background that communicates with the main ui thread to update the progress visualization on screen . Hint: check for a tutorial to work with a progress bar and background thread, the demonstrated example is most likely a good fit for what you need here .

4.    Navigation

4.1. Pressing the back button will stop the maze generation and return to State Title . The emulator for the Pixel 6 API level 32 has a back button on a separate side bar.

4.2. Switching from generating to playing waits for two conditions to hold: a) the progress bar reached 100% and b) the user made a selection for the driver (possibly followed by a selection of a robot if it was wall follower or wizard) . If the progress bar reaches 100% first, show a message to remind the user to select a driver. If the user selected the driver first, show a message that says that the game will start shortly if the maze is ready to play. As soon as both conditions are satisfied the game switches to State PlayManually if the manual driver was selected, respectively to state PlayAnimation if the wizard or the wall follower was selected.

State  PlayManually (class name PlayManuallyActivity):

1.    Displays the maze and lets the user manually navigate through the maze .

2.    Detailed features

2.1. Provides a feature to toggle visibility of the map plus functionality to toggle visibility of the solution on the map . You need to support the following choices :

•   show the map of 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)

•   scale the size of the map (increment, decrement size, with an initial setting that makes the map clearly and nicely visible on the reference architecture)

•   Note: this matches existing functionality in the maze: keyboard input m,s,z, but for this project P6, you just provide the UI elements, there is no maze to show.

2.2. Screen provides navigation buttons (forward, left, right, jump) .

•  You need to count the number of clicks on forward (+1) and jump (+1) to compute the path length . This will be communicated to State Winning together with the distance to the exit for the starting position .

2.3 Screen shows a squared custom view where the maze will be displayed on in the final project .

•  For P6, it will show a filled red circle on a background of two large rectangles, a black one on the bottom, a grey one the top that cover the whole space of the squared area .

3.    Navigation

3.1. Pressing the back button returns to State Title to allow the user to choose different parameter settings and restart .

3.2. If the user goes through the exit, switch to State Winning .

3.3. As an intermediate step only for this project 6 introduce a button "ShortCut" to directly move the UI to State Winning when clicked.

State  PlayAnimation (class name PlayAnimationActivity):

4.    Displays the maze and lets the user watch a robot exploring the maze .

5.    Detailed features

5.1. Displays the remaining energy, consider using a ProgressBar for this .

5.2. Provides a feature to show the map . Support the following choices :

•   show the map (whole maze with solution and visible walls) or not (toggle) .

•   scale the size of the map (increment, decrement size, with an initial setting that makes the map clearly visible)

•    Note: this matches existing functionality in the maze: keyboard input m,s,z, but for this project P6, you just provide the UI elements, there is no maze to show.

5.3. Provides a start/pause button to start the driver and to pause the animation (the inscription on the button changes after clicks, so one buttons supports 2 features in alternating way) . Again, P6 is UI only, you just need to produce feedback for clicks .

5.4. Provides a way to adjust the animation speed, consider using a SeekBar for this, say ranging from slow to fast .

5.5. Provides a visualization of the robot’s sensor state (operational or failed) for each of its four sensors . Suggestion: use some colors such as red for broken, green for ok .

5.6. As for State PlayManually, the Screen shows a squared custom view where the maze will be displayed on in the final project . For this activity and for P6, it will show two polygons, that look like walls with a perspective as in the maze game . One polygon is green, the other one is yellow. They reside on a background of two large rectangles, a black one on the bottom, a grey one the top that cover the whole space of the squared area .

6.    Navigation

6.1. Pressing the back button returns to State Title to allow the user to choose different parameter settings and restart .

6.2. If the driver/robot stops at the exit, switch to State Winning . You need to communicate path length, distance to exit for the starting position and the energy consumption. For P6, just communicate some hardcoded values for demonstrating purposes.

6.3. If the driver exhausts the robot’s energy or drives the robot into a wall or jumps over an exterior wall outside of the maze, switch to State Losing. You need to communicate path length, distance to exit for the starting position and the energy consumption . For P6, just use some fixed values for demonstrating purposes .

6.4. As an intermediate step only for this project 6 introduce a button "Go2Winning" to directly move the UI to State Winning, and a corresponding button “Go2Losing".

State Winning (class name WinningActivity):

1.    Displays the finish page for the case of winning the game and informs the user what happened and how to restart the game .

2.    It displays the length of the path taken and the length of the shortest possible path .

3.    If reached from PlayAnimation it also shows the robot’s overall energy consumption .

4.    Navigation

4.1. Pressing the back button returns to State Title.

State Losing (class name LosingActivity):

1.    Displays the finish page for the case of losing the game and informs the user what happened and how to restart the game .

2.    Shows the overall energy consumption, the length of the path taken and the length of the shortest possible path .

3.    Visualizes if robot stopped for lack of energy, or if it is broken (consider using audio or vibrations to enhance the user experience) .

4.    Navigation

4.1. 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 or snackbar) and a Log .v() output into the Android Studio Logcat window such that you can recognize that the bits and pieces of your app correctly communicate . While the toast or snackbar messaging is just to try this out, the Log .v output is something you need to retain and use for P7 .

•      State Generating: imitate the delay in this state and the update to the progress visualization by some simple code that just operates the progress bar but does not generate a maze .

•      State PlayManually and PlayAnimation:  you should prepare for the graphics part for the maze in your layout with a custom view. Reference: https://developer.android.com/training/custom-views/custom-drawing . You need to add simple buttons that when clicked, the display moves on to the Winning/Losing state . Also prepare for a user interface in state PlayManually that allows a user to navigate the game, for PlayAnimation to configure the animation.  Implement code that is called and responds any user input on the user interface.

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:

•      gui for the user interface and

•     generation for the code that we will incorporate at a later point in time.

•     Of course you need to replace <yourname> by your name. This will help to distinguish all the Android apps among students in class that otherwise all have the same name.

Hint: good starting point is: https://developer.android.com/training/basics/firstapp/index.html

Task list :

1.    Prerequisite : Install the Android Studio and the Android SDK on your machine, create an

AVD for a Pixel 6 API level 32 as a reference architecture .

1.    Install Android Studio, follow the installation instructions on developer.android.com or watch a lynda.com video for it (see CS301 course website on blackboard for details) .

2.   Create an AVD for a Pixel 6 API level 32 as a reference architecture.

2.   UI Design

1.   Do a paper prototype of the design

1.    Draw each individual screen, button etc on paper. Simulate common usage scenarios to convince yourself that the design works and is convenient & appealing .

If possible, ask a friend to play the game on your paper prototype, see if the person can get to the finish screen or if something is missing or confusing for a user.

•  Hint: consider giving your game a theme, a storyline, and potential features to enhance the user experience (images, music, …) as this can give you some bonus points . The Bonus points will be assigned in P7 (and not for P6) but it makes sense to plan early for this option .

•  Outcome: Create a report for your design named P6By<Yourname> .pdf and add photos/pictures of your drawings together with some explanations that you will submit for this assignment . Your work will not be graded for artistic and esthetic perfection, just draw a design that is clear enough to understand how the layout looks like and where the required functionality is placed .

2.    Perform a class design with CRC cards for the different Android activities in your user interface .

1.    Pick one activity per state and use the class names as suggested above, e .g . AMazeActivity.java for the title screen . Make sure you recognize collaborators from the existing Maze project your new classes will interact with .

2.    Outcome: Document your crc design in writing in P6By<Yourname> .pdf . Simply list each class, its responsibilities and collaborators . For collaborators on the existing Maze project, denote what changes will be necessary there . You will need to upload this to the Blackboard assignment .

3.    GitLab Project management, issue tracker: Create and use the issue tracker and board

for your GitLab project .

1.    Break down the overall assignment into a number of issues, decide on a time line for all issues and estimate the time you need for each issue, set a milestone for your project submission date . Use the P6By<Yourname> .pdf content to create issues on your GitLab project’s issue tracker. Provide each issue with a time estimate, sources of supporting information that you may need for it, and a risk estimate that corresponds to your level of familiarity or expectation on the difficulty for this issue (low, medium, high risk) .

2.    Warning : meaningful use of the issue tracker is graded . If you put it to good use to your advantage, you should be fine .

3.    The issue tracker must use default columns open and closed (more columns are optional), and issues must carry tags that indicate that you used them, see Gitlab documentation for details.

4.   Objective: learn how to work with an issue tracker for time management and as a project management tool. Get better at estimating your time from one project to the next !

4.   Getting started with Android Studio

1.   Create a new Android project in Android Studio.

1.    Any new project will be created as a fully functioning hello world implementation .

2.    Follow the Getting Started Guide on developer.android.com with sections "Building

your fi rst app" .

5.    Getting started with Android programming

1.    To get more familiar with Android projects, there are different ways to go from here .

1.    You can follow the Getting Started Guide on developer.android.com that helps you create an app with navigation from the fi rst to the next activity with an intent .

1.    Other alternative tutorials are for instance this one by Lars Vogel .

2.    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 .

1.    If you have successfully done this and messed up HelloWorld, just delete the

project and create a new from scratch for the next step.

6.   Implementation

1.   Start with your freshly created AMazeBy<YourName> project that comes as a Hello World implementation .

2.    Defi ne each activity :

1.    Follow the naming conventions for classes and UI elements (like buttons) listed under "Design Decisions" above .

3.    Some hints:

1.    Check tutorials on how to add more activities and how to make a switch from one activity to another with an intent and parameter settings (e .g . described here or here) .

2.    Add a corresponding layout xml file and specify its content in directory res/layout . For the fi rst activity you can refi ne the pregenerated file main .xml there but for others you need to add a new file for each new activity.

3.    All strings that you use need to be defined in file res/values/strings .xml .

4.    Update file AndroidManifest .xml to take the new activities into account .

5.    Add a corresponding java file to src/edu .wm .cs .cs301/<yourname>/gui/ for each activity. Each activity will need its own java class file there .

6.    Add navigation between activities by using intents such that perform the navigation as described under “Design Decisions” above .

7.    Create a custom view for PlayManually and PlayAnimation: Create a new MazePanel class a subclass of View and integrate it into the layout for your PlayManually and PlayAnimation activities . Choose its dimensions such that its area is a square .

1.    Hint: https://developer.android .com/guide/topics/ui/custom-components shows how to integrate a view like MazePanel into your layout XML file for an activity.

2.    Clarify from the Android documentation what you need a Canvas, a Bitmap, and a Paint for in your MazePanel class . Add instance variables for a Canvas, a Bitmap, and a Paint to your MazePanel class accordingly.

3.    Outcome: you can run the app, the PlayManually and PlayAnimation activity show an area with a hardcoded image (a red ball, respectively a green and yellow polygon on a black and grey background) for the new view for testing purposes. Make sure the circle, polygon and rectangles are drawn in the MazePanel constructor method with the help of the internal canvas and on the internal bitmap.