1/*
2 * Copyright 2018 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 android.view.textclassifier;
18
19import android.annotation.NonNull;
20import android.annotation.Nullable;
21import android.text.Spannable;
22import android.text.style.ClickableSpan;
23import android.text.util.Linkify;
24import android.text.util.Linkify.LinkifyMask;
25import android.view.textclassifier.TextLinks.TextLink;
26import android.view.textclassifier.TextLinks.TextLinkSpan;
27
28import com.android.internal.util.Preconditions;
29
30import java.util.ArrayList;
31import java.util.List;
32import java.util.function.Function;
33
34/**
35 * Parameters for generating and applying links.
36 * @hide
37 */
38public final class TextLinksParams {
39
40    /**
41     * A function to create spans from TextLinks.
42     */
43    private static final Function<TextLink, TextLinkSpan> DEFAULT_SPAN_FACTORY =
44            textLink -> new TextLinkSpan(textLink);
45
46    @TextLinks.ApplyStrategy
47    private final int mApplyStrategy;
48    private final Function<TextLink, TextLinkSpan> mSpanFactory;
49    private final TextClassifier.EntityConfig mEntityConfig;
50
51    private TextLinksParams(
52            @TextLinks.ApplyStrategy int applyStrategy,
53            Function<TextLink, TextLinkSpan> spanFactory) {
54        mApplyStrategy = applyStrategy;
55        mSpanFactory = spanFactory;
56        mEntityConfig = TextClassifier.EntityConfig.createWithHints(null);
57    }
58
59    /**
60     * Returns a new TextLinksParams object based on the specified link mask.
61     *
62     * @param mask the link mask
63     *      e.g. {@link LinkifyMask#PHONE_NUMBERS} | {@link LinkifyMask#EMAIL_ADDRESSES}
64     * @hide
65     */
66    @NonNull
67    public static TextLinksParams fromLinkMask(@LinkifyMask int mask) {
68        final List<String> entitiesToFind = new ArrayList<>();
69        if ((mask & Linkify.WEB_URLS) != 0) {
70            entitiesToFind.add(TextClassifier.TYPE_URL);
71        }
72        if ((mask & Linkify.EMAIL_ADDRESSES) != 0) {
73            entitiesToFind.add(TextClassifier.TYPE_EMAIL);
74        }
75        if ((mask & Linkify.PHONE_NUMBERS) != 0) {
76            entitiesToFind.add(TextClassifier.TYPE_PHONE);
77        }
78        if ((mask & Linkify.MAP_ADDRESSES) != 0) {
79            entitiesToFind.add(TextClassifier.TYPE_ADDRESS);
80        }
81        return new TextLinksParams.Builder().setEntityConfig(
82                TextClassifier.EntityConfig.createWithExplicitEntityList(entitiesToFind))
83                .build();
84    }
85
86    /**
87     * Returns the entity config used to determine what entity types to generate.
88     */
89    @NonNull
90    public TextClassifier.EntityConfig getEntityConfig() {
91        return mEntityConfig;
92    }
93
94    /**
95     * Annotates the given text with the generated links. It will fail if the provided text doesn't
96     * match the original text used to crete the TextLinks.
97     *
98     * @param text the text to apply the links to. Must match the original text
99     * @param textLinks the links to apply to the text
100     *
101     * @return a status code indicating whether or not the links were successfully applied
102     * @hide
103     */
104    @TextLinks.Status
105    public int apply(@NonNull Spannable text, @NonNull TextLinks textLinks) {
106        Preconditions.checkNotNull(text);
107        Preconditions.checkNotNull(textLinks);
108
109        final String textString = text.toString();
110        if (!textString.startsWith(textLinks.getText())) {
111            return TextLinks.STATUS_DIFFERENT_TEXT;
112        }
113        if (textLinks.getLinks().isEmpty()) {
114            return TextLinks.STATUS_NO_LINKS_FOUND;
115        }
116
117        int applyCount = 0;
118        for (TextLink link : textLinks.getLinks()) {
119            final TextLinkSpan span = mSpanFactory.apply(link);
120            if (span != null) {
121                final ClickableSpan[] existingSpans = text.getSpans(
122                        link.getStart(), link.getEnd(), ClickableSpan.class);
123                if (existingSpans.length > 0) {
124                    if (mApplyStrategy == TextLinks.APPLY_STRATEGY_REPLACE) {
125                        for (ClickableSpan existingSpan : existingSpans) {
126                            text.removeSpan(existingSpan);
127                        }
128                        text.setSpan(span, link.getStart(), link.getEnd(),
129                                Spannable.SPAN_EXCLUSIVE_EXCLUSIVE);
130                        applyCount++;
131                    }
132                } else {
133                    text.setSpan(span, link.getStart(), link.getEnd(),
134                            Spannable.SPAN_EXCLUSIVE_EXCLUSIVE);
135                    applyCount++;
136                }
137            }
138        }
139        if (applyCount == 0) {
140            return TextLinks.STATUS_NO_LINKS_APPLIED;
141        }
142        return TextLinks.STATUS_LINKS_APPLIED;
143    }
144
145    /**
146     * A builder for building TextLinksParams.
147     */
148    public static final class Builder {
149
150        @TextLinks.ApplyStrategy
151        private int mApplyStrategy = TextLinks.APPLY_STRATEGY_IGNORE;
152        private Function<TextLink, TextLinkSpan> mSpanFactory = DEFAULT_SPAN_FACTORY;
153
154        /**
155         * Sets the apply strategy used to determine how to apply links to text.
156         *      e.g {@link TextLinks#APPLY_STRATEGY_IGNORE}
157         *
158         * @return this builder
159         */
160        public Builder setApplyStrategy(@TextLinks.ApplyStrategy int applyStrategy) {
161            mApplyStrategy = checkApplyStrategy(applyStrategy);
162            return this;
163        }
164
165        /**
166         * Sets a custom span factory for converting TextLinks to TextLinkSpans.
167         * Set to {@code null} to use the default span factory.
168         *
169         * @return this builder
170         */
171        public Builder setSpanFactory(@Nullable Function<TextLink, TextLinkSpan> spanFactory) {
172            mSpanFactory = spanFactory == null ? DEFAULT_SPAN_FACTORY : spanFactory;
173            return this;
174        }
175
176        /**
177         * Sets the entity configuration used to determine what entity types to generate.
178         * Set to {@code null} for the default entity config which will automatically determine
179         * what links to generate.
180         *
181         * @return this builder
182         */
183        public Builder setEntityConfig(@Nullable TextClassifier.EntityConfig entityConfig) {
184            return this;
185        }
186
187        /**
188         * Builds and returns a TextLinksParams object.
189         */
190        public TextLinksParams build() {
191            return new TextLinksParams(mApplyStrategy, mSpanFactory);
192        }
193    }
194
195    /** @throws IllegalArgumentException if the value is invalid */
196    @TextLinks.ApplyStrategy
197    private static int checkApplyStrategy(int applyStrategy) {
198        if (applyStrategy != TextLinks.APPLY_STRATEGY_IGNORE
199                && applyStrategy != TextLinks.APPLY_STRATEGY_REPLACE) {
200            throw new IllegalArgumentException(
201                    "Invalid apply strategy. See TextLinksParams.ApplyStrategy for options.");
202        }
203        return applyStrategy;
204    }
205}
206
207