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-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 and
#register 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 or
#createStyledLabel 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.