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