org.eclipse.ercp.swt.mobile
Class CaptionedControl

java.lang.Object
  extended by org.eclipse.swt.widgets.Widget
      extended by org.eclipse.swt.widgets.Control
          extended by org.eclipse.swt.widgets.Scrollable
              extended by org.eclipse.swt.widgets.Composite
                  extended by 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.

When using CaptionedControl in a layout and setting layout data, be sure to set the data on the CaptionedControl instance and not on the captioned widget. The internal layout of the CaptionedControl is not user modifyable.

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.


Field Summary
 
Fields inherited from class org.eclipse.swt.widgets.Control
enableTraverse, internal_parent
 
Fields inherited from class org.eclipse.swt.widgets.Widget
internal_handle, internal_style
 
Constructor Summary
CaptionedControl(Composite parent, int style)
           
 
Method Summary
 Control[] getChildren()
          Returns a (possibly empty) array containing the receiver's children.
 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.
protected  void removeInternalFilter()
           
 void setImage(Image image)
          Sets the image as an icon to the CaptionedControl.
 void setLayout(Layout layout)
          Sets the layout which is associated with the receiver to be the argument which may be null.
 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
allowTraverseByArrowKey, checkSubclass, computeSize, getLayout, getTabList, internal_createHandle, internal_getNativeStyle, internal_removeChild, layout, layout, setBounds, setFocus, setSize, setTabList, traverse
 
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, dispose, forceFocus, getBackground, getBorderWidth, getBounds, getEnabled, getFont, getForeground, getLayoutData, getLocation, getMenu, getParent, getShell, getSize, getToolTipText, getVisible, internal_copyArea, internal_dispose_GC, internal_getBounds, internal_getDefaultClipping, internal_new_GC, isEnabled, isEnableTraverse, isFocusControl, isReparentable, isVisible, moveAbove, moveBelow, pack, pack, redraw, redraw, removeControlListener, removeFocusListener, removeKeyListener, removeMouseListener, removeMouseMoveListener, removePaintListener, removeTraverseListener, setBackground, setBounds, setCapture, setEnabled, setFont, setForeground, setLayoutData, setLocation, setLocation, setMenu, setParent, setRedraw, setSize, setToolTipText, setVisible, toControl, toControl, toDisplay, toDisplay, traverse, traverseByArrowKey, traverseGroup, update
 
Methods inherited from class org.eclipse.swt.widgets.Widget
addDisposeListener, addListener, checkWidget, getData, getData, getDisplay, getStyle, internal_sendEvent, isDisposed, isListening, notifyListeners, removeDisposeListener, removeListener, removeListener, sendEvent, 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)
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)

setLayout

public void setLayout(Layout layout)
Description copied from class: Composite
Sets the layout which is associated with the receiver to be the argument which may be null.

Overrides:
setLayout in class Composite
Parameters:
layout - the receiver's new layout or null

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)

getChildren

public Control[] getChildren()
Description copied from class: Composite
Returns a (possibly empty) array containing the receiver's children. Children are returned in the order that they are drawn.

Note: This is not the actual structure used by the receiver to maintain its list of children, so modifying the array will not affect the receiver.

Overrides:
getChildren in class Composite
Returns:
an array of children
See Also:
Control.moveAbove(org.eclipse.swt.widgets.Control), Control.moveBelow(org.eclipse.swt.widgets.Control)

removeInternalFilter

protected void removeInternalFilter()
Overrides:
removeInternalFilter in class Widget