How to use WebStyledLabel

Available since WebLaF v1.2.9 release, updated for WebLaF v1.2.12 release
Requires weblaf-ui module and Java 6 update 30 or any later to run

---

What is it for?

Primary focus of WebStyledLabel component is to replace poorly implemented HTML rendering within Swing labels with a highly optimized styled text rendering. Text rendered using the styled text approach instead of HTML takes around 50 to 100 times less processing time which is a really noticeable difference in applications with a rich UI.

---

What should I know about it?

WebStyledLabel keeps its styles in list of StyleRanges - each of those contains information on a specific text range style (font style, foreground, background etc.). Those can be easily modified in runtime and any changes will be instantly reflected in the text style if it is displayed.

In addition to the custom styles WebStyledLabel has also a few other useful settings:

• wrap - Text wrap type, one of the next: none, character, word or mixed
• horizontalTextAlignment - Horizontal text alignment relative to the icon
• verticalTextAlignment - Vertical text alignment relative to the icon
• rows - Preferred text rows amount
• maximumRows - Maximum text rows amount
• minimumRows - Minimum text rows amount

WebStyledLabel like many other components in WebLaF delegate the actual painting of its content to a decoration painter which uses IContent implementations for content painting. One of IContent implementations is AbstractStyledTextContent - it exists for the sole purpose of highly optimized styled text painting. Specific implementation of AbstractStyledTextContent exists for WebStyledLabel - StyledLabelTextContent, it delegates some settings from the label to the content painting implementation.

It is important to mention that AbstractStyledTextContent can be used not only for WebStyledLabel but also for any other component where you would like to have a styled text painting support. I won't go into details here, but there will be a separate wiki article covering that topic.

---

How to use it?

WebStyledLabel usage is quite simple and straightforward, simply add text and style ranges for it:

public class StyleRanges
{
    public static void main ( final String[] args )
    {
        SwingUtilities.invokeLater ( new Runnable ()
        {
            @Override
            public void run ()
            {
                WebLookAndFeel.install ();

                final WebStyledLabel styledLabel = new WebStyledLabel ( "Custom styled text" );
                styledLabel.addStyleRange ( new StyleRange ( 0, 6, Font.BOLD ) );
                styledLabel.addStyleRange ( new StyleRange ( 7, 6, Color.RED, CustomStyle.waved ) );
                styledLabel.addStyleRange ( new StyleRange ( 14, 4, CustomStyle.strikeThrough ) );

                TestFrame.show ( styledLabel, 150 );
            }
        } );
    }
}

Result should look like this:

As previously mentioned you can also modify styles at runtime:

public class StyleRangesModification
{
    public static void main ( final String[] args )
    {
        SwingUtilities.invokeLater ( new Runnable ()
        {
            @Override
            public void run ()
            {
                WebLookAndFeel.install ();

                final WebStyledLabel styledLabel = new WebStyledLabel ( "Custom styled text" );
                styledLabel.addStyleRange ( new StyleRange ( 0, 6, Font.BOLD ) );
                styledLabel.addStyleRange ( new StyleRange ( 7, 6, Color.RED, CustomStyle.waved ) );
                styledLabel.addStyleRange ( new StyleRange ( 14, 4, CustomStyle.strikeThrough ) );

                final WebButton remove = new WebButton ( "Remove style", new ActionListener ()
                {
                    @Override
                    public void actionPerformed ( final ActionEvent e )
                    {
                        styledLabel.removeStyleRange ( new StyleRange ( 7, 6 ) );
                    }
                } );

                final WebButton add = new WebButton ( "Add style", new ActionListener ()
                {
                    @Override
                    public void actionPerformed ( final ActionEvent e )
                    {
                        styledLabel.addStyleRange ( new StyleRange ( 7, 6, CustomStyle.superscript ) );
                    }
                } );

                TestFrame.show ( false, 100, styledLabel, remove, add );
            }
        } );
    }
}

Text wrap

As you might have noticed from the section above - WebStyledLabel provides multiple ways of wrapping text:

• none - Do not wrap text, similar to how plain JLabel works
• character - Wrap by characters
• word - Wrap by full words only
• mixed - Wrap by full words when possible, otherwise wrap by characters

Each of these wrap types might be quite useful in some specific cases, by default label is set to mixed wrapping as it is the most agile way to wrap text.

Wrapping works only when there is space available to fit in additional lines. For example if you reduce width of the window in the first example from above you will see this:

But then if you increase height of the window wrapping will start to work:

This is an important thing to remember when you are working with your application layout and placing a label that should be wrapped - wrap will only work if layout provides additional space for the label, otherwise it will keep its content in one line. It works like that because the label preferred size will always be equal to one line case unless you have any hard line breaks or rows amount settings set.

Styled text syntax

Even though providing StyleRanges is a quite straightforward way to work with WebStyledLabel it is by far not the most simple and convenient one. For example just to make text underlined you need to add an additional huge line of code:

final WebStyledLabel styledLabel = new WebStyledLabel ( "Underlined" );
styledLabel.addStyleRange ( new StyleRange ( 0, 10, CustomStyle.underlined ) );

And you should also be careful with providing the style range as it should perfectly hit actual text bounds which you want to style, otherwise you are risking to have a completely messed text.

This is one of the main reasons I have introduced custom styled text syntax which makes working with styles much more convenient and simple. Let's look at the previous example implemented through styled text syntax:

final WebStyledLabel styledLabel = new WebStyledLabel ( "{Underlined:u}" );

That's it, that simple! And you will also have exactly the same result visual and object -wise.

You can of course mix multiple styles in the same way you can with StyleRanges:

final WebStyledLabel styledLabel = new WebStyledLabel ( "{Bold:b} {red:b;c(red)} {text:u}{br}{with second line:ds}{tm:sp}" );

And achieve the same results:

Here is a full list of style settings supported in syntax:

• p, plain - Reverts text style to plain
• b, bold - Bold text
• i, italic - Italic text
• u, underlined - Underlined text
• w, waved - Underlined by a wavy line text
• s, strike - Striked text
• ds, doublestrike - Double-striked text
• sp, sup, superscript - Superscript text
• sb, sub, subscript - Subscript text
• c, color, fg, foreground - Text color
• bg, background - Text background color

There are also additional standalone features:

• {br} - hard line break, equal to simple \n

To apply any of the settings above to the text simply enclose it between "{" and "}".
Style settings should be separated from text with ":" and with ";" between each other.
Additional configuration for each separate setting is specified between "(" and ")" right after the setting.

Here are a few examples of style syntax usage:

• {Bold text:b}
• {Bold:b} and {underlined:u} text
• {Italic red text:i;c(red)}
• Text with {superscript:sp} and {subscript:sb}
• {Multiline:b}{br}{styled:u}{br}{text:i}

Custom text size is not yet supported since it heavily affects the layout of each row and might also require some additional settings to be provided. It is certainly on the list of enhancements and will eventually be added.

Support for some other text styling features will also be added with time. If some text styling feature important for you is missing simply post an enhancement request on GitHub:
https://github.com/mgarin/weblaf/issues/new