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 17 18 package com.android.ide.common.api; 19 20 import com.android.ide.common.api.IDragElement.IDragAttribute; 21 22 import java.util.List; 23 24 25 /** 26 * Represents a view in the XML layout being edited. 27 * Each view or layout maps to exactly one XML node, thus the name. 28 * <p/> 29 * The primordial characteristic of a node is the fully qualified View class name that 30 * it represents (a.k.a FQCN), for example "android.view.View" or "android.widget.Button". 31 * <p/> 32 * There are 2 kind of nodes: 33 * - Nodes matching a view actually rendered in the layout canvas have a valid "bounds" 34 * rectangle that describe their position in pixels in the canvas. <br/> 35 * - Nodes created by IViewRule scripts but not yet rendered have an invalid bounds rectangle 36 * since they only exist in the uncommitted XML model and not yet in the rendered View model. 37 * <p> 38 * <b>NOTE: This is not a public or final API; if you rely on this be prepared 39 * to adjust your code for the next tools release.</b> 40 * </p> 41 */ 42 public interface INode { 43 44 /** 45 * Returns the FQCN of the view class represented by this node. 46 */ 47 String getFqcn(); 48 49 /** 50 * Returns the bounds of this node. 51 * <p/> 52 * The bounds are valid when this node maps a view that is already rendered. 53 * Typically, if the node is the target of a drag'n'drop operation then you can be 54 * guaranteed that its bounds are known and thus are valid. 55 * <p/> 56 * However the bounds are invalid (e.g. not known yet) for new XML elements 57 * that have just been created, e.g. by the {@link #appendChild(String)} method. 58 * 59 * @return A non-null rectangle, in canvas coordinates. 60 */ 61 Rect getBounds(); 62 63 /** 64 * Returns the margins for this node. 65 * 66 * @return the margins for this node, never null 67 */ 68 Margins getMargins(); 69 70 /** 71 * Returns the baseline of this node, or -1 if it has no baseline. 72 * The baseline is the distance from the top down to the baseline. 73 * 74 * @return the baseline, or -1 if not applicable 75 */ 76 int getBaseline(); 77 78 // ---- Hierarchy handling ---- 79 80 /** 81 * Returns the root element of the view hierarchy. 82 * <p/> 83 * When a node is not attached to a hierarchy, it is its own root node. 84 * This may return null if the {@link INode} was not created using a correct UiNode, 85 * which is unlikely. 86 */ 87 INode getRoot(); 88 89 /** 90 * Returns the parent node of this node, corresponding to the parent view in the layout. 91 * The returned parent can be null when the node is the root element, or when the node is 92 * not yet or no longer attached to the hierarchy. 93 */ 94 INode getParent(); 95 96 /** 97 * Returns the list of valid children nodes. The list can be empty but not null. 98 */ 99 INode[] getChildren(); 100 101 102 // ---- XML Editing --- 103 104 /** 105 * Absolutely <em>all</em> calls that are going to edit the XML must be wrapped 106 * by an editXml() call. This call creates both an undo context wrapper and an 107 * edit-XML wrapper. 108 * 109 * @param undoName The UI name that will be given to the undo action. 110 * @param callback The code to execute. 111 */ 112 void editXml(String undoName, final INodeHandler callback); 113 114 // TODO define an exception that methods below will throw if editXml() is not wrapping 115 // these calls. 116 117 /** 118 * Creates a new XML element as a child of this node's XML element. 119 * <p/> 120 * For this to work, the editor must have a descriptor for the given FQCN. 121 * <p/> 122 * This call must be done in the context of editXml(). 123 * 124 * @param viewFqcn The FQCN of the element to create. The actual XML local name will 125 * depend on whether this is an Android view or a custom project view. 126 * @return The node for the newly created element. Can be null if we failed to create it. 127 */ 128 INode appendChild(String viewFqcn); 129 130 /** 131 * Creates a new XML element as a child of this node's XML element and inserts 132 * it at the specified position in the children list. 133 * <p/> 134 * For this to work, the editor must have a descriptor for the given FQCN. 135 * <p/> 136 * This call must be done in the context of editXml(). 137 * 138 * @param viewFqcn The FQCN of the element to create. The actual XML local name will 139 * depend on whether this is an Android view or a custom project view. 140 * @param index Index of the child to insert before. If the index is out of bounds 141 * (less than zero or larger that current last child), appends at the end. 142 * @return The node for the newly created element. Can be null if we failed to create it. 143 */ 144 INode insertChildAt(String viewFqcn, int index); 145 146 /** 147 * Removes the given XML element child from this node's list of children. 148 * <p/> 149 * This call must be done in the context of editXml(). 150 * 151 * @param node The child to be deleted. 152 */ 153 void removeChild(INode node); 154 155 /** 156 * Sets an attribute for the underlying XML element. 157 * Attributes are not written immediately -- instead the XML editor batches edits and 158 * then commits them all together at once later. 159 * <p/> 160 * Custom attributes will be created on the fly. 161 * <p/> 162 * Passing an empty value actually <em>removes</em> an attribute from the XML. 163 * <p/> 164 * This call must be done in the context of editXml(). 165 * 166 * @param uri The XML namespace URI of the attribute. 167 * @param localName The XML <em>local</em> name of the attribute to set. 168 * @param value It's value. Cannot be null. An empty value <em>removes</em> the attribute. 169 * @return Whether the attribute was actually set or not. 170 */ 171 boolean setAttribute(String uri, String localName, String value); 172 173 /** 174 * Returns a given XML attribute. 175 * <p/> 176 * This looks up an attribute in the <em>current</em> XML source, not the in-memory model. 177 * That means that if called in the context of {@link #editXml(String, INodeHandler)}, the value 178 * returned here is not affected by {@link #setAttribute(String, String, String)} until 179 * the editXml closure is completed and the actual XML is updated. 180 * 181 * @param uri The XML name-space URI of the attribute. 182 * @param attrName The <em>local</em> name of the attribute. 183 * @return the attribute as a {@link String}, if it exists, or <code>null</code>. 184 */ 185 String getStringAttr(String uri, String attrName); 186 187 /** 188 * Returns the {@link IAttributeInfo} for a given attribute. 189 * <p/> 190 * The information is useful to determine the format of an attribute (e.g. reference, string, 191 * float, enum, flag, etc.) and in the case of enums and flags also gives the possible values. 192 * <p/> 193 * Note: in Android resources, an enum can only take one of the possible values (e.g. 194 * "visibility" can be either "visible" or "none"), whereas a flag can accept one or more 195 * value (e.g. "align" can be "center_vertical|center_horizontal".) 196 * <p/> 197 * Note that this method does not handle custom non-android attributes. It may either 198 * return null for these or it may return a synthetic "string" format attribute depending 199 * on how the attribute was loaded. 200 * 201 * @param uri The XML name-space URI of the attribute. 202 * @param attrName The <em>local</em> name of the attribute. 203 * @return the {@link IAttributeInfo} if the attribute is known, or <code>null</code>. 204 */ 205 public IAttributeInfo getAttributeInfo(String uri, String attrName); 206 207 /** 208 * Returns the list of all attributes declared by this node's descriptor. 209 * <p/> 210 * This returns a fixed list of all attributes known to the view or layout descriptor. 211 * This list does not depend on whether the attributes are actually used in the 212 * XML for this node. 213 * <p/> 214 * Note that for views, the list of attributes also includes the layout attributes 215 * inherited from the parent view. This means callers must not cache this list based 216 * solely on the type of the node, as its attribute list changes depending on the place 217 * of the view in the view hierarchy. 218 * <p/> 219 * If you want attributes actually written in the XML and their values, please use 220 * {@link #getStringAttr(String, String)} or {@link #getLiveAttributes()} instead. 221 * 222 * @return A non-null possibly-empty list of {@link IAttributeInfo}. 223 */ 224 public IAttributeInfo[] getDeclaredAttributes(); 225 226 /** 227 * Returns the list of classes (fully qualified class names) that are 228 * contributing properties to the {@link #getDeclaredAttributes()} attribute 229 * list, in order from most specific to least specific (in other words, 230 * android.view.View will be last in the list.) This is usually the same as 231 * the super class chain of a view, but it skips any views that do not 232 * contribute attributes. 233 * 234 * @return a list of views classes that contribute attributes to this node, 235 * which is never null because at least android.view.View will 236 * contribute attributes. 237 */ 238 public List<String> getAttributeSources(); 239 240 /** 241 * Returns the list of all attributes defined in the XML for this node. 242 * <p/> 243 * This looks up an attribute in the <em>current</em> XML source, not the in-memory model. 244 * That means that if called in the context of {@link #editXml(String, INodeHandler)}, the value 245 * returned here is not affected by {@link #setAttribute(String, String, String)} until 246 * the editXml closure is completed and the actual XML is updated. 247 * <p/> 248 * If you want a list of all possible attributes, whether used in the XML or not by 249 * this node, please see {@link #getDeclaredAttributes()} instead. 250 * 251 * @return A non-null possibly-empty list of {@link IAttribute}. 252 */ 253 public IAttribute[] getLiveAttributes(); 254 255 // ----------- 256 257 /** 258 * An XML attribute in an {@link INode} with a namespace URI, a name and its current value. 259 * <p/> 260 * The name cannot be empty. 261 * The namespace URI can be empty for an attribute without a namespace but is never null. 262 * The value can be empty but cannot be null. 263 */ 264 public static interface IAttribute extends IDragAttribute { } 265 } 266
