CPSC 124, Fall 2005
Lab 3: Introduction to Eclipse

In the first two labs, you have written short Java programs using the edit/compile/run cycle on the command line. For serious programming, many programmers prefer to use an integrated development environment, or IDE. An IDE is a GUI program that lets you edit and run programs (often hiding the compile step, unless it generates an error). In general, an IDE also makes it easier to organize large projects, and it provides lots of specialized commands for working with programs. Because of their complexity, IDE's can be difficult to learn, but a well-designed IDE lets you do simple tasks without having to master its full complexity.

There are many IDE's for Java development. This lab will introduce you to Eclipse, one of the most popular. Eclipse is reasonably well designed, and it has the advantage of being free. With just a little experience, you will probably find it to be much easier to write your programs in Eclipse than with a plain text editor.

As a side note, Eclipse is itself written in Java, so it stands as evidence that Java can be used to write large, useful, high-performance programs.

Running Eclipse

You can start Eclipse using the "Integrated Environment" command in the "Development" submenu of the Start Menu. Since you will be using Eclipse for the rest of the course, you might want to add its icon (shown at left) to the panel along the bottom of your screen. To do this, right-click at any point in the panel. From the pop-up menu, select "Panel Menu" / "Add to Panel" / "Application" / "Integrated Environment" / "Development". (You can add a button for any other application to the panel in the same way.) After adding the icon, if you want to move it to a different position in the panel, right click the icon, choose "Move Eclipse Icon", move the mouse to move the icon, and click the left mouse button when the icon is in the position you want.

When Eclipse first starts, you will see a "Welcome" screen from which you can access extensive Eclipse documentation. For now, you want to get right into Java programming, so close the Welcome window by clicking the "X" next to the word "Welcome" in the top-left corner of the window. You can get back to the Welcome window by selecting "Welcome" from the Help Menu.

Java has several "perspectives" which define what's shown in its window and how it's organized. For programming, you want to use the "Java" perspective. To select the Java perspective, go to the "Window" menu, then to the "Show Perspective" submenu, and select the "Java" command. The window will be divided into several areas. The areas are called "views". The large area in the center is where you will eventually edit your Java files. To reclaim a little screen real estate, you might want to close the "Outline" view to the right of the edit area, since it's really not very useful except for large projects. (You could get it back using the "View" submenu of the "Window" menu.) Eclipse will remember the window setup when you quit and will restore the setup the next time you run it, so you won't have to reset it every time you rin Eclipse.

Eclipse will store files in the directory named "eclipse-workspace" in your home directory. (I have set up this directory so that I have access to the files that it contains.) Eclipse needs complete control over this directory; you should not directly edit, move, or rename the files in the eclipse-workspace directory.

It is possible to install Eclipse on your own computer (as long as you already have Java 1.4 or higher installed). It is available for Windows and Mac OS X as well as for Linux and can be downloaded from eclipse.org. If you run Eclipse on your own computer, then when you start it up it will ask you which directory you want to use as its workspace.

Starting a Java Project

Your work in Eclipse will be organized into "projects." To start a project, right-click in the "Project Explorer" view at the left side of the Eclipse window. Go to the "New" submenu of the pop-up menu, and select "Project". A dialog box will appear. "Java Project" should already be selected; if not, click it to select it. Click the "Next" button. On the next screen, you only need to fill in a name for the project, such as "First Project", and press the "Finish" button. Your project will appear in the Package Explorer view on the left edge of the Eclipse window.

The next step is to add a Java file to the project. To do this, right-click the project name, go to the "New" submenu, and select "Class". (You might think that you should select "File", and in fact you could, but by selecting "Class" you can get Eclipse to write part of the class for you!) A dialog box will appear. Fill in a name for the class, such as "FirstTest". (Note that you should enter just the class name and not the full file name "FirstTest.java".) Since you will be writing a main program, you can also check the "public static void main(String[] args)" option. You can ignore the other options for now. The box will look like this:

(Don't worry that the window says "The use of the default package is discouraged." We're doing it anyway.)

Click "Finish". The class will be added to the project, and the source code will appear in the edit area. The source code will contain some comments in a standard format -- you can erase them or edit them to say something more meaningful. (But please don't leave nonsensical generic comments in your code!)

Editing and Running

Type the code shown below into the main() subroutine of your program, and notice that Eclipse finds the errors and marks them. Once you type the final semicolon, it marks the line with an error icon in the left margin. You don't have to fix the error immediately, but you will have to fix it before you will be able to run the program.

The problem with "name" is that this variable is undeclared. Add the declaration "String name;" to the program. As soon as you do this, the red underlining of "name" will disappear. The problem with TextIO still remains. Here, the problem is that TextIO is not a standard part of Java. To make it available to your program, you have to add it to your project.

To add TextIO.java to your project, right-click on the project name in the Package Explorer view and select the "Import" command. A dialog box will appear. Select "File System" to indicate that you want to import files, and click the "Next" button. You will have to specify TextIO.java; unfortunately, this is a little complicated, since you first have to specify a directory and then choose files from that directory. There is a copy of TextIO.java in the directory /classes/s06/cs124. Click the "Browse" button, enter /classes/s06/cs124 in the file selection box (or navigate to this directory graphically) and press return. The directory will be entered in the "From Directory" box and TextIO.java should appear in the pane below the Browse button -- click the checkbox next to the name "TextIO.java". The dialog box will look something like this:

(Note that the only thing checked is "TextIO.java" and that the "Create selected files only" option is selected. If you don't have it set up like this, TextIO.java might end up in the wrong directory inside your project. If that happens, you can drag it to the correct location, which is in the "default package".)

Click "Finish". TextIO will be added to the project, and the TextIO error in your program should go away.

Start typing another line into the program, such as

         System.out.println("Hello " + name + ", nice to meet you");

but pause after typing one of the periods. A box will pop up listing all the things that you can legally type after the period, and you can select the continuation that you want from this list -- or hit ESC to dismiss the box. You'll notice that if you wait another second after highlighting one of the selections in the list, you'll see documentation for that item.

I find it really annoying to have this type of list pop up automatically as I am typing. Eclipse has many options; this is one that I advise changing. To do so, go to the "Preferences" command in the "Window" menu. Under Java / Edit / Code Assist, you'll find a checkbox labeled "Enable Auto Activation". Uncheck this box, and click OK. You will still be able to call up Code Assist manually. To call up Code Assist manually, press CONTROL-SPACE. You can do this at any time, even in the middle of words. This is particularly useful for auto-completing long variable names and should encourage you to use variable names that are long enough to be meaningful.

When you are ready to run your program, save it first. (It is possible that when you do this, Eclipse might mark additional errors that it missed when you were typing. You will want to fix them before proceeding.) To run the program, right click on the file name of the program in the Package Explorer view, go to the "Run" submenu, and select "Java Application". The program will run, and the command-line IO will go the "Console" pane in the bottom right corner of the window. You might have to click the "Console" tab to bring the console to the front:

Note that you can maximize the console pane (or any pane) to fill the whole Eclipse window by clicking on the appropriate tiny icon at the top-right of the pane. This will be convenient when you are running a more substantial program. It can also be convenient for editing a java source code file.

Once you have run the program once, there is a shortcut for running it again. Just click the Run button in the toolbar. (It's the middle button shown at the right.) This button re-runs the program that you have run most recently. Click the little triangle to the right of the button to get a menu of programs that you have run recently.

The Eclipse Printing Problem

I was dismayed to discover that Eclipse does not support printing (at least not yet or not under Linux). The easiest solution, if you want to get something printed, is to go into the eclipse_workspace directory and print the file from there using the a2ps or a2pslong command on the command line. (Hint: Try using the GUI to navigate to the file that contains the file that you want to print. Hit "F4". This will open a terminal window for that directory.) Please make sure that you understand how to do this before you leave lab. Try printing the program that you wrote for Exercise 1.

Programming Exercise

The main exercise of the lab asks you to write a longer program with Eclipse. For this exercise, you will be creating a simple animation. In a computer animation, the user is shown a series of "frames". The picture changes from one frame to the next, and the user perceives this as a moving image. To create the animation, you just have to say how to draw each frame. Drawing a single frame is no more complicated than drawing a still picture, except that you have to take into account which frame you are drawing and modify the picture accordingly.

To work on this exercise, you should create a new Java project in Eclipse, in the same way you created your first project above. The project needs four files, which you can import from the file system. The files are in the directory /classes/s06/cs124/BasicAnimation. To import the files, as before, right-click the project name and select "Import" then "File System" and click "Next". Click the "Browse" button and enter /classes/s06/cs124/BasicAnimation as the directory name. The four files that you need should appear. They are: BasicAnimationApplet.java, BasicAnimationFrame.java, BasicAnimationPanel.java, and cs124_lab3.html. Click the checkboxes next to all four file names, and click "Finish". The java files should be added to the "default package" in your project.

There are several classes here. The main() routine is located in the BasicAnimationFrame.java file. To run the program, you should right-click BasicAnimationFrame.java and select "Run" / "Java Application". Do this now to see what the program does.

The subroutine that draws the frames is in the file BasicAnimationPanel.java. That is the file that you have to edit. Double-click BasicAnimationPanel.java to open it in the editor. The subroutine that draws each frame is called drawFrame(). This is the only subroutine that you will have to modify to do the programming exercise for this lab. Note that the subroutine is automatically called over and over to draw the individual frames of the animation -- but the subroutine only draws a single frame each time it is called. There is a variable named frameNumber that tells you which frame you have to draw. This variable starts out at 0 and increases by 1 each time drawFrame() is called. It only goes up to 100 and then it returns to 0 and repeats, so the animation will have 100 different frames that repeat over and over.

The graphics commands that you can use in this week's lab are similar to those that were available in the BadGraphics program from last week's lab. However, this time you will be doing graphics more "correctly" since the graphics routines are contained in an object in the proper Java style. The drawFrame() subroutine has a variable named g that lets you use the following drawing routines:

• g.setColor(c); -- Sets a color to be used for subsequent drawing operations. For "c", use one of the constant values Color.BLACK, Color.WHITE, Color.RED, Color.GREEN, Color.BLUE, Color.YELLOW, Color.CYAN, Color.MAGENTA, Color.PINK, Color.ORANGE, Color.LIGHT_GRAY, or Color.DARK_GRAY. (If you want to be able to use other colors, ask how to do it!)
• g.drawString(str,x,y); -- Draws a string with its basepoint at the point (x,y). The string should be in double quotes, as in "Hello World". The basepoint of a string is the left endpoint of a line drawn along the bottom of the string.
• g.drawLine(x1,y1,x2,y2); -- Draws a line segment from the point (x1,y1) to the point (x2,y2).
• g.fillRect(x,y,width,height); -- Draws a filled-in rectangle whose upper left corner is at the point (x,y). The parameters should be integers. The width and height are positive integers giving the size of the rectangle, measured in pixels. For a square, use the same value for width and height.
• g.drawRect(x,y,width,height); -- Like fillRect, except it only draws the outline around the rectangle.
• g.fillOval(x,y,width,height); -- Draws a filled-in oval that just fits inside rectangle that would be drawn by g.fillRect(x,y,width,height). For a circle, use the same value for width and height.
• g.drawOval(x,y,width,height); -- Like fillOval, except it only draws the outline around the oval.

You might wonder what the other two files, BasicAnimationApplet.java and cs124_lab3.html, are for. An "applet" is a Java program that is meant to run on a Web page instead of as a stand-alone application. A Web page is defined by an html file, which can include commands to load the applet. BasicAnimationApplet.java defines an animation that can display your animation on the web page that is defined by cs124_lab3.html. You can publish this web page, with your animation, on the Web. In fact, your account contains a directory named www. Anything that you put in this directory is automatically published on the web.

After you finish your animation, you can "export" it from Eclipse into your www directory. For it to work properly, you will need to export three files: cs124_lab3.html and the compiled class files BasicAnimationApplet.class and BasicAnimationPanel.class. Exporting files is similar to importing them. To export files from an Eclipse project, right-click the project name, select "Export", click "File System", and click the "Next" button. In the next dialog box, the only files that need to be checked are cs124_lab3.html, BasicAnimationApplet.class and BasicAnimationPanel.class. Then click the "Browse" button and select the www directory. Finally, click "Finish" to export the files. You can look in your www directory to make sure that they are, in fact, there. As soon as you've done this, you will be able to see your work on the web at address math.hws.edu/~xx9999/cs124_lab3.html where you should replace xx9999 with your own user name. This address can be entered into a web browser's Location box -- don't leave out the little "~" character that comes before the user name. Note that in order for the applet to work, a recent version of Java must be installed properly on the computer where you are running the web browser. It will work in the FireFox or Konqueror web browser under Linux on the computers in the labs.

Many of the GUI programs that you work on in the future will follow the strategy of working in a dual form, both as an applet and as an application, which will make it possible to run the program on its own as well as to publish it as an applet.