5.4. Label

The contents of a label are formatted depending on the content mode. By default, the text is assumed to be plain text and any contained XML-specific characters will be quoted appropriately to allow rendering the contents of a label in XHTML in a web browser. The content mode can be set in the constructor or with setContentMode(), and can have the following values:

Using the XHTML, XML, or raw modes allow inclusion of, for example, images within the text flow, which is not possible with any regular layout components. The following example includes an image within the text flow, with the image coming from a class loader resource.

ClassResource labelimage = new ClassResource ("labelimage.jpg",
                                              this);
main.addComponent(new Label("Here we have an image <img src=\"" +
                            this.getRelativeLocation(labelimage) +
                            "\"/> within text.",
                            Label.CONTENT_XHTML));

When you use a class loader resource, the image has to be included in the JAR of the web application. In this case, the labelimage.jpg needs to be in the default package. When rendered in a web browser, the output will look as follows:

Another solution would be to use the CustomLayout component, where you can write the component content as an XHTML fragment in a theme, but such a solution may be too heavy for most cases.

Notice that the rendering of XHTML depends on the assumption that the client software and the terminal adapter are XHTML based. It is possible to write a terminal adapter for a custom thin client application, which may not be able to render XHTML at all. There are also differences between web browsers in their support of XHTML.

You can use a Label to create vertical or horizontal space in a layout. If you need a empty "line" in a vertical layout, having just a label with empty text is not enough, as it will collapse to zero height. The same goes for a label with only whitespace as the label text. You need to use a non-breaking space character, either   or  :

layout.addComponent(new Label(" ", Label.CONTENT_XHTML));

Using the Label.CONTENT_PREFORMATTED mode has the same effect; preformatted spaces do not collapse in a vertical layout. In a HorizontalLayout, the width of a space character may be unpredictable if the label font is proportional, so you can use the preformatted mode to add em-width wide spaces.

If you want a gap that has adjustable width or height, you can use an empty label if you specify a height or width for it. For example, to create vertical space in a VerticalLayout:

Label gap = new Label();
gap.setHeight("1em");
verticalLayout.addComponent(gap);

You can make a flexible expanding spacer by having a relatively sized empty label with 100% height or width and setting the label as expanding in the layout.

// A wide component bar
HorizontalLayout horizontal = new HorizontalLayout();
horizontal.setWidth("100%");

// Have a component before the gap (a collapsing cell)
Button button1 = new Button("I'm on the left");
horizontal.addComponent(button1);

// An expanding gap spacer
Label expandingGap = new Label();
expandingGap.setWidth("100%");
horizontal.addComponent(expandingGap);
horizontal.setExpandRatio(expandingGap, 1.0f);

// A component after the gap (a collapsing cell)
Button button2 = new Button("I'm on the right");
horizontal.addComponent(button2);

The Label component has a v-label overall style.

The Reindeer theme includes a number of predefined styles for typical formatting cases. These include "h1" (Reindeer.LABEL_H1) and "h2" (Reindeer.LABEL_H2) heading styles and "light" (Reindeer.LABEL_SMALL) style.