org.eclipse.ercp.swt.mobile
Class CaptionedControl

java.lang.Object
  org.eclipse.swt.widgets.Widget
      org.eclipse.swt.widgets.Control
          org.eclipse.swt.widgets.Scrollable
              org.eclipse.swt.widgets.Composite
                  org.eclipse.ercp.swt.mobile.CaptionedControl

All Implemented Interfaces:

Drawable

public class CaptionedControl

extends Composite

A CaptionedControl is used to display a label (caption) in front of a control. An optional trailing text can be used after the control, for example, to indicate units of measurement.

The highlighting is implementation dependent. Typically, a focused CaptionedControl will highlight all its elements, i.e. the leading label, the control, and optional trailing label, when it gets focus. The positioning order for the captions is determined by the SWT.LEFT_TO_RIGHT and SWT.RIGHT_TO_LEFT styles hints.

CaptionedControl does not support nested CaptionedControls. An exception will be thrown when an instance of CaptionedControl is given as the constructor's argument. To change the control contained by the CaptionedControl, a new control can be created using the CaptionedControl as its parent control. The old control must be disposed by the application manually. Only one control can be active and visible in a CaptionedControl. Which control is displayed when multiple controls have been added is implementation-dependent.

Example code:

 CaptionedControl control = new CaptionedControl(shell, SWT.NONE);
 ConstraintedText currency = new ConstraintedText(control, SWT.NONE,
 		ConstraintedText.NUMERIC);
 control.setText("Velocity");
 control.getTrailingText("cm");
 

Styles:

SWT.LEFT_TO_RIGHT (default)

SWT.RIGHT_TO_LEFT

Events:

(none)

Note: Even though this class is a subclass of Composite, setting a layout on it is not supported.

IMPORTANT: This class is not intended to be subclassed.

Constructor Summary

CaptionedControl(Composite parent, int style)
Constructs a new instance of this class given its parent and a style value describing its behavior and appearance.

Method Summary

Image	getImage() Returns the CaptionedControl's icon image, or null if it has never been set.
java.lang.String	getText() Gets the caption text, which will be an empty string if it has never been set.
java.lang.String	getTrailingText() Gets the trailing text, which will be an empty string if it has never been set.
void	setImage(Image image) Sets the image as an icon to the CaptionedControl.
void	setText(java.lang.String string) Sets the caption label
void	setTrailingText(java.lang.String string) Sets the trailing label

Methods inherited from class org.eclipse.swt.widgets.Composite

checkSubclass, getChildren, getLayout, getTabList, layout, layout, setLayout, setTabList

Methods inherited from class org.eclipse.swt.widgets.Scrollable

computeTrim, getClientArea, getHorizontalBar, getVerticalBar

Methods inherited from class org.eclipse.swt.widgets.Control

addControlListener, addFocusListener, addKeyListener, addMouseListener, addMouseMoveListener, addPaintListener, addTraverseListener, computeSize, computeSize, forceFocus, getBackground, getBorderWidth, getBounds, getEnabled, getFont, getForeground, getLayoutData, getLocation, getMenu, getParent, getShell, getSize, getToolTipText, getVisible, isEnabled, isFocusControl, isReparentable, isVisible, moveAbove, moveBelow, pack, pack, redraw, redraw, removeControlListener, removeFocusListener, removeKeyListener, removeMouseListener, removeMouseMoveListener, removePaintListener, removeTraverseListener, setBackground, setBounds, setBounds, setCapture, setEnabled, setFocus, setFont, setForeground, setLayoutData, setLocation, setLocation, setMenu, setParent, setRedraw, setSize, setSize, setToolTipText, setVisible, toControl, toControl, toDisplay, toDisplay, traverse, update

Methods inherited from class org.eclipse.swt.widgets.Widget

addDisposeListener, addListener, checkWidget, dispose, getData, getData, getDisplay, getStyle, isDisposed, isListening, notifyListeners, removeDisposeListener, removeListener, removeListener, setData, setData, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

CaptionedControl

public CaptionedControl(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 - a widget which will be the parent of the new instance (cannot be null)

style - the style of widget to construct

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the parent is null

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
• ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass

See Also:

SWT.LEFT_TO_RIGHT, SWT.RIGHT_TO_LEFT

Method Detail

setText

public void setText(java.lang.String string)

Sets the caption label

Parameters:

string - the new caption label

Throws:

java.lang.IllegalArgumentException - ERROR_NULL_ARGUMENT if the text is null

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent

See Also:

getText()

setTrailingText

public void setTrailingText(java.lang.String string)

Sets the trailing label

Parameters:

string - the new trailing label

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the string is null

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent

See Also:

getTrailingText()

getText

public java.lang.String getText()

Gets the caption text, which will be an empty string if it has never been set.

Returns:

The label text.

Throws:

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent

See Also:

setText(java.lang.String)

getTrailingText

public java.lang.String getTrailingText()

Gets the trailing text, which will be an empty string if it has never been set.

Returns:

The trailing text.

Throws:

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent

See Also:

setTrailingText(java.lang.String)

setImage

public void setImage(Image image)

Sets the image as an icon to the CaptionedControl. The icon can co-exist with caption text. The icon position is platform-dependent.

The parameter can be null indicating that no image should be displayed. The implementation will adjust the image size to make it best fit the CaptionedControl.

Parameters:

image - the image to display on the receiver

Throws:

java.lang.IllegalArgumentException -

• ERROR_INVALID_ARGUMENT - if the image has been disposed

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

getImage

public Image getImage()

Returns the CaptionedControl's icon image, or null if it has never been set.

Returns:

the icon image or null.

Throws:

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

See Also:

setImage(Image)