TextEditor properties and supported events

The following TextEditor properties can be modified:

  • View properties

    • Position

    • Size

    • Visibility

    • Focus state

  • Color properties

    • Background color with alpha channel

    • Background highlight color with alpha channel

    • Foreground color with alpha channel

    • Foreground highlight color with alpha channel

  • Text properties

    • Caret position

    • Editor constraints

    • Text font

    • Text selection

    • Text content

    • Maximal length of text

    • Multiline

  • Other properties

    • Initial input modes

    • Text editor listener

    • Receiving pointer events

The events in the Symbian implementation are not always be grouped to a single event, thus there can be several subsequent calls to TextEditorListener.inputAction( TextEditor, int) during a single user interaction in the editor.

Pointer events are by default sent to a focused TextEditor if on its area, but it can be disabled, so Canvas would receive all the events instead.

The following table lists the events that are supported in TextEditorListener.

Table: TextEditorListener supported events

Event

Occurance

ACTION_CONTENT_CHANGE

When content is changed in the editor. The event occurs also when the content is modified with the TextEditor API

ACTION_OPTIONS_CHANGE

When options of the TextEditor have changed.

ACTION_CARET_MOVE

When the user moves the cursor within the editor or content is scrolled with cursor movement. The event occurs also when the cursor position is modified with the TextEditor API.

Note: Some methods may change the cursor position when modifying the content of the editor, causing this event to occur.

ACTION_TRAVERSE_PREVIOUS

When the user tries to go upwards to the previous TextEditor.

ACTION_TRAVERSE_NEXT

When the user tries to go downwards to the next TextEditor.

ACTION_PAINT_REQUEST

When the TextEditor has to be repainted.

ACTION_DIRECTION_CHANGE

When the direction of the writing language has changed.

ACTION_INPUT_MODE_CHANGE

When a custom indicator position is used and the user changes the input mode (for example when predictive text input is activated or text case is changed).

Note: This event does not occur when the default indicator is used

ACTION_LANGUAGE_CHANGE

When the current input language has changed.

ACTION_TRAVERSE_OUT_SCROLL_UP

When the TextEditor is scrolled up, but user is still dragging above the TextEditor area.

ACTION_TRAVERSE_OUT_SCROLL_DOWN

When the TextEditor is scrolled down, but the user is still dragging below the TextEditor area.

ACTION_SCROLLBAR_CHANGED

When the content in the TextEditor was moved up or down and the scroll bar should be updated.

See also table Virtual keyboard events.

The following example sets a listener for the TextEditor, defines non-default background color with alpha channel and sets some content to the editor.

Additionally, it is possible to calculate, for example, a position for a custom scroll bar using the current layout metrics when an event is received through the listener interface.

// TextEditorExample.java

// Constant color – 128 alpha, red color.
private static final int BGCOLOR = 0x80ff0000;

// ...

public void startApp()
    {
    // ...

    // Set this object as a listener for text editor events.
    editor.setTextEditorListener(this);

    // Set some content to the editor. "\n" are interpreted as new lines
    editor.setContent("This is a\nTextEditor with\nthree lines.");
		
    // Override the default transparent white background color.
    // Note that it is also possible to get skin colors from Display
    // and to utilize them here.
    editor.setBackgroundColor(BGCOLOR);

    // ...
    }

// ...

// From TextEditorListener

/**
 * Called when an input action occurs in the editor.
 * 
 * @param editor The editor that generated the event.
 * @param actions The actions that occured.
 */
public void inputAction(TextEditor editor, int actions)
    {
    // Handle events that are needed by the client application

    if((actions & TextEditorListener.ACTION_CARET_MOVE) != 0)
        {
        // Caret was moved. Calculate for example a new position
        // for a custom scroll bar using layout metrics.
        int visibleContentPos = editor.getVisibleContentPosition();
        int height = editor.getHeight();
        int contentHeight = editor.getContentHeight();
        int caretPosition = editor.getCaretPosition();
            
        // Scroll bar calculations are done here.        
        }
    }
© Nokia 2011.