Use is subject to License Terms. Your use of this web site or any of its content or software indicates your agreement to be bound by these License Terms.

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.

JSR-209 (Final Approval Ballot)

javax.swing
Class JLabel

java.lang.Object
  extended byjava.awt.Component
      extended byjava.awt.Container
          extended byjavax.swing.JComponent
              extended byjavax.swing.JLabel
All Implemented Interfaces:
java.awt.image.ImageObserver, java.io.Serializable, SwingConstants

public class JLabel
extends JComponent
implements SwingConstants

A display area for a short text string or an image, or both. A label does not react to input events. As a result, it cannot get the keyboard focus. A label can, however, display a keyboard alternative as a convenience for a nearby component that has a keyboard alternative but can't display it.

A JLabel object can display either text, an image, or both. You can specify where in the label's display area the label's contents are aligned by setting the vertical and horizontal alignment. By default, labels are vertically centered in their display area. Text-only labels are leading edge aligned, by default; image-only labels are horizontally centered, by default.

You can also specify the position of the text relative to the image. By default, text is on the trailing edge of the image, with the text and image vertically aligned.

Finally, you can use the setIconTextGap method to specify how many pixels should appear between the text and the image. The default is 4 pixels.

See How to Use Labels in The Java Tutorial for further documentation.

Clarifications

The following clarifications apply to implementations this optional package: Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeansTM has been added to the java.beans package. Please see java.beans.XMLEncoder.


Field Summary
protected  java.awt.Component labelFor
           
 
Fields inherited from class javax.swing.JComponent
listenerList, TOOL_TIP_TEXT_KEY, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
 
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
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 java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
 
Constructor Summary
JLabel()
          Creates a JLabel instance with no image and with an empty string for the title.
JLabel(Icon image)
          Creates a JLabel instance with the specified image.
JLabel(Icon image, int horizontalAlignment)
          Creates a JLabel instance with the specified image and horizontal alignment.
JLabel(java.lang.String text)
          Creates a JLabel instance with the specified text.
JLabel(java.lang.String text, Icon icon, int horizontalAlignment)
          Creates a JLabel instance with the specified text, image, and horizontal alignment.
JLabel(java.lang.String text, int horizontalAlignment)
          Creates a JLabel instance with the specified text and horizontal alignment.
 
Method Summary
protected  int checkHorizontalKey(int key, java.lang.String message)
          Verify that key is a legal value for the horizontalAlignment properties.
protected  int checkVerticalKey(int key, java.lang.String message)
          Verify that key is a legal value for the verticalAlignment or verticalTextPosition properties.
 Icon getDisabledIcon()
          Returns the value of the disabledIcon property if it's been set, If it hasn't been set and the value of the icon property is an ImageIcon, we compute a "grayed out" version of the icon and update the disabledIcon property with that.
 int getDisplayedMnemonic()
          Return the keycode that indicates a mnemonic key.
 int getDisplayedMnemonicIndex()
          Returns the character, as an index, that the look and feel should provide decoration for as representing the mnemonic character.
 int getHorizontalAlignment()
          Returns the alignment of the label's contents along the X axis.
 int getHorizontalTextPosition()
          Returns the horizontal position of the label's text, relative to its image.
 Icon getIcon()
          Returns the graphic image (glyph, icon) that the label displays.
 int getIconTextGap()
          Returns the amount of space between the text and the icon displayed in this label.
 java.awt.Component getLabelFor()
          Get the component this is labelling.
 java.lang.String getText()
          Returns the text string that the label displays.
 int getVerticalAlignment()
          Returns the alignment of the label's contents along the Y axis.
 int getVerticalTextPosition()
          Returns the vertical position of the label's text, relative to its image.
 boolean imageUpdate(java.awt.Image img, int infoflags, int x, int y, int w, int h)
          This is overridden to return false if the current Icon's Image is not equal to the passed in Image img.
 void paint(java.awt.Graphics g)
          Invoked by Swing to draw components.
protected  void paintBorder(java.awt.Graphics g)
          Paints the component's border.
protected  void paintComponent(java.awt.Graphics g)
          Calls the UI delegate's paint method, if the UI delegate is non-null.
 void paintComponents(java.awt.Graphics g)
           
protected  java.lang.String paramString()
          Returns a string representation of this JLabel.
protected  void printBorder(java.awt.Graphics g)
          Prints the component's border.
protected  void printComponent(java.awt.Graphics g)
          This is invoked during a printing operation.
 void printComponents(java.awt.Graphics g)
           
 void setDisabledIcon(Icon disabledIcon)
          Set the icon to be displayed if this JLabel is "disabled" (JLabel.setEnabled(false)).
 void setDisplayedMnemonic(char aChar)
          Specifies the displayedMnemonic as a char value.
 void setDisplayedMnemonic(int key)
          Specify a keycode that indicates a mnemonic key.
 void setDisplayedMnemonicIndex(int index)
          Provides a hint to the look and feel as to which character in the text should be decorated to represent the mnemonic.
 void setHorizontalAlignment(int alignment)
          Sets the alignment of the label's contents along the X axis.
 void setHorizontalTextPosition(int textPosition)
          Sets the horizontal position of the label's text, relative to its image.
 void setIcon(Icon icon)
          Defines the icon this component will display.
 void setIconTextGap(int iconTextGap)
          If both the icon and text properties are set, this property defines the space between them.
 void setLabelFor(java.awt.Component c)
          Set the component this is labelling.
 void setText(java.lang.String text)
          Defines the single line of text this component will display.
 void setVerticalAlignment(int alignment)
          Sets the alignment of the label's contents along the Y axis.
 void setVerticalTextPosition(int textPosition)
          Sets the vertical position of the label's text, relative to its image.
 
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, computeVisibleRect, contains, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getConditionForKeyStroke, getDefaultLocale, getGraphics, getHeight, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getPreferredSize, getPropertyChangeListeners, getPropertyChangeListeners, getRegisteredKeyStrokes, getSize, getToolTipText, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, isDoubleBuffered, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isPreferredSizeSet, isRequestFocusEnabled, isValidateRoot, paintChildren, paintImmediately, paintImmediately, print, printAll, printChildren, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setDefaultLocale, setDoubleBuffered, setEnabled, setFont, setForeground, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
 
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, areFocusTraversalKeysSet, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicySet, list, list, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setFocusCycleRoot, setFocusTraversalKeys, setFocusTraversalPolicy, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
 
Methods inherited from class java.awt.Component
addComponentListener, addFocusListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enableEvents, enableInputMethods, getBackground, getBounds, getColorModel, getComponentListeners, getCursor, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphicsConfiguration, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMouseWheelListeners, getName, getParent, getSize, getToolkit, getTreeLock, hasFocus, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isShowing, isValid, isVisible, list, list, list, paintAll, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processInputMethodEvent, processMouseEvent, processMouseWheelEvent, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, repaint, repaint, repaint, setBounds, setBounds, setCursor, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, toString, transferFocus, transferFocusUpCycle
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

labelFor

protected java.awt.Component labelFor
Constructor Detail

JLabel

public JLabel(java.lang.String text,
              Icon icon,
              int horizontalAlignment)
Creates a JLabel instance with the specified text, image, and horizontal alignment. The label is centered vertically in its display area. The text is on the trailing edge of the image.

Parameters:
text - The text to be displayed by the label.
icon - The image to be displayed by the label.
horizontalAlignment - One of the following constants defined in SwingConstants: LEFT, CENTER, RIGHT, LEADING or TRAILING.

JLabel

public JLabel(java.lang.String text,
              int horizontalAlignment)
Creates a JLabel instance with the specified text and horizontal alignment. The label is centered vertically in its display area.

Parameters:
text - The text to be displayed by the label.
horizontalAlignment - One of the following constants defined in SwingConstants: LEFT, CENTER, RIGHT, LEADING or TRAILING.

JLabel

public JLabel(java.lang.String text)
Creates a JLabel instance with the specified text. The label is aligned against the leading edge of its display area, and centered vertically.

Parameters:
text - The text to be displayed by the label.

JLabel

public JLabel(Icon image,
              int horizontalAlignment)
Creates a JLabel instance with the specified image and horizontal alignment. The label is centered vertically in its display area.

Parameters:
image - The image to be displayed by the label.
horizontalAlignment - One of the following constants defined in SwingConstants: LEFT, CENTER, RIGHT, LEADING or TRAILING.

JLabel

public JLabel(Icon image)
Creates a JLabel instance with the specified image. The label is centered vertically and horizontally in its display area.

Parameters:
image - The image to be displayed by the label.

JLabel

public JLabel()
Creates a JLabel instance with no image and with an empty string for the title. The label is centered vertically in its display area. The label's contents, once set, will be displayed on the leading edge of the label's display area.

Method Detail

paint

public final void paint(java.awt.Graphics g)
Description copied from class: JComponent
Invoked by Swing to draw components. Applications should not invoke paint directly, but should instead use the repaint method to schedule the component for redrawing.

This method actually delegates the work of painting to three protected methods: paintComponent, paintBorder, and paintChildren. They're called in the order listed to ensure that children appear on top of component itself. Generally speaking, the component and its children should not paint in the insets area allocated to the border. Subclasses can just override this method, as always.

Overrides:
paint in class JComponent
Parameters:
g - the Graphics context in which to paint
See Also:
JComponent.paintBorder(java.awt.Graphics), JComponent.paintChildren(java.awt.Graphics), JComponent.getComponentGraphics(java.awt.Graphics), JComponent.repaint(long, int, int, int, int)

getText

public java.lang.String getText()
Returns the text string that the label displays.

Returns:
a String
See Also:
setText(java.lang.String)

setText

public void setText(java.lang.String text)
Defines the single line of text this component will display. If the value of text is null or empty string, nothing is displayed.

The default value of this property is null.

This is a JavaBeans bound property.

See Also:
setVerticalTextPosition(int), setHorizontalTextPosition(int), setIcon(javax.swing.Icon)

getIcon

public Icon getIcon()
Returns the graphic image (glyph, icon) that the label displays.

Returns:
an Icon
See Also:
setIcon(javax.swing.Icon)

setIcon

public void setIcon(Icon icon)
Defines the icon this component will display. If the value of icon is null, nothing is displayed.

The default value of this property is null.

This is a JavaBeans bound property.

See Also:
setVerticalTextPosition(int), setHorizontalTextPosition(int), getIcon()

getDisabledIcon

public Icon getDisabledIcon()
Returns the value of the disabledIcon property if it's been set, If it hasn't been set and the value of the icon property is an ImageIcon, we compute a "grayed out" version of the icon and update the disabledIcon property with that.

Returns:
The value of the disabledIcon property.
See Also:
setDisabledIcon(javax.swing.Icon), ImageIcon

setDisabledIcon

public void setDisabledIcon(Icon disabledIcon)
Set the icon to be displayed if this JLabel is "disabled" (JLabel.setEnabled(false)).

The default value of this property is null.

Parameters:
disabledIcon - the Icon to display when the component is disabled
See Also:
getDisabledIcon(), JComponent.setEnabled(boolean)

setDisplayedMnemonic

public void setDisplayedMnemonic(int key)
Specify a keycode that indicates a mnemonic key. This property is used when the label is part of a larger component. If the labelFor property of the label is not null, the label will call the requestFocus method of the component specified by the labelFor property when the mnemonic is activated.

See Also:
getLabelFor(), setLabelFor(java.awt.Component)

setDisplayedMnemonic

public void setDisplayedMnemonic(char aChar)
Specifies the displayedMnemonic as a char value.

Parameters:
aChar - a char specifying the mnemonic to display
See Also:
setDisplayedMnemonic(int)

getDisplayedMnemonic

public int getDisplayedMnemonic()
Return the keycode that indicates a mnemonic key. This property is used when the label is part of a larger component. If the labelFor property of the label is not null, the label will call the requestFocus method of the component specified by the labelFor property when the mnemonic is activated.

Returns:
int value for the mnemonic key
See Also:
getLabelFor(), setLabelFor(java.awt.Component)

setDisplayedMnemonicIndex

public void setDisplayedMnemonicIndex(int index)
                               throws java.lang.IllegalArgumentException
Provides a hint to the look and feel as to which character in the text should be decorated to represent the mnemonic. Not all look and feels may support this. A value of -1 indicates either there is no mnemonic, the mnemonic character is not contained in the string, or the developer does not wish the mnemonic to be displayed.

The value of this is updated as the properties relating to the mnemonic change (such as the mnemonic itself, the text...). You should only ever have to call this if you do not wish the default character to be underlined. For example, if the text was 'Save As', with a mnemonic of 'a', and you wanted the 'A' to be decorated, as 'Save As', you would have to invoke setDisplayedMnemonicIndex(5) after invoking setMnemonic(KeyEvent.VK_A).

Parameters:
index - Index into the String to underline
Throws:
java.lang.IllegalArgumentException - will be thrown if index= length of the text, or < -1
Since:
1.4

getDisplayedMnemonicIndex

public int getDisplayedMnemonicIndex()
Returns the character, as an index, that the look and feel should provide decoration for as representing the mnemonic character.

Returns:
index representing mnemonic character
Since:
1.4
See Also:
setDisplayedMnemonicIndex(int)

checkHorizontalKey

protected int checkHorizontalKey(int key,
                                 java.lang.String message)
Verify that key is a legal value for the horizontalAlignment properties.

Parameters:
key - the property value to check
message - the IllegalArgumentException detail message
Throws:
java.lang.IllegalArgumentException - if key isn't LEFT, CENTER, RIGHT, LEADING or TRAILING.
See Also:
setHorizontalTextPosition(int), setHorizontalAlignment(int)

checkVerticalKey

protected int checkVerticalKey(int key,
                               java.lang.String message)
Verify that key is a legal value for the verticalAlignment or verticalTextPosition properties.

Parameters:
key - the property value to check
message - the IllegalArgumentException detail message
Throws:
java.lang.IllegalArgumentException - if key isn't TOP, CENTER, or BOTTOM.
See Also:
setVerticalAlignment(int), setVerticalTextPosition(int)

getIconTextGap

public int getIconTextGap()
Returns the amount of space between the text and the icon displayed in this label.

Returns:
an int equal to the number of pixels between the text and the icon.
See Also:
setIconTextGap(int)

setIconTextGap

public void setIconTextGap(int iconTextGap)
If both the icon and text properties are set, this property defines the space between them.

The default value of this property is 4 pixels.

This is a JavaBeans bound property.

See Also:
getIconTextGap()

getVerticalAlignment

public int getVerticalAlignment()
Returns the alignment of the label's contents along the Y axis.

Returns:
The value of the verticalAlignment property, one of the following constants defined in SwingConstants: TOP, CENTER, or BOTTOM.
See Also:
SwingConstants, setVerticalAlignment(int)

setVerticalAlignment

public void setVerticalAlignment(int alignment)
Sets the alignment of the label's contents along the Y axis.

The default value of this property is CENTER.

Parameters:
alignment - One of the following constants defined in SwingConstants: TOP, CENTER (the default), or BOTTOM.
See Also:
SwingConstants, getVerticalAlignment()

getHorizontalAlignment

public int getHorizontalAlignment()
Returns the alignment of the label's contents along the X axis.

Returns:
The value of the horizontalAlignment property, one of the following constants defined in SwingConstants: LEFT, CENTER, RIGHT, LEADING or TRAILING.
See Also:
setHorizontalAlignment(int), SwingConstants

setHorizontalAlignment

public void setHorizontalAlignment(int alignment)
Sets the alignment of the label's contents along the X axis.

This is a JavaBeans bound property.

Parameters:
alignment - One of the following constants defined in SwingConstants: LEFT, CENTER (the default for image-only labels), RIGHT, LEADING (the default for text-only labels) or TRAILING.
See Also:
SwingConstants, getHorizontalAlignment()

getVerticalTextPosition

public int getVerticalTextPosition()
Returns the vertical position of the label's text, relative to its image.

Returns:
One of the following constants defined in SwingConstants: TOP, CENTER, or BOTTOM.
See Also:
setVerticalTextPosition(int), SwingConstants

setVerticalTextPosition

public void setVerticalTextPosition(int textPosition)
Sets the vertical position of the label's text, relative to its image.

The default value of this property is CENTER.

This is a JavaBeans bound property.

Parameters:
textPosition - One of the following constants defined in SwingConstants: TOP, CENTER (the default), or BOTTOM.
See Also:
SwingConstants, getVerticalTextPosition()

getHorizontalTextPosition

public int getHorizontalTextPosition()
Returns the horizontal position of the label's text, relative to its image.

Returns:
One of the following constants defined in SwingConstants: LEFT, CENTER, RIGHT, LEADING or TRAILING.
See Also:
SwingConstants

setHorizontalTextPosition

public void setHorizontalTextPosition(int textPosition)
Sets the horizontal position of the label's text, relative to its image.

Parameters:
textPosition - One of the following constants defined in SwingConstants: LEFT, CENTER, RIGHT, LEADING, or TRAILING (the default).
Throws:
java.lang.IllegalArgumentException
See Also:
SwingConstants

imageUpdate

public boolean imageUpdate(java.awt.Image img,
                           int infoflags,
                           int x,
                           int y,
                           int w,
                           int h)
This is overridden to return false if the current Icon's Image is not equal to the passed in Image img.

Specified by:
imageUpdate in interface java.awt.image.ImageObserver
See Also:
ImageObserver, Component.imageUpdate(java.awt.Image, int, int, int, int, int)

paramString

protected java.lang.String paramString()
Returns a string representation of this JLabel. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:
paramString in class JComponent
Returns:
a string representation of this JLabel.

getLabelFor

public java.awt.Component getLabelFor()
Get the component this is labelling.

Returns:
the Component this is labelling. Can be null if this does not label a Component. If the displayedMnemonic property is set and the labelFor property is also set, the label will call the requestFocus method of the component specified by the labelFor property when the mnemonic is activated.
See Also:
getDisplayedMnemonic(), setDisplayedMnemonic(int)

setLabelFor

public void setLabelFor(java.awt.Component c)
Set the component this is labelling. Can be null if this does not label a Component. If the displayedMnemonic property is set and the labelFor property is also set, the label will call the requestFocus method of the component specified by the labelFor property when the mnemonic is activated.

Parameters:
c - the Component this label is for, or null if the label is not the label for a component
See Also:
getDisplayedMnemonic(), setDisplayedMnemonic(int)

paintComponent

protected final void paintComponent(java.awt.Graphics g)
Description copied from class: JComponent
Calls the UI delegate's paint method, if the UI delegate is non-null. We pass the delegate a copy of the Graphics object to protect the rest of the paint code from irrevocable changes (for example, Graphics.translate).

Overrides:
paintComponent in class JComponent
Parameters:
g - the Graphics object to protect
See Also:
JComponent.paint(java.awt.Graphics), ComponentUI

paintBorder

protected final void paintBorder(java.awt.Graphics g)
Description copied from class: JComponent
Paints the component's border.

Overrides:
paintBorder in class JComponent
Parameters:
g - the Graphics context in which to paint
See Also:
JComponent.paint(java.awt.Graphics), JComponent.setBorder(javax.swing.border.Border)

paintComponents

public final void paintComponents(java.awt.Graphics g)

printComponent

protected final void printComponent(java.awt.Graphics g)
Description copied from class: JComponent
This is invoked during a printing operation. This is implemented to invoke paintComponent on the component.

Overrides:
printComponent in class JComponent
Parameters:
g - the Graphics context in which to paint
See Also:
JComponent.print(java.awt.Graphics)

printBorder

protected final void printBorder(java.awt.Graphics g)
Description copied from class: JComponent
Prints the component's border. This is implemented to invoke paintBorder on the component.

Overrides:
printBorder in class JComponent
Parameters:
g - the Graphics context in which to paint
See Also:
JComponent.print(java.awt.Graphics)

printComponents

public final void printComponents(java.awt.Graphics g)

JSR-209 (Final Approval Ballot)

Copyright © 2006 Sun Microsystems, Inc. All rights reserved. Use is subject to License Terms. Your use of this web site or any of its content or software indicates your agreement to be bound by these License Terms.

For more information, please consult the JSR 209 specification.