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