Objective

To practice using a library, reading and understanding JavaDoc, writing and calling methods, and to reinforce all of the techniques we've been learning so far.

Overview

For this project you will write a class called PicViewer, which will consist of several static methods.  These methods will display pictures, and will allow the user to modify and combine pictures in various ways.  The methods you will write will use tools that are available in a library we are providing, called "cmsc131PictureLibrary".  We are also providing a driver, which will present the user with a menu and will make calls to the methods that you are writing. 

We have provided the images, below, for you to use with your project, but the project will work with any pictures -- in fact, you can have it operate on any picture on the internet, if you know the URL.  Here are the pictures that are included with the project:

JavaDoc

JavaDoc is a tool that Java programmers use to create automatically-generated documentation for their projects.  This sort of documentation has been generated for all of the standard Java class Libraries.  If you haven't already discovered it, take a look:  Java 5.0 API Specifications.

We have created JavaDoc for the cmsc131PictureLibrary that you will be using for this project.  Take a look:  cmsc131PictureLibrary API Documentation.  There will be a lot of information in the JavaDoc that you won't be able to understand yet.  Please don't worry about that -- by the end of the course it will all make sense!  You should read and familiarize yourself with the JavaDoc for all of the classes in the cmsc131PictureLibrary.

Input/Output with Dialog Boxes

Instead of using the console for input and output, this project will use very simple dialog boxes to interact with the user.  To facilitate this, there is a class called TextInputOutput included in the cmsc131PictureLibrary.  There is a method in this class with the following prototype:

public static String simpleDialogBox(String prompt)

The parameter "prompt" is a prompt that will be displayed for the user; the return value is the user's response to the prompt.  For example, here is the result of what would happen if you called the method passing in the String "Enter your name:" as the value of the parameter "out":

The return value from the method would be whatever String the user typed into the box.  Try it and see how it works before proceeding with the rest of the project!

Driver.java

We are providing a Driver in a class called "Driver.java", located in the package called "photoLab".  (In Eclipse, click on the "photoLab" package to see what is inside.) The first thing our driver will do is ask the user for a password.  The driver will do this by calling a method that you have written (described later).  The two passwords that the Driver will accept are:  "CS1" or "cmsc131".

If the user provides an appropriate password, then the driver repeatedly displays a menu that the user will use to select various options for Image Processing.  Below is what the menu looks like:

The driver will then handle the user's choice mostly by making calls to methods that you have written (described below.)

PicViewer Class

This is where YOU come in.  You must fill in the implementation for the PicViewer class (lots of static methods.)  This class is located in the "photoLab" package -- in Eclipse, click the photoLab package to access the files inside.

IMPORTANT:  Whenever you need to interact with the user, your prompt (and the user's response) should be handled using the simpleDialogBox method described above!  DO NOT USE system.out.print for output, and DO NOT USE the Scanner class for input!

Below is a description of all of the static methods that you must implement:

1. public static boolean readPassword(String passwordOne, String passwordTwo, int maxAttempts)  -- The parameters "passwordOne" and "passwordTwo" represent the two valid passwords that the user could enter.  The value "maxAttempts" represents the maximum number of attempts the user is allowed to make at entering one of the two passwords.  This method will prompt the user with the String "Enter password:".  (Use the simpleDialogBox method described above.)  If the user enters the wrong thing, repeat this prompt up to "maxAttempts" number of times.  If the user enters wrong things "maxAttempts" number of times in a row, return false.  If the user enters either of the correct passwords within "maxAttempts" number of tries, return true.  Note that you can test whether or not this method is working correctly by submitting your project and checking the outcome of the release test. Your prompt should look like the one below:
   
   
2. public static BasicPicture loadBasicPic() -- This method will prompt the user with the String "Enter image location: ".  The method will then create (instantiate) a new BasicPicture object by passing the user's response to the appropriate constructor of the BasicPicture class.  The return value is a reference to the new BasicPicture that has been created.  Note that the pictures requested could be those included with the project files (kong.jpg, adrien.jpg, naomi.jpg, and jack.jpg) or the could be an internet URL, such as http://www.ahajokes.com/cartoon/overl.jpg.  Your prompt should look like the one below:
   
3. public static void displayPic(String option, Picture picture)-- This method will display a picture by calling the "show" method of the PictureUtil class.  The parameter "option" represents one of three valid choices.  If the option is "ProvidedPicture", then the method will display the parameter "picture" on the screen.  If the option is "LastPicture", then the method will display the last picture that was displayed most recently, and the second parameter is ignored.  (Hint:  There is a method in the PictureUtil class that can tell you what the last picture was.  Look at the JavaDoc.)  You may assume that the method you are writing will only be called if at least one picture has already been displayed.  If the option is "ClearScreen" then all of the images are cleared from the screen and the second parameter is ignored.  (Hint:  There is a method in the PictureUtil class that will clear the pictures from the screen.)
4. public static Picture processOnePic(Picture picture, String processing) -- The parameter "processing" represents one of three valid choices.  If processing is "BlackAndWhite" then the return value is a reference to a new BlackAndWhitePicture generated by passing the parameter "picture" to the constructor of the BlackAndWhitePicture class.  If processing is "Mosaic", then the return value is a reference to a new "one picture mosaic", created from the parameter "picture".  (See below for a description of what a "one picture mosaic" looks like.)  If processing is "Rotate" then the return value is a reference to a new RotatedPicture object generated by passing the parameter "picture" to the RotatedPicture constructor.
5.  public static Picture processTwoPics(Picture pictureOne, Picture pictureTwo, String processing) -- The parameter "processing" could represent one of four valid choices.  If processing is "CombineTopBottom", then the return value is a reference to a new AboveAndBelowPicture object created by passing the two pictures to the constructor in the same order as the order of the parameters.  If processing is "CombineLeftRight" then the return value is a reference to a new SideBySidePicture object created using the two pictures in the same order as the order of the parameters.  If processing is "Merged" then the return value is a reference to a new MergedPicture object created from the two pictures in the same order as the order of the parameters.  If processing is "Mosaic" then the return value is a reference to a new "two picture mosaic" created from the two pictures.  (See below for a description of what a "two picture mosaic" looks like.)
6. private static Picture createOnePictureMosaic(Picture picture) -- The return value is a reference to a "one picture mosaic".  A "one picture mosaic" is a picture that looks like the example below, which has been created from the image "kong.jpg", which has been distributed with the project files.  Note that there are many different ways to generate this kind of image and you are free to use whatever technique you like!  (Hint:  You'll need to use a combination of the classes you've been given to rotate the original repeatedly, and to combine pictures together to make this gigantic picture.)  Here is the example of a "one picture mosaic":
   
7. private static Picture createTwoPictureMosaic(Picture a, Picture b)  -- The return value is a reference to a new "two picture mosaic".  A "two picture mosaic" is a picture that looks like the example below, which has been created from the images "kong.jpg" and "jack.jpg", respectively.  (Be sure to put them in the right order -- in this example, kong.jpg is the FIRST parameter.)  Note that there are many different ways to generate this kind of image and you are free to use whatever technique you like!  Your two picture mosaic must have the pictures oriented correctly, and must have color where we have color, and black-and-white where we have black-and-white. In the lower-left-hand-corner of the example below, both pictures (kong and jack) are in color. Elsewhere, all pictures are black-and-white.   Here is the example of a "two picture mosaic":
   

Requirements

• Your may only write a single class called PicViewer.
• You may write extra private static methods if you want to.  You may NOT write any extra methods that are not static or not private.
• We are grading your projects for appropriate commenting this time, as discussed briefly in class.  Each method should have a comment above it.  Other comments should be provided wherever clarification is warranted.
• If your program is not displaying the pictures, you will receive no credit.
• You must use meaningful variable names and good indentation.
• Input and output operations must be implemented using the simpleDialogBox method, described above.
• You do not need to worry about incorrect input.  You may assume that the responses the user enters are the right types, and that he/she follows instructions.
• You should not modify the project specifications. For example, do not add extra behavior or output.
• Just in case you know what an array is -- you may not use arrays (or any Java collections of any kind) while implementing this project.
• Your program must terminate without using anything like System.exit().  (Don't worry if you don't know what that is.)

Grading

For this project, we are only providing a single release test, which will check if your password checker is performing correctly.  The rest of the testing will be done SECRETLY while we are grading the projects.  It is your responsibility to do your own testing to make sure that your project is performing as expected.  Your grade will be determined as follows:

• Release test (just one)  -- 15%
• Further "secret" testing -- 75%
• Style -- 10%