• Introduction
• Working on GFX

JavaDocs and Swing

Now that you've become familiar with the process of coding, you are going to start coding graphics based programs using Java's swing library. This probably seems like a somewhat daunting task, but don't worry, swing is well documented and you can lookup any method you would like using JavaDocs, you're new best programming friend.

Goal: Gain familiarity with JavaDocs and work on your own graphics package, gfx.

Java Docs

The best place to look for how to use the classes already implemented by java are the Java Docs. You might have heard the word mentioned before, but what are these mysterious things called "JavaDocs"?

First, let's talk about Java API. Java API (Application Programming Interface) is a collection of build-in classes in Java that provide commonly needed functionality for programmers like yourself (like java.awt.Color or javax.swing.JPanel). After all, do you really want to program how a frame and buttons work? Don't you have better things to do with your time? Java API is "support code" provided directly by Java and available to anyone who uses Java, its "magic".

The sheer number of methods and classes that Java API provides for you is staggering. How are you supposed to keep track of them all?

Java Docs!

JavaDocs is the documentation of the entire Java API. Treat it like a user's guide to Java libraries. JavaDocs tell you which classes you can use and how you should use them, as well as brief description of what all the methods in each class and what they do. JavaDocs also include information about the inheritance structure of classes and much, much more...

You don't believe me do you? How can one set of documentation provide all the answers you might want? Let's run through a few scenarios:

• Do you want know what parameters the constructor for JSliders take?
  Look at the Java Docs
• Do you want to know what the subclasses of java.awt.geom.RectangularShape are?
  Look at the Java Docs
• Do you want to know what method to call to set radio buttons?
  Look at the Java Docs
• Confused about life in general?
  Look at the Java Docs

Where are these magical Java Docs you ask?

We have conveniently linked them off of the CS015 we page. Simply go to cs015 webpage -> Documentation -> JavaDocs.

A window that looks like this will open

There are three parts to the Java Docs:

1. The Package List is on the top left:
   Lists all the available packages, for example: javax.swing and java.awt.
2. The Class List is on the bottom left:
   Lists all the classes contained within a particular package, for example: if you are select javax.swing you would find JButton and JFrame classes listed here among many others.
3. All of the Class Details are on the right side:
   When you click on a class from the class list it will display all information specific to that class.

Navigation

You can navigate to the information page for a class that you want by

1. Selecting the appropriate package in the 1st panel.
2. Selecting the needed class name from the 2nd panel.
3. Details of that class will appear on the 3rd panel.

Now, this will require some prior knowledge, that is, the class's package, but you should have no problem figuring out where the classes you'll use for CS15 are--we constantly reference them in our lecture slides. For example, javax.swing.JPanel gives the information that JPanel is in the javax.swing package.

Alternatively, if you search for the name of a Java class in Google, the corresponding Java Docs page will often be one of the first results.

Another useful technique for navigating the JavaDocs is the "Find" feature provided by Firefox and other internet browsers. This will be particularly useful when trying to find a class description in the Class Details.

The real usefulness of the Java Docs is in the Class Details panel.

1. Provides the inheritance tree for the class.
2. Provides the interfaces the class implements.
3. Provides a list of all known subclasses of the class.

After those nuggets of knowledge comes a summary of the class and then

1. Nested Class Summary: list of inner classes (listeners anyone?).
2. Field Summary: list of public instance variables (public instance variables?!! Gasp! Yes its true, but you still shouldn't declare public instance them in your own classes, or else Andy gets angry... and you won't like Andy when he's angry).
3. Constructor Summary: lists all of the constructors.
4. Method Summary: lists all methods written in this class (does not include inherited methods).
5. Inherited Method Summary: lists all methods that this class inherited from its superclass.

Working on GFX