WDecoratedLabel

WDecoratedLabel is a labeling component for a number of other WComponents but may also be used as a stand-alone component. It contains one to three sub components. The styling and relationship of these sub components is determined by the parent WComponent.

• Why use WDecoratedLabel
  • When not to use
• Creating WDecoratedLabel
  • Implicit constructors
• Adding content
  • Content restrictions
• Structure
  • Accessing content
• WComponents using WDecoratedLabel
• Hiding
  • Do not hide labelling elements
• Further information

Why use WDecoratedLabel

WDecoratedLabel may be used as a stand-alone component but this is rather difficult to justify. It is usually used as the labelling component for another WComponent.

When not to use

WDecoratedLabel is not a more convoluted version of WLabel and must not be used to label data input controls.

Creating WDecoratedLabel

WDecoratedLabel has four constructors. The default constructor will create an empty WDecoratedLabel component. There is a constructor which takes a single WComponent argument which will create a WDecoratedLabel with the passed-in component in its body segment. The third constructor takes three WComponent arguments; the first in placed in the head segment, the second in the body segment and the third in the tail segment (see structure).

// an empty WDecoratedLabel
WDecoratedLabel dl = new WDecoratedLabel();

// one containing a WComponent `content` in its body segment
WDecoratedLabel dlWithBodyContent = new WDecoratedLabel(content);

// one containing three content WComponents `headContent`,
// `bodyContent` and `tailContent`
WDecoratedLabel dlWithContent =
    new WDecoratedLabel(headContent, bodyContent, tailContent);

Finally there is a constructor which accepts a String and an optional Serializable. This is used to create a WDecoratedLabel containing a WText in the body segment. The WText contains the String (which may be modified by the Serializable - if present, eg to internationalise).

WDecoratedLabel dlWithTextContent = new WDecoratedLabel("Some labelling text");

Implicit constructors

A WDecoratedLabel will be created implicitly during construction of WComponents which use WDecoratedLabel as a labelling component (unless that WComponent is itself instantiated using a constructor which accepts a WDecoratedLabel as an argument) except WHeading (no, I do not know why this exception exists).

These WComponents all have a method to get the WDecoratedLabel.

// Use WFieldSet as an example
// create a WFieldSet with a text legend
WFieldSet fs = new WFieldSet("Legend text");

// ...

// The text legend is contained within a WDecoratedLabel
// as the `body` segment:
WDecoratedLabel dl = fs.getTitle();
WText legendText = dl.getBody();
String legend = legendText.getText(); // is "Legend text"
// and someone claimed Java was convoluted...

Adding content

Whilst any WComponent may be added to a WDecoratedLabel some are not appropriate for some uses. WText is probably the best content component to use in most cases where WDecoratedLabel is used to label another component. When the WDecoratedLabel is used as a labelling component the the content should, of course, be appropriate to describe the parent component.

To add content to an existing WDecoratedLabel the content component is set as the content of a particular segment as shown below. These methods can also be used to replace an existing content component.

// add `component` to the `head` segment:
dl.setHead(component);
// add `component` to the `body` segment:
dl.setBody(component);
// add `component` to the `tail` segment:
dl.setTail(component);

To remove a content component use the appropriate setter with a null argument.

// Given WDecoratedLabel `dl` with a head component,
// to remove the head component:
dl.setHead(null);

If the WDecoratedLabel body component is not set or is one of WText, WLabel, WButton or WLink then the body component's text may also be set or updated using setText(String) as shown below.

// Given WDecoratedLabel dl with `body` component WLabel `label`
// the following will set the text of the WLabel
dl.setText("New label text");

// given WDecoratedLabel with no body segment
// the following will set the body segment to a WText
// containing the provided String
WDecoratedLabel dl = new WDecoratedLabel(); // no body
dl.setText("Label content");
// dl now has a WText as its body component. The WText contains
// the provided String.

Content may be added or set in WDecoratedLabels which are created implicitly by another component.

// Using WSection `section` as an example
WDecoratedLabel dl = section.getDecoratedLabel();
if (dl != null) {
	// with WComponent `tailComponent`
	dl.setTail(tailComponent);
}

Content restrictions

WDecoratedLabel may only contain WComponents which output phrasing content except when used in the following scenarios:

• as the column heading component of a WTableColumn;
• as the caption of a WFigure; or
• as the header of a WSection - note though that in this case the the body component must be a WComponent which outputs phrasing content and it is recommended that this be simple text (using WText).

It is recommended that WDecoratedLabel never contain interactive content. When the WDecoratedLabel is the label component of a WMenuItem or WSubMenu the the content component(s) must not contain interactive content.

Structure

A WDecoratedLabel consists of 1 to 3 sections. Each of these is usually output as the same HTML element as the WDecoratedLabel. There is always a body child element. There may be one or both of a head and/or tail child elements. The head, if present, is output before the body. The tail, if present, is output after the body. Within a single WDecoratedLabel the elements will normally render inline within the content box of the WDecoratedLabel.

Accessing content

Each segment's content component may be accessed using the appropriate segment getter.

// With WDecoratedLabel `dl` get the `head` component
WComponent tailComponent = dl.getHead();
// With WDecoratedLabel `dl` get the `body` component
WComponent tailComponent = dl.getBody();
// With WDecoratedLabel `dl` get the `tail` component
WComponent tailComponent = dl.getTail();

Obviously the returned component, if not null, will be a WComponent and therefore may have to be cast to be useful. Next we will be learning how to suck lemons.

WComponents using WDecoratedLabel

The following WComponents have a WComponent as a label element.

• WCollapsible;
• WFieldSet;
• WFigure;
• WHeading;
• WMenuItem;
• WSection;
• WSubMenu;
• WTab; and
• WTableColumn.

Hiding

A WDecoratedLabel may be hidden on page load. When hidden the WDecoratedLabel is not available to any compliant user agent. It is present in the source and is not obscured in any way. This property is determined by a WSubordinateControl. When a WDecoratedLabel is hidden all of its content is hidden.

Do not hide labelling elements

If the WDecoratedLabel is a labelling component of another WComponent then it should not be hidden independently of the containing component. If one specifies a WDecoratedLabel be hidden when it is the labelling element of another WComponent the application may not be accessible to all users.

Further information

• JavaDoc;
• List of WComponents.