To include an inset, override the insets() method in your class (your Applet class or other class that serves as a panel). Inside the insets() method, create a new Insets object, where the constructor to the Insets class takes four integer values representing the insets on the top, left, bottom, and right of the panel. The insets() method should then return that Insets object. Here's some code to add insets for a grid layout, 10 to the top and bottom, and 30 to the left and right. (Figure 13.20 shows the inset):
public Insets insets() {
return new Insets(10, 30, 10, 30);
}
The arguments to the Insets constructor provide pixel insets for the top, bottom, left, and right edges of the panel, respectively. This particular example provides an inset of 10 pixels on all four sides of the panel.
Handling UI Actions and Events
If you stopped reading today's lesson right now, you could go out and create an applet that had lots of little UI components, nicely laid out on the screen with the proper layout manager, gap, and insets. If you did stop right here, however, your applet would be really dull, because none of your UI components would actually do anything when they were pressed, typed into, or selected.
For your UI components to do something when they are activated, you need to hook up the UI's action with an operation. Actions are a form of event, and testing for an action by a UI component involves event management. Everything you learned yesterday about events will come in handy here.
UI actions are events that occur when a UI component is activated-pressed, selected, typed into, and so on.
To intercept an action event generated by any UI component, you define an action() method in your applet or class:
public boolean action(Event evt, Object arg) {
...
}
The action() method should look similar to the basic mouse and keyboard event methods. Like those methods, it gets passed the event object that represents this event. It also gets an extra object (in this code, the parameter arg), which can be of any class type.
What kind of object that second argument to the action method is depends on the UI component that's generating the action. The basic definition is that it's any arbitrary argument-when a component generates an event, it can pass along any extra information that might be useful for you to use in processing that action.
All the basic UI components (except for labels, which have no action) have different actions and arguments:
- Buttons create actions when they are pressed and released with the mouse, and a button's extra argument is the label string of that button.
- Check boxes, both exclusive and nonexclusive, generate actions when a box is checked. The extra argument is always true.
- Choice menus generate an action when a menu item is selected, and the extra argument is the label string of that item.
- Text fields create actions when the user presses Return or Enter inside that text field. Note that if the user tabs to a different text field or uses the mouse to change the input focus, an action is not generated. Pressing Return or Enter is the only thing that triggers the action.
Note that with actions, unlike with ordinary events, you can have many different kinds of objects generating the action event, as opposed to a single movement (a mouse press) generating a single event (such as a mouseDown). To deal with those different UI components and the actions they generate, you have to test for the type of object that sent/created the event in the first place inside the body of your action() method. That object is stored in the event's target instance variable, and you can use the instanceof operator to find out what kind of UI component sent it:
public boolean action(Event evt, Object arg) {
if (evt.target instanceof TextField)
return handleText(evt.target);
else if (evt.target instanceof Choice)
return handleChoice(arg);
...
}
Although you can handle UI actions in the body of the action() method, it's much more common simply to define a special method in your action() method and call that method instead. Here, there are two special methods: one to handle the action on the text field (handleText()) and one to handle the action on the choice menu (handleChoice()). Depending on the action you want to handle, you may also want to pass on the argument from the action, the UI component that sent it, or any other information that the event might contain.
As with the other event methods, action() returns a boolean value. As with all the event methods, you should return true if action() itself deals with the method, or false if it passes the method on somewhere else (or ignores it).
Listing 13.2 shows a simple applet that has five buttons labeled with colors. The action() method tests for a button action and then passes control to a method called changeColor(), which changes the background color of the applet based on which button was pressed (see Figure 13.21 to see the applet in action).
Figure 13.21: The ButtonAction
applet.
Listing 13.2. The ButtonActionsTest applet.
1:import java.awt.*;
2:
3:public class ButtonActionsTest extends java.applet.Applet {
4:
5: public void init() {
6: setBackground(Color.white);
7:
8: add(new Button("Red"));
9: add(new Button("Blue"));
10: add(new Button("Green"));
11: add(new Button("White"));
12: add(new Button("Black"));
13: }
14:
15: public boolean action(Event evt, Object arg) {
16: if (evt.target instanceof Button) {
17: changeColor((String)arg);
18: return true;
19: } else return false;
20: }
21:
22: void changeColor(String bname) {
23: if (bname.equals("Red")) setBackground(Color.red);
24: else if (bname.equals("Blue")) setBackground(Color.blue);
25: else if (bname.equals("Green")) setBackground(Color.green);
26: else if (bname.equals("White")) setBackground(Color.white);
27: else setBackground(Color.black);
28:
29: repaint();
30: }
31:}
As with most awt-based applets, this one starts with an init() method that initializes the applet's state and creates and adds components to the layout. The init() method defined in lines 8 through 13 here sets the applet's background color to white and creates five new buttons with color labels. Here we'll use the default layout manager, which is a FlowLayout. The buttons will appear all in a row at the top of the screen.
With the buttons in place, the second step is to attach actions to those buttons. The action() method, defined in lines 15 through 20, does this. The first thing to check is to make sure it's a button action that's been generated (line 16) and, if so, to pass the extra argument (cast to a string) to the changeColor() method, which will do all the work to change the color. If the event is indeed a button action, we'll return true to intercept that event. Otherwise, we'll return false and let some other component handle the event.
The changeColor() method is where all the work goes on. Here we test for each of the button labels in turn to see which button it was that was pressed and to set the background to the appropriate color. A final repaint at the end does the actual change (setting the background color does not automatically trigger a repaint; you'll have to do it yourself).
Nesting Panels and Components
Adding UI components to individual panels or applets is fun, but working with the awt begins to turn into lots of fun when you start working with nested panels. By nesting different panels inside your applet, and panels inside those panels, you can create different layouts for different parts of the overall applet area, isolate background and foreground colors and fonts to individual parts of an applet, and manage the design of your UI components individually and in distinct groups. The more complex the layout of your applet, the more likely you're going to want to use nested panels.
Nested Panels
Panels, as you've already learned, are components that can be actually displayed onscreen; Panel's superclass Container provides the generic behavior for holding other components inside it. The Applet class, from which your applets all inherit, is a subclass of Panel. To nest other panels inside an applet, you merely create a new panel and add it to the applet, just as you would add any other UI component:
setLayout(new GridLayout(1, 2, 10, 10)); Panel panel1 = new Panel(); Panel panel2 = new Panel(); add(panel1); add(panel2);
You can then set up an independent layout for those subpanels and add awt components to them (including still more subpanels) by calling the add() method in the appropriate panel:
panel1.setLayout(new FlowLayout());
panel1.add(new Button("Up"));
panel1.add(new Button("Down"));
Although you can do all this in a single class, it's common in graphical applets and applications that make heavy use of subpanels to factor out the layout and behavior of the subpanels into separate classes and to communicate between the panels by using methods. You'll look at an extensive example of this later in today's lesson in the section "A Complete Example: RGB-to-HSB Converter."
Events and Nested Panels
When you create applets with nested panels, those panels form a hierarchy from the outermost panel (the applet, usually) to the innermost UI component. This hierarchy is important to how each component in the interface interacts with other components; for example, the component hierarchy determines the order in which those components are painted to the screen.
More importantly, however, the hierarchy also affects event handling, particularly for user-input events such as mouse and keyboard events.
Events are received by the innermost component in the component hierarchy and passed up the chain to the applet's panel (or to the root window in Java applications). Suppose, for example, that you have an applet with a subpanel that can handle mouse events (using the mouseDown() and mouseUp() methods), and that panel contains a button. Clicking the button means that the button receives the event before the panel does; if the button isn't interested in that mouseDown(), the event gets passed to the panel, which can then process it or pass it further up the hierarchy.
Remember the discussion about the basic event methods yesterday? You learned that the basic event methods all return boolean values. Those boolean values become important when you're talking about handling events or passing them on.
An event-handling method, whether it is the set of basic event methods or the more generic handleEvent(), can do one of three things, given any random event:
- Ignore the event entirely, if the event doesn't match whatever criteria the event-handling method set-for example, the mouseDown wasn't in the right area, or the action wasn't a button action. If this is the case, the event handler should return false so the event is passed up the hierarchy until a component processes it (or it is ignored altogether).
- Intercept the event, process it, and return true. In this case, the event stops with that event method.
- Intercept the method, process it, and pass it on to another, more specific event handler-for example, as handleEvent passes events onto mouseDown().
More UI Components
After you master the basic UI components and how to add them to panels, organize their layout, and manage their events, you can add more UI components. In this section, you'll learn about text areas, scrolling lists, scrollbars, and canvases.
Note that most of the components in this section do not produce actions, so you can't use the action() method to handle their behavior. Instead, you have to use a generic handleEvent() method to test for specific events that these UI components generate. You'll learn more about this in the next section.
Text Areas
Text areas are like text fields, except they have more functionality for handling large amounts of text. Because text fields are limited in size and don't scroll, they are better for one-line responses and simple data entry; text areas can be any given width and height and have scrollbars by default, so you can deal with larger amounts of text more easily.
Text areas are larger, scrollable text-entry components. Whereas text fields only provide one line of text, text areas can hold any amount of editable text.
To create a text area, use one of the following constructors:
- TextArea() creates an empty text area 0 rows long and 0 characters wide (the text area will be automatically resized based on the layout manager).
- TextArea(int, int) creates an empty text area with the given number of rows and columns (characters).
- TextArea(String) creates a text area displaying the given string, which will be sized according to the current layout manager.
- TextArea(String, int, int) creates a text area displaying the given string and with the given dimensions.
Figure 13.22 shows a simple text area generated from the following code:
import java.awt.*;
public class TextAreaTest extends java.applet.Applet {
public void init() {
String str = "Once upon a midnight dreary, while I pondered, weak and weary,\n" +
"Over many a quaint and curious volume of forgotten lore,\n" +
"While I nodded, nearly napping, suddenly there came a tapping,\n" +
"As of some one gently rapping, rapping at my chamber door.\n" +
"\"'Tis some visitor,\" I muttered, \"tapping at my chamber door-\n" +
"Only this, and nothing more.\"\n\n";
// more text deleted for space
add(new TextArea(str,10,50));
}
}
Both text areas and text fields inherit from the TextComponent
class, so a lot of the behavior for text fields (particularly
getting and setting text and selections) is usable on text areas
as well (refer to Table 13.4). Text areas also have a number of
their own methods that you may find useful. Table 13.5 shows a
sampling of those methods.
| Method | Action |
| getColumns() | Returns the width of the text area, in characters or columns |
| getRows() | Returns the number of rows in the text area (not the number of rows of text that the text area contains) |
| insertText(String, int) | Inserts the string at the given position in the text (text positions start at 0) |
| replaceText(String, int, int) | Replaces the text between the given integer positions with the new string |
Scrolling Lists
Remember the choice menu, with which you could choose one of several different options? A scrolling list is functionally similar to a choice menu in that it lets you pick several options from a list, but scrolling lists differ in two significant ways:
- Scrolling lists are not pop-up menus. They're displayed as a list of items from which you can choose one or more items. If the number of items is larger than the list box, a scrollbar is automatically provided so that you can see the other items.
- You can choose more than one item in the list (if the list has been defined to allow it).
Scrolling lists provide a menu of items that can be selected or deselected. Unlike choice menus, scrolling lists are not pop-up menus and can be defined to allow multiple selections.
To create a scrolling list, create an instance of the List class and then add individual items to that list. The List class has two constructors:
- List() creates an empty scrolling list that enables only one selection at a time.
- List(int, boolean) creates a scrolling list with the given number of visible lines on the screen (you're unlimited as to the number of actual items you can add to the list). The boolean argument indicates whether this list enables multiple selections (true) or not (false).
After creating a List object, add items to it using the addItem() method and then add the list itself to the panel that contains it. Here's an example that creates a list five items high that allows multiple selections (the result of this code is shown in Figure 13.23):
Figure 13.23: A scrolling list.
import java.awt.*;
public class ListsTest extends java.applet.Applet {
public void init() {
List lst = new List(5, true);
lst.addItem("Hamlet");
lst.addItem("Claudius");
lst.addItem("Gertrude");
lst.addItem("Polonius");
lst.addItem("Horatio");
lst.addItem("Laertes");
lst.addItem("Ophelia");
add(lst);
}
}
Scrolling lists generate actions when the user double-clicks a list item (single-clicking generates a LIST_SELECT or LIST_DESELECT event ID; you'll learn more about these in the section "More UI Events"). A scrolling list action has the argument of the string of the item that was double-clicked.
Table 13.6 shows some of the methods available to scrolling lists.
See the API documentation for a complete set.
| Method | Action |
| getItem(int) | Returns the string item at the given position |
| countItems() | Returns the number of items in the menu |
| getSelectedIndex() | Returns the index position of the item that's selected (used for lists that allow only single selections) |
| getSelectedIndexes() | Returns an array of index positions (used for lists that allow multiple selections) |
| getSelectedItem() | Returns the currently selected item as a string |
| getSelectedItems() | Returns an array of strings containing all the selected items |
| select(int) | Selects the item at the given position |
| select(String) | Selects the item with that string |
Scrollbars and Sliders
Text areas and scrolling lists come with their own scrollbars, which are built into those UI components and enable you to manage both the body of the area or the list and its scrollbar as a single unit. You can also create individual scrollbars, or sliders, to manipulate a range of values.
Scrollbars are used to select a value between a maximum and a minimum value. To change the current value of that scrollbar, you can use three different parts of the scrollbar (seeFigure 13.24):
Figure 13.24: Scrollbar parts.
- Arrows on either end, which increment or decrement the values by some small unit (1 by default).
- A range in the middle, which increments or decrements the value by a larger amount (10 by default).
- A box in the middle, often called an elevator or thumb, whose position shows where in the range of values the current value is located. Moving this box with the mouse causes an absolute change in the value, based on the position of the box within the scrollbar.
Choosing any of these visual elements causes a change in the scrollbar's value; you don't have to update anything or handle any events. All you have to do is give the scrollbar a maximum and minimum, and Java will handle the rest.
A scrollbar is a visual UI element that allows you to choose a value between some minimum and some maximum. Scrollbars are sometimes called sliders.
To create a scrollbar, you can use one of three constructors:
- Scrollbar() creates a scrollbar with its initial maximum and minimum values both 0, in a vertical orientation.
- Scrollbar(int) creates a scrollbar with its initial maximum and minimum values both 0. The argument represents an orientation, for which you can use the class variables Scrollbar.HORIZONTAL and Scrollbar.VERTICAL.
- Scrollbar(int, int, int, int, int) creates a scrollbar with the following arguments (each one is an integer, and they must be presented in this order):
- The first argument is the orientation of the scrollbar: Scrollbar.HORIZONTAL and Scrollbar.VERTICAL.
- The second argument is the initial value of the scrollbar, which should be a value between the scrollbar's maximum and minimum values.
- The third argument is the overall width (or height, depending on the orientation) of the scrollbar's box. In user-interface design, a larger box implies that a larger amount of the total range is currently showing (applies best to things such as windows and text areas).
- The fourth and fifth arguments are the minimum and maximum values for the scrollbar.
Here's a simple example of a scrollbar that increments a single value (see Figure 13.25). The label to the left of the scrollbar is updated each time the scrollbar's value changes:
import java.awt.*;
public class SliderTest extends java.applet.Applet {
Label l;
public void init() {
setLayout(new GridLayout(1,2));
l = new Label("0", Label.CENTER);
add(l);
add(new Scrollbar(Scrollbar.HORIZONTAL,0,0,1,100));
}
public Insets insets() {
return new Insets(15,15,15,15);
}
public boolean handleEvent(Event evt) {
if (evt.target instanceof Scrollbar) {
int v = ((Scrollbar)evt.target).getValue();
l.setText(String.valueOf(v));
repaint();
return true;
} else return false;
}
}
The Scrollbar class provides
several methods for managing the values within scrollbars. (See
Table 13.7.)
| Method | Action |
| getMaximum() | Returns the maximum value. |
| getMinimum() | Returns the minimum value. |
| getOrientation() | Returns the orientation of this scrollbar:
0 is Scrollbar.HORIZONTAL; 1 is Scrollbar.VERTICAL. |
| getValue() | Returns the scrollbar's current value. |
| setValue(int) | Sets the current value of the scrollbar. |
| setLineIncrement(int inc) | Change the increment for how far to scroll when the endpoints of the scrollbar are selected. The default is 1. |
| getLineIncrement() | Returns the increment for how far to scroll when the endpoints of the scrollbar are selected. |
| setPageIncrement(int inc) | Change the increment for how far to scroll when the inside range of the scrollbar is selected. The default is 10. |
| getPageIncrement() | Returns the increment for how far to scroll when the inside range of the scrollbar is selected. |
Canvases
Although you can draw on most awt components such as panels using the graphics methods you learned about on Day 11, "More Animation, Images, and Sound," canvases do little except let you draw on them. They can't contain other components, but they can accept events, and you can create animation and display images on them. If you have a panel that doesn't need to do anything except display images or animation, a canvas would make a lighter-weight surface than a panel would.
A canvas is a component that you can draw on.
To create a canvas, use the Canvas class and add it to a panel as you would any other component:
Canvas can = new Canvas(); add(can);
More UI Events
Yesterday, you learned about some basic event types that are generated from user input to the mouse or the keyboard. These event types are stored in the Event object as the event ID, and can be tested for in the body of a handleEvent() method by using class variables defined in Event. For many basic events, such as mouseDown() and keyDown(), you can define methods for those events to handle the event directly. You learned a similar mechanism today for UI actions where creating an action() method handled a specific action generated by a UI component.
The most general way of managing events, however, continues to be the handleEvent() method. For events relating to scrollbars and scrolling lists, the only way to intercept these events is to override handleEvent().
To intercept a specific event, test for that event's ID. The available
IDs are defined as class variables in the Event
class, so you can test them by name. You learned about some of
the basic events yesterday; Table 13.8 shows additional events
that may be useful to you for the components you've learned about
today (or that you might find useful in general).
| Event ID | What It Represents |
| ACTION_EVENT | Generated when a UI component action occurs |
| GOT_FOCUS | Generated when the user clicks inside a text area |
| LOST_FOCUS | Generated when the user clicks anywhere outside a text area (after being inside one) |
| LIST_DESELECT | Generated when an item in a scrolling list is deselected |
| LIST_SELECT | Generated when an item in a scrolling list is selected |
| SCROLL_ABSOLUTE | Generated when a scrollbar's box has been moved |
| SCROLL_LINE_DOWN | Generated when a scrollbar's bottom or left endpoint (button) is selected |
| SCROLL_LINE_UP | Generated when a scrollbar's top or right endpoint (button) is selected |
| SCROLL_PAGE_DOWN | Generated when the scrollbar's field below (or to the left of) the box is selected |
| SCROLL_PAGE_UP | Generated when the scrollbar's field above (or to the right of) the box is selected |
Fun with Components
The Component class is the root of all the awt objects: all the UI elements, panels, canvases, even applets. Just about everything you can display, lay out, change the color of, draw to, or interact with using events in the awt is a component.
Components have a set of methods that allow you to modify their appearance or change their behavior. You've seen the use of a few of these methods already (setBackground(), setFont, size()), applied specifically to applets. But the methods defined in Component can be used with any component, allowing you to modify the appearance or the behavior of just about any element in your program. You can also create custom components (classes that inherit from Panel or Canvas) to make your own special awt elements or user interface widgets.
Table 13.9 summarizes some of the methods you can use with individual components. For more methods, check out the Java API documentation for the class Component. The JDK 1.0.2 documentation is online at
http://java.sun.com:80/products/JDK/CurrentRelease/api/
| getBackground() | Returns a Color object representing the component's background color. |
| setBackground(Color) | Sets the component's background color. |
| getForeground() | Returns a Color object representing the component's current foreground color. |
| setForeground(Color) | Sets the component's foreground color |
| getFont() | Returns a Font object representing the component's current font. |
| setFont(Font) | Changes the component's current font. |
| size() | Returns a Dimension object representing the component's current size. You can then get to the individual width and height using size().width() and size().height(). |
| minimumSize() | The component's smallest possible size as a Dimension object. minimumSize() is usually only used by layout managers to determine how small it can draw a component; if you create a custom component you'll want to override this method to return the minimum size of that component. |
| preferredSize() | The component's preferred size (usually equal to or larger than the component's minimumSize()) as a Dimension object. |
| resize(Dimension) | Changes the size of the applet to be the current size. For custom components you'll want to also call validate() after resizing the applet so that the layout can be redrawn. |
| inside(x, y) | Returns true if the given x and y coordinates are inside the component. |
| hide() | Hides the component. Hidden components do not show up onscreen. |
| show() | Shows a component previously hidden. |
| isVisible() | Returns true or false depending on whether this component is visible (not hidden). |
| disable() | Disables the component-that is, stops generating events. Disabled components cannot be pressed, selected from, typed into, and so on. |
| enable() | Enables a previously disabled object. |
| isEnabled() | Returns true or false depending on whether the component is enabled. |
A Complete Example: RGB-to-HSB Converter
Let's take a break here from theory and smaller examples to create a larger example that puts together much of what you've learned so far. The following applet example demonstrates layouts, nesting panels, creating user-interface components, and catching and handling actions, as well as using multiple classes to put together a single applet. In short, it's the most complex applet you've created so far.
Figure 13.26 shows the applet you'll be creating in this example. The ColorTest applet enables you to pick colors based on RGB (red, green, and blue) and HSB (hue, saturation, and brightness) values.
Figure 13.26: The ColorTest
applet.
| Note |
A very quick summary in case you're not familiar with basic color theory: RGB color defines a color by its red, green, and blue values; some combination of these values can produce any color in the spectrum (red, green, and blue are called additive colors; that's how your monitor and your TV represent different colors). HSB stands for hue, saturation, and brightness and is a different way of indicating color. Hue is the actual color in the spectrum you're representing (think of it as values along a color wheel). Saturation is the amount of that color; low saturation results in pastels; high-saturation colors are more vibrant and "colorful." Brightness, finally, is the lightness or darkness of the color. No brightness is black; full brightness is white. A single color can be represented either by its RGB values or by its HSB values, and there are mathematical algorithms to convert between them. The ColorTest applet provides a graphical converter between the two. |
The ColorTest applet has
three main parts: a colored box on the left side and two groups
of text fields on the right. The first group indicates RGB values;
the right, HSB. By changing any of the values in any of the text
boxes, the colored box is updated to the new color, as are the
values in the other group of text boxes.
| Note |
If you try this applet, be aware that you have to press Enter or Return after changing a number for the updating to occur. Using the Tab key to move between text fields or clicking with the mouse will not cause the applet to update. |
This applet uses two classes:
- ColorTest, which inherits from Applet. This is the controlling class for the applet itself.
- ColorControls, which inherits from Panel. You'll create this class to represent a group of three text fields and to handle actions from those text fields. Two instances of this class, one for the RGB values and one for the HSB ones, will be created and added to the applet.
Let's work through this step by step, because it's very complicated and can get confusing. All the code for this applet will be shown at the end of this section.
Designing and Creating the Applet Layout
The best way to start creating an applet that uses awt components is to worry about the layout first and then worry about the functionality. When dealing with the layout, you should start with the outermost panel first and work inward.
Making a sketch of your UI design can help you figure out how to organize the panels inside your applet or window to best take advantage of layout and space. Paper designs are helpful even when you're not using grid bag layouts, but doubly so when you are (we'll be using a simple grid layout for this applet).
Figure 13.27 shows the ColorTest applet with a grid drawn over it so that you can get an idea of how the panels and embedded panels work.
Figure 13.27: The ColorTest applet panels and components.
Let's start with the outermost panel-the applet itself. This panel has three parts: the color box on the left, the RGB text fields in the middle, and the HSB fields on the right.
Because the outermost panel is the applet itself, your ColorTest class will be the applet class and will inherit from Applet. You'll also import the awt classes here (note that because you use so many of them in this program, it's easiest to just import the entire package):
import java.awt.*;
public class ColorTest extends java.applet.Applet {
...
}
This applet has three main things to keep track of: the color box and the two subpanels. The two subpanels each refer to different things, but they're essentially the same panel and behave in the same ways. Rather than duplicate a lot of code here in this class, this is a perfect opportunity to create another class just for the subpanels, use instances of that class here in the applet, and communicate between everything using methods. In a bit we'll define that new class, called ColorControls.
For now, however, we know we need to keep a handle to all three parts of the applet so you can update them when they change. So let's create three instance variables: one of type Canvas for the color box, and the other two of type ColorControls for the control panels:
ColorControls RGBcontrols, HSBcontrols; Canvas swatch;
Now we'll move onto the init() method, where all the basic initialization and layout of the applet takes place. There are three steps to initializing this applet:
- Create the layout for the big parts of the panel. Although a flow layout would work, a grid layout with one row and three columns is a much better idea.
- Create and initialize the three components of this applet: a canvas for the color box and two subpanels for the text fields.
- Add those components to the applet.
Step one is the layout. Let's use a grid layout and a gap of 10 points to separate each of the components:
setLayout(new GridLayout(1, 3, 5, 15));
Step two is creating the components-the canvas first. You have an instance variable to hold that one. Here we'll create the canvas and initialize its background to black:
swatch = new Canvas(); swatch.setBackground(Color.black);
You need to create two instances of your as-of-yet nonexistent ColorControls panels here as well, but because we haven't created the class yet we don't know what the constructors to that class will look like. Let's put in some placeholder constructors here; we'll fill in the details later:
RGBcontrols = new ColorControls(...) HSBcontrols = new ColorControls(...);
Step three is adding all three components to the applet panel:
add(swatch); add(RGBcontrols); add(HSBcontrols);
While you're working on layout, let's add insets for the applet: 10 points along all the edges:
public Insets insets() {
return new Insets(10, 10, 10, 10);
}
Got it so far? At this point you have three instance variables, an init() method with two incomplete constructors, and an insets() method in your ColorTest class. Let's move on now to creating the subpanel layout in the ColorControls class so we can fill in those constructors and finish up the layout.
Defining the Subpanels
The ColorControls class will have behavior for laying out and handling the subpanels that represent the RGB and HSB values for the color. ColorControls doesn't need to be a subclass of Applet because it isn't actually an applet; it's just a panel. Define it to inherit from Panel:
import java.awt.*
class ColorControls extends Panel {
...
}
| Note |
I've put the ColorControls source code into its own file, called ColorControls.java. However, you can put the ColorControls class in the same file as the ColorTest class. Up to this point, you've only defined one class per file, with the filename the same name as the class. In Java you can have multiple class definitions in a file as long as only one of those classes is declared public (and the name of the source file is the same as that public class). In this case, the ColorTest class is public (it's an applet, so it has to be), but the ColorControls class isn't public, so it can be in the same source file. When you compile the file, Java will create the appropriate multiple class files for each class definition. You'll learn more about public classes on Day 15, "Modifiers, Access Control, and Class Design," and Day 16, "Packages and Interfaces." In general, however, I prefer to use separate source files for my classes. It makes it easier for me to find the source for a particular class because I don't have to remember which file I defined it in. |
The ColorControls class will need a number of instance variables so that information from the panel can get back to the applet. The first of these instance variables is a hook back up to the applet class that contains this panel. Because it's the outer applet class that controls the updating of each panel, this panel will need a way to tell the applet that something has changed. And to call a method in that applet, you need a reference to that object. So, instance variable number one is a reference an instance of the class ColorTest:
ColorTest applet;
If you figure that the applet class is the one that's going to be updating everything, that class if going to be interested in the individual text fields in this subpanel. We'll create instance variables for those text fields:
TextField tfield1, tfield2, tfield3;
Now let's move on to the constructor for this class. Because this class isn't an applet, we won't use init() to initialize it; instead we'll use a constructor method.
Inside the constructor you'll do much of what you did inside init(): create the layout for the subpanel, create the text fields, and add them to the panel.
The goal here is to make the ColorControls class generic enough so that you can use it for both the RGB fields and the HSB fields. Those two panels differ in only one respect: the labels for the text. That's three values to get before you can create the object. You can pass those three values in through the constructors in ColorTest. You also need one more: that reference to the enclosing applet, which you can get from the constructor as well.
You now have four arguments to the basic constructor for the ColorControls class. Here's the signature for that constructor:
ColorControls(ColorTest parent,
String l1, String l2, String l3) {
}
Let's start this constructor by first setting the value of parent to the applet instance variable:
applet = parent;
Next, create the layout for this panel. You can also use a grid layout for these subpanels, as you did for the applet panel, but this time the grid will have three rows (one for each of the text field and label pairs) and two columns (one for the labels and one for the fields). We'll also define a 10-point gap between the components in the grid:
setLayout(new GridLayout(3,2,10,10));
Now we can create and add the components to the panel. First, we'll create the text field objects (initialized to the string "0"), and assign them to the appropriate instance variables:
tfield1 = new TextField("0");
tfield2 = new TextField("0");
tfield3 = new TextField("0");
Now we'll add those fields and the appropriate labels to the panel, using the remaining three parameters to the constructor as the text for the labels:
add(new Label(l1, Label.RIGHT)); add(tfield1); add(new Label(l2, Label.RIGHT)); add(tfield2); add(new Label(l3, Label.RIGHT)); add(tfield3);
That finishes up the constructor for the subpanel class ColorControls. Are we done with the layout? Not quite. We'll also add an inset around the subpanel-only on the top and bottom edges-to tinker the layout. Add the inset here as you did in the ColorTest class, using the insets() method:
public Insets insets() {
return new Insets(10, 10, 0, 0);
}
You're almost there. You have 98 percent of the basic structure in place and ready to go, but there's one step left: going back to ColorTest and fixing those placeholder constructors for the subpanel so they match the actual constructors for ColorControls.
The constructor for ColorControls that we just created now has four arguments: the ColorTest object and three labels (strings). Remember back to when we created the init() method for ColorTest: We added two placeholders for creating new ColorControls objects; we'll replace those placeholders with the correct versions now. Make sure you add the four arguments that constructor needs to work: the ColorTest object and three strings. To pass the ColorTest object to those constructors, we can use the this keyword:
RGBcontrols = new ColorControls(this, "Red", "Green", "Blue"); HSBcontrols = new ColorControls(this, "Hue", "Saturation", "Brightness");
| Note |
For the initial values of all the text fields in this example, I used the number 0 (actually, the string "0"). For the color black, both the RGB and the HSB values are 0, which is why I can make this assumption. If you wanted to initialize the applet to be some other color, you might want to rewrite the ColorControls class to use initializer values as well as to initialize labels. This way made for a shorter example. |
Handling the Actions
With the layout done, its time to set up event handling and updating between the various components so that when the user interacts with the applet, the applet can respond.
The action of this applet occurs when the user changes a value in any of the text fields and presses Enter. By causing an action in a text field, the color changes, the color box updates to the new color, and the values of the fields in the opposite subpanel change to reflect the new color.
The ColorTest class is responsible for actually doing the updating because it keeps track of all the subpanels. Because the actual event occurs in the subpanel, however, you'll need to track and intercept those events in that subpanel using the action() method in the ColorControls class:
public boolean action(Event evt, Object arg) {
if (evt.target instanceof TextField) {
applet.update(this);
return true;
}
else return false;
}
In the action() method, you test to make sure the action was indeed generated by a text field (because there are only text fields available, that's the only action you'll get, but it's a good idea to test for it anyhow). If there was indeed a text field action, we'll call a method to update all the subpanels. That method, which we'll call update(), is defined in the enclosing class, so we'll call it using the object stored in the applet instance variable (and pass along a reference to the panel so that the applet can get at our values). And, finally, we'll return either true or false so that other actions that might occur on this applet can be passed along to enclosing panels or components.
Updating the Result
Now comes the hard part: actually doing the updating based on
the new values of whatever text field was changed. For this, you
define the update() method
in the ColorTest class. This
update() method takes a single
argument-the ColorControls
instance that contains the changed value (you get that argument
from the action() method
in the ColorControls object).
| Note |
Won't this update() method interfere with the system's update() method? Nope. Remember, methods can have the same name, but different signatures and definitions. Because this update() has a single argument of type ColorControls, it doesn't interfere with the other version of update(). Normally, all methods called update() should mean basically the same thing; it's not true here, but it's only an example. |
The update() method is responsible for updating all the panels in the applet. To know which panel to update, you need to know which panel changed. You can find out by testing to see whether the argument you got passed from the panel is the same as the subpanels you have stored in the RGBcontrols and HSBcontrols instance variables:
void update(ColorControls controlPanel) {
if (controlPanel == RGBcontrols) { // RGB has changed, update HSB
...
} else { // HSB has changed, update RGB
...
}
}
This test is the heart of the update() method. Let's start with that first case-a number has been changed in the RGB text fields. So now, based on those new RGB values, you have to generate a new Color object and update the values on the HSB panel. To reduce some typing, you create a few local variables to hold some basic values. In particular, the values of the text fields are strings whose values you can get to using the getText() method defined in the TextField objects of the ColorControls object. Because most of the time in this method we'll want to deal with those values as integers, we'll get those string values, convert them to integers, and store them in local variables (value1, value2, value3). Here's the code to do this (it looks more complicated than it actually is):
int value1 = Integer.parseInt(controlPanel.tfield1.getText()); int value2 = Integer.parseInt(controlPanel.tfield2.getText()); int value3 = Integer.parseInt(controlPanel.tfield3.getText());
While we're here defining local variables, we'll also need one for the new Color object:
Color c;
OK. Let's assume one of the text fields in the RGB side of the applet has changed and add the code to the if part of the update() method. We'll need to create a new Color object and update the HSB side of the panel. That first part is easy; given the three RGB values, you can create a new Color object using those as arguments to the constructor:
c = new Color(value1, value2, value3);
| Note |
This part of the example isn't very robust; it assumes that the user has indeed entered integers from 0 to 255 into the text fields. A better version of this would test to make sure that no data-entry errors had occurred (I was trying to keep this example small). |
Now we'll convert the RGB values to HSB. There are standard algorithms to convert an RGB-based color to an HSB color, but we don't have to go look them up. The Color class has a class method we can use called RGBtoHSB() that will do the work for us-or, at least, most of it. There are two problems with the RGBtoHSB() method, however:
- The RGBtoHSB() method returns an array of the three HSB values, so we'll have to extract those values from the array.
- The HSB values are measured in floating-point values from 0.0 to 1.0. I prefer to think of HSB values as integers, where the hue is a degree value around a color wheel (0 through 360), and saturation and brightness are percentages from 0 to 100.
Neither of these problems is insurmountable; it just means some extra lines of code. Let's start by calling RGBtoHSB() with the new RGB values we have. The return type of that method is an array of floats, so we'll create a local variable (HSB) to store the results of the RBGtoHSB() method. (Note that you'll also need to create and pass in an empty array of floats as the fourth argument to RGBtoHSB()):
float[] HSB = Color.RGBtoHSB(value1, value2, value3, (new float[3]));
Now we'll convert those floating-point values that range from 0.0 to 1.0 to values that range from 0 and 100 (for the saturation and brightness) and 0 to 360 for the hue by multiplying the appropriate numbers and reassigning the value back to the array:
HSB[0] *= 360; HSB[1] *= 100; HSB[2] *= 100;
Now we have the numbers we want. The last part of the update is to put those values back into the text fields. Of course, those values are still floating-point numbers, so we'll have to cast them to ints before turning them into strings and storing them:
HSBcontrols.tfield1.setText(String.valueOf((int)HSB[0])); HSBcontrols.tfield2.setText(String.valueOf((int)HSB[1])); HSBcontrols.tfield3.setText(String.valueOf((int)HSB[2]));
You're halfway there. The next part of the applet is that part that updates the RGB values where a text field on the HSB side has changed. This is the else in the big if-else that defines this method and determines what to update, given a change.
It's actually easier to generate values from HSB values than it is to do it the other way around. There's a class method in the Color class, called getHSBColor(), that creates a new Color object from three HSB values, and once you have a Color object you can easily pull the RGB values out of there. The catch, of course, is that getHSBColor takes three floating-point arguments, and the values we have are the integer values I prefer to use. So in the call to getHSBColor, we'll have to cast the integer values from the text fields to floats and divide them by the proper conversion factor. The result of getHSBColor is a Color object, so we can simply assign that object to our c local variable so we can use it again later:
c = Color.getHSBColor((float)value1 / 360,
(float)value2 / 100, (float)value3 / 100);
With the Color object all set, updating the RGB values involves extracting those values from that Color object. The getRed(), getGreen() and getBlue() methods, defined in the Color class, will do just that:
RGBcontrols.tfield1.setText(String.valueOf(c.getRed())); RGBcontrols.tfield2.setText(String.valueOf(c.getGreen())); RGBcontrols.tfield3.setText(String.valueOf(c.getBlue()));
And finally, regardless of whether the RGB or HSB value has changed, you'll need to update the color box on the left to reflect the new color. Because we have a new Color object stored in the variable c, we can use the setBackground method to change that color. Also note that setBackground doesn't automatically repaint the screen, so you'll want to fire off a repaint() as well:
swatch.setBackground(c); swatch.repaint();
That's it! You're done. Compile both the ColorTest and ColorControls classes, create an HTML file to load the ColorTest applet, and check it out.
The Complete Source Code
Listing 13.3 shows the complete source code for the applet class ColorTest, and Listing 13.4 shows the source for the helper class ColorControls. Often it's easier to figure out what's going on in an applet when it's all in one place and you can follow the method calls and how values are passed back and forth. Start with the init() method in the ColorTest applet and go from there.
Listing 13.3. The ColorTest applet.
1:import java.awt.*;
2:
3:public class ColorTest extends java.applet.Applet {
4: ColorControls RGBcontrols, HSBcontrols;
5: Canvas swatch;
6:
7: public void init() {
8: setLayout(new GridLayout(1,3,5,15));
9:
10: // The color swatch
11: swatch = new Canvas();
12: swatch.setBackground(Color.black);
13:
14: // the subpanels for the controls
15: RGBcontrols = new ColorControls(this, "Red", "Green", "Blue");
16: HSBcontrols = new ColorControls(this, "Hue", "Saturation", "Brightness");
17:
18: //add it all to the layout
19: add(swatch);
20: add(RGBcontrols);
21: add(HSBcontrols);
22: }
23:
24: public Insets insets() {
25: return new Insets(10,10,10,10);
26: }
27:
28: void update(ColorControls controlPanel) {
29: Color c;
30: // get string values from text fields, convert to ints
31: int value1 = Integer.parseInt(controlPanel.tfield1.getText());
32: int value2 = Integer.parseInt(controlPanel.tfield2.getText());
33: int value3 = Integer.parseInt(controlPanel.tfield3.getText());
34:
35: if (controlPanel == RGBcontrols) { // RGB has changed, update HSB
36: c = new Color(value1, value2, value3);
37:
38: // convert RGB values to HSB values
39: float[] HSB = Color.RGBtoHSB(value1, value2, value3, (new float[3]));
40: HSB[0] *= 360;
41: HSB[1] *= 100;
42: HSB[2] *= 100;
43:
44: // reset HSB fields
45: HSBcontrols.tfield1.setText(String.valueOf((int)HSB[0]));
46: HSBcontrols.tfield2.setText(String.valueOf((int)HSB[1]));
47: HSBcontrols.tfield3.setText(String.valueOf((int)HSB[2]));
48:
49: } else { // HSB has changed, update RGB
50: c = Color.getHSBColor((float)value1 / 360,
51: (float)value2 / 100, (float)value3 / 100);
52:
53: // reset RGB fields
54: RGBcontrols.tfield1.setText(String.valueOf(c.getRed()));
55: RGBcontrols.tfield2.setText(String.valueOf(c.getGreen()));
56: RGBcontrols.tfield3.setText(String.valueOf(c.getBlue()));
57: }
58:
59: //update swatch
60: swatch.setBackground(c);
61: swatch.repaint();
62:}
63:}
Listing 13.4. The ColorControls class.
1:import java.awt.*;
2:
3:class ColorControls extends Panel {
4: TextField tfield1, tfield2, tfield3;
5: ColorTest applet;
6:
7: ColorControls(ColorTest parent,
8: String l1, String l2, String l3) {
9:
10: // get hook to outer applet parent
11: applet = parent;
12:
13: //do layouts
14: setLayout(new GridLayout(3,2,10,10));
15:
16: tfield1 = new TextField("0");
17: tfield2 = new TextField("0");
18: tfield3 = new TextField("0");
19:
20: add(new Label(l1, Label.RIGHT));
21: add(tfield1);
22: add(new Label(l2, Label.RIGHT));
23: add(tfield2);
24: add(new Label(l3, Label.RIGHT));
25: add(tfield3);
26: }
27:
28: public Insets insets() {
29: return new Insets(10,10,0,0);
30: }
31:
32: public boolean action(Event evt, Object arg) {
33: if (evt.target instanceof TextField) {
34: applet.update(this);
35: return true;
36: } else return false;
37: }
38:}
Up and Coming in Java 1.1
Everything you've learned up to this point is available in the 1.0.2 Java API. Java 1.1, however, will add many more features to the awt, as well as improve performance and robustness across platforms. The goal for the awt is to move beyond the basics that 1.0.2 provided and make the awt more suitable for large-scale application development. Note, also, that the 1.1 API will be backward-compatible with the 1.0.2 features; none of the code you write after reading this chapter will be obsolete in 1.1.
Explicit details about the changes to the awt for 1.1 were not available at the time this book was being written. Sun has announced the following teasers, however for new features in 1.1:
- New components for pop-up menus, buttons with images on top of them, and menu accelerators
- Support for clipboard operations (copy and paste), drag and drop, and printing
- The ability to set a cursor for each component (currently you can have only one cursor per window; you'll learn about this on Day 14, "Windows, Networking, and Other Tidbits")
- A new set of graphics primitives as part of the new 2D graphics model; you'll learn more about this on Day 27, "The Standard Extension APIs"
- A new event model that delegates event actions to other objects, as opposed to requiring special methods (mouseDown(), action(), handleEvent(), and so on) to be overridden in the component classes themselves. Those action objects are often called callbacks in other event-driven programming systems.
- Performance enhancements: a complete rewrite for Windows 95 and NT, improvements in how components are laid out and painted, better scrolling of components, and a "number of bug fixes."
For more information about the Java 1.1 changes to the awt, check out the 1.1 preview page at http://java.sun.com/products/JDK/1.1/designspecs/.
Summary
The Java awt, or Abstract Windowing Toolkit, is a package of Java classes and interfaces for creating full-fledged access to a window-based graphical user interface system, with mechanisms for graphics display, event management, text and graphics primitives, user-interface components, and cross-platform layout. Applets are also an integral part of the awt.
Today has been a big day; the lesson has brought together everything you've learned up to this point about simple applet management and added a lot more about creating applets, panels, and user-interface components and managing the interactions between all of them. With the information you got today and the few bits you'll learn tomorrow, you can create cross-platform Java applications that do just about anything you want.
Q&A
| I really dislike working with layout managers; they're either too simplistic or too complicated (grid bag layout). Even with a whole lot of tinkering, I can never get my applets to look like I want them to. All I want to do is define the sizes of my components and put them at an x and y position on the screen. Can I do this? | |
| I'm going to tell you how to do this, but not without a lecture. Java applications and the awt were designed such that the same graphical user interface could run equally well on different platforms and with different resolutions, different fonts, different screen sizes, and so on. Relying on pixel coordinates in this case is a really bad idea; variations from one platform to another or even from one Java environment to another on the same platform can mess up your careful layouts such that you can easily have components overlapping or obscuring each other, the edges of your applet cut off, or other layout disasters. Just as an example-I found significant differences in the layout of the same applet running in the JDK's appletviewer and in Netscape, both on Windows 95, side by side. Can you guarantee that your applet will always be run in precisely the same environment as the one in which you designed it? Layout managers, by dynamically placing elements on the screen, get around these problems. This does mean that your applet may end up looking not quite right on any platform-but at least it's usable on any platform. New versions of the awt promise to offer better layout and UI design controls. Still not convinced? Well, then. To make a component a specific size and to place it at a particular position, use a null layout manager and the reshape() method:
setLayout(null); You can find out more about reshape() in the Component class. | |
| I was exploring the awt classes, and I saw this subpackage called peer. There are also references to the peer classes sprinkled throughout the API documentation. What do peers do? | |
| Peers are responsible for the platform-specific parts of the awt. For example, when you create a Java awt window, you have an instance of the Window class that provides generic window behavior, and then you have an instance of a class implementing WindowPeer that creates the very specific window for that platform-a motif window under X Window, a Macintosh-style window under the Macintosh, or a Windows 95 window under Windows 95. These "peer" classes also handle communication between the window system and the Java window itself. By separating the generic component behavior (the awt classes) from the actual system implementation and appearance (the peer classes), you can focus on providing behavior in your Java application and let the Java implementation deal with the platform-specific details. | |
| There's a whole lot of functionality in the awt that you haven't talked about here. Why? | |
| Given that even a basic introduction took this long, I figured that if I put in even more detail than I already have, this book would turn into Teach Yourself Java in 21 Days Plus a Few Extra for the awt Stuff. | |
| As it is, I've left windows, menus, and dialog boxes until tomorrow, so you'll have to wait for those. But you can find out about a lot of the other features of awt merely by exploring the API documentation. Start with the Applet class and examine the sorts of methods you can call. Then look at Panel, from which Applet inherits-you have all that class's functionality as well. The superclass of Panel is Container, which provides still more interesting detail. Component comes next. Explore the API and see what you can do with it. You might find something interesting. | |
| I have a new button class I defined to look different from the standard awt button objects. I'd like to implement callbacks on this button (that is, to execute an arbitrary function when the button is pressed), but I can't figure out how to get Java to execute an arbitrary method. In C++ I'd just have a pointer to a function. In Smalltalk I'd use perform:. How can I do this in Java? | |
| You can't; Java doesn't have this facility. This is why normal button actions are executed from the generic action() method rather than using a mechanism for actions attached to the button itself (which would be more object-oriented, easier to extend, and wouldn't require a whole lot of if...elses inside action()). |
