# 1

## JCLabel and JCButton

Introduction · Sample Program Code · Specifying an Image

Text and Image Positioning · Specifying the JCButton Arm Label

Events · Property Listing · Example Programs

### Introduction

Labels and Buttons are standard Graphical User Interface (GUI) components that are common to virtually all windowing systems. A label contains text which identifies the function of another GUI component. The text in a label can be changed from within the application, but it is not directly accessible to the user. A button (or "pushbutton") enables the user to initiate an action by pressing the button.

Labels and buttons have been incorporated into the Java Development Kit (JDK), but their functionality is limited. In the JDK, labels and buttons are limited to displaying single lines of text. The chief advantages of `JCLabel`s and `JCButton`s are that they can contain multiple lines of text, images, or contain both text and images. In addition, `JCButton`s use a callback mechanism that enables the use of "`armLabels`", so that a different label is temporarily displayed when the button is pressed (or "armed").

#### Behavior

`JCLabel`s behave in the following manner:

- they are static displays capable of displaying multiple lines of read-only text and/or images.

### Keyboard traversal:

`JCButton`s behave in the following manner:

- before a button is pressed, it appears raised with respect to the rest of the display. When a button is pressed, it appears depressed
- after a button is pushed and released, an action event occurs
- when the button is pressed, its shadows are reversed to display the "pushed" appearance
- if the button is pressed, and then the mouse is dragged outside the button and subsequently released, no action event is called
- if a particular event occurs, the read-only text and/or image is changed or is displayed in a "greyed-out", unselected format
- if the mouse is pressed and then released within the button, the button is activated (an event is generated)
- if the RETURN or space key is depressed by the user while it has focus, the button is depressed. It is equivalent to clicking on a button with the mouse.

#### Keyboard Traversal

There are no keyboard traversal routines for `JCLabel`.

When a `JCButton` has focus, hitting the SPACE BAR or ENTER key depresses the `JCButton`.

### Sample Program Code

The following code fragment, when inserted into a program, creates a `JCLabel` component and illustrates some of `JCLabel`'s capabilities:

    package jclass.bwt.examples;
    import jclass.bwt.BWTEnum;
    import jclass.bwt.JCLabel;
    import jclass.util.JCString;
    import jclass.util.JCImageCreator;
    import jclass.util.JCUtilConverter;
    import jclass.contrib.ContribFrame;
    import java.awt.*;
    import java.applet.Applet;

    /**
     * This example demonstrates various types of JCLabels.
     * Using JCStrings, you can easily create complex and attractive labels.
     */
    public class labels extends Applet {

    static final String[] arrow_pixels = {
    	"  rrrrr  ",
    	"  rrrrr  ",
    	"  rrrrr  ",
    	"  rrrrr  ",
    	"  rrrrr  ",
    	"  rrrrr  ",
    	"rrrrrrrrr",
    	" rrrrrrr ",
    	"  rrrrr  ",
    	"   rrr   ",
    	"    r    ",
    };

    Applet applet;

    public labels() {}
    public labels(Applet applet) { this.applet = applet; }

    public void init() {
    	if (applet == null) applet = this;
    	setBackground(Color.lightGray);

    	JCLabel label = new JCLabel("Simple label");
    	label.setBackground(Color.red);
    	label.setForeground(Color.yellow);
    	add(label);

    	label = new JCLabel("Multi-line\nLabel");
    	label.setBackground(Color.lightGray);
    	label.setFont(new Font("TimesRoman", Font.BOLD, 14));
    	label.setPreferredSize(80, 50);
    	add(label);

    	label = new JCLabel(null, "../images/smile32.gif", applet,
    						BWTEnum.STRING_RIGHT);
    	label.setBackground(Color.lightGray);
    	add(label);

    	label = new JCLabel("Image", "../images/smile32.gif",
    						applet, BWTEnum.STRING_BOTTOM);
    	label.setBackground(Color.cyan);
    	label.setFont(new Font("Courier", Font.ITALIC, 14));
    	add(label);

    	JCImageCreator im =
    		new JCImageCreator(this, arrow_pixels[0].length(), arrow_pixels.length);
    	im.setColor('r', Color.red);
    	Image arrow = im.create(arrow_pixels);
    	label = new JCLabel("Aligned\nBottom-Right", arrow, BWTEnum.STRING_TOP);
    	label.setBackground(Color.yellow);
    	label.setForeground(Color.blue);
    	label.setFont(new Font("Helvetica", Font.PLAIN, 14));
    	label.setAlignment(BWTEnum.BOTTOMRIGHT);
    	label.setPreferredSize(100, 80);
    	add(label);

    	label = new JCLabel();
    	label.setBackground(Color.white);
    	JCString s = JCString.parse(applet, "Mix images [IMG=../images/cut16.gif], [COLOR=red]colors,\n[RESET][font=TimesRoman-ITALIC-20]fonts,[DEFAULT_FONT]\n[ST]Mistakes[/ST],\n even URLs: [COLOR=blue][href=http://www.klg.com/jclass]KL's JClass page[/href]");
    	label.setLabel(s);
    	add(label);
    }

    public static void main(String args[]) {
    	ContribFrame frame = new ContribFrame("Labels");
    	labels s = new labels();

    	s.init();
    	frame.add(s);
    	frame.pack();
    	frame.show();
    }
    }

This creates the following program display:

##### A program incorporating several JCLabels

Almost all of the properties defined for `JCLabel` are also defined for `JCButton`. The following code fragment, when inserted into a program, creates a `JCButton` component:

    package jclass.bwt.examples;
    import jclass.bwt.BWTEnum;
    import jclass.bwt.JCActionEvent;
    import jclass.bwt.JCActionListener;
    import jclass.bwt.JCButton;
    import jclass.bwt.JCButtonEvent;
    import jclass.bwt.JCButtonListener;
    import jclass.contrib.ContribFrame;
    import jclass.util.JCString;
    import jclass.util.JCUtilConverter;
    import java.awt.*;
    import java.applet.Applet;

    /**
     * This example demonstrates various types of JCButtons and events.
     * Using JCStrings, you can easily create complex and attractive labels.
     */
    public class buttons extends java.applet.Applet
    implements JCActionListener, JCButtonListener {

    /* ActionListener method */
    public void actionPerformed(JCActionEvent ev) {
    	//System.out.println(""+ev);
    }

    /*
     * JCButtonListener methods
     */
    public void buttonArmBegin(JCButtonEvent ev) {
    	((Component)ev.getSource()).setBackground(Color.white);
    }
    public void buttonArmEnd(JCButtonEvent ev) {}
    public void buttonDisarmBegin(JCButtonEvent ev) {
    	((Component)ev.getSource()).setBackground(Color.lightGray);
    }
    public void buttonDisarmEnd(JCButtonEvent ev) {}

    Applet parent;

    public buttons() {}
    public buttons(Applet p) { parent = p; }

    public void init() {
        Applet app = (parent != null) ? parent : this;
    	setBackground(Color.lightGray);

    	JCButton button = new JCButton("Simple button", app, "simple_button");
    	button.addActionListener(this);
    	add(button);

    	button = new JCButton("Multi-line\nButton");
    	button.addActionListener(this);
    	add(button);

    	button = new JCButton("Images and Text", "../images/smile32.gif",
    						  app, BWTEnum.STRING_RIGHT);
    	button.setBackground(Color.white);
    	add(button);

    	button = new JCButton("Image", "../images/smile32.gif",
    						  app, BWTEnum.STRING_BOTTOM);
    	button.setBackground(Color.white);
    	add(button);

    	Image im = JCUtilConverter.toImage(app, "../images/smile32.gif");
    	button = new JCButton(im);
    	button.addButtonListener(this);
    	add(button);

    	JCString s1 = JCString.parse(app, "[IMG=../images/smile32.gif][HORIZ_SPACE=10][ALIGN=MIDDLE]Push Me");
    	JCString s2 = JCString.parse(app, "[IMG=../images/sad32.gif][HORIZ_SPACE=10][ALIGN=MIDDLE]I'm Pushed");
    	button = new JCButton(s1, app, null);
    	button.setArmLabel(s2);
    	button.setAlignment(BWTEnum.MIDDLELEFT);
    	button.setBackground(Color.cyan);
    	add(button);
    }

    public static void main(String args[]) {
    	ContribFrame frame = new ContribFrame("Buttons");
    	buttons s = new buttons();

    	s.init();
    	frame.add(s);
    	frame.pack();
    	frame.show();
    }
    }

This produces the following button display:

##### A program incorporating several JCButtons

Both of these examples use JCStrings to insert images within the button or label. For more information on JCStrings, see JCString Properties.

The sample code used in these examples are incorporated into the files `label.class` and `button.class` provided with JClass BWT. For information on how to run these program, see the "Example Programs" section at the end of this chapter.

### Specifying an Image

To specify a image for a `JCLabel` or `JCButton` component, pass an image to the `JCButton` or `JCLabel` constructor. The `JCButton` or `JCLabel` constructor can be passed a text String, image, JCString or an Object.

### Text and Image Positioning

Text and images can be aligned within a `JCLabel` by using the `Alignment` property which has nine possible values: `TOPLEFT`, `TOPCENTER`, `TOPRIGHT, MIDDLELEFT`, `MIDDLECENTER`, `MIDDLERIGHT, BOTTOMLEFT, BOTTOMCENTER,` and `BOTTOMRIGHT`. All nine values are shown using text strings in the following display:

##### String and image positioning for labels

The default value for `Alignment` is `MIDDLECENTER`.

Text and images can also be aligned using JCStrings. This approach is limited to the three values possible with `ALIGN`: `TOP`, `BOTTOM` and `MIDDLE`.

### Specifying the JCButton Arm Label

`JCButton` enables you to define a label to be displayed when the user has pressed the button but has not yet released it. This image is called an arm label.

The following is an example of a `JCButton` using the `setArmLabel()` method:

    button = new JCButton();
    s1 = JCString.parse(this, "[IMG=../images/smile32.gif][HORIZ_SPACE=10][ALIGN=MIDDLE]Push Me");
    button.setLabel(s1);
    JCString s2 = JCString.parse(this, "[IMG=../images/sad32.gif][HORIZ_SPACE=10][ALIGN=MIDDLE]I'm Pushed");
    button.setArmLabel(s2);

This produces the effect shown in the following figure:

##### Effect of an arm image

Note that the pressed button in the previous illustration displays the dotted lines associated with a button that has focus.

### Events

A class can be notified when the user clicks a `JCButton` by implementing the `JCActionListener` interface and registering itself with the button via `addActionListener`:

    public interface JCActionListener {
            public void actionPerformed(JCActionEvent e);
    }
    public class JCActionEvent {
            // Returns the component where the event originated.
            public Object getSource()
            // Returns the event type: ACTION_PERFORMED.
            public int getId()
            // Returns the command name set via JCButton.setActionCommand()
        public String getActionCommand()
    }

In addition, if a class wishes to be notified before and after the user presses the button, it can implement the `JCButtonListener` interface and register itself with the button via `addButtonListener`, as the following code demonstrates:

    public interface JCButtonListener {
            // Invoked before the button is armed (i.e. pushed).
            public void buttonArmBegin(JCButtonEvent e);
            // Invoked after the button is armed (i.e. pushed).
            public void buttonArmEnd(JCButtonEvent e);
            // Invoked before the button is disarmed (i.e. released).
            public void buttonDisarmBegin(JCButtonEvent e);
            // Invoked after the button is disarmed (i.e. released).
            public void buttonDisarmEnd(JCButtonEvent e);
    }

As `JCLabel`s are non-interactive, there are no event handlers for them.

### Property Listing

The following is a listing of available properties for `JCButton` and `JCLabel`:

##### jclass.bwt.JCButton

#####

Name | Method | Inherited from
--- | --- | ---
`Alignment` | `setAlignment` | `jclass.bwt.JCLabel`
`ArmLabel` | `setArmLabel` | `jclass.bwt.JCButton`
`Background` | `setBackground` | `jclass.bwt.JCComponent`
`DoubleBuffer` | `setDoubleBuffer` | `jclass.bwt.JCComponent`
`Font` | `setFont` | `jclass.bwt.JCComponent`
`Foreground` | `setForeground` | `jclass.bwt.JCComponent`
`HighlightColor` | `setHighlightColor` | `jclass.bwt.JCComponent`
`HighlightThickness` | `setHighlightThickness` | `jclass.bwt.JCComponent`
`Insets` | `setInsets` | `jclass.bwt.JCComponent`
`Label` | `setLabel` | `jclass.bwt.JCLabel`
`PreferredSize` | `setPreferredSize` | `jclass.bwt.JCComponent`
`Traversable` | `setTraversable` | `jclass.bwt.JCComponent`
`UserData` | `setUserData` | `jclass.bwt.JCComponent`

##### jclass.bwt.JCLabel

#####

Name | Method | Inherited from
--- | --- | ---
`Alignment` | `setAlignment` | `jclass.bwt.JCLabel`
`Background` | `setBackground` | `jclass.bwt.JCComponent`
`DoubleBuffer` | `setDoubleBuffer` | `jclass.bwt.JCComponent`
`Font` | `setFont` | `jclass.bwt.JCComponent`
`Foreground` | `setForeground` | `jclass.bwt.JCComponent`
`HighlightColor` | `setHighlightColor` | `jclass.bwt.JCComponent`
`HighlightThickness` | `setHighlightThickness` | `jclass.bwt.JCComponent`
`Insets` | `setInsets` | `jclass.bwt.JCComponent`
`Label` | `setLabel` | `jclass.bwt.JCLabel`
`PreferredSize` | `setPreferredSize` | `jclass.bwt.JCComponent`
`Traversable` | `setTraversable` | `jclass.bwt.JCComponent`
`UserData` | `setUserData` | `jclass.bwt.JCComponent`

### Example Programs

Demonstration programs and example code containing `JCButton`s and `JCLabel`s come with JClass BWT. The examples can be viewed in applet form by launching index.html within the /jclass/bwt/examples directory. buttons.class and labels.class can also be run as stand-alone Java applications from the command prompt by typing:

    	java jclass.bwt.examples.labels

and

    	java jclass.bwt.examples.buttons