7.1 Class Label - SWT: The Standard Widget Toolkit

7.1 Class Label

7.1.1 Example

7.1.2 Label Hierarchy

7.1.3 Label Styles

Style	Description
SWT.WRAP	Wrap the text to fit the visible area
SWT.LEFT	Left-align the label
SWT.CENTER	Center-align the label
SWT.RIGHT	Right-align the label
SWT.SEPARATOR	Draw a separator instead of text or an image
SWT.HORIZONTAL	Draw the separator horizontally
SWT.VERTICAL	Draw the separator vertically
SWT.SHADOW_IN	Draw the separator with a "shadow in" effect
SWT.SHADOW_OUT`	Draw the separator with a "shadow out" effect

7.1.4 Label Events (none)

Event	Description

Labels are static widgets that draw text, images, or separators. A static control neither takes focus nor participates in tab traversal. Clicking on a static control with the mouse has no effect.

Labels are common, and most programs make use of them. For example, to provide descriptive text, a label is placed in front of a "text entry" field in a dialog. Often a label, acting as a separator, appears in a "wizard" as the line between the wizard content and a row of navigation buttons.

Although it is possible to use SWT graphics operations to draw text, images, and separators, using Label instead ensures that the appropriate operating system theme and colors are used. In addition, because Label is implemented using the underlying native label control, platform-specific automated testing tools and screen readers (used to facilitate computing for the visually impaired) will deal with them correctly.^[1]

^[1] This is just another of the many good reasons to "go native," even for very simple controls.

The following code fragment creates a label using the SWT.NONE style. This is used to indicate that the label will display either text or an image.

Label label = new Label(parent, SWT.NONE);

label.setText("User Name:");

It is interesting to note that Label does not support events other than those inherited from Control. This is a feature of all static controls in SWT, not just Label.

7.1.5 Text and Images

Labels allow you to set the text or image that they display. If you do not set either, the label is empty. An empty label displays the background color or draws using the operating system theme.

setText(String string) Sets the text of a label. If the label is a separator, no action is taken. The string can include mnemonic characters (see Specifying the Mnemonic Character) and line delimiters. When the user presses a key sequence that matches the mnemonic, focus is assigned to the "next" control that follows the label. This is usually the next child in the children list of the parent. If no such child exists, a platform-specific algorithm is applied that finds the closest control.

getText() Returns the label text. This is an empty string if the label is a separator or if the text has never been set.

setImage(Image image) Sets the image for a label. If the label is a separator, no action is taken.

getImage() Returns the label image. This is null if the label is a separator or if the image has never been set.

Text or Image But Not Both As of R3.0, a label can display either a string or an image but not both at the same time.[2] When you set a string and an image, the label displays the last object that you set. This behavior is currently undocumented, so don't rely on it. It is quite possible that a future release of SWT will provide the ability to display both objects. If you need to display both a string and an image in a static control, you can use a CLabel, found in the org.eclipse.swt.custom package.

^[2] This is a platform limitation on X/Motif and Microsoft Windows.

7.1.6 Wrapping

When a label is created with the SWT.WRAP style, it will wrap strings that are too long to fit within the control. If you embed a linefeed character '\n' in the string, the label will always wrap the string at this location. Because the rules for wrapping strings are operating system- and locale-specific and because labels implement these rules correctly, you should use a label to display text that might wrap, rather than writing the code to wrap and draw it yourself.

The following code fragment creates a label and ensures that it will wrap its text. This is achieved by computing the width required to show the string without wrapping, then setting the width of the label to be half of that value.

Label label = new Label(parent, SWT.WRAP);

label.setText("This is a label with text that wraps.");

Point size = label.computeSize(SWT.DEFAULT, SWT.DEFAULT);

label.setSize(size.x / 2, 200);

Sometimes, even though the SWT.WRAP style is set, when used within Layout (see the Layout chapter), the text does not appear to wrap. For an in-depth discussion of this issue, see Forcing Controls to Wrap in the Layout chapter.

7.1.7 Alignment

If you create a label with one of the SWT.LEFT, SWT.CENTER, or SWT.RIGHT^[3] styles, it will horizontally align the text or image. As well as using the style bits, the setAlignment() method can be used to change the label alignment after the control has been created.^[4]

^[3] As of R3.0, the convenience constants SWT.LEAD and SWT.TRAIL were added to support bidirectional (BIDI) languages. These have the same value as SWT.LEFT and SWT.RIGHT. Because SWT uses coordinate mirroring to support BIDI, the use of these convenience constants can make code clearer but is not a requirement. For example, when you left-align a label that was created with the style SWT.RIGHT_TO_LEFT, the result is right-aligned.

^[4] This is an example of a method that can change a widget style after the widget has been created.

setAlignment(int alignment) Sets the alignment of the control to be left-, center-, or right-aligned, depending on the argument, which must be one of SWT.LEFT, SWT.CENTER, or SWT.RIGHT.

getAlignment() Returns the alignment of the control.

The default alignment for Label is SWT.LEFT. The alignment of a label is typically a property that most programs will not change. Instead, the control itself is often aligned with its siblings using setBounds() or Layout.

7.1.8 Separators

Labels are capable of behaving like separators. A separator is a "line" that is drawn by a widget.^[5] The number and position of the lines as well as their shading and color are operating system-dependent. Sometimes nothing is drawn at all, depending on the operating system theme.

^[5] The separator concept also occurs in MenuItem and ToolItem.

To create a label that draws a separator, use the SWT.SEPARATOR style. Note that once the label has been created with this style, it will not draw text or an image. Attempts to set and get either of these properties are ignored.

The orientation of the separator is controlled using style bits SWT .HORIZONTAL and SWT.VERTICAL.

The style bits SWT.SHADOW_IN or SWT.SHADOW_OUT are used to specify the appearance of a shadow for the separator on platforms that support this. Because the appearance of the separator is platform-specific and not all platforms support shadows, these style bits will have no effect on some platforms.

One common use for separators, as was described earlier, is to create the line that separates content from buttons in a wizard dialog. The following code fragment creates this kind of separator.

Label separator =

    new Label(parent, SWT.SEPARATOR | SWT.SHADOW_OUT);