1/*
2 * Copyright (C) 2009 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.android.annotations.Nullable;
21import com.google.common.annotations.Beta;
22
23/**
24 * Represents an XML element with a name, attributes and inner elements.
25 * <p/>
26 * The semantic of the element name is to be a fully qualified class name of a View to inflate.
27 * The element name is not expected to have a namespace.
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 * </p>
32 */
33@Beta
34public interface IDragElement {
35
36    /**
37     * Returns the element name, which must match a fully qualified class name of
38     * a View to inflate.
39     */
40    @NonNull
41    public abstract String getFqcn();
42
43    /**
44     * Returns the bounds of the element's node, if it originated from an existing
45     * canvas. The rectangle is invalid and non-null when the element originated
46     * from the object palette.
47     *
48     * The bounds are absolute for the canvas.
49     */
50    @NonNull
51    public abstract Rect getBounds();
52
53    /**
54     * Returns the fully qualified class name of the parent, if the element originated
55     * from an existing canvas. Returns null if the element has no parent, such as a top
56     * level element or an element originating from the object palette.
57     */
58    @Nullable
59    public abstract String getParentFqcn();
60
61    /**
62     * Returns the bounds of the element's parent, absolute for the canvas, or invalid if there
63     * is no suitable parent. This is generally invalid when {@link #getParentFqcn()} is null.
64     *
65     * The returned rectangle can be invalid. It is never null.
66     */
67    @NonNull
68    public abstract Rect getParentBounds();
69
70    /**
71     * Returns a list of attributes. The list can be empty but is never null.
72     */
73    @NonNull
74    public abstract IDragAttribute[] getAttributes();
75
76    /**
77     * Returns the requested attribute or null if not found.
78     */
79    @Nullable
80    public abstract IDragAttribute getAttribute(@Nullable String uri, @NonNull String localName);
81
82    /**
83     * Returns a list of inner elements. The list can be empty but is never null.
84     */
85    @NonNull
86    public abstract IDragElement[] getInnerElements();
87
88    /**
89     * Returns true if the given {@link INode} represents this drag element
90     *
91     * @param node the node to be checked
92     * @return true if the given node represents this drag element
93     */
94    public abstract boolean isSame(@NonNull INode node);
95
96    /**
97     * An XML attribute in the {@link IDragElement}.
98     * <p/>
99     * The attribute is always represented by a namespace URI, a name and a value.
100     * The name cannot be empty.
101     * The namespace URI can be empty for an attribute without a namespace but is never null.
102     * The value can be empty but cannot be null.
103     */
104    public interface IDragAttribute {
105
106        /**
107         * Returns the namespace URI of the attribute.
108         * Can be empty for an attribute without a namespace but is never null.
109         */
110        @NonNull
111        public abstract String getUri();
112
113        /** Returns the XML local name of the attribute. Cannot be null nor empty. */
114        @NonNull
115        public abstract String getName();
116
117        /** Returns the value of the attribute. Cannot be null. Can be empty. */
118        @NonNull
119        public abstract String getValue();
120    }
121}
122
123