Copyright (c) 1999 by Charlie Calvert
(Last updated March 9, 2000)
(Download the myfirstapplet example shown in this chapter. The file is in zip format.)
In this chapter you will see how to create a simple applet in JBuilder. I will be working primarily in JBuilder Foundation (v 3.100.24.0) loaded on Linux, but the instructions I give you will also work for Windows.
The first program you create will be an Applet with a button on it. When you click on the button, the caption of the button itself will be changed. Creating this simple application will give you experience:
For the purposes of this course, an understanding of how to navigate inside the JBuilder environment is essential. Coming to understand that basics of that tool is one of the primary purposes of this chapter.
Remember that JBuilder Foundation is created entirely in Java. It is therefore an excellent example of what you can do in Java if you have the necessary skill and experience. Getting you started on the road to gaining that experience is one of the primary purposes of this text.
Choose File | Close Active Project to be sure that you do not have any currently open projects. Now select File | New to pop up the Object Gallery. In the JBuilder Foundation edition, you will be able to create a Project, Application or Applet. All the other options will be grayed out. Of course, if you are using a different version of JBuilder, then you will have more options available to you. In any case, what you should do now is choose Applet. Click the Okay button to bring up the Project Wizard.
Figure 01: Choosing to create a new Applet in the File | New menu.
The Project Wizard is a series of dialogs that allow you to define certain characteristics of your Applet, as well as the location on your hard drive where the files you create can reside. In particular, you need to declare the directory where you want your project to reside, as well as the name of the project file.
Take a moment to try to understand exactly what you are trying to accomplish. You need to create two entities. The first entity is the directory where you project files are going to reside. The second is the Java Project File, or JPR, file that will allow JBuilder to manager your project. Let's take those two entities one at a time.
First, let's talk for a bit about the directory you need to create. You are going to create several different files which will work together to create you application. These files need a place to live, they need a home on your hard drive. If you didn't give them a home of their own, then they would be all mixed in with your other projects, creating a huge mess that would be very difficult to untangle. So the first thing you do is specify the name of the directory where these files will live. That way they can all be bundled together neatly in one place. (In fact, JBuilder will create a directory structure beneath this directory. The files that make up your project will reside inside this hierarchical directory structure.)
On Linux, by default, JBuilder might ask you to store you file as follows:
/home/ccalvert/jbproject/untitled1/untitled1.jpr
A similar directory structure would be proposed on a Windows machine.
In this example, untitled1 is the directory where your projects will be stored. After a forward slash, you find untitled1.jpr, which is your Java Project File or JPR.
The directory is used as a home for your project. The project file, on the other hand, is used by JBuilder to help you manage your project. It is, as it were, the bookkeeper used to mark down, and define, each of the files in your project, as well as the settings for your project. None of the Java source code that you create will be stored in your JPR file. In fact, you can, and will by default, write totally valid Java applications that have no need for the JPR file. This file exists solely to help JBuilder itself manage your project. At the same time that you compile your project from inside JBuilder using the JPR file, you could also go to the command prompt, ignore the JPR file, and compile your project using the standard JDK 1.2.2 that you downloaded from Sun, Borland or Blackdown.
If you want, you can open up your JPR file and examine its contents in a text editor. Curiosity might well drive you to do this, but there is rarely any practical reason for you to understand its structure. The JPR file is just plumbing, and you can ignore it. We didn't have to understand how water reaches the sink in our kitchen in order to use the sink. In the same way, you don't have to understand the JPR file, you can just take it for granted that it is the mechanism that JBuilder uses to manage your project. However, this is not a binary black box which you can't control. If you want, you can edit the JPR file, I just see no reason for you to do that, especially at an early stage in a JBuilder programming journey.
Suppose you change the default project name to the following:
/home/ccalvert/jbproject/myfirstapplet/myfirstapplet.jpr
Now you are saying you want to create your project in a directory called myfirstapplet. Furthermore, you want the project file to be called myfirstapplet.jpr. You don't have to do anything to create the myfirstapplet directory. Simply specifying its name in the Project File edit control, as shown in Figure 2, is enough to automatically generate the directory. JBuilder will create the directory for you automatically based on the entry you typed in to the Project Wizard. Or, if you want to select a directory that already exists, that will also work. (In Windows, I would tend to call the file and directory, MyFirstApplet/MyFirstApplet.jpr, but using camel caps like that in Linux proves painful over time, since Linux is case sensitive.)
Figure 2: Completing the first step in the JBuilder project wizard. (This screen shot was taken when I first started out in Linux, and so I used camel caps. I have since changed my habits.)
Make sure the Make Project Notes option is selected, and then press the Next button. In the second dialog of the wizard, fill in the Title, Author, and Company fields, as shown in Figure 3. Select the Finish button.
Figure 3: Filling in the Title, Author and Company fields.
In the next dialog you can designate the Package, main Class, and Base Class for your project. The Package and Class fields should be filled in automatically for you. In this program, you can leave them with their default values.
Figure 4: Setting up the package, main class and base class.
The Base Class, however, needs to be changed. By default, it is set to javax.swing.JApplet. You may not want to use this option, because it is only available in the most recent JDKs. At the time of this writing, the popular browsers do not come equipped with the most recent JDKs. Specifically, they do not come equiped with JDK 1.2.2, which is the one JBuilder Foundation 3.1 uses. Since you probably want your applet to run on the majority of browsers, you don't want to use code that is too modern, too advanced, and therefore beyond the reach of most users.
To avoid using JApplet, drop down the Base Class combo box and select java.applet.Applet. This will be the base class from which your applet will descend.
By choosing a particular base class, you are defining a certain set of behaviors for your project. Picking a base class is a bit like selecting a product at a store, or a new car at a car lot. For instance, you might have two choices when you look for a new car: you could get a VW Bug or a Ford Mustang. After you pick the car, you can add on extras to it. In our world, we are not picking cars, but classes. So we can choose a swing JApplet or a regular Java Applet. Later, when you are building your application, you can add other features to your purchase, just as you might choose to add air conditioning or electric windows to your car. In particular, you can start adding buttons, edit controls, combo boxes, etc.
NOTE: In later portions of this text, I will show you how to use the JApplet class, but for now our goal is to create an applet that can be used on a wide variety of browsers without asking the user to take any extra steps.
After deciding to work with the Applet class, the next step is to select the Generate Header Comments and Generate Standard Methods options. Now click the Next button. The dialog that appears allows you to add parameters to your project. You don't need to do that, so just click the Next button.
In the final page of the Wizard, you can choose to generate an HTML page. Just stick with the default options, and then click Finish.
Figure 05: The last page of the Applet Wizard.
At this stage, you have generated a working applet. To run it, just push the green button at the top of the page. You should see the run time properties dialog as shown in Figure 6. Make sure you are on the Applet page. Click the Set button to set the main class to Applet1, as shown in Figure 7.
Figure 06: Viewing the Runtime Properties dialog
Figure 07: Setting the main class for the Applet.
Of course, when when your first Applet finally comes up, it doesn't look very exciting. Its just a plain Applet with no content. Later in the chapter we will add a button to it. And of course, in later chapters of this course we will add many other new features to our applications. (Returning to the analogy I created earlier, this simple Applet is like the base model for a car. When we add on buttons and other tools, we will be adding in the extras....)
Figure 08: Your first Applet at run time. Later we will add a button to the applet.
Go ahead and run your Applet a few times if you wish, but when you are done, be sure to close the applet, as we want to make some further changes to it.
NOTE: It's very unlikely that anything went wrong in the process I have outlined here for creating a simple Applet. However, if you do have troubles, there are two suggestions I can make:
1) Try highlighting the myfirstapplet.jpr file in the Navigation Pane on the left of the environment and then again pressing the green arrow. If that doesn't work, try highlighting myfirstapplet.html in the Navigation Pane and again pressing the green arrow.
2) If you still can't run your applet, try going through all the steps I've outlined in this chapter a second time. Sometimes you make mistakes going through the process the first time, or the wizards might get confused because you made a series of changes. Now that you know more of what you are about, close all your current projects, and the start again from the beginning. If you do this, you might want to put your second try at creating the applet in a directory called myfirstapplet2, with the JPR file called myfirstapplet2.jpr.
After creating your Applet, the next step is to add a button to it. To begin, click on Applet1.java in the Navigation Pane. This should put the focus on Applet1.java, as shown in Figure 9. In the structure pane, you should now see an Imports section, and another section called Applet1 that details the members of the Applet1 class, such as Applet, Applet1(), destroy(), getAppletInfo(), etc.. For now, we are going to ignore all this information in the structure pane. However, I will come back and explore it in more detail in Chapter 3.
Figure 9: Putting the focus on Applet1.java allows the structure pane to reveal information about the classes in that source file.
At the bottom of the Content pane there are four tabs called Source, Bean, Design and Doc. Choose the Design tab. After a few moments, you will be able to see your applet, as shown in Figure 10. Above the applet are a set of tabbed pages called the component palette. The tabs have names like Swing, Swing Containers, Data Express, dbSwing, etc.
Figure 10: In Design mode you can see a "preview" of how your applet will look at run time. You can also see the component palette.
The first page in the component palette contains a set of Swing components. The Swing components are great tools, but we don't have any use for them in this chapter, because they require a JDK that are not supported by popular web browsers. As a result, I will usually ask you to search for, and if necessary, remove, the string "import javax.swing.*" from the top of your source file. It will appear at the top of your Applet1.java file, in a section that looks like this:
package forloops; import java.awt.*; import java.awt.event.*; import javax.swing.*;
Rather than use the swing components, you want to use an older setter of tools called the AWT. To find the AWT, skipp over the Swing components, bypass by the Swing Containers, and then a series of tabs with controls that are grayed out. These tabls will have names like Data Express, dbSwing, etc. You need one of the full versions of JBuilder to use these pages. JBuilder Foundation, which is what this article is about, does not include working versions of those controls. However, if you put your mouse over these controls, you can still get hints describing what they are.
The page we are interested in is called AWT, which stands for Alternative Windowing Toolkit. It contains an older, and less well designed, set of visual controls. These controls are reasonably usable, they just don't include a lot of the fancy features and elegant architectures found in the Swing controls. They do, however, have one great virtue: they work on virtually any browser that your clients are likely to use! This is what we like about them. They are available on almost all Java aware systems, while Swing is only available a small subset of those systems. (Most of this book will use Swing controls, I just happen to be starting the text by showing you how to create simple applets that run on all browsers.)
If you don't see the AWT page on the component palette, then push the little buttons on the right of the palette to scroll any hidden pages into view. In Figure 11, you can see those buttons to the right of the word dbSwing, and to the right of the partial word Mor.... There are two buttons there, each with an arrow on them. Select the button the right to scroll the hidden pages of the component palette into view.
An the AWT page, you will find a button icon with the word Ok on it. If you hold your mouse over it, the hint message "java.awt.button" will pop up. Left click once on this button control, then left click again on the surface of your applet, up near the top edge. When you are done, you should be able to see an instance of the button on your applet, as shown in Figure 11.
Figure 11: Dropping a button on your Applet in the JBuilder designer. (Screenshot taken in Windows, not Linux.)
If you have trouble with the button you are using, you can select it with the mouse over in the structure pane. (Look at the bottom left of the Figure 11. In this picture, the word "button1" is highlighted. Just to help you get oriented in the complex JBuilder IDE, I'll point out that above button1 you see the word <FlowLayout>. We will talk about layouts later in this text. Below it you see the word Menu and the word Other. All of these elements will be discussed in the appropriate portions of the text.
The point here is that at design time I sometimes find it easiest to select controls in the structure pane, rather than selecting them on the surface of your Applet itself. This fact may not be obvious when you only have one control on your Applet, but when you begin working with more complicated interfaces, the structure pane can become very helpful.
As an exercise, you can delete the button1 control and then drop it down again. To do this, select button1 in the structure pane. Now press the delete key to delete the control. Now you can start again by dropping down another button. There is no reason to perform this exercise other than simply getting the opportunity to become familiar with JBuilder. You need to spend time "playing" with the IDE. Programming should be at least a little fun, and learning to play with your tools is a worthwhile undertaking. At the end of this chapter, I give you some suggestions on further ways to "play" with the environment, so that you will learn to feel at home with this powerful, time saving tool.
At this stage you have a button on your form, but it doesn't do anything. The next step is to associate an action with the button, so that when you click on it at run time there is some kind of result. In this case, the only result I want to produce is to change the caption of the button. In other words, I want to create a Java program that will allow me to change the caption of its button at run time. By default, the button has a captions that says "button1." Our goal is to change that caption so that it reads "JavaButton."
NOTE: When I say, "at runtime," I mean "when your application is running." At design time programmers can edit their application. Then they can click the green button and run their program. So your program is usually in one of two states. The first state is called design time, and the second state is called runtime.
To get started adding an action to the button, you can do one of two things:
Figure 12: When you double click on a the button control, or choose the actionPerformed event in the inspector, the designer is closed and you are placed in the editor.
The following lines of code should be visible:
void button1_actionPerformed(ActionEvent e)
{
}
This is the part of your code that will be called when the user clicks on the button. Now it is up to you to define the event that will occur as a result of the user's action.
Change the above method so that it looks like this:
void button1_actionPerformed(ActionEvent e)
{
button1.setLabel("JavaButton");
}
This line of code will set button1's label to the word "JavaButton." To see this happen at run time, you need to start the application again by pressing the green button. When your applet loads, press button1 with the mouse. The caption on the button should change to the word "JavaButton," as shown in Figure 13.
Figure 13: Your application at runtime. (Screenshot taken in Windows)
In Figure 12, you can also see the beginning of the declaration of another class, called an adaptor. This class was created automatically by the IDE when you double clicked on the button in the form designer. Without this class, or something similar to it, your event handling would not work correctly at run time.
Back in Chapter 1, when I talked about configuring your environment, I said that you could use standard adaptors or anonymous adaptors. I told you then that I like to use standard adaptors. If you chose to do the same, then your code should look like mine. If you took the other path, then your action performed code will look the same as mine, but the adaptor itself will be handled differently.
For now, I don't want to say any more than this about adaptors. I will handle events in later chapters, and at that point in time I will explain all about adaptors and other mechanisms for handling events.
As I mentioned earlier, you probably don't want to import swing into your Applet. The reason you don't want to do this is that most systems that have Java aware browsers don't have support for swing. Swing first appeared in JDK 1.1.7, and most browsers support no more than JDK 1.1.1.
This does not mean that these browsers won't run applets compiled under 1.2.2, only that they won't run them if you are using features that were not present in JDK 1.1.1. So you can use JBuilder and JDK 1.2.2 to create your applets, just don't use features that were part of any version of the JDK later than 1.1.1.
The process of numbering the various versions of the JDK is a bit confusing. The JDK releases are divided into 1.0, 1.1, and 1.2. However, certain sub-releases of 1.0, 1.1, and 1.2 have become particularly important. For instance, version 1.0.2, is well known, as is 1.1.1, and 1.1.7. JBuilder Foundation, version 3.0, works with 1.2.2.
Just to add to the confusion, Java 1.2.2 is now officially referred to by Sun as Java 2. For instance, here is one way that sun refers to this release of Java : "The JavaTM 2 SDK, Standard Edition, v 1.2.2...."
There are now two editions of Java, the Standard Edition, and the Enterprise Addition. What you need right now is the Standard Edition. The Enterprise Edition adds additional features such as Servlets, EJB and Java Server Pages (JSP). The opening 10 or 15 chapters of this text will focus on the standard features. Advanced Enterprise features may be included in later chapters of this text.
The version number 1.2.2 has not gone away. It is still part of the official name of the product. It just happens that Sun is calling versions 1.2.X of Java by the name Java 2. This does not mean that versions 1.1.X are now called Java 1, nor does it mean that Java 1.3 will necessarily be called Java 3.
Please remember that all these naming conventions are just the ruminations of a no-doubt overstressed marketing department. You don't have to take it too seriously, though it does help to keep up with jargon so you can understand text that you are reading. Furthermore, you can go to http://java.sun.com/products/jdk/1.2/java2.html to find out more about the Sun naming conventions for Java.
In this chapter you learned how to create a very simple Java applet. It may appear that you haven't accomplished a great deal so far, but you in fact laid the foundation on which a lot of other important work can be built. The point is to get started, and if you completed the tasks outlined in this chapter, then you have indeed made progress toward your goal of becoming a good Java programmer.
1) Drop down a few more buttons on your applet and associate different bits of text with each button. For instance, you could have one button say: "Hi, I'm button one," and the next could say: "Hi, I'm button two." It doesn't matter what the text is, the point is to get used to dropping buttons on the form and associating events with them. When you are doing an exercises like this, try to cultivate a playfull attitude. Children play games because it helps teach them how to get ready to perform adult actions. Right now you can play with JBuilder, because it will help prepare the way for you when it is time to take on more serious projects. And don't worry, the serious projects will come along soon enough. Take the time to play some now, so that you can lay the proper foundation for the more serious work to come.
2) Practice creating new applets by repeat the steps outlined in this chapter. Change the name of each of your projects by appending a number to it. Call the first project MyFirstProject, the second MyFirstProject2, the third MyFirstProject3, etc. The point of this exercise is simply to get used to creating projects. Follow all the steps outlined in this chapter until you can do them all without effort. The act of creating an applet with a button and an associated event should be intuitive and easy. Again, this is a form of play, but it has a serious purpose. You need to be able to easily go through the basic steps of creating an applet. Also, you need to get over any fear you may have about creating applets or about working in the JBuilder environment. This is your playground, your work area. Its your virtual office, the place where you belong, and you need to take ownership of it. To do that, you should first become familiar with the tools by performing basic actions over and over until you begin to establish a comfortable, easy raport with the JBuilder programming environment.
Return to the Java Madness index.