[Chapter 5] 5.6 Creating Your Own Component

5.6 Creating Your Own Component

If you find that no AWT component satisfies your needs, you can create your own. This is usually done either by extending an existing component or by starting from scratch. When extending an existing component, you start with the base functionality of an existing object and add to it. The users will not see anything new or different about the object until they start to interact with it, since it is not a new component. For example, a TextField could be subclassed to convert all letters input to uppercase. On the other hand, if you create a new component from scratch, it will appear the same on all platforms (regardless of what the platform's native components look like), and you have to make sure the user can fairly easily figure out how to work with it. Example 5.3 shows how to create your own Component by creating a Label that displays vertically, as opposed to the standard Label Component that displays horizontally. The whole process is fairly easy.

The third possibility for creating your own components involves adding functionality to containers. This is fairly easy to do and can be useful if you are constantly grouping components together. For example, if you are always adding a TextField or Label to go with a Scrollbar to display the value, do it once, and call it something meaningful like LabeledScrollbarPanel. Then whenever you need it again, reuse your LabeledScrollbarPanel. Think about reusability whenever you can.

With Java 1.1, the colors for these new components should be set to color values consistent to the user's platform. This is done through color constants provided in the SystemColor class introduced in Chapter 2, Simple Graphics.

VerticalLabel

When you create new components, they must meet three requirements:

In Java 1.0, you must extend a subclass of Component, usually Canvas. In Java 1.1, you can extend Component itself, creating a lightweight component. In many cases, this alternative is more efficient.
You must provide a constructor for the new component so that you can create new instances of it; if you really don't need a constructor, you can use the default constructor that you inherit from Canvas or Component.
You must provide a way to draw the object on the screen by overriding the paint() method.

If initializing the component requires information about display characteristics (for example, you need to know the default Font), you must wait until the object is displayed on the screen before you initialize it. This is done by overriding the addNotify() method. First, call super.addNotify() to create the peer; you can now ask for platform-dependent information and initialize your component accordingly. Remember to override getPreferredSize() and getMinimumSize() (the Java 1.0 names are preferredSize() and minimumSize()) to return the proper dimensions for the new component, so that layout management works properly. There can be other support methods, depending upon the requirements of the object. For example, it is helpful, but not required, to provide a toString() or paramString() method.

Creating a new component sounds a lot harder than it is. Example 5.3 contains the source for a new component called VerticalLabel. It displays a label that reads from top to bottom, instead of from left to right, and can be configured to display its text right or left justified or centered. Figure 5.5 displays the new component VerticalLabel in action.

Example 5.3: Source for VerticalLabel Component

import java.awt.*;
public class VerticalLabel extends Canvas {
   public static final int LEFT = 0;
   public static final int CENTER = 1;
   public static final int RIGHT = 2;
   private String text;
   private int    vgap;
   private int    alignment;
   Dimension      mySize;
   int            textLength;
   char           chars[];
   // constructors
   public VerticalLabel () {
        this (null, 0, CENTER);
   }
   public VerticalLabel (String text) {
        this (text, 0, CENTER);
   }
   public VerticalLabel (String text, int vgap, int alignment) {
      this.text = text;
      this.vgap = vgap;
      this.alignment = alignment;
   }
   void init () {
      textLength = text.length();
      chars = new char[textLength];
      text.getChars (0, textLength, chars, 0);
      Font f = getFont();
      FontMetrics fm = getFontMetrics (f);
      mySize = new Dimension(0,0);
      mySize.height = (fm.getHeight() * textLength) + (vgap * 2);
      for (int i=0; i < textLength; i++) {
          mySize.width = Math.max (mySize.width, fm.charsWidth(chars, i, 1));
      }
   }
   public int getAlignment () {
      return alignment;
   }
   public void addNotify () {
       super.addNotify();
       init();  // Component must be visible for init to work
   }
   public void setText (String text)    {this.text = text; init();}
   public String getText ()             {return text; }
   public void setVgap (int vgap)       {this.vgap = vgap; init();}
   public int getVgap ()                {return vgap; }
   public Dimension preferredSize ()    {return mySize; }
   public Dimension minimumSize ()      {return mySize; }
   public void paint (Graphics g) {
      int x,y;
      int xPositions[];
      int yPositions[];
// Must redo this each time since font/screen area might change
// Use actual width for alignment
      Font f = getFont();
      FontMetrics fm = getFontMetrics (f);
      xPositions = new int[textLength];
      for (int i=0; i < textLength; i++) {
         if (alignment == RIGHT) {
            xPositions[i] = size().width - fm.charWidth (chars[i]);
         } else if (alignment == LEFT) {
            xPositions[i] = 0;
         } else {// CENTER
            xPositions[i] = (size().width - fm.charWidth (chars[i])) / 2;
         }
      }
      yPositions = new int[textLength];
      for (int i=0; i < textLength; i++) {
         yPositions[i] = (fm.getHeight() * (i+1)) + vgap;
      }
      for (int i = 0; i < textLength; i++) {
         x = xPositions[i];
         y = yPositions[i];
         g.drawChars (chars, i, 1, x, y);
      }
   }
   protected String paramString () {
      String str=",align=";
      switch (alignment) {
         case LEFT:    str += "left"; break;
         case CENTER:  str += "center"; break;
         case RIGHT:   str += "right"; break;
      }
      if (vgap!=0) str+= ",vgap=" + vgap;
      return super.paramString() + str + ",label=" + text;
   }
}

Figure 5.5: Using VerticalLabel

[Graphic: Figure 5-5]

The following code is a simple applet using the VerticalLabel. It creates five instances of VerticalLabel within a BorderLayout panel, with gaps (see Chapter 7, Layouts for more on BorderLayout). The top and bottom labels are justified to the left and right, respectively, to demonstrate justification.

import java.awt.*;
import java.applet.*;
public class vlabels extends Applet {
   public void init () {
        setLayout (new BorderLayout (10, 10));
        setFont (new Font ("TimesRoman", Font.BOLD, 12));
        add ("North",  new VerticalLabel ("One", 10, VerticalLabel.LEFT));
        add ("South",  new VerticalLabel ("Two", 10, VerticalLabel.RIGHT));
        add ("West",   new VerticalLabel ("Three"));
        add ("East",   new VerticalLabel ("Four"));
        add ("Center", new VerticalLabel ("Five"));
        resize (preferredSize());
   }
}

Lightweight VerticalLabel

The VerticalLabel in Example 5.3 works in both Java 1.0 and 1.1 but is relatively inefficient. When you create one, the system must create a Canvas and the peer of the Canvas. This work doesn't gain you anything; since this is a new component, it doesn't have to match the native appearance of any other component.

In Java 1.1, there's a way to avoid the overhead if you are creating a component that doesn't have to match a native object. This is called a lightweight component. To create one, you just subclass Component itself. To make a lightweight version of our VerticalLabel, we have to change only one line of code.

// Java 1.1 only
public class VerticalLabel extends Component

Everything else remains unchanged.