Class UIEdit

public class UIEdit extends UIDrawText
{
  // Fields
  public static final int EXCLUDE;
  public static final int INCLUDE;
  protected final static int READONLY;

  // Constructors
  public UIEdit();
  public UIEdit(String newBuff);
  public UIEdit(char newBuff[]);

  // Methods
  public synchronized void addActionListener(IUIActionListener l);
  public synchronized void addTextListener(IUITextListener l);
  public int append(char key);
  public int append(char key, boolean notify);
  public int append(char key[], boolean notify);
  public int append(char key[]);
  public int append(String s, boolean notify);
  public int append(String s);
  public void clear(boolean notify);
  public void clear();
  public void clearUndo();
  public Color getBackground();
  public String getMaskChars();
  public int getMaskMode();
  public int getMaxBufferSize();
  public int getRoleCode();
  public int insert(String s, int iPos);
  public int insert(String s, int iPos, boolean notify);
  public int insert(char key, int iPos, boolean notify);
  public int insert(char key, int iPos);
  public int insert(char key[], int iPos, boolean notify);
  public int insert(char key[], int iPos);
  public boolean isReadOnly();
  public boolean isRedoable();
  public boolean isUndoable();
  public boolean keyDown(Event evt, int key);
  protected void processActionEvent(UIActionEvent e);
  protected void processEvent(UIEvent e);
  protected void processTextEvent(UITextEvent e);
  public boolean redo(boolean notify);
  public boolean redo();
  public void remove(int iPos, int numberToRemove, boolean notify);
  public void remove(int iPos, int numberToRemove);
  public synchronized void removeActionListener(
        IUIActionListener l);
  public synchronized void removeTextListener(IUITextListener l);
  public void setBackground(Color c);
  public void setMaskChars(String mask);
  public void setMaskMode(int maskMode);
  public void setMaxBufferSize(int newMax);
  public void setReadOnly(boolean ro);
  public void setValueText(String value, boolean notify);
  public void setValueText(char newBuff[], int offset, int len,
        boolean notify);
  public boolean undo(boolean notify);
  public boolean undo();
}

This class implements an edit control. UIEdit extends UIDrawText to allow the user to edit the control's text. Typically, a UIEdit control is placed inside a layout manager that provides a fixed size container. UIScrollViewer, UISplitViewer, and UIColumnViewer are all examples of fixed size layout managers. By using a fixed size layout manager, the size of the edit window will be fixed also.

To get a 3D edge effect for the UIEdit control, you must place it in a UIViewer or UIScrollViewer. You cannot use the setEdge method because UIEdit extends from UICanvas.

Note insert, append, remove, clear, setValueText, undo, or redo must be called with the boolean parameter notify set to true to generate event notification for text value changes.

Also see com.ms.ui.UIDrawText.setValueText

UIComponent
  |
  +--UIStateComponent
    |
    +--UICanvas
      |
      +--UIDrawText
        |
        +--UIEdit

Constructors

UIEdit

public UIEdit();

Creates an empty edit control.

UIEdit

public UIEdit(String newBuff);

Creates an edit control with the specified string.

Parameter	Description
newBuff	The text of the control.

UIEdit

public UIEdit(char newBuff[]);

Creates an edit control with the specified character buffer.

Parameter	Description
newBuff	The text of the control.

Methods

addActionListener

public synchronized void addActionListener(IUIActionListener l);

Adds the specified action listener. The listener receives all action events generated for the control.

Return Value:

No return value.

Parameter	Description
l	The action listener to be added.

See Also: removeActionListener

addTextListener

public synchronized void addTextListener(IUITextListener l);

Adds the specified text listener. The listener receives all text events generated for the control.

Return Value:

No return value.

Parameter	Description
l	The text listener to be added.

See Also: removeTextListener

append

public int append(char key);

Appends a character to the end of the text in the control.

Return Value:

Returns the number of characters added.

Parameter	Description
key	The character to be appended.

append

public int append(char key, boolean notify);

Appends a character to the end of the control.

Return Value:

Returns the number of characters added.

Parameter	Description
key	The character to be appended.
notify	Set notify to true if an event listener is notified when the append operation is performed successfully.

append

public int append(char key[], boolean notify);

Appends an array of characters to the end of the control.

Return Value:

Returns the number of characters added.

Parameter	Description
key	The array of characters to be appended.
notify	Set to true if an event listener is notified when the append operation is performed successfully.

append

public int append(char key[]);

Appends an array of characters to the end of the control.

Return Value:

Returns the number of characters added.

Parameter	Description
key	The array of characters to be appended.

append

public int append(String s, boolean notify);

Appends a string to the end of the control.

Return Value:

Returns the number of characters added.

Parameter	Description
s	The string to be appended.
notify	Set to true if an event listener is notified when the append operation is performed successfully.

append

public int append(String s);

Appends a string to the end of the control.

Return Value:

Returns the number of characters added.

Parameter	Description
s	The string to be appended.

clear

public void clear(boolean notify);

Deletes all the text from the edit control.

Return Value:

No return value.

Parameter	Description
notify	Set to true if an event listener is notified when the clear operation is performed successfully.

clear

public void clear();

Deletes all the text from the edit control.

Return Value:

No return value.

clearUndo

public void clearUndo();

Clears and resets all the redo and undo information associated with the current UIEdit control.

Return Value:

No return value.

getBackground

public Color getBackground();

Retrieves the background color of the UIEdit control.

Return Value:

Returns the background Color of the control.

Remarks:

If the control's background color has been set (using the setBackground method), this color is returned. Otherwise, if the control's text field is read-only or the control is disabled, the text is shaded and the background color is the same as the text. If the control's text field is editable, the background color is the same as the system window color.

If the current background color is set, the background color will not change if the control is set to read-only. If the background color is set and the state is read-only, call setBackground(null) to clear the previous state.

See Also: setBackground

getMaskChars

public String getMaskChars();

Retrieves the set of characters used as a mask for input to the control.

Return Value:

Returns the set of characters used as a mask for input to the control.

getMaskMode

public int getMaskMode();

Retrieves the mode for interpreting the character mask.

Return Value:

Returns the mode for interpreting the character mask.

getMaxBufferSize

public int getMaxBufferSize();

Retrieves the maximum number of characters that the control can hold. By default, the maximum buffer size is set to Integer.MAX_VALUE.

Return Value:

Returns the maximum number of characters that the control can hold.

getRoleCode

public int getRoleCode();

Retrieves the ROLE_SYSTEM code that best describes the role of the edit control.

Return Value:

Returns the ROLE_SYSTEM_TEXT code.

Overrides:

getRoleCode() in UIDrawText.

insert

public int insert(String s, int iPos);

Inserts a string into the control at the specified position.

Return Value:

Returns the number of characters inserted.

Parameter	Description
s	The string to be inserted.
iPos	The character index where the string will be inserted.

insert

public int insert(String s, int iPos, boolean notify);

Inserts a string into the control at the specified position.

Return Value:

Returns the number of characters inserted.

Parameter	Description
s	The string to be inserted.
iPos	The character index where the string will be inserted.
notify	Set to true if an event listener is notified when the insert operation is performed successfully.

insert

public int insert(char key, int iPos, boolean notify);

Inserts a character into the control at the specified position.

Return Value:

Returns the number of characters inserted.

Parameter	Description
key	The character to be inserted.
iPos	The character index where the character will be inserted.
notify	Set to true if an event listener is notified when the insert operation is performed successfully.

insert

public int insert(char key, int iPos);

Inserts a character into the control at the specified position.

Return Value:

Returns the number of characters inserted.

Parameter	Description
key	The character to be inserted.
iPos	The character index where the character will be inserted.

insert

public int insert(char key[], int iPos, boolean notify);

Inserts an array of characters into the control at the specified position.

Return Value:

Returns the number of characters inserted.

Parameter	Description
key[]	The array of characters to be inserted.
iPos	The character index where the characters will be inserted.
notify	Set to true if an event listener is notified when the insert operation is performed successfully.

insert

public int insert(char key[], int iPos);

Inserts an array of characters into the control at the specified position.

Return Value:

Returns the number of characters inserted.

Parameter	Description
key[]	The array of characters to be inserted.
iPos	The character index where the characters will be inserted.

isReadOnly

public boolean isReadOnly();

Determines whether the control is read-only.

Return Value:

Returns true if the READONLY style is set; otherwise, returns false.

isRedoable

public boolean isRedoable();

Determines if the previous undo operation is recoverable.

Return Value:

Returns true if the undo can be recovered.

isUndoable

public boolean isUndoable();

Determines if the previous operation can be undone.

Return Value:

Returns true if the operation can be undone; otherwise, returns false.

keyDown

public boolean keyDown(Event evt, int key);

Processes a key down event.

Return Value:

Returns true if the event was handled; otherwise, returns false.

Parameter	Description
evt	The event posted to the control.
key	The key that was pressed.

Overrides:

keyDown(Event,int) in UIDrawText.

processActionEvent

protected void processActionEvent(UIActionEvent e);

Processes action events.

Return Value:

No return value.

Parameter	Description
e	The action event.

Remarks:

This method is called by processEvent and dispatches the event to a registered action listener. When overriding this method, call the super method processActionEvent to ensure the default event processing continues normally.

See Also: addActionListener

processEvent

protected void processEvent(UIEvent e);

Processes the specified event.

Return Value:

No return value.

Parameter	Description
e	The event.

Remarks:

This method is automatically invoked if a listener has has been registered through a call to addXXXListener. Depending on the type of event, processEvent calls one of the following methods.

Event type	Method called
action event	processActionEvent
text event	processTextEvent
focus event	processFocusEvent (inherited through UIStateComponent)
key event	processKeyEvent (inherited through UIStateComponent)
mouse event	processMouseEvent (inherited through UIStateComponent)
mouse motion event	processMouseMotionEvent (inherited through UIStateComponent)

When overriding processEvent, call the super method processEvent to ensure the default event processing continues normally.

processTextEvent

protected void processTextEvent(UITextEvent e);

Processes text events.

Return Value:

No return value.

Parameter	Description
e	The text event.

Remarks:

This method is called by processEvent and dispatches the event to a registered action listener. When overriding this method, call the super method processTextEvent to ensure the default event processing continues normally.

See Also: addTextListener

redo

public boolean redo(boolean notify);

Recovers the last undo operation, if it is recoverable.

Return Value:

Returns true if the undo is recovered.

Parameter	Description
notify	Set to true if an event listener is notified when the redo operation is performed successfully.

redo

public boolean redo();

Recovers the last undo operation, if it is recoverable, without notifying an event listener.

Return Value:

Returns true if the undo is recovered.

remove

public void remove(int iPos, int numberToRemove, boolean notify);

Deletes one or more characters from the edit control.

Return Value:

No return value.

Parameter	Description
iPos	Specifies the character index where the characters will be deleted.
numberToRemove	Specifies the number of characters that will be deleted.
notify	Set to true if an event listener is notified when the remove operation is performed successfully.

remove

public void remove(int iPos, int numberToRemove);

Deletes one or more characters from the edit control.

Return Value:

No return value.

Parameter	Description
iPos	Specifies the character index where the characters will be deleted.
numberToRemove	Specifies the number of characters that will be deleted.

removeActionListener

public synchronized void removeActionListener(IUIActionListener l);

Removes the specified action listener. The listener no longer receives the control's action events.

Return Value:

No return value.

Parameter	Description
l	The action listener to be removed.

See Also: addActionListener

removeTextListener

public synchronized void removeTextListener(IUITextListener l);

Removes the specified text listener. The listener no longer receives the control's text events.

Return Value:

No return value.

Parameter	Description
l	The text listener to be removed.

See Also: addTextListener

setBackground

public void setBackground(Color c);

Sets the background color of the control.

Return Value:

No return value.

Parameter	Description
c	A Color object that specifies the background color. If the current background color is set, the background color will not change when the control is set to read-only. If the background color is set, and the state is read-only, call setBackground(null) to clear the previous state.

Overrides:

setBackground(Color) in UIDrawText.

See Also: getBackground

setMaskChars

public void setMaskChars(String mask);

Sets the set of characters to use as a mask for input to the control.

Return Value:

No return value.

Parameter	Description
mask	The set of mask characters.

Remarks:

The interpretation of these characters is determined by calling the setMaskMode method.

See Also: setMaskMode

setMaskMode

public void setMaskMode(int maskMode);

Sets the mode for interpreting the character mask.

Return Value:

No return value.

Parameter	Description
maskMode	This may be INCLUDE or EXCLUDE.

Remarks:

The character mask is set by calling setMaskChars.

See Also: getMaskMode, setMaskChars

setMaxBufferSize

public void setMaxBufferSize(int newMax);

Sets the maximum number of characters that the control can hold. By default, the maximum buffer size is set to Integer.MAX_VALUE.

Return Value:

No return value.

Parameter	Description
newMax	Specifies the new maximum number of characters that the control can hold.

setReadOnly

public void setReadOnly(boolean ro);

Changes the read-only attribute of the control.

Return Value:

No return value.

Parameter	Description
ro	If true, the READONLY style is set; otherwise, it is cleared.

setValueText

public void setValueText(String value, boolean notify);

Sets the text in the control.

Return Value:

No return value.

Parameter	Description
value	A String object that specifies the new text.
notify	Set to true if an event listener is notified when the setValueText operation is performed successfully.

setValueText

public void setValueText(char newBuff[], int offset, int len,
        boolean notify);

Sets the text in the control.

Return Value:

No return value.

Parameter	Description
newBuff[]	A character array that contains the new text.
offset	The offset of the newBuff text buffer where the text begins.
len	The length of the character array to use.
notify	Set to true if an event listener is notified when the setValueText operation is performed successfully.

undo

public boolean undo(boolean notify);

Clears the previous operation, if it can be undone.

Return Value:

Returns true if the previous operation was undone.

Parameter	Description
notify	Set to true if an event listener is notified when the undo operation is performed successfully.

undo

public boolean undo();

Clears the previous operation, if it can be undone, without notifying an event listener.

Return Value:

Returns true if the previous operation was undone.

Fields

EXCLUDE

Specifies that mask characters are excluded.

INCLUDE

Specifies that mask characters are an include list, so only those characters are allowed.

READONLY

Specifies that the control is read-only.