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 JCLabels and JCButtons are that they can contain multiple lines of text, images, or contain both text and images. In addition, JCButtons 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

JCLabels behave in the following manner:

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

JCButtons 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();
}
}

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();
}
}

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:

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);

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()
}

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);
}

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.

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

	java jclass.bwt.examples.buttons