Wildcrest Associates User Manual

MultiLineLabel 1.2
User Manual

WILDCREST ASSOCIATES

[Main Page] [Sample Applet] [User Manual] [Javadoc Documentation]
[Installation & Compatibility] [License & Contact Information]

MultiLineLabel is a Java AWT component for displaying multiple line text labels. It supports line breaks, line spacing, tab expansion, margins (left, right, top, and bottom insets), line wrap, font selection, height autosizing, and a multiple line property sheet editor. MultiLineLabel can be used as either a JavaBean in visual programming environments or programmatically as a regular Java class.

Using MultiLineLabel as a JavaBean

After MultiLineLabel.jar is properly installed, you will see the MultiLineLabel bean in the component palette of your visual programming environment. Click on the MultiLineLabel bean and drop it on your work area. You will see a small highlighted empty label area one line high (two lines in the case of the free "EVALUATION USE ONLY" version).

When you bring up the property list for MultiLineLabel (left), you will be able to see and edit all the property values supported by MultiLineLabel. Clicking on the "Text" field brings up a separate scrolling text area property editor, into which you can type or paste text for your label. It may contain hard line separators typed in explicitly by you (using the Enter or Return key). Or you can type continuously and rely on MultiLineLabel's automatic line wrapping feature to break the lines. The rest of the properties may be set as desired, with values as defined in the MultiLineLabel Javadoc documentation.

The width of the label will either be as specified by you in the MultiLineLabel constructor, or in a subsequent call to MultiLineLabel's setLabelWidth method, or as modified by you using the mouse in your visual programming editor (NOTE: different visual programming editors and bean tools differ on when and how interactive size changes at design time are reflected back in the property list and in the code that is generated. The code that is generated and the property values saved are the values that will ultimately apply at run-time).

MultiLineLabel will not change the width of the label specified by you. It will, however, automatically adjust its height to accommodate all your lines of text plus top and/or bottom margins specified by you. If line wrap is on, these features guarantee that no text of a MultiLineLabel will be clipped or lost. This is particularly valuable in cross-platform applications where different font rendering systems often result in quite different font sizes, line breaks, and numbers of lines.

If line wrap is off, long lines will simply disappear past the right side of the label. MultiLineLabel will truncate these lines on white space (tabs or spaces), so that no partial words or characters will be displayed.

MultiLineLabel is a subclass of Canvas. It overrides "paint" to draw the multi-line label itself, "setSize" and "setBounds" to control the component size, and "setFont" and "getFont" for specifying the font. All other Canvas methods are unchanged.

All the MultiLineLabel properties are bound properties. You may use your visual programming environment to do property-to-property binding in either direction between and among MultiLineLabels and your other beans. None of the MultiLineLabel properties are constrained properties since MultiLineLabel computes no properties of its own and presumes values will be constrained where they originate. This frees you from having to place try...catch blocks around set calls in regular programming.

MultiLineLabel is fully serializable. After customizing any of their properties (including the text), instances of MultiLineLabel beans can be saved along with any other beans to which they may be wired. When reloaded, the MultiLineLabel beans will each come back with their customized values. Only the copyright notice MultiLineLabel "property" is declared transient.

You can perform event wiring from an actionPerformed event such as a button push to the MultiLineLabel bean. MultiLineLabel has no special action methods beyond the regular component methods inherited from Canvas such as show, hide, enable, disable, etc.

Using MultiLineLabel as a class

MultiLineLabel may also be used programmatically as a simple class. MultiLineLabel is distributed in the package com.wildcrest. A com folder with a wildcrest subfolder containing MultiLineLabel.class should be placed somewhere in your classpath (see Installation instructions).

You may find it useful to begin your program with:
import com.wildcrest.MultiLineLabel;
or you may make calls to MultiLineLabel with the full package name:
com.wildcrest.MultiLineLabel();

MultiLineLabel can instantiated with a zero-argument constructor:
MultiLineLabel()

This creates a MultiLineLabel object and initializes all its property values to their defaults (shown in the property list above). You can then use:

setText("Here is some text")

to specify the text in your label.

MultiLineLabel has two other contructors:

MultiLineLabel("Here is some text")
to create a MultiLineLabel object with the given string as its label, or:
MultiLineLabel("Here is some text", labelWidth)
where labelWidth is an int giving the initial width of the label in pixels.

The following is a very simple but complete Java applet that uses MultiLineLabel:

import java.applet.Applet;
import java.awt.*;
import com.wildcrest.MultiLineLabel;

public class MultiLineLabelTest extends Applet {
    public void init() {
      add(new MultiLineLabel("Here is some text\nAnd a second line of text"));
    }
}

The rest of the MultiLineLabel methods are set and get methods for controlling the label property values shown in the property list editor in the "Using MultiLineLabel as a JavaBean" section above. The full list of MultiLineLabel constructors and methods, what they do, and their default values are given in the MultiLineLabel Javadoc documentation.