Lab 8

Introduction

Congratulations! If you're reading this, you've survived flocks of bird, swarms of bees, bacteria and more bouncing shapes than anyone cares to count. Up until now, we've told you what to do -- but times they are a changin'. It's time for you, the CSE115 students, to give expression to your inner creative spirits.

Your job for this assignment is to create a graphical user interface that accomplishes some minor task yet wows your friends and the TAs. We tell you what graphics and components you can use — the rest is up to you!

Extra Credit

To encourage you to be creative we are holding a contest for lab 8 submissions.

There are 2 categories: 1) technical and 2) creative. For the technical category we are looking in the technical aspects of your GUI. For the creative category, you must write a creative story about your GUI, include it as story.txt in the jar file you submit.

There are 3 prizes in each category:

The first place winner in each category earns 10 extra points on their lab.
The second place winner in each category earns 8 extra points on their lab.
The third place winner in each category earns 5 extra points on their lab.

The competition is open across all sections of the course.

To compete in this competition, you must decide whether you want to be in the creative competition or the technical competition (your submission will be considered only for one), and complete your Lab 8 program accordingly. If your submission contains a story.txt file, then it will be considered for the creative category, otherwise it will be considered for the technical category.

Good luck to all!

New Concepts Covered

The following are the new concepts covered in this lab.

GUIs
Graphical Containment
Layout Management
Using our graphics package
Using Java Swing graphics
Creating projects in eclipse
Applications using the main method

Assignment Specification

Here's your chance to be creative. The assignment specification is simple: create a "super cool" graphical user interface that accomplishes some minor task. Use your imagination, artistic ability, and programming skill to make something that wows your friends and the TAs. Think moving shapes, changing colors, and 3-D rotating fractal landscapes. We've shown you how to create color changing and "mutating" bacteria. What will you make?

To provide some direction we require the following elements:

Your GUI must be an application (not an applet). See the section Defining a main method, below, for details on how to do this.
You must have a graphics.DrawingCanvas
There must be a graphics element on the DrawingCanvas that is affected in some way by another component of your program (e.g. it changes color when a button is clicked, or moves when a timer goes off). Here are the graphics package elements you can use:
- graphics.Ellipse
- graphics.FramedEllipse
- graphics.Rectangle
- graphics.FramedRectangle
- graphics.Rectangle3D
- graphics.Image
- graphics.Polygon
- graphics.CompoundGraphic
You must put at least 2 different components from the list below onto the GUI to control the graphics elements that are on the DrawingCanvas. All of these classes are located in the javax.swing package. This means you should have at least two different components on the GUI - you can have more. The only elements that count for this requirement are the ones listed below. Remember, each must do something useful.

JButton
JCheckBox
JColorChooser
JComboBox
JFileChooser
JList
JProgressBar
JRadioButton
JSlider
JSpinner
JToggleButton
If you use more than one of the following components, note that they count as just one compnent:

JPopupMenu (Cannot repeat functionality of JMenu if used)
If you use any of the following components, your program must do something useful with the input text:

As a final option, you can make your drawing canvas or graphic react to mouse clicks.

By creating a GUI we hope that you will get a solid grasp of creating graphical programs using a mix of the native swing graphical components and the graphics framework we have provided for you. Use your creativity!

Defining a `main` method

Up until now we have used DrJava's interactions pane to create an instance of the "top-level" class of each of our programs, thereby causing it to start executing.

In this lab we show you how to execute programs without relying on DrJava, and also how to create what's known as an executable jar file.

When we use DrJava to run a program, we can specify which class to create an instance of. When we run a Java program in the usual way, we rely on the Java Virtual Machine (jvm) to get things started. The jvm calls a method named main. To run any of the programs we have written in class, or that you have written for lab, without using DrJava, you can put the class instantiation that you would otherwise have written in DrJava's interaction pane into this main method.

You can either define this method in your top-level class, or in a separate class. The main method must be defined as follows:

    public static void main(String... args) {
    }

Here we see some new features of Java. First, the reserved word static is used to denote an element which is accessed through the class rather than through any particular instance of the class. In this sense a static method is a class method rather than an instance method. Second, the parameter list of the main method uses a special syntax which allows a variable number of parameters, all of the same type (String in this case) to be declared. For now we will not make use of the parameters of the main method.

So, for example, thinking back to lab 7, if your started your lab 7 program by writing

    new lab7.PetriDish();

you could define main in the PetriDish class as follows:

    public class PetriDish {

        ...

        public static void main(String... args) {
            new lab7.PetriDish();
        }

        ...

    }

Do the analogous thing for Lab 8. To run your program from withing Eclipse, in the package explorer right-click on the class containing the main method, and select "Run As"->"Java Application".

Creating an executable jar file

OK, so now we know we can run (Java) programs without relying on DrJava. Can we also run (Java) programs without relying on Eclispe? The answer is yes!

One (relatively) easy way to do this is to package up all the code needed to run your program into what's referred to as an executable jar file. You can do this using Eclipse's export functionality. However, since your project relies on the code in Classlibs.jar, we must somehow include that code in this new jar file that we're creating. What about all the code in the standard Java class libraries? It turns out that every jvm has access to that code already, so we don't need to include that in our jar file.

In order to include the code that is in the Classlibs.jar file, this code must be accessiblein your workspace as a project. Here's how you do that. First, create a new Java project - name it "Classlibs". Next, import contents of Classlibs.jar into this new project, overwriting any pre-existing resources (like the .project or .classpath files).

To create the jar file, right-click on the Lab8 project in the package explorer, and select Export.... In the "Export" dialog window that opens, select "JAR file", and click "Next>". In the "JAR Export/JAR File Specification" dialog window that opens, click both the "Lab8" and "Classlibs" projects, and click "Next>". The next dialog that opens is called "JAR Export/JAR Packaging Options". Simply click "Next>". The next dialog is the last one, and it is called "JAR Export/JAR Manifest Specification". It is in this dialog that you can specify in which class you defined the main method. If you click "Browse..." a "Select Main Class" window will open, and it should show the name of the class in which main is defined. Just click on the name of the class, and click "OK". Finally, click "Finish" in the "JAR Export/JAR Manifest Specification" dialog window. You may see a window appear saying that the export of the Jar file completed with warnings. This is (in all likelihood) OK.

You're all done! On a Windows system, at least, you can now simply double-click on the jar-file icon of the project you just exported to run it! On other platforms you may need to run the jar file from a command prompt, in which case you would type the following at the prompt:

java -jar Lab8.jar

Helpful Hints

Don't hesitate to also examine the code, from any of labs we've worked on this semester, in the Classlibs.jar file.

Read the javadocs of the classes you are permitted to use.

Before coding, you should draw a picture of what you want your GUI to look like. From this, determine which graphical components you will need and which graphical containers you will need to format them. Also, you should draw yourself a class hierarchy diagram to understand which objects have to communicate and in what way. If you know exactly what you are doing before you start coding, you should have no problem writing it.

Preparatory work

In order to be able to carry out the tasks required during your lab session, you must come prepared. Do the following before coming to your lab session:

Reading

Review the graphics code (and class notes) that were discussed in class.

Lab tasks

At your lab session your teaching assistant will briefly discuss how to carry out each of the tasks below. She or he will also be available to answer questions you might have. You must carry out each of the following tasks.

Create a new project in Eclipse

This time, there's no skeleton. You must create your own project from scratch. Here are the steps you need to follow:

You're going to be developing your code in a project called "Lab8." To create a new Java project in Eclipse, under the File menu, select New -> Project.
Select "Java Project" and click Next. Name your project "Lab8." If you see that the Java compiler being used is 1.4 in the "JDK Compliance" section, click the "Use a project specific compliance" button and select "5.0" from the dropdown menu. Then click Finish. You will see the new project pop up in the Package Explorer.
Now right click on the project, and select New -> Package.
Name the package "lab8." Then click Finish. All of your work will be in the lab8 package.

Congratulations: your project, along with a new package, is officially created! But, in order for you to use cse115-specific libraries, such as the cse115 packages, you must explicitly tell your project to include the Classlibs.jar archive. Steps 5-8 will explain this process.
Right-click on your project folder and select "Properties."
In the left pane of the "Properties for Lab8" window, select "Java Build Path."
In the right pane of the "Properties for Lab8" window, click the "Libraries" tab.
Click "Add External JARs..." This is where the magic happens. Navigate to /projects/CSE115/Classlibs/Fall2007/ in the JAR Selection dialog and double click Classlibs.jar. Click OK on the Properties window. You're done!

Lab Design

Once again you are required to design your solution to the lab. Use Green to create a UML class diagram of your lab design - name it Lab8.dia, and place it in the Lab8project and submit it with your project's jar file.

Use your picture of your GUI and the Classes' Public Interfaces to decide what has been written and what you need to create.

Once again, remember to design and code iteratively

Classes' Public Interfaces

You should consult the javadocs for both the CSE115 Classlibs and main Java API docs.

Submission Directions

After you are finished writing your code, jar the Lab8 project and submit the resulting jar file, Lab8.jar.

You must follow all directions about filenames exactly, otherwise your work will not be graded.

Now you are ready to submit your work. Use the electronic submission program that corresponds to your recitation.

Due Dates

Due 11:59:59pm on the day before your recitation meets during the week of November 12th.