com.codename1.ui

Class TextSelection

java.lang.Object

com.codename1.ui.TextSelection

public class TextSelection
extends 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).

Since:

7.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and 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 class	TextSelection.TextSelectionTrigger Trigger types for text selection.

Method Summary

Modifier and Type	Method and 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.
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	update() Updates the text selected spans based on the selected bounds.

Methods inherited from class java.lang.Object

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

Method Detail

isEnabled

public boolean isEnabled()

Returns true if text selection is enabled. Default is false.

Returns:

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 TextSelection.TextSelectionTrigger.LongPress, and on desktop environments with a mouse, it will return TextSelection.TextSelectionTrigger.Press.

Returns:

The default trigger type for text selection.

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

Returns:

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.

Returns:

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()

Returns:

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).

Returns:

getSelectionAsText

public String getSelectionAsText()

Gets the selected text as a string.

Returns:

update

public void update()

Updates the text selected spans based on the selected bounds.

setEnabled

public void setEnabled(boolean enabled)

Enables or disables text selection.

Parameters:

enabled -

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 -

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.

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 -