JMultiLineLabel 1.0 User Manual

WILDCREST ASSOCIATES

Using JMultiLineLabel as a JavaBean

When you bring up the property list for JMultiLineLabel (left), you will be able to see and edit all the property values supported by JMultiLineLabel.  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 JMultiLineLabel's automatic line wrapping feature to break the lines. You can also enter tabs and quotation marks (") in the property editor.  The rest of the properties may be set as desired directly in the property list, with values as defined in the JMultiLineLabel Javadoc documentation.

The width of the label will either be as specified by you in the JMultiLineLabel constructor, or in a subsequent call to JMultiLineLabel's setWidth 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).

JMultiLineLabel 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 in addition the line wrap feature is on, these features guarantee that no text of a JMultiLineLabel will be clipped or lost.  This is particularly valuable under different layout managers or in cross-platform applications where different font rendering systems often result in quite different font sizes, line breaks, and numbers of lines.

The height autosizing feature also makes JMultiLineLabel particularly useful as a dynamic text display facility.  Simply update the text in JMultiLineLabel using its setText(string) method and the JMultiLineLabel will automatically resize, redisplay, and request that its parent container recompute its layout.  Even though Java labels are often thought of as static, this behavior make JMultiLineLabel also quite useful as a dynamic component.

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

All the JMultiLineLabel properties are bound properties.  You may use your visual programming environment to do property-to-property binding in either direction between and among JMultiLineLabels and your other beans.  None of the JMultiLineLabel properties are constrained properties.  This frees you from having to place try...catch blocks around set calls in regular programming.

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

You can perform event wiring from an actionPerformed event such as a button push to the JMultiLineLabel bean.  JMultiLineLabel is a subclass of JComponent and has no special action methods beyond the regular component methods inherited from JComponent such as setVisible, setEnabled, etc.
 

Swing compatibility

Accessibility - JMultiLineLabel inherits from JComponent and adds the required methods to allow JMultiLineLabel to respond to accessibility customization.  In particular, JMultiLineLabel supports the same additional methods as JLabel.

Pluggable look-and-feel - Because JMultiLineLabel is conceptually the same as JLabel, it has been designed to use JLabel for its pluggable look-and-feel.  JMultiLineLabel has three pluggable facets of it UI: foreground color, background color, and font.  Rather than have its own UI class, JMultiLineLabel accesses the JLabelUI class for this pluggable look-and-feel information when it receives updateUI calls. Run the PLAFSimpleExample demo to see how JMultiLineLabel and JLabel respond to pluggable look-and-feel changes.

Transparency/opacity - JMultiLineLabel supports the JComponent opacity property and renders transparent backgrounds when this property is false.  Run the JMultiLineLabelTestApplet to see this behavior.

Enabled/disabled display - JMultiLineLabel dims its foreground drawing color consistent with other Swing components when it is disabled. Run the JMultiLineLabelTestApplet to see this behavior. Using JMultiLineLabel as a class

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

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

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

The following is a simple but complete Java applet that uses JMultiLineLabel:
import javax.swing.*;
import com.wildcrest.jmultilinelabel.JMultiLineLabel;

public class JMultiLineLabelTest extends JApplet {
  public void init() {
    getContentPane().add(new JMultiLineLabel("Here is some text\nAnd a second line of text"));
  }
}

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