1/*
2 * Copyright (C) 2015 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;
18
19import android.annotation.NonNull;
20import android.annotation.Nullable;
21import android.graphics.Matrix;
22import android.graphics.Rect;
23import android.os.Bundle;
24import android.os.LocaleList;
25import android.util.Pair;
26import android.view.View.AutofillImportance;
27import android.view.ViewStructure.HtmlInfo;
28import android.view.autofill.AutofillId;
29import android.view.autofill.AutofillValue;
30
31import com.android.internal.util.Preconditions;
32
33import java.util.List;
34
35/**
36 * Container for storing additional per-view data generated by {@link View#onProvideStructure
37 * View.onProvideStructure} and {@link View#onProvideAutofillStructure
38 * View.onProvideAutofillStructure}.
39 */
40public abstract class ViewStructure {
41
42    /**
43     * Set the identifier for this view.
44     *
45     * @param id The view's identifier, as per {@link View#getId View.getId()}.
46     * @param packageName The package name of the view's identifier, or null if there is none.
47     * @param typeName The type name of the view's identifier, or null if there is none.
48     * @param entryName The entry name of the view's identifier, or null if there is none.
49     */
50    public abstract void setId(int id, String packageName, String typeName, String entryName);
51
52    /**
53     * Set the basic dimensions of this view.
54     *
55     * @param left The view's left position, in pixels relative to its parent's left edge.
56     * @param top The view's top position, in pixels relative to its parent's top edge.
57     * @param scrollX How much the view's x coordinate space has been scrolled, in pixels.
58     * @param scrollY How much the view's y coordinate space has been scrolled, in pixels.
59     * @param width The view's visible width, in pixels.  This is the width visible on screen,
60     * not the total data width of a scrollable view.
61     * @param height The view's visible height, in pixels.  This is the height visible on
62     * screen, not the total data height of a scrollable view.
63     */
64    public abstract void setDimens(int left, int top, int scrollX, int scrollY, int width,
65            int height);
66
67    /**
68     * Set the transformation matrix associated with this view, as per
69     * {@link View#getMatrix View.getMatrix()}, or null if there is none.
70     */
71    public abstract void setTransformation(Matrix matrix);
72
73    /**
74     * Set the visual elevation (shadow) of the view, as per
75     * {@link View#getZ View.getZ()}.  Note this is <em>not</em> related
76     * to the physical Z-ordering of this view relative to its other siblings (that is how
77     * they overlap when drawing), it is only the visual representation for shadowing.
78     */
79    public abstract void setElevation(float elevation);
80
81    /**
82     * Set an alpha transformation that is applied to this view, as per
83     * {@link View#getAlpha View.getAlpha()}.  Value ranges from 0
84     * (completely transparent) to 1 (completely opaque); the default is 1, which means
85     * no transformation.
86     */
87    public abstract void setAlpha(float alpha);
88
89    /**
90     * Set the visibility state of this view, as per
91     * {@link View#getVisibility View.getVisibility()}.
92     */
93    public abstract void setVisibility(int visibility);
94
95    /** @hide */
96    public abstract void setAssistBlocked(boolean state);
97
98    /**
99     * Set the enabled state of this view, as per {@link View#isEnabled View.isEnabled()}.
100     */
101    public abstract void setEnabled(boolean state);
102
103    /**
104     * Set the clickable state of this view, as per {@link View#isClickable View.isClickable()}.
105     */
106    public abstract void setClickable(boolean state);
107
108    /**
109     * Set the long clickable state of this view, as per
110     * {@link View#isLongClickable View.isLongClickable()}.
111     */
112    public abstract void setLongClickable(boolean state);
113
114    /**
115     * Set the context clickable state of this view, as per
116     * {@link View#isContextClickable View.isContextClickable()}.
117     */
118    public abstract void setContextClickable(boolean state);
119
120    /**
121     * Set the focusable state of this view, as per {@link View#isFocusable View.isFocusable()}.
122     */
123    public abstract void setFocusable(boolean state);
124
125    /**
126     * Set the focused state of this view, as per {@link View#isFocused View.isFocused()}.
127     */
128    public abstract void setFocused(boolean state);
129
130    /**
131     * Set the accessibility focused state of this view, as per
132     * {@link View#isAccessibilityFocused View.isAccessibilityFocused()}.
133     */
134    public abstract void setAccessibilityFocused(boolean state);
135
136    /**
137     * Set the checkable state of this view, such as whether it implements the
138     * {@link android.widget.Checkable} interface.
139     */
140    public abstract void setCheckable(boolean state);
141
142    /**
143     * Set the checked state of this view, such as
144     * {@link android.widget.Checkable#isChecked Checkable.isChecked()}.
145     */
146    public abstract void setChecked(boolean state);
147
148    /**
149     * Set the selected state of this view, as per {@link View#isSelected View.isSelected()}.
150     */
151    public abstract void setSelected(boolean state);
152
153    /**
154     * Set the activated state of this view, as per {@link View#isActivated View.isActivated()}.
155     */
156    public abstract void setActivated(boolean state);
157
158    /**
159     * Set the opaque state of this view, as per {@link View#isOpaque View.isOpaque()}.
160     */
161    public abstract void setOpaque(boolean opaque);
162
163    /**
164     * Set the class name of the view, as per
165     * {@link View#getAccessibilityClassName View.getAccessibilityClassName()}.
166     */
167    public abstract void setClassName(String className);
168
169    /**
170     * Set the content description of the view, as per
171     * {@link View#getContentDescription View.getContentDescription()}.
172     */
173    public abstract void setContentDescription(CharSequence contentDescription);
174
175    /**
176     * Set the text that is associated with this view.  There is no selection
177     * associated with the text.  The text may have style spans to supply additional
178     * display and semantic information.
179     */
180    public abstract void setText(CharSequence text);
181
182    /**
183     * Like {@link #setText(CharSequence)} but with an active selection
184     * extending from <var>selectionStart</var> through <var>selectionEnd</var>.
185     */
186    public abstract void setText(CharSequence text, int selectionStart, int selectionEnd);
187
188    /**
189     * Explicitly set default global style information for text that was previously set with
190     * {@link #setText}.
191     *
192     * @param size The size, in pixels, of the text.
193     * @param fgColor The foreground color, packed as 0xAARRGGBB.
194     * @param bgColor The background color, packed as 0xAARRGGBB.
195     * @param style Style flags, as defined by {@link android.app.assist.AssistStructure.ViewNode}.
196     */
197    public abstract void setTextStyle(float size, int fgColor, int bgColor, int style);
198
199    /**
200     * Set line information for test that was previously supplied through
201     * {@link #setText(CharSequence)}.  This provides the line breaking of the text as it
202     * is shown on screen.  This function takes ownership of the provided arrays; you should
203     * not make further modification to them.
204     *
205     * @param charOffsets The offset in to {@link #setText} where a line starts.
206     * @param baselines The baseline where the line is drawn on screen.
207     */
208    public abstract void setTextLines(int[] charOffsets, int[] baselines);
209
210    /**
211     * Sets the identifier used to set the text associated with this view.
212     *
213     * <p>Should only be set when the node is used for autofill purposes - it will be ignored
214     * when used for Assist.
215     */
216    public void setTextIdEntry(@NonNull String entryName) {
217        Preconditions.checkNotNull(entryName);
218    }
219
220    /**
221     * Set optional hint text associated with this view; this is for example the text that is
222     * shown by an EditText when it is empty to indicate to the user the kind of text to input.
223     */
224    public abstract void setHint(CharSequence hint);
225
226    /**
227     * Retrieve the last {@link #setText(CharSequence)}.
228     */
229    public abstract CharSequence getText();
230
231    /**
232     * Retrieve the last selection start set by {@link #setText(CharSequence, int, int)}.
233     */
234    public abstract int getTextSelectionStart();
235
236    /**
237     * Retrieve the last selection end set by {@link #setText(CharSequence, int, int)}.
238     */
239    public abstract int getTextSelectionEnd();
240
241    /**
242     * Retrieve the last hint set by {@link #setHint}.
243     */
244    public abstract CharSequence getHint();
245
246    /**
247     * Get extra data associated with this view structure; the returned Bundle is mutable,
248     * allowing you to view and modify its contents.  Keys placed in the Bundle should use
249     * an appropriate namespace prefix (such as com.google.MY_KEY) to avoid conflicts.
250     */
251    public abstract Bundle getExtras();
252
253    /**
254     * Returns true if {@link #getExtras} has been used to create extra content.
255     */
256    public abstract boolean hasExtras();
257
258    /**
259     * Set the number of children of this view, which defines the range of indices you can
260     * use with {@link #newChild} and {@link #asyncNewChild}.  Calling this method again
261     * resets all of the child state of the view, removing any children that had previously
262     * been added.
263     */
264    public abstract void setChildCount(int num);
265
266    /**
267     * Add to this view's child count.  This increases the current child count by
268     * <var>num</var> children beyond what was last set by {@link #setChildCount}
269     * or {@link #addChildCount}.  The index at which the new child starts in the child
270     * array is returned.
271     *
272     * @param num The number of new children to add.
273     * @return Returns the index in the child array at which the new children start.
274     */
275    public abstract int addChildCount(int num);
276
277    /**
278     * Return the child count as set by {@link #setChildCount}.
279     */
280    public abstract int getChildCount();
281
282    /**
283     * Create a new child {@link ViewStructure} in this view, putting into the list of
284     * children at <var>index</var>.
285     *
286     * <p><b>NOTE: </b>you must pre-allocate space for the child first, by calling either
287     * {@link #addChildCount(int)} or {@link #setChildCount(int)}.
288     *
289     * @return Returns an fresh {@link ViewStructure} ready to be filled in.
290     */
291    public abstract ViewStructure newChild(int index);
292
293    /**
294     * Like {@link #newChild}, but allows the caller to asynchronously populate the returned
295     * child.  It can transfer the returned {@link ViewStructure} to another thread for it
296     * to build its content (and children etc).  Once done, some thread must call
297     * {@link #asyncCommit} to tell the containing {@link ViewStructure} that the async
298     * population is done.
299     *
300     * <p><b>NOTE: </b>you must pre-allocate space for the child first, by calling either
301     * {@link #addChildCount(int)} or {@link #setChildCount(int)}.
302     *
303     * @return Returns an fresh {@link ViewStructure} ready to be filled in.
304     */
305    public abstract ViewStructure asyncNewChild(int index);
306
307    /**
308     * Gets the {@link AutofillId} associated with this node.
309     */
310    @Nullable
311    public abstract AutofillId getAutofillId();
312
313    /**
314     * Sets the {@link AutofillId} associated with this node.
315     */
316    public abstract void setAutofillId(@NonNull AutofillId id);
317
318    /**
319     * Sets the {@link AutofillId} for this virtual node.
320     *
321     * @param parentId id of the parent node.
322     * @param virtualId an opaque ID to the Android System; it's the same id used on
323     *            {@link View#autofill(android.util.SparseArray)}.
324     */
325    public abstract void setAutofillId(@NonNull AutofillId parentId, int virtualId);
326
327    /**
328     * Sets the {@link View#getAutofillType()} that can be used to autofill this node.
329     */
330    public abstract void setAutofillType(@View.AutofillType int type);
331
332    /**
333     * Sets the a hints that helps the autofill service to select the appropriate data to fill the
334     * view.
335     */
336    public abstract void setAutofillHints(@Nullable String[] hint);
337
338    /**
339     * Sets the {@link AutofillValue} representing the current value of this node.
340     */
341    public abstract void setAutofillValue(AutofillValue value);
342
343    /**
344     * Sets the options that can be used to autofill this node.
345     *
346     * <p>Typically used by nodes whose {@link View#getAutofillType()} is a list to indicate the
347     * meaning of each possible value in the list.
348     */
349    public abstract void setAutofillOptions(CharSequence[] options);
350
351    /**
352     * Sets the {@link View#setImportantForAutofill(int) importantForAutofill mode} of the
353     * view associated with this node.
354     */
355    public void setImportantForAutofill(@AutofillImportance int mode) {}
356
357    /**
358     * Sets the {@link android.text.InputType} bits of this node.
359     *
360     * @param inputType inputType bits as defined by {@link android.text.InputType}.
361     */
362    public abstract void setInputType(int inputType);
363
364    /**
365     * Sets whether the data on this node is sensitive; if it is, then its content (text, autofill
366     * value, etc..) is striped before calls to {@link
367     * android.service.autofill.AutofillService#onFillRequest(android.service.autofill.FillRequest,
368     * android.os.CancellationSignal, android.service.autofill.FillCallback)}.
369     *
370     * <p>By default, all nodes are assumed to be sensitive, and only nodes that does not have PII
371     * (Personally Identifiable Information - sensitive data such as email addresses, credit card
372     * numbers, passwords, etc...) should be marked as non-sensitive; a good rule of thumb is to
373     * mark as non-sensitive nodes whose value were statically set from resources.
374     *
375     * <p>Notice that the content of even sensitive nodes are sent to the service (through the
376     * {@link
377     * android.service.autofill.AutofillService#onSaveRequest(android.service.autofill.SaveRequest,
378     * android.service.autofill.SaveCallback)} call) when the user consented to save
379     * thedata, so it is important to set the content of sensitive nodes as well, but mark them as
380     * sensitive.
381     *
382     * <p>Should only be set when the node is used for autofill purposes - it will be ignored
383     * when used for Assist.
384     */
385    public abstract void setDataIsSensitive(boolean sensitive);
386
387    /**
388     * Sets the minimum width in ems of the text associated with this view, when supported.
389     *
390     * <p>Should only be set when the node is used for autofill purposes - it will be ignored
391     * when used for Assist.
392     */
393    public void setMinTextEms(@SuppressWarnings("unused") int minEms) {}
394
395    /**
396     * Sets the maximum width in ems of the text associated with this view, when supported.
397     *
398     * <p>Should only be set when the node is used for autofill purposes - it will be ignored
399     * when used for Assist.
400     */
401    public void setMaxTextEms(@SuppressWarnings("unused") int maxEms) {}
402
403    /**
404     * Sets the maximum length of the text associated with this view, when supported.
405     *
406     * <p>Should only be set when the node is used for autofill purposes - it will be ignored
407     * when used for Assist.
408     */
409    public void setMaxTextLength(@SuppressWarnings("unused") int maxLength) {}
410
411    /**
412     * Call when done populating a {@link ViewStructure} returned by
413     * {@link #asyncNewChild}.
414     */
415    public abstract void asyncCommit();
416
417    /** @hide */
418    public abstract Rect getTempRect();
419
420    /**
421     * Sets the Web domain represented by this node.
422     *
423     * <p>Typically used when the view is a container for an HTML document.
424     *
425     * @param domain RFC 2396-compliant URI representing the domain.
426     */
427    public abstract void setWebDomain(@Nullable String domain);
428
429    /**
430     * Sets the the list of locales associated with this node.
431     */
432    public abstract void setLocaleList(LocaleList localeList);
433
434    /**
435     * Creates a new {@link HtmlInfo.Builder} for the given HTML tag.
436     *
437     * @param tagName name of the HTML tag.
438     * @return a new builder.
439     */
440    public abstract HtmlInfo.Builder newHtmlInfoBuilder(@NonNull String tagName);
441
442    /**
443     * Sets the HTML properties of this node when it represents an HTML element.
444     *
445     * <p>Should only be set when the node is used for autofill purposes - it will be ignored
446     * when used for assist.
447     *
448     * @param htmlInfo HTML properties.
449     */
450    public abstract void setHtmlInfo(@NonNull HtmlInfo htmlInfo);
451
452    /**
453     * Simplified representation of the HTML properties of a node that represents an HTML element.
454     */
455    public abstract static class HtmlInfo {
456
457        /**
458         * Gets the HTML tag.
459         */
460        @NonNull
461        public abstract String getTag();
462
463        /**
464         * Gets the list of HTML attributes.
465         *
466         * @return list of key/value pairs; could contain pairs with the same keys.
467         */
468        @Nullable
469        public abstract List<Pair<String, String>> getAttributes();
470
471        /**
472         * Builder for {@link HtmlInfo} objects.
473         */
474        public abstract static class Builder {
475
476            /**
477             * Adds an HTML attribute.
478             *
479             * @param name name of the attribute.
480             * @param value value of the attribute.
481             * @return same builder, for chaining.
482             */
483            public abstract Builder addAttribute(@NonNull String name, @NonNull String value);
484
485            /**
486             * Builds the {@link HtmlInfo} object.
487             *
488             * @return a new {@link HtmlInfo} instance.
489             */
490            public abstract HtmlInfo build();
491        }
492    }
493}
494