# 2

# JCLabel and JCButton

Introduction · Sample Program Code · Specifying an Image

Text and Image Positioning · Specifying the JCButton Arm Label

Events · Property Listing · Example Programs

This chapter describes the common features of the `JCLabel` and `JCButton` components, then provides information on features unique to each component.

## 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 `JCButtons` are that they can contain multiple lines of text, images, or contain both text and images. In addition, `JCButton`s use an event listener 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

`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 indented;
- 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 "grey-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 BAR 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 example 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]");

    	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 label display:

A program incorporating several JCLabels

Almost all of the properties defined for `JCLabel` are also defined for `JCButton`. The following code 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");

    	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 codes 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 programs, 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 for `ALIGN`: `TOP`, `BOTTOM` or `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");

    JCString s2 = JCString.parse(this, "[IMG=../images/sad32.gif][HORIZ_SPACE=10][ALIGN=MIDDLE]I'm Pushed");

    This produces the effect shown in
    Effect of an arm image
    .

    Effect of an arm image

    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 JCLabels are non-interactive, there are no event handlers for them.

    Property Listing

    The following summarizes the properties of JCButton and JCLabel. Complete reference documentation is available online in standard
    javadoc format in
    jclass.bwt.JCButton.html and
    jclass.bwt.JCLabel.html.

    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 JCButtons and JCLabels 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