1 /* 2 * Copyright (C) 2017 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 17 package android.view.textclassifier; 18 19 import android.annotation.IntRange; 20 import android.annotation.NonNull; 21 import android.annotation.Nullable; 22 import android.annotation.StringDef; 23 import android.annotation.WorkerThread; 24 import android.os.LocaleList; 25 26 import java.lang.annotation.Retention; 27 import java.lang.annotation.RetentionPolicy; 28 29 /** 30 * Interface for providing text classification related features. 31 * 32 * <p>Unless otherwise stated, methods of this interface are blocking operations and you should 33 * avoid calling them on the UI thread. 34 */ 35 public interface TextClassifier { 36 37 String TYPE_OTHER = "other"; 38 String TYPE_EMAIL = "email"; 39 String TYPE_PHONE = "phone"; 40 String TYPE_ADDRESS = "address"; 41 String TYPE_URL = "url"; 42 43 /** @hide */ 44 @Retention(RetentionPolicy.SOURCE) 45 @StringDef({ 46 TYPE_OTHER, TYPE_EMAIL, TYPE_PHONE, TYPE_ADDRESS, TYPE_URL 47 }) 48 @interface EntityType {} 49 50 /** 51 * No-op TextClassifier. 52 * This may be used to turn off TextClassifier features. 53 */ 54 TextClassifier NO_OP = new TextClassifier() { 55 56 @Override 57 public TextSelection suggestSelection( 58 CharSequence text, 59 int selectionStartIndex, 60 int selectionEndIndex, 61 LocaleList defaultLocales) { 62 return new TextSelection.Builder(selectionStartIndex, selectionEndIndex).build(); 63 } 64 65 @Override 66 public TextClassification classifyText( 67 CharSequence text, int startIndex, int endIndex, LocaleList defaultLocales) { 68 return TextClassification.EMPTY; 69 } 70 }; 71 72 /** 73 * Returns suggested text selection indices, recognized types and their associated confidence 74 * scores. The selections are ordered from highest to lowest scoring. 75 * 76 * @param text text providing context for the selected text (which is specified 77 * by the sub sequence starting at selectionStartIndex and ending at selectionEndIndex) 78 * @param selectionStartIndex start index of the selected part of text 79 * @param selectionEndIndex end index of the selected part of text 80 * @param defaultLocales ordered list of locale preferences that can be used to disambiguate 81 * the provided text. If no locale preferences exist, set this to null or an empty locale 82 * list in which case the classifier will decide whether to use no locale information, use 83 * a default locale, or use the system default. 84 * 85 * @throws IllegalArgumentException if text is null; selectionStartIndex is negative; 86 * selectionEndIndex is greater than text.length() or not greater than selectionStartIndex 87 */ 88 @WorkerThread 89 @NonNull suggestSelection( @onNull CharSequence text, @IntRange(from = 0) int selectionStartIndex, @IntRange(from = 0) int selectionEndIndex, @Nullable LocaleList defaultLocales)90 TextSelection suggestSelection( 91 @NonNull CharSequence text, 92 @IntRange(from = 0) int selectionStartIndex, 93 @IntRange(from = 0) int selectionEndIndex, 94 @Nullable LocaleList defaultLocales); 95 96 /** 97 * Classifies the specified text and returns a {@link TextClassification} object that can be 98 * used to generate a widget for handling the classified text. 99 * 100 * @param text text providing context for the text to classify (which is specified 101 * by the sub sequence starting at startIndex and ending at endIndex) 102 * @param startIndex start index of the text to classify 103 * @param endIndex end index of the text to classify 104 * @param defaultLocales ordered list of locale preferences that can be used to disambiguate 105 * the provided text. If no locale preferences exist, set this to null or an empty locale 106 * list in which case the classifier will decide whether to use no locale information, use 107 * a default locale, or use the system default. 108 * 109 * @throws IllegalArgumentException if text is null; startIndex is negative; 110 * endIndex is greater than text.length() or not greater than startIndex 111 */ 112 @WorkerThread 113 @NonNull classifyText( @onNull CharSequence text, @IntRange(from = 0) int startIndex, @IntRange(from = 0) int endIndex, @Nullable LocaleList defaultLocales)114 TextClassification classifyText( 115 @NonNull CharSequence text, 116 @IntRange(from = 0) int startIndex, 117 @IntRange(from = 0) int endIndex, 118 @Nullable LocaleList defaultLocales); 119 120 /** 121 * Returns a {@link LinksInfo} that may be applied to the text to annotate it with links 122 * information. 123 * 124 * @param text the text to generate annotations for 125 * @param linkMask See {@link android.text.util.Linkify} for a list of linkMasks that may be 126 * specified. Subclasses of this interface may specify additional linkMasks 127 * @param defaultLocales ordered list of locale preferences that can be used to disambiguate 128 * the provided text. If no locale preferences exist, set this to null or an empty locale 129 * list in which case the classifier will decide whether to use no locale information, use 130 * a default locale, or use the system default. 131 * 132 * @throws IllegalArgumentException if text is null 133 * @hide 134 */ 135 @WorkerThread getLinks( @onNull CharSequence text, int linkMask, @Nullable LocaleList defaultLocales)136 default LinksInfo getLinks( 137 @NonNull CharSequence text, int linkMask, @Nullable LocaleList defaultLocales) { 138 return LinksInfo.NO_OP; 139 } 140 141 /** 142 * Logs a TextClassifier event. 143 * 144 * @param source the text classifier used to generate this event 145 * @param event the text classifier related event 146 * @hide 147 */ 148 @WorkerThread logEvent(String source, String event)149 default void logEvent(String source, String event) {} 150 } 151