# Class TextSelection

java.lang.Object
com.codename1.ui.TextSelection

public class TextSelection extends java.lang.Object

Text selection support for Codename One applications. The class provides a light-weight text selection implementation, allowing users to select and copy text from a form.

Enabling Text Selection

Text selection needs to be enabled on a per-form basis.

    `myForm.getTextSelection().setEnabled(true);`

If text selection is enabled on a form, then non-editable text fields and text areas will allow text selection by default. Labels and SpanLabels have text selection disabled by default, but can be enabled using `Label#setTextSelectionEnabled(boolean)`, and `SpanLabel#setTextSelectionEnabled(boolean)` respectively. Similarly, text selection can be disabled on TextFields and TextAreas using `TextArea#setTextSelectionEnabled(boolean)`.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `class`
  `TextSelection.Char`
  Encapsulates a box around a single character/glyph in the UI, storing the component that it belongs to, the position of its corresponding character in the component's text, and the bounds of the box, relative to `#getSelectionRoot()`.
  `class`
  `TextSelection.Span`
  Encapsulates a span of text on the screen.
  `class`
  `TextSelection.Spans`
  Encapsulates a collection of Spans.
  `static interface`
  `TextSelection.TextSelectionSupport`
  An interface that can be returned from any Component's `Component#getTextSelectionSupport()` method to provide text selection support on that component.
  `static enum`
  `TextSelection.TextSelectionTrigger`
  Trigger types for text selection.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addTextSelectionListener(ActionListener l)`
  Adds a listener to be notified when the text selection changes.
  `void`
  `copy()`
  Copies the current selection to the system clipboard.
  `static Component`
  `findSelectionRoot(Component cmp)`
  Finds the selection root for a component.
  `static TextSelection.TextSelectionTrigger`
  `getDefaultTextSelectionTrigger()`
  Gets the default trigger type for text selection.
  `String`
  `getSelectionAsText()`
  Gets the selected text as a string.
  `Component`
  `getSelectionRoot()`
  Gets the selection root for the current text selection.
  `boolean`
  `isEnabled()`
  Returns true if text selection is enabled.
  `boolean`
  `isRtl()`
  Indicates if selection is operating in RTL (Right to left, bidi) mode.
  `TextSelection.Char`
  `newChar(int pos, int x, int y, int w, int h)`
  Creates a new Char box.
  `TextSelection.Char`
  `newChar(int pos, Rectangle bounds)`
  Creates a new Char box
  `TextSelection.Span`
  `newSpan(Component component)`
  Creates a new Span based on content in the given component.
  `TextSelection.Spans`
  `newSpans()`
  Creates a new Spans (a collection of Spans).
  `void`
  `removeTextSelectionListener(ActionListener l)`
  Removes a listener so it no longer is notified when text selection changes.
  `void`
  `selectAll()`
  Selects all of the selectable text in the TextSelection (generally on the current form).
  `void`
  `setEnabled(boolean enabled)`
  Enables or disables text selection.
  `void`
  `setIgnoreEvents(boolean ignore)`
  This flag can be set to cause text selection to ignore pointer events which might cause the selection to get lost or changed.
  `void`
  `setRtl(boolean rtl)`
  Toggles selection RTL (Right to left, bidi) mode.
  `void`
  `update()`
  Updates the text selected spans based on the selected bounds.

  ### Methods inherited from class java.lang.Object

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

- ## Method Details

  - ### getDefaultTextSelectionTrigger

    public static TextSelection.TextSelectionTrigger getDefaultTextSelectionTrigger()

    Gets the default trigger type for text selection. This will vary by platform. On mobile/touch devices, it will return `TextSelectionTrigger#LongPress`, and on desktop environments with a mouse, it will return `TextSelectionTrigger#Press`.

    ###### Returns

    The default trigger type for text selection.

  - ### findSelectionRoot

    public static Component findSelectionRoot(Component cmp)

    Finds the selection root for a component. This is generally just the first scrollable component discovered with crawling up the component hierarchy from the given component.

    ###### Parameters

    - `cmp`: The component we start with.

    ###### Returns

    The selection root for a given component.

  - ### isEnabled

    public boolean isEnabled()
    Returns true if text selection is enabled. Default is false.

  - ### setEnabled

    public void setEnabled(boolean enabled)

    Enables or disables text selection.

    ###### Parameters

    - `enabled`

  - ### getSelectionRoot

    public Component getSelectionRoot()

    Gets the selection root for the current text selection. The selection root will be the nearest scrollable parent of the component that triggered the text selection.

    Note: All Span coordinates are relative to the selection root

  - ### newChar

    public TextSelection.Char newChar(int pos, int x, int y, int w, int h)

    Creates a new Char box.

    ###### Parameters

    - `pos`: The position of the character that this is referencing within its text component.

    - `x`: The x coordinate of the box, relative to `#getSelectionRoot()`

    - `y`: The y coordinate of the box, relative to `#getSelectionRoot()`

    - `w`: The width of the box.

    - `h`: The height of the box.

  - ### newChar

    public TextSelection.Char newChar(int pos, Rectangle bounds)

    Creates a new Char box

    ###### Parameters

    - `pos`: The position of the character that this is referencing within its text component.

    - `bounds`: The bounds of the box, relative to `#getSelectionRoot()`

  - ### newSpan

    public TextSelection.Span newSpan(Component component)

    Creates a new Span based on content in the given component.

    ###### Parameters

    - `component`

    ###### Returns

    A new span

  - ### newSpans

    public TextSelection.Spans newSpans()
    Creates a new Spans (a collection of Spans).

  - ### getSelectionAsText

    public String getSelectionAsText()
    Gets the selected text as a string.

  - ### update

    public void update()
    Updates the text selected spans based on the selected bounds.

  - ### isRtl

    public boolean isRtl()

    Indicates if selection is operating in RTL (Right to left, bidi) mode.

    ###### Returns

    true if the selection is in RTL mode

  - ### setRtl

    public void setRtl(boolean rtl)

    Toggles selection RTL (Right to left, bidi) mode.

    ###### Parameters

    - `rtl`: true to activate the right to left mode

  - ### addTextSelectionListener

    public void addTextSelectionListener(ActionListener l)

    Adds a listener to be notified when the text selection changes.

    ###### Parameters

    - `l`

  - ### removeTextSelectionListener

    public void removeTextSelectionListener(ActionListener l)

    Removes a listener so it no longer is notified when text selection changes.

    ###### Parameters

    - `l`

  - ### copy

    public void copy()
    Copies the current selection to the system clipboard.

  - ### selectAll

    public void selectAll()
    Selects all of the selectable text in the TextSelection (generally on the current form).

  - ### setIgnoreEvents

    public void setIgnoreEvents(boolean ignore)

    This flag can be set to cause text selection to ignore pointer events which might cause the selection to get lost or changed. This is used internally when a context menu is displayed so that clicking on the context menu doesn't cause the current text selection to be lost.

    ###### Parameters

    - `ignore`