IViewMetadata.java revision 5d7dc30638953195ed55d32bc9dc37102a613ff8 
1/*
2 * Copyright (C) 2010 The Android Open Source Project
3 *
4 * Licensed under the Eclipse Public License, Version 1.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.eclipse.org/org/documents/epl-v10.php
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.android.ide.common.api;
18
19import com.android.annotations.NonNull;
20import com.google.common.annotations.Beta;
21
22import java.util.List;
23
24/**
25 * Metadata about a particular view. The metadata for a View can be found by asking the
26 * {@link IClientRulesEngine} for the metadata for a given class via
27 * {@link IClientRulesEngine#getMetadata}.
28 * <p>
29 * <b>NOTE: This is not a public or final API; if you rely on this be prepared
30 * to adjust your code for the next tools release.</b>
31 */
32@Beta
33public interface IViewMetadata {
34    /**
35     * Returns the display name views of this type (a name suitable to display to the
36     * user, normally capitalized and usually but not necessarily tied to the
37     * implementation class). To be clear, a specific view may have an id attribute and a
38     * text attribute, <b>neither</b> of these is the display name. Instead, the class
39     * android.widget.ZoomControls may have the display name "Zoom Controls", and an
40     * individual view created into a layout can for example have the id "ZoomControl01".
41     *
42     * @return the user visible name of views of this type (never null)
43     */
44    @NonNull
45    public String getDisplayName();
46
47    /**
48     * Gets the insets for this view
49     *
50     * @return the insets for this view
51     */
52    @NonNull
53    public Margins getInsets();
54
55    /**
56     * Returns the {@link FillPreference} of this view
57     *
58     * @return the {@link FillPreference} of this view, never null but may be
59     *     {@link FillPreference#NONE}
60     */
61    @NonNull
62    public FillPreference getFillPreference();
63
64    /**
65     * Returns the most common attributes for this view.
66     *
67     * @return a list of attribute names (not including a namespace prefix) that
68     *         are commonly set for this type of view, never null
69     */
70    @NonNull
71    public List<String> getTopAttributes();
72
73    /**
74     * Types of fill behavior that views can prefer.
75     * <p>
76     * TODO: Consider better names. FillPolicy? Stretchiness?
77     */
78    public enum FillPreference {
79        /** This view does not want to fill */
80        NONE,
81        /** This view wants to always fill both horizontal and vertical */
82        BOTH,
83        /** This view wants to fill horizontally but not vertically */
84        WIDTH,
85        /** This view wants to fill vertically but not horizontally */
86        HEIGHT,
87        /**
88         * This view wants to fill in the opposite dimension of the context, e.g. in a
89         * vertical context it wants to fill horizontally, and vice versa
90         */
91        OPPOSITE,
92        /** This view wants to fill horizontally, but only in a vertical context */
93        WIDTH_IN_VERTICAL,
94        /** This view wants to fill vertically, but only in a horizontal context */
95        HEIGHT_IN_HORIZONTAL;
96
97        /**
98         * Returns true if this view wants to fill horizontally, if the context is
99         * vertical or horizontal as indicated by the parameter.
100         *
101         * @param verticalContext If true, the context is vertical, otherwise it is
102         *            horizontal.
103         * @return true if this view wants to fill horizontally
104         */
105        public boolean fillHorizontally(boolean verticalContext) {
106            return (this == BOTH || this == WIDTH ||
107                    (verticalContext && (this == OPPOSITE || this == WIDTH_IN_VERTICAL)));
108        }
109
110        /**
111         * Returns true if this view wants to fill vertically, if the context is
112         * vertical or horizontal as indicated by the parameter.
113         *
114         * @param verticalContext If true, the context is vertical, otherwise it is
115         *            horizontal.
116         * @return true if this view wants to fill vertically
117         */
118        public boolean fillVertically(boolean verticalContext) {
119            return (this == BOTH || this == HEIGHT ||
120                    (!verticalContext && (this == OPPOSITE || this == HEIGHT_IN_HORIZONTAL)));
121        }
122    }
123}
124