Class StyledLabel

All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, SwingConstants
Direct Known Subclasses:
ClickThroughStyledLabel, StyledListCellRenderer, StyledTreeCellRenderer

public class StyledLabel extends JLabel
StyledLabel is a special JLabel which can display text in different styles. It is a component between JLabel and JTextPane. JLabel is simple, fast but has limited features. For example, you can't use different color to draw the text. You may argue JLabel can use HTML tag to display text in different colors. However there are two main reasons to use StyledLabel. First of all, StyledLabel is very fast and almost as fast as JLabel with plain text. HTML JLabel is very slow. You can see StyledLabelPerformanceDemo.java in examples\B15. StyledLabel folder to see a performace test of HTML JLabel and StyledLabel. HTML JLabel is also buggy. See bug report at http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4373575. Sun claimed it is fixed but it is not as another user pointed it out at the end. If you run the test case provided by original submitter, you will immediately notice the tree node disappeared when you click on the tree nodes. This bug is actually one of the main reasons we decided to create StyledLabel. JTextPane is powerful and can display text in different color. But in the cases like cell renderer, JTextPane is obviously an overkill.

StyledLabel sits between JLabel and JTextPane and provides a very simple and fast way to display text in different color and style. It can also support decorations using all kinds of line styles.

All the methods on JLabel still work as before. The methods added in StyledLabel are several methods for StyleRange, such as addStyleRange(StyleRange), setStyleRanges(StyleRange[]), clearStyleRange(StyleRange), and clearStyleRanges().

This is one thing about StyleRange that you should be aware of, which could be considered as a future enhancement item, is that the StyleRanges can't overlap with each other. For example, if you defined a StyleRange that covers from index 0 to index 3, you can't define any other StyleRange that overlaps with the first one. If you do so, the second StyleRange will be ignored.

We borrowed some ideas from SWT's StyledText when we designed StyledLabel, especially StyleRange concept. Saying that, the features of the two components are not exactly the same since the purpose of the two components are quite different.

See Also:
  • Field Details

  • Constructor Details

    • StyledLabel

      public StyledLabel()
    • StyledLabel

      public StyledLabel(Icon image)
    • StyledLabel

      public StyledLabel(Icon image, int horizontalAlignment)
    • StyledLabel

      public StyledLabel(String text)
    • StyledLabel

      public StyledLabel(String text, int horizontalAlignment)
    • StyledLabel

      public StyledLabel(String text, Icon icon, int horizontalAlignment)
  • Method Details

    • updateUI

      public void updateUI()
      Resets the UI property to a value from the current look and feel.
      Overrides:
      updateUI in class JLabel
      See Also:
    • getUIClassID

      public String getUIClassID()
      Returns a string that specifies the name of the Linvalid input: '&F' class that renders this component.
      Overrides:
      getUIClassID in class JLabel
      Returns:
      the string "StyledLabelUI"
      See Also:
    • addStyleRange

      public void addStyleRange(StyleRange styleRange)
      Adds a StyleRange into this StyledLabel.
      Parameters:
      styleRange - the new StyleRange.
    • setStyleRanges

      public void setStyleRanges(StyleRange[] styleRanges)
      Clears all the old StyleRanges and adds a list of StyleRanges into this StyledLabel.
      Parameters:
      styleRanges - set the StyleRanges.
    • addStyleRanges

      public void addStyleRanges(StyleRange[] styleRanges)
      Adds a list of StyleRanges into this StyledLabel.
      Parameters:
      styleRanges - an array of StyleRanges.
    • getStyleRanges

      public StyleRange[] getStyleRanges()
      Gets the array of StyledText.
      Returns:
      the array of StyledText.
    • clearStyleRange

      public void clearStyleRange(StyleRange styleRange)
      Removes the StyleRange.
      Parameters:
      styleRange - the StyleRange to be removed.
    • clearStyleRanges

      public void clearStyleRanges()
      Clears all the StyleRanges.
    • isIgnoreColorSettings

      public boolean isIgnoreColorSettings()
      StyleRange could define color for the text and lines. However when StyledLabel is used in cell renderer, the color could be conflict with selection color. So usually when it is used as cell renderer, the color defined in StyleRange should be ignored when cell is selected. If so, the foreground is used to paint all text and lines.
      Returns:
      true if the color defined by StyleRange should be ignored.
    • setIgnoreColorSettings

      public void setIgnoreColorSettings(boolean ignoreColorSettings)
      Sets if the color defined by StyleRange should be ignored. This flag is used when StyledLabel is used as a selected cell renderer. Since the selection usually has it own unique selection background and foreground, the color setting set on this StyledLabel could be unreadable on the selection background, it'd better if we don't use any color settings in this case.
      Parameters:
      ignoreColorSettings - true or false.
    • getMinimumSize

      public Dimension getMinimumSize()
      Overrides:
      getMinimumSize in class JComponent
    • getMaximumSize

      public Dimension getMaximumSize()
      Overrides:
      getMaximumSize in class JComponent
    • setPreferredWidth

      public void setPreferredWidth(int preferredWidth)
      Sets the preferred width of the styled label.
      Parameters:
      preferredWidth - the preferred width
      Since:
      3.2.0
    • getPreferredWidth

      public int getPreferredWidth()
      Gets the preferred width of the styled label.
      Returns:
      the preferred width
      Since:
      3.2.0
    • isLineWrap

      public boolean isLineWrap()
      Gets the flag indicating if the line should be automatically wrapped when the column width is limited.
      Returns:
      true if line wrap is needed. Otherwise false.
      Since:
      3.2.0
    • setLineWrap

      public void setLineWrap(boolean lineWrap)
      Sets the flag indicating if the line should be automatically wrapped when the column width is limited.
      Parameters:
      lineWrap - the flag
      Since:
      3.2.0
    • getRows

      public int getRows()
      Gets the default row count to wrap the StyledLabel.
      Returns:
      the row count.
      Since:
      3.2.0
      See Also:
    • setRows

      public void setRows(int rows)
      Sets the default row count to wrap the StyledLabel.

      By default, the value is 0. Any non-positive value is deemed as not configured.

      This has lower priority than setPreferredWidth(int). If preferred width is set, this flag does not take effect.

      Parameters:
      rows - the row count
      Since:
      3.2.0
    • getRowGap

      public int getRowGap()
      Gets the gap pixels between rows.
      Returns:
      the gap pixels.
      Since:
      3.2.0
      See Also:
    • setRowGap

      public void setRowGap(int rowGap)
      Sets the gap pixels between rows.

      By default, the value is 0.

      Parameters:
      rowGap - the gap pixels.
    • getMaxRows

      public int getMaxRows()
      Gets the maximum rows possible after wrapping.
      Returns:
      the maximum rows.
      Since:
      3.2.0
    • setMaxRows

      public void setMaxRows(int maxRows)
      Sets the maximum rows possible after wrapping.

      By default, the value is 0. Any non-positive value is deemed as not configured.

      Parameters:
      maxRows - the maximum rows
      Since:
      3.2.0
    • getMinRows

      public int getMinRows()
      Gets the minimum rows possible after wrapping.
      Returns:
      the minimum rows.
      Since:
      3.2.0
    • setMinRows

      public void setMinRows(int minRows)
      Sets the minimum rows possible after wrapping.

      By default, the value is 0. Any non-positive value is deemed as not configured.

      Parameters:
      minRows - the minimum rows
      Since:
      3.2.0
    • isTruncated

      public boolean isTruncated()
      Gets the status indicating if the StyledLabel is painted truncated.
      Returns:
      true if its truncated. Otherwise false.
      Since:
      3.2.1
    • setTruncated

      public void setTruncated(boolean truncated)
      It will be invoked by BasicStyledLabelUI each time the StyledLabel is painted. Please do NOT try to call this method to change the flag and NOT expect the setting could change the behavior of isTruncated().
      Parameters:
      truncated - the flag
      Since:
      3.2.1