com.samskivert.swing
Class Label

java.lang.Object
  com.samskivert.swing.Label

All Implemented Interfaces:

LabelStyleConstants, SwingConstants

public class Label
extends Object
implements SwingConstants, LabelStyleConstants

The label is a multipurpose text display mechanism that can display small amounts of text wrapped to fit into a variety of constrained spaces. It can be requested to conform to a particular width or height and will expand into the other dimension in order to accomodate the text at hand. It is not a component, but is intended for use by components and other more heavyweight entities.

Field Summary

protected int	_align The text alignment.
protected Color	_alternateColor The color in which to render the text outline or shadow if we're rendering in outline or shadow mode.
protected Dimension	_constraints Our size constraints in either the x or y direction.
protected Font	_font The font we use when laying out and rendering out text, or null if we're to use the default font.
protected TextLayout[]	_layouts Formatted text layout instances that contain each line of text.
protected Rectangle2D[]	_lbounds Formatted text layout instances that contain each line of text.
protected float[]	_leaders Some fonts (God bless 'em) extend to the left of the position at which you request that they be rendered.
protected boolean	_mainDraw Will be true only when we're drawing a textlayout for the "main" portion of the label.
protected String	_rawText The raw text, with color tags, or null if there are no color tags.
protected Dimension	_size Our calculated size.
protected int	_style The text style.
protected String	_text The text of the label.
protected Color	_textColor The color in which to render the text or null if the text should be rendered with the graphics context color.
static Pattern	COLOR_PATTERN The pattern used to mark the start/end of color blocks.
protected static double	GOLDEN_RATIO An approximation of the golden ratio.

Fields inherited from interface javax.swing.SwingConstants

BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST

Fields inherited from interface com.samskivert.swing.LabelStyleConstants

BOLD, NORMAL, OUTLINE, SHADOW, UNDERLINE

Constructor Summary

Label()
Constructs a blank label.

Label(String text)
Constructs a label with the supplied text.

Label(String text, Color textColor, Font font)
Constructs a label with the supplied text and configuration parameters.

Label(String text, int style, Color textColor, Color altColor, Font font)
Constructs a label with the supplied text and configuration parameters.

Method Summary

protected void	addAttributes(AttributedString text) Add any attributes to the text.
void	clearTargetDimens() Clears out previously configured target dimensions for this label.
protected ArrayList<Tuple<TextLayout,Rectangle2D>>	computeLines(LineBreakMeasurer measurer, int targetWidth, Dimension size, boolean keepWordsWhole) Computes the lines of text for this label given the specified target width.
static String	escapeColors(String txt) Escape any special tags so that they won't be interpreted by the label.
static String	filterColors(String txt) Filter out any color tags from the specified text.
int	getAlignment() Returns the alignment of the text within the label.
Color	getAlternateColor() Returns the alternate color used to render the text's outline or shadow, if any.
protected Rectangle2D	getBounds(TextLayout layout) Gets the bounds of the supplied text layout in a way that works around the various befuckeries that currently happen on the Mac.
protected float	getHeight(TextLayout layout) Computes the height based on the leading, ascent and descent rather than what the layout reports via getBounds() which rarely seems to have any bearing on reality.
int	getLineCount() Returns the number of lines used by this label.
Dimension	getSize() Returns our computed dimensions.
String	getText() Returns the text displayed by this label.
Color	getTextColor() Returns the color used to render the text.
protected double	getWidth(Rectangle2D laybounds) Computes the total width of a TextLayout given bounds returned from a call to TextLayout.getBounds().
protected void	invalidate(String where) Called when the label is changed in such a way that it must be relaid out before again being rendered.
boolean	isLaidOut() Returns true if this label has been laid out, false if not.
void	layout(Component comp) Calls layout(Graphics2D) with the graphics context for the given component.
void	layout(Graphics2D gfx) Requests that this label lay out its text, obtaining information from the supplied graphics context to do so.
void	render(Graphics2D gfx, float x, float y) Renders the layout at the specified position in the supplied graphics context.
void	setAlignment(int align) Sets the alignment of the text within the label to either SwingConstants.LEFT, SwingConstants.RIGHT, or SwingConstants.CENTER.
void	setAlternateColor(Color color) Instructs the label to render the text with the specified alternate color when rendering.
void	setFont(Font font) Sets the font to be used by this label.
void	setGoldenLayout() Instructs the label to attempt to achieve a balance between width and height that approximates the golden ratio (width ~1.618 times height).
void	setStyle(int style) Sets the style of the text within the label to one of the styles defined in LabelStyleConstants.
void	setTargetHeight(int targetHeight) Sets the target height for this label.
void	setTargetWidth(int targetWidth) Sets the target width for this label.
boolean	setText(String text) Sets the text to be displayed by this label.
void	setTextColor(Color color) Sets the color used to render the text.
protected AttributedCharacterIterator	textIterator(Graphics2D gfx) Constructs an attributed character iterator with our text and the appropriate font.
static String	unescapeColors(String txt) Un-escape special tags so that they again look correct.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

COLOR_PATTERN

public static final Pattern COLOR_PATTERN

The pattern used to mark the start/end of color blocks.

_text

protected String _text

The text of the label.

_rawText

protected String _rawText

The raw text, with color tags, or null if there are no color tags.

_style

protected int _style

The text style.

_align

protected int _align

The text alignment.

_constraints

protected Dimension _constraints

Our size constraints in either the x or y direction.

_size

protected Dimension _size

Our calculated size.

_leaders

protected float[] _leaders

Some fonts (God bless 'em) extend to the left of the position at which you request that they be rendered. We opt to push such lines to the right sufficiently that they line up with the rest of the lines (perhaps not the typographically ideal thing to do, but we're in computer land and when we say our bounds are (0, 0, width, height) we damned well better not render outside those bounds, which these wonderful fonts are choosing to do).

_font

protected Font _font

The font we use when laying out and rendering out text, or null if we're to use the default font.

_layouts

protected TextLayout[] _layouts

Formatted text layout instances that contain each line of text.

_lbounds

protected Rectangle2D[] _lbounds

Formatted text layout instances that contain each line of text.

_alternateColor

protected Color _alternateColor

The color in which to render the text outline or shadow if we're rendering in outline or shadow mode.

_textColor

protected Color _textColor

The color in which to render the text or null if the text should be rendered with the graphics context color.

_mainDraw

protected boolean _mainDraw

Will be true only when we're drawing a textlayout for the "main" portion of the label. If we are in OUTLINE mode, we draw each layout 9 times: the last one is the only main one.

GOLDEN_RATIO

protected static final double GOLDEN_RATIO

An approximation of the golden ratio.

See Also:

Constant Field Values

Constructor Detail

Label

public Label()

Constructs a blank label.

Label

public Label(String text)

Constructs a label with the supplied text.

Label

public Label(String text,
             Color textColor,
             Font font)

Constructs a label with the supplied text and configuration parameters.

Label

public Label(String text,
             int style,
             Color textColor,
             Color altColor,
             Font font)

Constructs a label with the supplied text and configuration parameters.

Method Detail

filterColors

public static String filterColors(String txt)

Filter out any color tags from the specified text.

escapeColors

public static String escapeColors(String txt)

Escape any special tags so that they won't be interpreted by the label.

unescapeColors

public static String unescapeColors(String txt)

Un-escape special tags so that they again look correct. Called by rendering components that do not understand the color tags to filter colors and unescape any escaped colors.

getText

public String getText()

Returns the text displayed by this label.

setText

public boolean setText(String text)

Sets the text to be displayed by this label.

This should be followed by a call to layout(java.awt.Component) before a call is made to render(java.awt.Graphics2D, float, float) as this method invalidates the layout information.

Returns:

true if the text changed as a result of being set, false if the label was already displaying the requested text.

setFont

public void setFont(Font font)

Sets the font to be used by this label. If the font is not set, the current font of the graphics context will be used.

This should be followed by a call to layout(java.awt.Component) before a call is made to render(java.awt.Graphics2D, float, float) as this method invalidates the layout information.

getTextColor

public Color getTextColor()

Returns the color used to render the text.

setTextColor

public void setTextColor(Color color)

Sets the color used to render the text. Setting the text color to null will render the label in the graphics context color (which is the default).

getAlternateColor

public Color getAlternateColor()

Returns the alternate color used to render the text's outline or shadow, if any.

setAlternateColor

public void setAlternateColor(Color color)

Instructs the label to render the text with the specified alternate color when rendering. The text itself will be rendered in whatever color is currently set in the graphics context, but the outline or shadow (if any) will always be in the specified color.

getAlignment

public int getAlignment()

Returns the alignment of the text within the label.

setAlignment

public void setAlignment(int align)

Sets the alignment of the text within the label to either SwingConstants.LEFT, SwingConstants.RIGHT, or SwingConstants.CENTER. The default alignment is selected to be appropriate for the locale of the text being rendered.

This should be followed by a call to layout(java.awt.Component) before a call is made to render(java.awt.Graphics2D, float, float) as this method invalidates the layout information.

setStyle

public void setStyle(int style)

Sets the style of the text within the label to one of the styles defined in LabelStyleConstants. Some styles can be combined together into a mask, ie. BOLD|UNDERLINE.

This should be followed by a call to layout(java.awt.Component) before a call is made to render(java.awt.Graphics2D, float, float) as this method invalidates the layout information.

setGoldenLayout

public void setGoldenLayout()

Instructs the label to attempt to achieve a balance between width and height that approximates the golden ratio (width ~1.618 times height).

This should be followed by a call to layout(java.awt.Component) before a call is made to render(java.awt.Graphics2D, float, float) as this method invalidates the layout information.

setTargetWidth

public void setTargetWidth(int targetWidth)

Sets the target width for this label. Text will be wrapped to fit into this width, forcibly breaking words on character boundaries if a single word is too long to fit into the target width. Calling this method will annul any previously established target height as we must have one degree of freedom in which to maneuver.

This should be followed by a call to layout(java.awt.Component) before a call is made to render(java.awt.Graphics2D, float, float) as this method invalidates the layout information.

setTargetHeight

public void setTargetHeight(int targetHeight)

Sets the target height for this label. A simple algorithm will be used to balance the width of the text in order that there are only as many lines of text as fit into the target height. If rendering the label as a single line of text causes it to be taller than the target height, we simply render ourselves anyway. Calling this method will annul any previously established target width as we must have one degree of freedom in which to maneuver.

This should be followed by a call to layout(java.awt.Component) before a call is made to render(java.awt.Graphics2D, float, float) as this method invalidates the layout information.

clearTargetDimens

public void clearTargetDimens()

Clears out previously configured target dimensions for this label.

getLineCount

public int getLineCount()

Returns the number of lines used by this label.

getSize

public Dimension getSize()

Returns our computed dimensions. Only valid after a call to layout(java.awt.Component).

isLaidOut

public boolean isLaidOut()

Returns true if this label has been laid out, false if not.

layout

public void layout(Component comp)

Calls layout(Graphics2D) with the graphics context for the given component.

layout

public void layout(Graphics2D gfx)

Requests that this label lay out its text, obtaining information from the supplied graphics context to do so. It is expected that the label will be subsequently rendered in the same graphics context or at least one that is configured very similarly. If not, wackiness may ensue.

computeLines

protected ArrayList<Tuple<TextLayout,Rectangle2D>> computeLines(LineBreakMeasurer measurer,
                                                                int targetWidth,
                                                                Dimension size,
                                                                boolean keepWordsWhole)

Computes the lines of text for this label given the specified target width. The overall size of the computed lines is stored into the size parameter.

Returns:

an ArrayList or null if keepWordsWhole was true and the lines could not be layed out in the target width.

render

public void render(Graphics2D gfx,
                   float x,
                   float y)

Renders the layout at the specified position in the supplied graphics context.

textIterator

protected AttributedCharacterIterator textIterator(Graphics2D gfx)

Constructs an attributed character iterator with our text and the appropriate font.

addAttributes

protected void addAttributes(AttributedString text)

Add any attributes to the text.

getWidth

protected double getWidth(Rectangle2D laybounds)

Computes the total width of a TextLayout given bounds returned from a call to TextLayout.getBounds().

getBounds

protected Rectangle2D getBounds(TextLayout layout)

Gets the bounds of the supplied text layout in a way that works around the various befuckeries that currently happen on the Mac.

getHeight

protected float getHeight(TextLayout layout)

Computes the height based on the leading, ascent and descent rather than what the layout reports via getBounds() which rarely seems to have any bearing on reality.

invalidate

protected void invalidate(String where)

Called when the label is changed in such a way that it must be relaid out before again being rendered.