com.jidesoft.swing

Class StyledLabelBuilder

java.lang.Object

com.jidesoft.swing.StyledLabelBuilder

public class StyledLabelBuilder
extends Object

StyledLabelBuilder is a quick way to define StyledLabel. It provides two ways to handle the creation and modification of StyleLabels.

The first is to use it as a builder (thus the name). This way is preferred if you want to create a StyledLabel with a specific format and partially generic content. Example:

StyledLabel label = new StyledLabelBuilder()
        .add(file.getName())
        .add(" (", Font.BOLD)
        .add(file.getPath(), "italic") // using annotation style - see section two for information about annotations
        .add(")", Font.BOLD)
        .createLabel();

This code would be used to create a label like "something.txt (/temp/something.txt)" with some styling (the braces would be bold, the path would be italic). In case you find yourself reusing a specific style quite often in such a label you might consider to create a style for it. This can be done with the help of the register(java.lang.String, java.awt.Color)-methods. As an example, the code above could be rewritten like this (though it only pays off when used for creation of longer styles):

StyledLabelBuilder builder = new StyledLabelBuilder()
        .register("OPERATOR", Font.BOLD, new Color(0x000052)) // use parameters
        .register("PATH", "italic, f:#0000CD"); // or style annotations
 StyledLabel label = builder
        .add(file.getName())
        .add(" (", "OPERATOR")
        .add(file.getPath(), "PATH,underlined") // use a style + style annotation
        .add(")", "OPERATOR")
        .createLabel();

Note that we're using different font colors this time. It pays off as soon as you want to modify a specific group of text parts or as your styles start to get more complicated. The clear()-method is very useful if you want to use these styles. Instead of re-creating a new builder each time, you can use the clear-method to clear the internal buffer of text without removing the previously defined styles.

Let's have an example (we're going to reuse the code from above!):

builder.clear();
 builder
        .add(file.getName())
        .add(" (", "OPERATOR")
        .add(file.getPath(), "PATH")
        .add(")", "OPERATOR")
  .configure(label);

Please be noted that you need escape the ":" in your text string when necessary. For example, "{00:00:00:BOLD}" need to be changed as "{00\\:00\\:00:BOLD}.

If we were using Java 5, we could also do this:

// no need to call clear() this time
 builder.configure(label, String.format("%s ({%s:PATH})", file.getName(), file.getPath()));

Each of the add(java.lang.String) and register(java.lang.String, java.awt.Color) methods is the same as using the corresponding StyleRange-constructor directly (except that you don't have to care about its start and length).

The second, even more advanced, way to use this class is in combination with an annotated string. Using the static setStyledText(com.jidesoft.swing.StyledLabel, java.lang.String) or createStyledLabel(java.lang.String) methods you can create a fully styled label from just on string. This is ideal if you need the string to be configurable or locale-specific. The usage is even more easy than the builder-approach: StyledLabel label = StyledLabelBuilder.createStyledLabel("I'm your {first:bold} styled {label:italic}!"); In the above example, the resulting label would have a a bold "first" and an italic "label". Each annotation is started by a "{" and ended by a "}". The text you want to be styled accordingly is separated from its annotations by a ":". If your text needs to contain a ":" itself, you need to escape it using the "\" character. The same goes for "{" that are not supposed to start an annotation. You don't need to escape the "}" at all. If it is used within the annotated string it'll be ignored. It only counts after the annotation separator (":"). There are multiply annotations available. Each annotation offers a shortcut made up from one or two of their characters. For example: We used "bold" and "italic" in the example above, but we could've used "b" and "i" instead. It is also possible to combine multiple styles by separating them with a ",". As an example: {This text is bold, italic and blue:b,i,f:blue} Instead of writing "b,i" you can also write "bi" or "bolditalic". This example brings us to colors. They've to be started with "f" or "font" for the font-color or "l" or "line" for the line-color or "b" or "background" for the background color. There are a lot of ways to specify a color. You may use its HTML name (as I did in the above example) or any of these: f:(0,0,255) f:#00F l:#0000FF l:0x0000FF The "#00F" notation is just like it is in CSS. It is the same as if you had written "#0000FF". You can get and modify the map of color-names the parser is using with the static getColorNamesMap()-method.

You saw some styles above. Here is a complete list of styles and its shortcut.

Font styles

• plain or p
• bold or b
• italic or i
• bolditalic or bi

Additional styles

• strike or s
• doublestrike or ds
• waved or w
• underlined or u
• dotted or d
• superscript or sp
• subscript or sb

Global flags: You can enable global flags by using "@" at the end of the String.

• rows or row or r: it can take up to three parameters separately ":". The first one is preferred rows, the second one is minimum rows and the last one is the maximum rows.

Author:

Patrick Gotthardt

Constructor Summary

Constructors

Constructor and Description
StyledLabelBuilder()

Method Summary

Methods

Modifier and Type	Method and Description
StyledLabelBuilder	add(String text)
StyledLabelBuilder	add(String text, Color fontColor)
StyledLabelBuilder	add(String text, int fontStyle)
StyledLabelBuilder	add(String text, int fontStyle, Color fontColor)
StyledLabelBuilder	add(String text, int fontStyle, Color fontColor, Color backgroundColor, int additionalStyle, Color lineColor)
StyledLabelBuilder	add(String text, int fontStyle, Color fontColor, Color backgroundColor, int additionalStyle, Color lineColor, Stroke lineStroke)
StyledLabelBuilder	add(String text, int fontStyle, Color fontColor, int additionalStyle)
StyledLabelBuilder	add(String text, int fontStyle, Color fontColor, int additionalStyle, Color lineColor)
StyledLabelBuilder	add(String text, int fontStyle, Color fontColor, int additionalStyle, Color lineColor, Stroke lineStroke, float fontShrinkRatio)
StyledLabelBuilder	add(String text, int fontStyle, int additionalStyle)
StyledLabelBuilder	add(String text, int fontStyle, int additionalStyle, float fontShrinkRatio)
StyledLabelBuilder	add(String text, String style)
void	clear()
StyledLabel	configure(StyledLabel label)
StyledLabel	configure(StyledLabel label, String style)
StyledLabel	createLabel()
static StyledLabel	createStyledLabel(String text)
static Map	getColorNamesMap()
static String	parseToVoidStyledTextConfusion(String originalString) This method need to be invoked to format your string before you invoke setStyledText(StyledLabel, String) or setStyledText(StyledLabel, char[])
StyledLabelBuilder	register(String text, Color fontColor)
StyledLabelBuilder	register(String text, int fontStyle)
StyledLabelBuilder	register(String text, int fontStyle, Color fontColor)
StyledLabelBuilder	register(String text, int fontStyle, Color fontColor, int additionalStyle)
StyledLabelBuilder	register(String text, int fontStyle, Color fontColor, int additionalStyle, Color lineColor)
StyledLabelBuilder	register(String text, int fontStyle, Color fontColor, int additionalStyle, Color lineColor, Stroke lineStroke)
StyledLabelBuilder	register(String text, int fontStyle, Color fontColor, int additionalStyle, Color lineColor, Stroke lineStroke, float fontShrinkRatio)
StyledLabelBuilder	register(String text, int fontStyle, int additionalStyle)
StyledLabelBuilder	register(String text, int fontStyle, int additionalStyle, float fontShrinkRatio)
StyledLabelBuilder	register(String text, String format)
static void	setStyledText(StyledLabel label, char[] text) Before your call this method, you need call {link@ #parseToVoidStyledTextConfusion(String)} to make sure the text will not contain confusion "\" or "{"
static void	setStyledText(StyledLabel label, String text) Before your call this method, you need call {link@ #parseToVoidStyledTextConfusion(String)} to make sure the text will not contain confusion "\" or "{"

Methods inherited from class java.lang.Object

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

Constructor Detail

StyledLabelBuilder

public StyledLabelBuilder()

Method Detail

clear

public void clear()

register

public StyledLabelBuilder register(String text,
                          Color fontColor)

register

public StyledLabelBuilder register(String text,
                          int fontStyle)

register

public StyledLabelBuilder register(String text,
                          int fontStyle,
                          Color fontColor)

register

public StyledLabelBuilder register(String text,
                          int fontStyle,
                          Color fontColor,
                          int additionalStyle)

register

public StyledLabelBuilder register(String text,
                          int fontStyle,
                          Color fontColor,
                          int additionalStyle,
                          Color lineColor)

register

public StyledLabelBuilder register(String text,
                          int fontStyle,
                          Color fontColor,
                          int additionalStyle,
                          Color lineColor,
                          Stroke lineStroke)

register

public StyledLabelBuilder register(String text,
                          int fontStyle,
                          Color fontColor,
                          int additionalStyle,
                          Color lineColor,
                          Stroke lineStroke,
                          float fontShrinkRatio)

register

public StyledLabelBuilder register(String text,
                          int fontStyle,
                          int additionalStyle)

register

public StyledLabelBuilder register(String text,
                          int fontStyle,
                          int additionalStyle,
                          float fontShrinkRatio)

register

public StyledLabelBuilder register(String text,
                          String format)

add

public StyledLabelBuilder add(String text)

add

public StyledLabelBuilder add(String text,
                     Color fontColor)

add

public StyledLabelBuilder add(String text,
                     int fontStyle)

add

public StyledLabelBuilder add(String text,
                     int fontStyle,
                     Color fontColor)

add

public StyledLabelBuilder add(String text,
                     int fontStyle,
                     Color fontColor,
                     int additionalStyle)

add

public StyledLabelBuilder add(String text,
                     int fontStyle,
                     Color fontColor,
                     int additionalStyle,
                     Color lineColor)

add

public StyledLabelBuilder add(String text,
                     int fontStyle,
                     Color fontColor,
                     Color backgroundColor,
                     int additionalStyle,
                     Color lineColor)

add

public StyledLabelBuilder add(String text,
                     int fontStyle,
                     Color fontColor,
                     Color backgroundColor,
                     int additionalStyle,
                     Color lineColor,
                     Stroke lineStroke)

add

public StyledLabelBuilder add(String text,
                     int fontStyle,
                     Color fontColor,
                     int additionalStyle,
                     Color lineColor,
                     Stroke lineStroke,
                     float fontShrinkRatio)

add

public StyledLabelBuilder add(String text,
                     String style)

add

public StyledLabelBuilder add(String text,
                     int fontStyle,
                     int additionalStyle)

add

public StyledLabelBuilder add(String text,
                     int fontStyle,
                     int additionalStyle,
                     float fontShrinkRatio)

configure

public StyledLabel configure(StyledLabel label,
                    String style)

configure

public StyledLabel configure(StyledLabel label)

createLabel

public StyledLabel createLabel()

createStyledLabel

public static StyledLabel createStyledLabel(String text)

setStyledText

public static void setStyledText(StyledLabel label,
                 String text)

Before your call this method, you need call {link@ #parseToVoidStyledTextConfusion(String)} to make sure the text will not contain confusion "\" or "{"

Parameters:

label - the styledLabel to be set with the text

text - the styled text

setStyledText

public static void setStyledText(StyledLabel label,
                 char[] text)

Before your call this method, you need call {link@ #parseToVoidStyledTextConfusion(String)} to make sure the text will not contain confusion "\" or "{"

Parameters:

label - the styledLabel to be set with the text

text - the styled text

parseToVoidStyledTextConfusion

public static String parseToVoidStyledTextConfusion(String originalString)

This method need to be invoked to format your string before you invoke setStyledText(StyledLabel, String) or setStyledText(StyledLabel, char[])

Parameters:

originalString - the original string.

Returns:

a parsed string with "\" replaced by "\\" and "{" replaced by "\{".

getColorNamesMap

public static Map getColorNamesMap()