Label
is a text component that you can use to
display non-editable text. The text will wrap
around if the width of the containing component limits the length of the
lines, except for the preformatted text.
/* Some container for the Label. */ Panel panel = new Panel("Panel Containing a Label"); main.addComponent(panel); panel.addComponent(new Label("This is a Label inside a Panel. There is enough " + "text in the label to make the text wrap if it " + "exceeds the width of the panel."));
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:
Table 4.1. Content Modes for Label
CONTENT_DEFAULT |
The default content mode is
CONTENT_TEXT (see below).
|
CONTENT_PREFORMATTED |
Content mode, where the label contains preformatted
text. It will be, by default, rendered with a
fixed-width typewriter font. Preformatted text can
contain line breaks, written in Java with the
\n escape sequence for a newline
character (ASCII 0x0a), or tabulator characters
written with \t (ASCII 0x08).
|
CONTENT_RAW | Content mode, where the label contains raw text. Output is not required to be valid XML. It can be, for example, HTML, which can be unbalanced or otherwise invalid XML. The example below uses the <br> tag in HTML. While XHTML should be preferred in most cases, this can be useful for some specific purposes where you may need to display loosely formatted HTML content. The raw mode also preserves character entities, some of which might otherwise be interpreted incorrectly. |
CONTENT_TEXT |
Content mode, where the label contains only plain
text. All characters are allowed, including the
special < ,
> , and &
characters in XML or HTML, which are quoted properly
in XHTML while rendering the component. This is the
default mode.
|
CONTENT_UIDL | Formatted content mode, where the contents are XML that is restricted to UIDL 1.0, the internal language of IT Mill Toolkit for AJAX communications between the server and the browser. Obsolete since IT Mill Toolkit 5.0. |
CONTENT_XHTML |
Content mode, where the label contains XHTML. The
content will be enclosed in a DIV element having the
namespace
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd ".
|
CONTENT_XML | Content mode, where the label contains well-formed and well-balanced XML. Each of the root elements must have their default namespace specified. |
Notice that the validity of XML or XHTML in a Label is not checked in the server during rendering of the component and any errors can result in an error in the browser! You should validate the content before displaying it in the component, especially if it comes from an uncertain source.
The following example demonstrates the use of
Label
in different modes.
GridLayout labelgrid = new GridLayout (2,1); labelgrid.addComponent (new Label ("CONTENT_DEFAULT")); labelgrid.addComponent (new Label ("This is a label in default mode: <plain text>", Label.CONTENT_DEFAULT)); labelgrid.addComponent (new Label ("CONTENT_PREFORMATTED")); labelgrid.addComponent (new Label ("This is a preformatted label.\n"+ "The newline character \\n breaks the line.", Label.CONTENT_PREFORMATTED)); labelgrid.addComponent (new Label ("CONTENT_RAW")); labelgrid.addComponent (new Label ("This is a label in raw mode.<br>It can contain, "+ "for example, unbalanced markup.", Label.CONTENT_RAW)); labelgrid.addComponent (new Label ("CONTENT_TEXT")); labelgrid.addComponent (new Label ("This is a label in (plain) text mode", Label.CONTENT_TEXT)); labelgrid.addComponent (new Label ("CONTENT_XHTML")); labelgrid.addComponent (new Label ("<i>This</i> is an <b>XHTML</b> formatted label", Label.CONTENT_XHTML)); labelgrid.addComponent (new Label ("CONTENT_XML")); labelgrid.addComponent (new Label ("This is an <myelement>XML</myelement> formatted "+ "label", Label.CONTENT_XML)); main.addComponent(labelgrid);
The rendering will look as follows:
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, and not flexible enough if
the content needs to be dynamically generated.
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.