/ime/aimelib/src/com/google/android/marvin/aime/TextNavigation.java

 1/*
 2 * Copyright (C) 2010 The Android Open Source Project
 3 *
 4 * Licensed under the Apache License, Version 2.0 (the "License");
 5 * you may not use this file except in compliance with the License.
 6 * You may obtain a copy of the License at
 7 *
 8 *      http://www.apache.org/licenses/LICENSE-2.0
 9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package com.google.android.marvin.aime;
18
19/**
20 * This interface allows to navigate through text by character, word, sentence and paragraph.
21 *
22 * @author hiteshk@google.com (Hitesh Khandelwal)
23 */
24public interface TextNavigation {
25    /** Flag to indicate moving cursor. */
26    public static final int ACTION_MOVE = 0;
27
28    /** Flag to indicate extending selection. */
29    public static final int ACTION_EXTEND = 1;
30
31    /** Flag for navigating by character. */
32    public static final int GRANULARITY_CHAR = 0;
33
34    /** Flag for navigating by word. */
35    public static final int GRANULARITY_WORD = 1;
36
37    /** Flag for navigating by sentence. */
38    public static final int GRANULARITY_SENTENCE = 2;
39
40    /** Flag for navigating by paragraph (hard line breaks). */
41    public static final int GRANULARITY_PARAGRAPH = 3;
42
43    /** Flag for entire content. */
44    public static final int GRANULARITY_ENTIRE_TEXT = 4;
45
46    /** Number of granularity types. */
47    public static final int NUM_GRANULARITY_TYPES = 5;
48
49    /**
50     * Move cursor or extend selection to the beginning of next unit.
51     *
52     * @param granularity Granularity for navigation. Value could be {@link #GRANULARITY_CHAR},
53     *            {@link #GRANULARITY_WORD}, {@link #GRANULARITY_SENTENCE},
54     *            {@link #GRANULARITY_PARAGRAPH} or {@link #GRANULARITY_ENTIRE_TEXT}
55     * @param action Set action need to be performed on Selection. Value could be either
56     *            {@link #ACTION_MOVE} or{@link #ACTION_EXTEND}.
57     * @return Start and end positions of the unit. Returns null if <code>granularity</code> or
58     *         <code>action</code> is invalid.
59     */
60    public Position next(int granularity, int action);
61
62    /**
63     * Move cursor or extend selection to the beginning of previous unit.
64     *
65     * @param granularity Granularity for navigation. Value could be {@link #GRANULARITY_CHAR},
66     *            {@link #GRANULARITY_WORD}, {@link #GRANULARITY_SENTENCE},
67     *            {@link #GRANULARITY_PARAGRAPH} or {@link #GRANULARITY_ENTIRE_TEXT}
68     * @param action Set action need to be performed on Selection. Value could be either
69     *            {@link #ACTION_MOVE} or{@link #ACTION_EXTEND}.
70     * @return Start and end positions of the unit. Returns null if <code>granularity</code> or
71     *         <code>action</code> is invalid.
72     */
73    public Position previous(int granularity, int action);
74
75    /**
76     * Get current text unit, pointed by cursor position. For character as granularity, current
77     * character is the character on the right of cursor position.
78     *
79     * @param granularity Granularity for navigation. Value could be {@link #GRANULARITY_CHAR},
80     *            {@link #GRANULARITY_WORD}, {@link #GRANULARITY_SENTENCE},
81     *            {@link #GRANULARITY_PARAGRAPH} or {@link #GRANULARITY_ENTIRE_TEXT}
82     * @return Start and end positions of the unit. Returns null if <code>granularity</code> or
83     *         <code>action</code> is invalid, or text is in selection mode.
84     */
85    public Position get(int granularity);
86}