org.eclipse.ercp.swt.mobile
Class ConstrainedText

java.lang.Object
  org.eclipse.swt.widgets.Widget
      org.eclipse.swt.widgets.Control
          org.eclipse.ercp.swt.mobile.ConstrainedText

All Implemented Interfaces:

Drawable

public final class ConstrainedText

extends Control

A single-line Text control which constrains the user input by styles.

This control limits the characters that users can enter by the styles to make data entry more efficient. This capability is usually implemented by the underlying platform and applications are not allowed to change or override the constraints. An IllegalArgumentException will be thrown if illegal content is set programmatically by applications.

Constraint Styles (exclusive):

NUMERIC: limit to digits and an optional minus sign in the beginning of the string

DECIMAL: limit to digits, fractional separator and an optional minus sign in the beginning of the string

PHONENUMBER: all dialing digitals: 0-9, *, #, +, A, B, C, D and modifier characters , T P ! W @ ; > I i G g. See the standard at 3GPP TS 27.007, ITU-T dial command . In addition to the "standard" characters allowed, a platform may also allow other characters in keeping with the platform's native components.

Events:

Selection, DefaultSelection, Modify

Field Summary

static int	DECIMAL Decimal input style allows the input of numeric values with optional decimal fractions, for example, "-123", "0.123", or ".5" are all valid input.
static int	NUMERIC Numeric input style allows the input of numeric values.
static int	PHONENUMBER Phone number input style allows the input of numeric values with optional phone specific characters like "+", "* and "#".

Constructor Summary

ConstrainedText(Composite parent, int style, int constrainedStyle)
Constructs a new instance of this class given its parent, a style value describing behaviour and appearance, and an additional constrained style specifying the input styles defined above.

Method Summary

void	addModifyListener(ModifyListener listener) Adds the listener to the collection of listeners who will be notified when the receiver's text is modified, by sending it one of the messages defined in the ModifyListener interface.
void	addSelectionListener(SelectionListener listener) Adds the listener to the collection of listeners who will be notified when the control is selected, by sending it one of the messages defined in the SelectionListener interface.
void	append(java.lang.String string) Appends a string.
void	clearSelection() Clears the selection.
void	copy() Copies the selected text.
void	cut() Cuts the selected text.
int	getCaretPosition() Gets the position of the caret.
int	getCharCount() Gets the number of characters.
boolean	getEditable() Gets the editable state.
java.lang.String	getText() Gets the widget text.
int	getTextLimit() Returns the maximum number of characters that the receiver is capable of holding.
void	insert(java.lang.String string) Inserts a string after the caret position.
void	paste() Pastes text from clipboard.
void	removeModifyListener(ModifyListener listener) Removes the listener from the collection of listeners who will be notified when the receiver's text is modified.
void	removeSelectionListener(SelectionListener listener) Removes the listener from the collection of listeners who will be notified when the control is selected.
void	selectAll() Selects all the text in the receiver.
void	setEditable(boolean editable) Sets the editable state.
void	setSelection(int start) Sets the selection.
void	setSelection(int start, int end) Sets the selection.
void	setText(java.lang.String text) Sets the initial contents of the receiver to the given string.
void	setTextLimit(int limit) Sets the maximum number of characters that the receiver is capable of holding to be the argument.
void	showSelection() Shows the selection.

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, checkSubclass, 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

Field Detail

NUMERIC

public static final int NUMERIC

Numeric input style allows the input of numeric values.

Value 1 is assigned to NUMERIC.

See Also:

Constant Field Values

DECIMAL

public static final int DECIMAL

Decimal input style allows the input of numeric values with optional decimal fractions, for example, "-123", "0.123", or ".5" are all valid input.

Value 2 is assigned to DECIMAL.

See Also:

Constant Field Values

PHONENUMBER

public static final int PHONENUMBER

Phone number input style allows the input of numeric values with optional phone specific characters like "+", "* and "#".

Value 4 is assigned to PHONENUMBER.

See Also:

Constant Field Values

Constructor Detail

ConstrainedText

public ConstrainedText(Composite parent,
                       int style,
                       int constrainedStyle)

Constructs a new instance of this class given its parent, a style value describing behaviour and appearance, and an additional constrained style specifying the input styles defined above.

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. Style bits are also inherited from superclasses. The class description lists the constrained style constants that can be set in constrainedStyle.

Parameters:

parent - a composite control which will be the parent of the new instance (cannot be null)

style - the style of control to construct

constrainedStyle - the constrained style

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the parent is null

• ERROR_INVALID_ARGUMENT - if either the style or the constrainedStyle is invalid

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent

See Also:

NUMERIC, DECIMAL, PHONENUMBER

Method Detail

addModifyListener

public void addModifyListener(ModifyListener listener)

Adds the listener to the collection of listeners who will be notified when the receiver's text is modified, by sending it one of the messages defined in the ModifyListener interface.

Parameters:

listener - the listener which should be notified

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the listener 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 receiver

See Also:

ModifyListener, removeModifyListener(org.eclipse.swt.events.ModifyListener)

addSelectionListener

public void addSelectionListener(SelectionListener listener)

Adds the listener to the collection of listeners who will be notified when the control is selected, by sending it one of the messages defined in the SelectionListener interface.

widgetSelected is not called for this control.
widgetDefaultSelected is called when a selection key is pressed.

Parameters:

listener - the listener which should be notified

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the listener 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 receiver

See Also:

SelectionListener, removeSelectionListener(org.eclipse.swt.events.SelectionListener), SelectionEvent

append

public void append(java.lang.String string)

Appends a string.

The new text is appended to the text at the end of the widget. The excessive characters will be truncated if the length exceeds the maximum number of characters that the receiver is capable of holding.

Parameters:

string - the string to be appended

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the string is null
• ERROR_INVALID_ARGUMENT - if the string is invalid

SWTException -

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

clearSelection

public void clearSelection()

Clears the selection.

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

copy

public void copy()

Copies the selected text.

The current selection is copied to the clipboard.

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

cut

public void cut()

Cuts the selected text.

The current selection is first copied to the clipboard and then deleted from the widget.

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

getCaretPosition

public int getCaretPosition()

Gets the position of the caret.

The character position of the caret is returned.

Returns:

the position of the caret

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

getCharCount

public int getCharCount()

Gets the number of characters.

Returns:

number of characters in the widget

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

getEditable

public boolean getEditable()

Gets the editable state.

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

getText

public java.lang.String getText()

Gets the widget text.

The text for a text widget is the characters in the widget.

Returns:

the widget 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 receiver

getTextLimit

public int getTextLimit()

Returns the maximum number of characters that the receiver is capable of holding.

If this has not been changed by setTextLimit(), it will be the constant Text.LIMIT.

Returns:

the text limit

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

insert

public void insert(java.lang.String string)

Inserts a string after the caret position.

The old selection is replaced with the new text. The excessive characters will be truncated if the length exceeds the maximum number of characters that the receiver is capable of holding.

Parameters:

string - the string value.

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the string is null
• ERROR_INVALID_ARGUMENT - if the string is invalid

SWTException -

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

paste

public void paste()

Pastes text from clipboard.

The selected text is deleted from the widget and new text inserted from the clipboard. The excessive characters will be truncated if the length exceeds the maximum number of characters that the receiver is capable of holding.

Throws:

java.lang.IllegalArgumentException -

• ERROR_INVALID_ARGUMENT - if the string is invalid

SWTException -

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

removeModifyListener

public void removeModifyListener(ModifyListener listener)

Removes the listener from the collection of listeners who will be notified when the receiver's text is modified.

Parameters:

listener - the listener which should no longer be notified

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the listener 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 receiver

See Also:

ModifyListener, addModifyListener(org.eclipse.swt.events.ModifyListener)

removeSelectionListener

public void removeSelectionListener(SelectionListener listener)

Removes the listener from the collection of listeners who will be notified when the control is selected.

Parameters:

listener - the listener which should be notified

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the listener 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 receiver

See Also:

SelectionListener, addSelectionListener(org.eclipse.swt.events.SelectionListener)

selectAll

public void selectAll()

Selects all the text in the receiver.

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

setEditable

public void setEditable(boolean editable)

Sets the editable state.

Parameters:

editable - the new editable state

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

setSelection

public void setSelection(int start)

Sets the selection.

Indexing is zero based. The range of a selection is from 0..N where N is the number of characters in the widget.

Text selections are specified in terms of caret positions. In a text widget that contains N characters, there are N+1 caret positions, ranging from 0..N. This differs from other functions that address character position such as getText () that use the regular array indexing rules.

Parameters:

start - new caret position

Throws:

java.lang.IllegalArgumentException -

• ERROR_INVALID_ARGUMENT - if the start is less than zero.
• ERROR_INVALID_RANGE - if the start value is greater than N.
SWTException -
• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

setSelection

public void setSelection(int start,
                         int end)

Sets the selection.

Indexing is zero based. The range of a selection is from 0..N where N is the number of characters in the widget.

Text selections are specified in terms of caret positions. In a text widget that contains N characters, there are N+1 caret positions, ranging from 0..N. This differs from other functions that address character position such as getText () that use the usual array indexing rules.

Parameters:

start - the start of the range

end - the end of the range

Throws:

java.lang.IllegalArgumentException -

• ERROR_INVALID_ARGUMENT - if the start or end values are less than zero.
• ERROR_INVALID_RANGE - if the start value is greater than the end value; or if the end value is greater than N.
SWTException -
• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

setText

public void setText(java.lang.String text)

Sets the initial contents of the receiver to the given string. If the argument contains multiple lines of text, the result of this operation is undefined and may vary from platform to platform.

It is not recommended to set the initial contents especially when the style is PHONENUMBER because an IllegalArgumentException will be thrown when the string format does not match the present locale-specific format.

Parameters:

text - the new text

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the string is null
• ERROR_INVALID_ARGUMENT - if the string format is invalid

SWTException -

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

setTextLimit

public void setTextLimit(int limit)

Sets the maximum number of characters that the receiver is capable of holding to be the argument.

Instead of trying to set the text limit to zero, consider creating a read-only text widget.

To reset this value to the default, use setTextLimit(Text.LIMIT).

Parameters:

limit - new text limit

Throws:

java.lang.IllegalArgumentException -

• ERROR_INVALID_ARGUMENT - if the limit is lower or equal to zero, or greater than Text.LIMIT

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:

Text.LIMIT

showSelection

public void showSelection()

Shows the selection.

If the selection is already showing in the receiver, this method simply returns. Otherwise, lines are scrolled until the selection is visible.

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