Top Description Fields Constructors Methods
org.eclipse.swt.custom

public Class CLabel

extends Canvas
Class Inheritance
Imports
org.eclipse.swt.*, org.eclipse.swt.accessibility.*, org.eclipse.swt.events.*, org.eclipse.swt.graphics.*, org.eclipse.swt.widgets.*
A Label which supports aligned text and/or an image and different border styles.

If there is not enough space a CLabel uses the following strategy to fit the information into the available space: 

 		ignores the indent in left align mode
 		ignores the image and the gap
 		shortens the text by replacing the center portion of the label with an ellipsis
 		shortens the text by removing the center portion of the label
Styles:
LEFT, RIGHT, CENTER, SHADOW_IN, SHADOW_OUT, SHADOW_NONE
Events:
(NONE)

This class may be subclassed for the purpose of overriding the default string shortening algorithm that is implemented in method shortenText().

See Also
SWT Example: CustomControlExample, Sample code and further information, CLabel#shortenText(GC, String, int)

Field Summary

Modifier and TypeField and Description
private int
align

the alignment.

private String
appToolTipText

private Color
background

private Image
backgroundImage

Hides org.eclipse.swt.widgets.Control.backgroundImage.

private int
bottomMargin

private static final int
DEFAULT_MARGIN

Left and right margins

private static int
DRAW_FLAGS

private static final String
ELLIPSIS

a string inserted in the middle of text that has been shortened

private static final int
GAP

Gap between icon and text

private Color[]
gradientColors

private int[]
gradientPercents

private boolean
gradientVertical

private boolean
ignoreDispose

private Image
image

the current icon

private int
leftMargin

private int
rightMargin

private String
text

the current text

private int
topMargin

Constructor Summary

AccessConstructor and Description
public
CLabel(Composite
a widget which will be the parent of the new instance (cannot be null)
parent, int
the style of widget to construct
style)

Constructs a new instance of this class given its parent and a style value describing its behavior and appearance.

Method Summary

Modifier and TypeMethod and Description
pack-priv char
_findMnemonic(String string)

private static int
checkStyle(int style)

Hides org.eclipse.swt.widgets.Composite.checkStyle.

Check the style bits to ensure that no invalid styles are applied.
public Point
computeSize(int
the width hint (can be SWT.DEFAULT)
wHint, int
the height hint (can be SWT.DEFAULT)
hHint, boolean
true if the control's contents have changed, and false otherwise
changed)

Overrides org.eclipse.swt.widgets.Control.computeSize.

Returns the preferred size (in points) of the receiver.
private void
drawBevelRect(GC gc, int x, int y, int w, int h, Color topleft, Color bottomright)

Draw a rectangle in the given colors.

public int

Returns:

SWT.LEFT, SWT.RIGHT or SWT.CENTER
getAlignment()

Returns the horizontal alignment.

public int

Returns:

the bottom margin of the label
getBottomMargin()

Return the CLabel's bottom margin.

public Image

Returns:

the image of the label or null
getImage()

Return the CLabel's image or null.

public int

Returns:

the left margin of the label
getLeftMargin()

Return the CLabel's left margin.

public int

Returns:

the right margin of the label
getRightMargin()

Return the CLabel's right margin.

public int
getStyle()

Overrides org.eclipse.swt.widgets.Widget.getStyle.

Returns the receiver's style information.
public String

Returns:

the text of the label or null
getText()

Return the Label's text.

public String
getToolTipText()

Overrides org.eclipse.swt.widgets.Control.getToolTipText.

Returns the receiver's tool tip text, or null if it has not been set.
public int

Returns:

the top margin of the label
getTopMargin()

Return the CLabel's top margin.

private Point
getTotalSize(Image image, String text)

Compute the minimum size.

private void
initAccessible()

pack-priv void
onDispose(Event event)

pack-priv void
onMnemonic(TraverseEvent event)

pack-priv void
onPaint(PaintEvent event)

private void
paintBorder(GC gc, Rectangle r)

Paint the Label's border.

public void
setAlignment(int
the alignment style of LEFT, RIGHT or CENTER
align)

Set the horizontal alignment of the CLabel.

public void
setBackground(Color
the new color (or null)
color)

Overrides org.eclipse.swt.widgets.Control.setBackground.

Sets the receiver's background color to the color specified by the argument, or to the default system color for the control if the argument is null.
public void
setBackground(Color[]
an array of Color that specifies the colors to appear in the gradient in order of appearance from left to right; The value null clears the background gradient; the value null can be used inside the array of Color to specify the background color.
colors, int[]
an array of integers between 0 and 100 specifying the percent of the width of the widget at which the color should change; the size of the percents array must be one less than the size of the colors array.
percents)

Specify a gradient of colours to be drawn in the background of the CLabel.

public void
setBackground(Color[]
an array of Color that specifies the colors to appear in the gradient in order of appearance from left/top to right/bottom; The value null clears the background gradient; the value null can be used inside the array of Color to specify the background color.
colors, int[]
an array of integers between 0 and 100 specifying the percent of the width/height of the widget at which the color should change; the size of the percents array must be one less than the size of the colors array.
percents, boolean
indicate the direction of the gradient. True is vertical and false is horizontal.
vertical)

Specify a gradient of colours to be drawn in the background of the CLabel.

public void
setBackground(Image
the image to be drawn in the background
image)

Set the image to be drawn in the background of the label.

public void
setBottomMargin(int
the bottom margin of the label, which must be equal to or greater than zero
bottomMargin)

Set the label's bottom margin, in points.

public void
setFont(Font
the new font (or null)
font)

Overrides org.eclipse.swt.widgets.Canvas.setFont.

Sets the font that the receiver will use to paint textual information to the font specified by the argument, or to the default font for that kind of control if the argument is null.
public void
setImage(Image
the image to be displayed in the label or null
image)

Set the label's Image.

public void
setLeftMargin(int
the left margin of the label, which must be equal to or greater than zero
leftMargin)

Set the label's horizontal left margin, in points.

public void
setMargins(int
the left margin.
leftMargin, int
the top margin.
topMargin, int
the right margin.
rightMargin, int
the bottom margin.
bottomMargin)

Set the label's margins, in points.

public void
setRightMargin(int
the right margin of the label, which must be equal to or greater than zero
rightMargin)

Set the label's right margin, in points.

public void
setText(String
the text to be displayed in the label or null
text)

Set the label's text.

public void
setToolTipText(String
the new tool tip text (or null)
string)

Overrides org.eclipse.swt.widgets.Control.setToolTipText.

Sets the receiver's tool tip text to the argument, which may be null indicating that the default tool tip for the control will be shown.
public void
setTopMargin(int
the top margin of the label, which must be equal to or greater than zero
topMargin)

Set the label's top margin, in points.

protected String

Returns:

the shortened text
shortenText(GC
the gc to use for text measurement
gc, String
the text to shorten
t, int
the width to shorten the text to, in points
width)

Shorten the given text t so that its length doesn't exceed the given width.

private String[]
splitString(String text)

pack-priv int
validateOffset(TextLayout layout, int offset)

Inherited from org.eclipse.swt.widgets.Canvas:
drawBackgroundgetCaretgetIMEscrollsetCaretsetIME

Field Detail

alignback to summary
private int align

the alignment. Either CENTER, RIGHT, LEFT. Default is LEFT

appToolTipTextback to summary
private String appToolTipText
backgroundback to summary
private Color background
backgroundImageback to summary
private Image backgroundImage

Hides org.eclipse.swt.widgets.Control.backgroundImage.

bottomMarginback to summary
private int bottomMargin
DEFAULT_MARGINback to summary
private static final int DEFAULT_MARGIN

Left and right margins

DRAW_FLAGSback to summary
private static int DRAW_FLAGS
ELLIPSISback to summary
private static final String ELLIPSIS

a string inserted in the middle of text that has been shortened

GAPback to summary
private static final int GAP

Gap between icon and text

gradientColorsback to summary
private Color[] gradientColors
gradientPercentsback to summary
private int[] gradientPercents
gradientVerticalback to summary
private boolean gradientVertical
ignoreDisposeback to summary
private boolean ignoreDispose
imageback to summary
private Image image

the current icon

leftMarginback to summary
private int leftMargin
rightMarginback to summary
private int rightMargin
textback to summary
private String text

the current text

topMarginback to summary
private int topMargin

Constructor Detail

CLabelback to summary
public CLabel(Composite parent, int style)

Constructs a new instance of this class given its parent and a style value describing its behavior and appearance.

The style value is either one of the style constants defined in class SWT which is applicable to instances of this class, or must be built by bitwise OR'ing together (that is, using the int "|" operator) two or more of those SWT style constants. The class description lists the style constants that are applicable to the class. Style bits are also inherited from superclasses.

Parameters
parent:Composite

a widget which will be the parent of the new instance (cannot be null)

style:int

the style of widget to construct

Exceptions
IllegalArgumentException:
  • ERROR_NULL_ARGUMENT - if the parent is null
SWTException:
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
See Also
SWT#LEFT, SWT#RIGHT, SWT#CENTER, SWT#SHADOW_IN, SWT#SHADOW_OUT, SWT#SHADOW_NONE, getStyle()

Method Detail

_findMnemonicback to summary
pack-priv char _findMnemonic(String string)
checkStyleback to summary
private static int checkStyle(int style)

Hides org.eclipse.swt.widgets.Composite.checkStyle.

Check the style bits to ensure that no invalid styles are applied.

computeSizeback to summary
public Point computeSize(int wHint, int hHint, boolean changed)

Overrides org.eclipse.swt.widgets.Control.computeSize.

Doc from org.eclipse.swt.widgets.Control.computeSize.

Returns the preferred size (in points) of the receiver.

The preferred size of a control is the size that it would best be displayed at. The width hint and height hint arguments allow the caller to ask a control questions such as "Given a particular width, how high does the control need to be to show all of the contents?" To indicate that the caller does not wish to constrain a particular dimension, the constant SWT.DEFAULT is passed for the hint.

If the changed flag is true, it indicates that the receiver's contents have changed, therefore any caches that a layout manager containing the control may have been keeping need to be flushed. When the control is resized, the changed flag will be false, so layout manager caches can be retained.

Parameters
wHint:int

the width hint (can be SWT.DEFAULT)

hHint:int

the height hint (can be SWT.DEFAULT)

changed:boolean

true if the control's contents have changed, and false otherwise

Returns:Point

the preferred size of the control.

Annotations
@Override
drawBevelRectback to summary
private void drawBevelRect(GC gc, int x, int y, int w, int h, Color topleft, Color bottomright)

Draw a rectangle in the given colors.

getAlignmentback to summary
public int getAlignment()

Returns the horizontal alignment. The alignment style (LEFT, CENTER or RIGHT) is returned.

Returns:int

SWT.LEFT, SWT.RIGHT or SWT.CENTER

getBottomMarginback to summary
public int getBottomMargin()

Return the CLabel's bottom margin.

Returns:int

the bottom margin of the label

Since
3.6
getImageback to summary
public Image getImage()

Return the CLabel's image or null.

Returns:Image

the image of the label or null

getLeftMarginback to summary
public int getLeftMargin()

Return the CLabel's left margin.

Returns:int

the left margin of the label

Since
3.6
getRightMarginback to summary
public int getRightMargin()

Return the CLabel's right margin.

Returns:int

the right margin of the label

Since
3.6
getStyleback to summary
public int getStyle()

Overrides org.eclipse.swt.widgets.Widget.getStyle.

Doc from org.eclipse.swt.widgets.Widget.getStyle.

Returns the receiver's style information.

Note that the value which is returned by this method may not match the value which was provided to the constructor when the receiver was created. This can occur when the underlying operating system does not support a particular combination of requested styles. For example, if the platform widget used to implement a particular SWT widget always has scroll bars, the result of calling this method would always have the SWT.H_SCROLL and SWT.V_SCROLL bits set.

Returns:int

the style bits

Annotations
@Override
getTextback to summary
public String getText()

Return the Label's text.

Returns:String

the text of the label or null

getToolTipTextback to summary
public String getToolTipText()

Overrides org.eclipse.swt.widgets.Control.getToolTipText.

Doc from org.eclipse.swt.widgets.Control.getToolTipText.

Returns the receiver's tool tip text, or null if it has not been set.

Returns:String

the receiver's tool tip text

Annotations
@Override
getTopMarginback to summary
public int getTopMargin()

Return the CLabel's top margin.

Returns:int

the top margin of the label

Since
3.6
getTotalSizeback to summary
private Point getTotalSize(Image image, String text)

Compute the minimum size.

initAccessibleback to summary
private void initAccessible()
onDisposeback to summary
pack-priv void onDispose(Event event)
onMnemonicback to summary
pack-priv void onMnemonic(TraverseEvent event)
onPaintback to summary
pack-priv void onPaint(PaintEvent event)
paintBorderback to summary
private void paintBorder(GC gc, Rectangle r)

Paint the Label's border.

setAlignmentback to summary
public void setAlignment(int align)

Set the horizontal alignment of the CLabel. Use the values LEFT, CENTER and RIGHT to align image and text within the available space.

Parameters
align:int

the alignment style of LEFT, RIGHT or CENTER

Exceptions
SWTException:
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
  • ERROR_INVALID_ARGUMENT - if the value of align is not one of SWT.LEFT, SWT.RIGHT or SWT.CENTER
setBackgroundback to summary
public void setBackground(Color color)

Overrides org.eclipse.swt.widgets.Control.setBackground.

Doc from org.eclipse.swt.widgets.Control.setBackground.

Sets the receiver's background color to the color specified by the argument, or to the default system color for the control if the argument is null.

Note

This operation is a hint and may be overridden by the platform.

Parameters
color:Color

the new color (or null)

Annotations
@Override
setBackgroundback to summary
public void setBackground(Color[] colors, int[] percents)

Specify a gradient of colours to be drawn in the background of the CLabel.

For example, to draw a gradient that varies from dark blue to blue and then to white and stays white for the right half of the label, use the following call to setBackground:

	clabel.setBackground(new Color[]{display.getSystemColor(SWT.COLOR_DARK_BLUE),
		                           display.getSystemColor(SWT.COLOR_BLUE),
		                           display.getSystemColor(SWT.COLOR_WHITE),
		                           display.getSystemColor(SWT.COLOR_WHITE)},
		               new int[] {25, 50, 100});
Parameters
colors:Color[]

an array of Color that specifies the colors to appear in the gradient in order of appearance from left to right; The value null clears the background gradient; the value null can be used inside the array of Color to specify the background color.

percents:int[]

an array of integers between 0 and 100 specifying the percent of the width of the widget at which the color should change; the size of the percents array must be one less than the size of the colors array.

Exceptions
SWTException:
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
  • ERROR_INVALID_ARGUMENT - if the values of colors and percents are not consistent
setBackgroundback to summary
public void setBackground(Color[] colors, int[] percents, boolean vertical)

Specify a gradient of colours to be drawn in the background of the CLabel.

For example, to draw a gradient that varies from dark blue to white in the vertical, direction use the following call to setBackground:

	clabel.setBackground(new Color[]{display.getSystemColor(SWT.COLOR_DARK_BLUE),
		                           display.getSystemColor(SWT.COLOR_WHITE)},
		                 new int[] {100}, true);
Parameters
colors:Color[]

an array of Color that specifies the colors to appear in the gradient in order of appearance from left/top to right/bottom; The value null clears the background gradient; the value null can be used inside the array of Color to specify the background color.

percents:int[]

an array of integers between 0 and 100 specifying the percent of the width/height of the widget at which the color should change; the size of the percents array must be one less than the size of the colors array.

vertical:boolean

indicate the direction of the gradient. True is vertical and false is horizontal.

Exceptions
SWTException:
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
  • ERROR_INVALID_ARGUMENT - if the values of colors and percents are not consistent
Since
3.0
setBackgroundback to summary
public void setBackground(Image image)

Set the image to be drawn in the background of the label.

Parameters
image:Image

the image to be drawn in the background

Exceptions
SWTException:
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
setBottomMarginback to summary
public void setBottomMargin(int bottomMargin)

Set the label's bottom margin, in points.

Parameters
bottomMargin:int

the bottom margin of the label, which must be equal to or greater than zero

Exceptions
SWTException:
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
Since
3.6
setFontback to summary
public void setFont(Font font)

Overrides org.eclipse.swt.widgets.Canvas.setFont.

Doc from org.eclipse.swt.widgets.Control.setFont.

Sets the font that the receiver will use to paint textual information to the font specified by the argument, or to the default font for that kind of control if the argument is null.

Parameters
font:Font

the new font (or null)

Annotations
@Override
setImageback to summary
public void setImage(Image image)

Set the label's Image. The value null clears it.

Parameters
image:Image

the image to be displayed in the label or null

Exceptions
SWTException:
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
setLeftMarginback to summary
public void setLeftMargin(int leftMargin)

Set the label's horizontal left margin, in points.

Parameters
leftMargin:int

the left margin of the label, which must be equal to or greater than zero

Exceptions
SWTException:
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
Since
3.6
setMarginsback to summary
public void setMargins(int leftMargin, int topMargin, int rightMargin, int bottomMargin)

Set the label's margins, in points.

Parameters
leftMargin:int

the left margin.

topMargin:int

the top margin.

rightMargin:int

the right margin.

bottomMargin:int

the bottom margin.

Exceptions
SWTException:
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
Since
3.6
setRightMarginback to summary
public void setRightMargin(int rightMargin)

Set the label's right margin, in points.

Parameters
rightMargin:int

the right margin of the label, which must be equal to or greater than zero

Exceptions
SWTException:
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
Since
3.6
setTextback to summary
public void setText(String text)

Set the label's text. The value null clears it.

Mnemonics are indicated by an '&' that causes the next character to be the mnemonic. When the user presses a key sequence that matches the mnemonic, focus is assigned to the control that follows the label. On most platforms, the mnemonic appears underlined but may be emphasised in a platform specific manner. The mnemonic indicator character '&' can be escaped by doubling it in the string, causing a single '&' to be displayed.

Note

If control characters like '\n', '\t' etc. are used in the string, then the behavior is platform dependent.

Parameters
text:String

the text to be displayed in the label or null

Exceptions
SWTException:
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
setToolTipTextback to summary
public void setToolTipText(String string)

Overrides org.eclipse.swt.widgets.Control.setToolTipText.

Doc from org.eclipse.swt.widgets.Control.setToolTipText.

Sets the receiver's tool tip text to the argument, which may be null indicating that the default tool tip for the control will be shown. For a control that has a default tool tip, such as the Tree control on Windows, setting the tool tip text to an empty string replaces the default, causing no tool tip text to be shown.

The mnemonic indicator (character '&') is not displayed in a tool tip. To display a single '&' in the tool tip, the character '&' can be escaped by doubling it in the string.

Note

This operation is a hint and behavior is platform specific, on Windows for CJK-style mnemonics of the form " (&C)" at the end of the tooltip text are not shown in tooltip.

Parameters
string:String

the new tool tip text (or null)

Annotations
@Override
setTopMarginback to summary
public void setTopMargin(int topMargin)

Set the label's top margin, in points.

Parameters
topMargin:int

the top margin of the label, which must be equal to or greater than zero

Exceptions
SWTException:
  • ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
Since
3.6
shortenTextback to summary
protected String shortenText(GC gc, String t, int width)

Shorten the given text t so that its length doesn't exceed the given width. The default implementation replaces characters in the center of the original string with an ellipsis ("..."). Override if you need a different strategy.

Parameters
gc:GC

the gc to use for text measurement

t:String

the text to shorten

width:int

the width to shorten the text to, in points

Returns:String

the shortened text

splitStringback to summary
private String[] splitString(String text)
validateOffsetback to summary
pack-priv int validateOffset(TextLayout layout, int offset)