Class Text

  • All Implemented Interfaces:
    Adaptable, Drawable

    public class Text
    extends Scrollable
    Instances of this class are selectable user interface objects that allow the user to enter and modify text.

    Styles:
    CENTER, LEFT, MULTI, PASSWORD, SEARCH, SINGLE, RIGHT, READ_ONLY, WRAP
    Events:
    DefaultSelection, Modify, Verify

    Note: Only one of the styles MULTI and SINGLE may be specified.

    Note: The styles ICON_CANCEL and ICON_SEARCH are hints used in combination with SEARCH. When the platform supports the hint, the text control shows these icons. When an icon is selected, a default selection event is sent with the detail field set to one of ICON_CANCEL or ICON_SEARCH. Normally, application code does not need to check the detail. In the case of ICON_CANCEL, the text is cleared before the default selection event is sent causing the application to search for an empty string.

    IMPORTANT: This class is not intended to be subclassed.

    Due to limitations of the JavaScript library, the current WRAP behavior of a MULI line text is always as if WRAP was set.

    Since:
    1.0
    • Field Detail

      • LIMIT

        public static final int LIMIT
        The maximum number of characters that can be entered into a text widget.

        Note that this value is platform dependent, based upon the native widget implementation.

        See Also:
        Constant Field Values
      • DELIMITER

        public static final java.lang.String DELIMITER
        The delimiter used by multi-line text widgets. When text is queried from the widget, it will be delimited using this delimiter.
        See Also:
        Constant Field Values
    • Constructor Detail

      • Text

        public Text​(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 composite control which will be the parent of the new instance (cannot be null)
        style - the style of control 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.SINGLE, SWT.MULTI, SWT.READ_ONLY, SWT.WRAP, SWT.PASSWORD, SWT.SEARCH, SWT.ICON_SEARCH, SWT.ICON_CANCEL, Widget.checkSubclass(), Widget.getStyle()
    • Method Detail

      • setText

        public void setText​(java.lang.String text)
        Sets the contents of the receiver to the given string. If the receiver has style SINGLE and the argument contains multiple lines of text, the result of this operation is undefined and may vary from platform to platform.
        Parameters:
        text - the new text
        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 receiver
      • getText

        public java.lang.String getText()
        Returns the widget text.

        The text for a text widget is the characters in the widget, or an empty string if this has never been set.

        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
      • setTextChars

        public void setTextChars​(char[] text)
        Sets the contents of the receiver to the characters in the array. If the receiver has style SINGLE and the argument contains multiple lines of text, the result of this operation is undefined and may vary from platform to platform.
        Parameters:
        text - a character array that contains the new text
        Throws:
        java.lang.IllegalArgumentException -
        • ERROR_NULL_ARGUMENT - if the array 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
        Since:
        1.4
        See Also:
        getTextChars()
      • getTextChars

        public char[] getTextChars()
        Returns the widget's text as a character array.

        The text for a text widget is the characters in the widget, or a zero length array if this has never been set.

        Returns:
        a character array that contains the widget's 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
        Since:
        1.4
        See Also:
        setTextChars(char[])
      • getText

        public java.lang.String getText​(int start,
                                        int end)
        Returns a range of text. Returns an empty string if the start of the range is greater than the end.

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

        Parameters:
        start - the start of the range
        end - the end of the range
        Returns:
        the range of 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
        Since:
        1.3
      • 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.

        Parameters:
        string - the string to be appended
        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 receiver
      • getLineDelimiter

        public java.lang.String getLineDelimiter()
        Returns the line delimiter.
        Returns:
        a string that is the line delimiter
        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:
        DELIMITER
      • getLineHeight

        public int getLineHeight()
        Returns the height of a line.
        Returns:
        the height of a row of 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
      • setMessage

        public void setMessage​(java.lang.String message)
        Sets the widget message. The message text is displayed as a hint for the user, indicating the purpose of the field.

        Typically this is used in conjunction with SWT.SEARCH.

        Parameters:
        message - the new message
        Throws:
        java.lang.IllegalArgumentException -
        • ERROR_NULL_ARGUMENT - if the message 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
        Since:
        1.3
      • getMessage

        public java.lang.String getMessage()
        Returns the widget message. The message text is displayed as a hint for the user, indicating the purpose of the field.

        Typically this is used in conjunction with SWT.SEARCH.

        Returns:
        the widget message
        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
        Since:
        1.3
      • setEchoChar

        public void setEchoChar​(char echo)
        Sets the echo character.

        The echo character is the character that is displayed when the user enters text or the text is changed by the programmer. Setting the echo character to '\0' clears the echo character and redraws the original text. If for any reason the echo character is invalid, or if the platform does not allow modification of the echo character, the default echo character for the platform is used.

        Parameters:
        echo - the new echo character
        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
        Since:
        1.3
      • getEchoChar

        public char getEchoChar()
        Returns the echo character.

        The echo character is the character that is displayed when the user enters text or the text is changed by the programmer.

        Returns:
        the echo character
        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
        Since:
        1.3
        See Also:
        setEchoChar(char)
      • setTextLimit

        public void setTextLimit​(int textLimit)
        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). Specifying a limit value larger than Text.LIMIT sets the receiver's limit to Text.LIMIT.

        Parameters:
        textLimit - new text limit
        Throws:
        java.lang.IllegalArgumentException -
        • ERROR_CANNOT_BE_ZERO - if the limit is zero
        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:
        LIMIT
      • 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
        See Also:
        LIMIT
      • getCharCount

        public int getCharCount()
        Returns 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
        Since:
        1.2
      • 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:
        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 to the range specified by the given start and end indices.

        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:
        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​(Point selection)
        Sets the selection to the range specified by the given point, where the x coordinate represents the start index and the y coordinate represents the end index.

        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:
        selection - the point
        Throws:
        java.lang.IllegalArgumentException -
        • ERROR_NULL_ARGUMENT - if the point 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
      • getSelection

        public Point getSelection()
        Returns a Point whose x coordinate is the character position representing the start of the selected text, and whose y coordinate is the character position representing the end of the selection. An "empty" selection is indicated by the x and y coordinates having the same value.

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

        Returns:
        a point representing the selection start and end
        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
      • getSelectionCount

        public int getSelectionCount()
        Returns the number of selected characters.
        Returns:
        the number of selected characters.
        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
      • getSelectionText

        public java.lang.String getSelectionText()
        Gets the selected text, or an empty string if there is no current selection.
        Returns:
        the selected 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
      • 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
      • 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
      • getCaretPosition

        public int getCaretPosition()
        Returns the character position of the caret.

        Indexing is zero based.

        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
        Since:
        1.3
      • 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
      • getEditable

        public boolean getEditable()
        Returns the editable state.
        Returns:
        whether or not the receiver is editable
        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.

        The old selection is replaced with the new text.

        Parameters:
        string - the string
        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 receiver
      • computeSize

        public Point computeSize​(int wHint,
                                 int hHint,
                                 boolean changed)
        Description copied from class: Control
        Returns the preferred size 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.

        Overrides:
        computeSize in class Control
        Parameters:
        wHint - the width hint (can be SWT.DEFAULT)
        hHint - the height hint (can be SWT.DEFAULT)
        changed - true if the control's contents have changed, and false otherwise
        Returns:
        the preferred size of the control.
        See Also:
        Layout, Control.getBorderWidth(), Control.getBounds(), Control.getSize(), Control.pack(boolean), "computeTrim, getClientArea for controls that implement them"
      • computeTrim

        public Rectangle computeTrim​(int x,
                                     int y,
                                     int width,
                                     int height)
        Description copied from class: Scrollable
        Given a desired client area for the receiver (as described by the arguments), returns the bounding rectangle which would be required to produce that client area.

        In other words, it returns a rectangle such that, if the receiver's bounds were set to that rectangle, the area of the receiver which is capable of displaying data (that is, not covered by the "trimmings") would be the rectangle described by the arguments (relative to the receiver's parent).

        Overrides:
        computeTrim in class Scrollable
        Parameters:
        x - the desired x coordinate of the client area
        y - the desired y coordinate of the client area
        width - the desired width of the client area
        height - the desired height of the client area
        Returns:
        the required bounds to produce the given client area
        See Also:
        Scrollable.getClientArea()
      • addSelectionListener

        public void addSelectionListener​(SelectionListener listener)
        Adds the listener to the collection of listeners who will be notified when the control is selected by the user, by sending it one of the messages defined in the SelectionListener interface.

        widgetSelected is not called for texts. widgetDefaultSelected is typically called when ENTER is pressed in a single-line text, or when ENTER is pressed in a search text. If the receiver has the SWT.SEARCH | SWT.ICON_CANCEL style and the user cancels the search, the event object detail field contains the value SWT.ICON_CANCEL. Likewise, if the receiver has the SWT.ICON_SEARCH style and the icon search is selected, the event object detail field contains the value SWT.ICON_SEARCH.

        Parameters:
        listener - the listener which should be notified when the control is selected by the user
        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
      • 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 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:
        SelectionListener, addSelectionListener(org.eclipse.swt.events.SelectionListener)
      • 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)
      • 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)
      • addVerifyListener

        public void addVerifyListener​(VerifyListener listener)
        Adds the listener to the collection of listeners who will be notified when the receiver's text is verified, by sending it one of the messages defined in the VerifyListener 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:
        VerifyListener, removeVerifyListener(org.eclipse.swt.events.VerifyListener)
      • removeVerifyListener

        public void removeVerifyListener​(VerifyListener listener)
        Removes the listener from the collection of listeners who will be notified when the control is verified.
        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:
        VerifyListener, addVerifyListener(org.eclipse.swt.events.VerifyListener)
      • cut

        public void cut()
        Cuts the selected text.

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

        Throws:
        java.lang.UnsupportedOperationException - when running the application in JEE_COMPATIBILITY mode
        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.16
        See Also:
        Application.OperationMode
      • copy

        public void copy()
        Copies the selected text.

        The current selection is copied to the clipboard.

        Throws:
        java.lang.UnsupportedOperationException - when running the application in JEE_COMPATIBILITY mode
        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.16
        See Also:
        Application.OperationMode
      • paste

        public void paste()
        Pastes text from clipboard.

        The selected text is deleted from the widget and new text inserted from the clipboard.

        Throws:
        java.lang.UnsupportedOperationException - when running the application in JEE_COMPATIBILITY mode
        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.16
        See Also:
        Application.OperationMode
      • getAdapter

        public <T> T getAdapter​(java.lang.Class<T> adapter)
        Description copied from class: Widget
        Implementation of the Adaptable interface.

        IMPORTANT: This method is not part of the RWT public API. It is marked public only so that it can be shared within the packages provided by RWT. It should never be accessed from application code.

        Specified by:
        getAdapter in interface Adaptable
        Overrides:
        getAdapter in class Control
        Parameters:
        adapter - the lookup class
        Returns:
        an object that can be cast to the given class or null if there is no adapter associated with the given class.
      • getHorizontalBar

        public ScrollBar getHorizontalBar()
        Description copied from class: Scrollable
        Returns the receiver's horizontal scroll bar if it has one, and null if it does not.
        Overrides:
        getHorizontalBar in class Scrollable
        Returns:
        the horizontal scroll bar (or null)
      • getVerticalBar

        public ScrollBar getVerticalBar()
        Description copied from class: Scrollable
        Returns the receiver's vertical scroll bar if it has one, and null if it does not.
        Overrides:
        getVerticalBar in class Scrollable
        Returns:
        the vertical scroll bar (or null)