javax.swing

Class JLabel

public class JLabel extends JComponent implements Accessible, SwingConstants

A component that displays a static text message and/or an icon.

Nested Class Summary
protected class	JLabel.AccessibleJLabel Provides the accessibility features for the `JLabel` component.

Field Summary
protected Component	labelFor The Component the label will give focus to when its mnemonic is activated.

Constructor Summary
	JLabel() Creates a new vertically centered, horizontally on the leading edge JLabel object with text and no icon.
	JLabel(Icon image) Creates a new vertically and horizontally centered JLabel object with no text and the given icon.
	JLabel(Icon image, int horizontalAlignment) Creates a new vertically centered JLabel object with no text and the given icon and horizontal alignment.
	JLabel(String text) Creates a new horizontally leading and vertically centered JLabel object with no icon and the given text.
	JLabel(String text, int horizontalAlignment) Creates a new vertically centered JLabel object with no icon and the given text and horizontal alignment.
	JLabel(String text, Icon icon, int horizontalAlignment) Creates a new vertically centered JLabel object with the given text, icon, and horizontal alignment.

Method Summary
protected int	checkHorizontalKey(int key, String message) Checks the specified key to ensure that it is valid as a horizontal alignment, throwing an {@link IllegalArgumentException} if the key is invalid.
protected int	checkVerticalKey(int key, String message) Checks the specified key to ensure that it is valid as a vertical alignment, throwing an {@link IllegalArgumentException} if the key is invalid.
AccessibleContext	getAccessibleContext() Returns the object that provides accessibility features for this `JLabel` component.
Icon	getDisabledIcon() Returns the disabled icon.
int	getDisplayedMnemonic() Returns the keycode that is used for the label's mnemonic.
int	getDisplayedMnemonicIndex() Returns the index of the character in the label's text that will be underlined (to indicate that it is the mnemonic character), or -1 if no character is to be underlined.
int	getHorizontalAlignment() Returns the horizontal alignment of the label (one of {@link #LEFT}, {@link #CENTER}, {@link #RIGHT}, {@link #LEADING} and {@link #TRAILING}).
int	getHorizontalTextPosition() Returns the horizontal position of the label's text relative to the icon.
Icon	getIcon() Returns the active icon.
int	getIconTextGap() Returns the gap between the icon and the text.
Component	getLabelFor() Returns the component that this `JLabel` is providing the label for.
String	getText() Returns the text displayed by the label.
LabelUI	getUI() Returns the label's UI delegate.
String	getUIClassID() Returns a name to identify which look and feel class will be the UI delegate for this label.
int	getVerticalAlignment() Returns the vertical alignment of the label (one of {@link #TOP}, {@link #CENTER} and {@link #BOTTOM}).
int	getVerticalTextPosition() Returns the vertical position of the label's text relative to the icon.
boolean	imageUpdate(Image img, int infoflags, int x, int y, int w, int h) Returns false if the current icon image (current icon will depend on whether the label is enabled) is not equal to the passed in image.
protected String	paramString() Returns a string describing the attributes for the `JLabel` component, for use in debugging.
void	setDisabledIcon(Icon newIcon) Sets the icon displayed when the label is disabled (this is a bound property with the name 'disabledIcon').
void	setDisplayedMnemonic(int mnemonic) Sets the keycode that will be the label's mnemonic (this is a bound property with the name 'displayedMnemonic').
void	setDisplayedMnemonic(char mnemonic) Sets the character that will be the label's mnemonic.
void	setDisplayedMnemonicIndex(int newIndex) Sets the index of the character in the text that will be underlined to indicate that it is the mnemonic character for the label.
void	setFont(Font f) Sets the font for the label (this a bound property with the name 'font').
void	setHorizontalAlignment(int alignment) Sets the horizontal alignment for the label (this is a bound property with the name 'horizontalAlignment').
void	setHorizontalTextPosition(int textPosition) Sets the horizontal position of the label's text relative to the icon (this is a bound property with the name 'horizontalTextPosition').
void	setIcon(Icon newIcon) Sets the icon for the label (this is a bound property with the name 'icon').
void	setIconTextGap(int newGap) Sets the gap between the icon and the text, in the case that both are visible (this is a bound property with the name 'iconTextGap').
void	setLabelFor(Component c) Sets the component that this `JLabel` is providing the label for (this is a bound property with the name 'labelFor').
void	setText(String newText) Sets the text for the label and sends a {@link PropertyChangeEvent} (with the name 'text') to all registered listeners.
void	setUI(LabelUI ui) Sets the label's UI delegate.
void	setVerticalAlignment(int alignment) Sets the vertical alignment for the label (this is a bound property with the name 'verticalAlignment').
void	setVerticalTextPosition(int textPosition) Sets the vertical position of the label's text relative to the icon (this is a bound property with the name 'verticalTextPosition').
void	updateUI() Resets the label's UI delegate to the default UI for the current look and feel.

Field Detail

labelFor

protected Component labelFor

The Component the label will give focus to when its mnemonic is activated.

Constructor Detail

JLabel

public JLabel()

Creates a new vertically centered, horizontally on the leading edge JLabel object with text and no icon.

JLabel

public JLabel(Icon image)

Creates a new vertically and horizontally centered JLabel object with no text and the given icon.

Parameters: image The icon to use with the label, null permitted.

JLabel

public JLabel(Icon image, int horizontalAlignment)

Creates a new vertically centered JLabel object with no text and the given icon and horizontal alignment. By default, the text is TRAILING the image.

Parameters: image The icon to use with the label, null premitted. horizontalAlignment The horizontal alignment of the label, must be either CENTER, LEFT, RIGHT, LEADING or TRAILING.

JLabel

public JLabel(String text)

Creates a new horizontally leading and vertically centered JLabel object with no icon and the given text.

Parameters: text The text to use with the label, null permitted.

JLabel

public JLabel(String text, int horizontalAlignment)

Creates a new vertically centered JLabel object with no icon and the given text and horizontal alignment.

Parameters: text The text to use with the label, null permitted. horizontalAlignment The horizontal alignment of the label, must be either CENTER, LEFT, RIGHT, LEADING or TRAILING.

JLabel

public JLabel(String text, Icon icon, int horizontalAlignment)

Creates a new vertically centered JLabel object with the given text, icon, and horizontal alignment.

Parameters: text The text to use with the label, null permitted. icon The icon to use with the label, null premitted. horizontalAlignment The horizontal alignment of the label, must be either CENTER, LEFT, RIGHT, LEADING or TRAILING.

Method Detail

checkHorizontalKey

protected int checkHorizontalKey(int key, String message)

Checks the specified key to ensure that it is valid as a horizontal alignment, throwing an {@link IllegalArgumentException} if the key is invalid. Valid keys are {@link #LEFT}, {@link #CENTER}, {@link #RIGHT}, {@link #LEADING} and {@link #TRAILING}.

Parameters: key The key to check. message The message of the exception to be thrown if the key is invalid.

Returns: The key if it is valid.

Throws: IllegalArgumentException If the key is invalid.

checkVerticalKey

protected int checkVerticalKey(int key, String message)

Checks the specified key to ensure that it is valid as a vertical alignment, throwing an {@link IllegalArgumentException} if the key is invalid. Valid keys are {@link #TOP}, {@link #CENTER} and {@link #BOTTOM}.

Parameters: key The key to check. message The message of the exception to be thrown if the key is invalid.

Returns: The key if it is valid.

Throws: IllegalArgumentException If the key is invalid.

getAccessibleContext

public AccessibleContext getAccessibleContext()

Returns the object that provides accessibility features for this JLabel component.

Returns: The accessible context (an instance of {@link AccessibleJLabel}).

getDisabledIcon

public Icon getDisabledIcon()

Returns the disabled icon. The disabled icon is painted when the label is disabled. If the disabled icon is null and the active icon is an {@link ImageIcon}, this method returns a grayed version of the icon. The grayed version of the icon becomes the disabledIcon.

Returns: The disabled icon.

getDisplayedMnemonic

public int getDisplayedMnemonic()

Returns the keycode that is used for the label's mnemonic.

Returns: The keycode that is used for the label's mnemonic.

See Also: JLabel

getDisplayedMnemonicIndex

public int getDisplayedMnemonicIndex()

Returns the index of the character in the label's text that will be underlined (to indicate that it is the mnemonic character), or -1 if no character is to be underlined.

Returns: The index of the character that will be underlined.

Since: 1.4

See Also: JLabel

getHorizontalAlignment

public int getHorizontalAlignment()

Returns the horizontal alignment of the label (one of {@link #LEFT}, {@link #CENTER}, {@link #RIGHT}, {@link #LEADING} and {@link #TRAILING}). The default value depends on the installed look and feel, but is usually {@link #LEFT}.

Returns: The horizontal alignment.

See Also: JLabel

getHorizontalTextPosition

public int getHorizontalTextPosition()

Returns the horizontal position of the label's text relative to the icon. This will be one of {@link #LEFT}, {@link #CENTER}, {@link #RIGHT}, {@link #LEADING} and {@link #TRAILING}.

Returns: The horizontal position of the label's text relative to the icon.

See Also: JLabel

getIcon

public Icon getIcon()

Returns the active icon. The active icon is painted when the label is enabled.

Returns: The active icon.

getIconTextGap

public int getIconTextGap()

Returns the gap between the icon and the text.

Returns: The gap between the icon and the text.

See Also: JLabel

getLabelFor

public Component getLabelFor()

Returns the component that this JLabel is providing the label for. This component will typically receive the focus when the label's mnemonic key is activated via the keyboard.

Returns: The component (possibly null).

getText

public String getText()

Returns the text displayed by the label.

Returns: The label text (possibly null).

getUI

public LabelUI getUI()

Returns the label's UI delegate.

Returns: The label's UI delegate.

getUIClassID

public String getUIClassID()

Returns a name to identify which look and feel class will be the UI delegate for this label.

Returns: "LabelUI"

getVerticalAlignment

public int getVerticalAlignment()

Returns the vertical alignment of the label (one of {@link #TOP}, {@link #CENTER} and {@link #BOTTOM}). The default value depends on the installed look and feel, but is usually {@link #CENTER}.

Returns: The vertical alignment.

See Also: JLabel

getVerticalTextPosition

public int getVerticalTextPosition()

Returns the vertical position of the label's text relative to the icon. This will be one of {@link #TOP}, {@link #CENTER} and {@link #BOTTOM}.

Returns: The vertical position of the label's text relative to the icon.

See Also: JLabel

imageUpdate

public boolean imageUpdate(Image img, int infoflags, int x, int y, int w, int h)

Returns false if the current icon image (current icon will depend on whether the label is enabled) is not equal to the passed in image.

Parameters: img The image to check. infoflags The bitwise inclusive OR of ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, and WIDTH x The x position y The y position w The width h The height

Returns: Whether the current icon image is equal to the image given.

paramString

protected String paramString()

Returns a string describing the attributes for the JLabel component, for use in debugging. The return value is guaranteed to be non-null, but the format of the string may vary between implementations.

Returns: A string describing the attributes of the JLabel.

setDisabledIcon

public void setDisabledIcon(Icon newIcon)

Sets the icon displayed when the label is disabled (this is a bound property with the name 'disabledIcon').

Parameters: newIcon The disabled icon (null permitted).

setDisplayedMnemonic

public void setDisplayedMnemonic(int mnemonic)

Sets the keycode that will be the label's mnemonic (this is a bound property with the name 'displayedMnemonic'). If the label is used as a label for another component, the label will give focus to that component when the mnemonic is activated.

Parameters: mnemonic The keycode to use for the mnemonic.

setDisplayedMnemonic

public void setDisplayedMnemonic(char mnemonic)

Sets the character that will be the label's mnemonic. If the label is used as a label for another component, the label will give focus to that component when the mnemonic is activated via the keyboard.

Parameters: mnemonic The character to use for the mnemonic (this will be converted to the equivalent upper case character).

setDisplayedMnemonicIndex

public void setDisplayedMnemonicIndex(int newIndex)

Sets the index of the character in the text that will be underlined to indicate that it is the mnemonic character for the label. You only need to call this method if you wish to override the automatically calculated character index. For instance, for a label "Find Next" with the mnemonic character 'n', you might wish to underline the second occurrence of 'n' rather than the first (which is the default).

Note that this method does not validate the character at the specified index to ensure that it matches the key code returned by {@link #getDisplayedMnemonic()}.

Parameters: newIndex The index of the character to underline.

Throws: IllegalArgumentException If index less than -1 or index is greater than or equal to the label length.

Since: 1.4

setFont

public void setFont(Font f)

Sets the font for the label (this a bound property with the name 'font').

Parameters: f The font (null permitted).

setHorizontalAlignment

public void setHorizontalAlignment(int alignment)

Sets the horizontal alignment for the label (this is a bound property with the name 'horizontalAlignment'). The horizontal alignment determines where the label (icon and text) will be placed horizontally within the component bounds. Valid alignment codes are {@link #LEFT}, {@link #CENTER}, {@link #RIGHT}, {@link #LEADING} and {@link #TRAILING}.

Parameters: alignment The horizontal alignment of the label.

Throws: IllegalArgumentException if alignment is not one of the specified values.

setHorizontalTextPosition

public void setHorizontalTextPosition(int textPosition)

Sets the horizontal position of the label's text relative to the icon (this is a bound property with the name 'horizontalTextPosition'). Valid positions are {@link #LEFT}, {@link #CENTER}, {@link #RIGHT}, {@link #LEADING} and {@link #TRAILING}.

Parameters: textPosition The horizontal text position.

Throws: IllegalArgumentException if textPosition is not one of the specified values.

setIcon

public void setIcon(Icon newIcon)

Sets the icon for the label (this is a bound property with the name 'icon'). This icon will be displayed when the label is enabled.

Parameters: newIcon The icon (null permitted).

setIconTextGap

public void setIconTextGap(int newGap)

Sets the gap between the icon and the text, in the case that both are visible (this is a bound property with the name 'iconTextGap').

Parameters: newGap The gap (in pixels).

setLabelFor

public void setLabelFor(Component c)

Sets the component that this JLabel is providing the label for (this is a bound property with the name 'labelFor'). This component will typically receive the focus when the label's mnemonic key is activated via the keyboard.

Parameters: c the component (null permitted).

setText

public void setText(String newText)

Sets the text for the label and sends a {@link PropertyChangeEvent} (with the name 'text') to all registered listeners. This method will also update the displayedMnemonicIndex, if necessary.

Parameters: newText The text (null permitted).

setUI

public void setUI(LabelUI ui)

Sets the label's UI delegate.

Parameters: ui The label's UI delegate (null not permitted).

setVerticalAlignment

public void setVerticalAlignment(int alignment)

Sets the vertical alignment for the label (this is a bound property with the name 'verticalAlignment'). The vertical alignment determines where the label (icon and text) will be placed vertically within the component bounds. Valid alignment codes are {@link #TOP}, {@link #CENTER} and {@link #BOTTOM}.

Parameters: alignment The vertical alignment of the label.

Throws: IllegalArgumentException if alignment is not one of the specified values.

setVerticalTextPosition

public void setVerticalTextPosition(int textPosition)

Sets the vertical position of the label's text relative to the icon (this is a bound property with the name 'verticalTextPosition'). Valid positions are {@link #TOP}, {@link #CENTER} and {@link #BOTTOM}.

Parameters: textPosition The vertical text position.

Throws: IllegalArgumentException if textPosition is not one of the specified values.

updateUI

public void updateUI()

Resets the label's UI delegate to the default UI for the current look and feel.