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 17 18 package com.android.ide.common.api; 19 20 import com.android.annotations.NonNull; 21 import com.android.annotations.Nullable; 22 import com.google.common.annotations.Beta; 23 24 import java.util.Collection; 25 import java.util.Map; 26 27 /** 28 * A Client Rules Engine is a set of methods that {@link IViewRule}s can use to 29 * access the client public API of the Rules Engine. 30 * <p> 31 * <b>NOTE: This is not a public or final API; if you rely on this be prepared 32 * to adjust your code for the next tools release.</b> 33 * </p> 34 */ 35 @Beta 36 public interface IClientRulesEngine { 37 38 /** 39 * Returns the FQCN for which the rule was loaded. 40 * 41 * @return the fully qualified name of the rule 42 */ 43 @NonNull 44 String getFqcn(); 45 46 /** 47 * Returns the most recently rendered View object for this node, if any. 48 * 49 * @param node the node to look up the view object for 50 * @return the corresponding view object, or null 51 */ 52 @Nullable 53 Object getViewObject(@NonNull INode node); 54 55 /** 56 * Prints a debug line in the Eclipse console using the ADT formatter. 57 * 58 * @param msg A String format message. 59 * @param params Optional parameters for the message. 60 */ 61 void debugPrintf(@NonNull String msg, Object...params); 62 63 /** 64 * Loads and returns an {@link IViewRule} for the given FQCN. 65 * 66 * @param fqcn A non-null, non-empty FQCN for the rule to load. 67 * @return The rule that best matches the given FQCN according to the 68 * inheritance chain. Rules are cached and requesting the same FQCN twice 69 * is fast and will return the same rule instance. 70 */ 71 @Nullable 72 IViewRule loadRule(@NonNull String fqcn); 73 74 /** 75 * Returns the metadata associated with the given fully qualified class name. Note that 76 * this will always return an {@link IViewMetadata} instance, even when the class name 77 * is unknown to the layout editor, such as for custom views. In that case, some 78 * heuristics will be applied to return metadata information such as guesses for 79 * what the most common attribute is, and so on. 80 * 81 * @param fqcn a fully qualified class name for an Android view class 82 * @return the metadata associated with the given fully qualified class name. 83 */ 84 @NonNull 85 IViewMetadata getMetadata(@NonNull String fqcn); 86 87 /** 88 * Displays the given message string in an alert dialog with an "OK" button. 89 * 90 * @param message the message to be shown 91 */ 92 void displayAlert(@NonNull String message); 93 94 /** 95 * Displays a simple input alert dialog with an OK and Cancel buttons. 96 * 97 * @param message The message to display in the alert dialog. 98 * @param value The initial value to display in the input field. Can be null. 99 * @param filter An optional filter to validate the input. Specify null (or 100 * a validator which always returns true) if you do not want 101 * input validation. 102 * @return Null if canceled by the user. Otherwise the possibly-empty input string. 103 */ 104 @Nullable 105 String displayInput(@NonNull String message, @Nullable String value, 106 @Nullable IValidator filter); 107 108 /** 109 * Returns the minimum API level that the current Android project is targeting. 110 * 111 * @return the minimum API level to be supported, or -1 if it cannot be determined 112 */ 113 int getMinApiLevel(); 114 115 /** 116 * Returns a resource name validator for the current project 117 * 118 * @param resourceTypeName resource type, such as "id", "string", and so on 119 * @param uniqueInProject if true, the resource name must be unique in the 120 * project (not already be defined anywhere else) 121 * @param uniqueInLayout if true, the resource name must be unique at least 122 * within the current layout. This only applies to {@code @id} 123 * resources since only those resources can be defined in-place 124 * within a layout 125 * @param exists if true, the resource name must already exist 126 * @param allowed allowed names (optional). This can for example be used to 127 * request a unique-in-layout validator, but to remove the 128 * current value of the node being edited from consideration such 129 * that it allows you to leave the value the same 130 * @return an {@link IValidator} for validating a new resource name in the 131 * current project 132 */ 133 @Nullable 134 IValidator getResourceValidator(@NonNull String resourceTypeName, 135 boolean uniqueInProject, boolean uniqueInLayout, boolean exists, 136 String... allowed); 137 138 /** 139 * Displays an input dialog where the user can enter an Android reference value 140 * 141 * @param currentValue the current reference to select 142 * @return the reference selected by the user, or null 143 */ 144 @Nullable 145 String displayReferenceInput(@Nullable String currentValue); 146 147 /** 148 * Displays an input dialog where the user can enter an Android resource name of the 149 * given resource type ("id", "string", "drawable", and so on.) 150 * 151 * @param currentValue the current reference to select 152 * @param resourceTypeName resource type, such as "id", "string", and so on (never 153 * null) 154 * @return the margins selected by the user in the same order as the input arguments, 155 * or null 156 */ 157 @Nullable 158 String displayResourceInput(@NonNull String resourceTypeName, @Nullable String currentValue); 159 160 /** 161 * Displays an input dialog tailored for editing margin properties. 162 * 163 * @param all The current, initial value display for "all" margins (applied to all 164 * sides) 165 * @param left The current, initial value to display for the "left" margin 166 * @param right The current, initial value to display for the "right" margin 167 * @param top The current, initial value to display for the "top" margin 168 * @param bottom The current, initial value to display for the "bottom" margin 169 * @return an array of length 5 containing the user entered values for the all, left, 170 * right, top and bottom margins respectively, or null if canceled 171 */ 172 @Nullable 173 String[] displayMarginInput( 174 @Nullable String all, 175 @Nullable String left, 176 @Nullable String right, 177 @Nullable String top, 178 @Nullable String bottom); 179 180 /** 181 * Displays an input dialog tailored for inputing the source of an {@code <include>} 182 * layout tag. This is similar to {@link #displayResourceInput} for resource type 183 * "layout", but should also attempt to filter out layout resources that cannot be 184 * included from the current context (because it would result in a cyclic dependency). 185 * 186 * @return the layout resource to include, or null if canceled 187 */ 188 @Nullable 189 String displayIncludeSourceInput(); 190 191 /** 192 * Displays an input dialog tailored for inputing the source of a {@code <fragment>} 193 * layout tag. 194 * 195 * @return the fully qualified class name of the fragment activity, or null if canceled 196 */ 197 @Nullable 198 String displayFragmentSourceInput(); 199 200 /** 201 * Select the given nodes 202 * 203 * @param nodes the nodes to be selected, never null 204 */ 205 void select(@NonNull Collection<INode> nodes); 206 207 /** 208 * Triggers a redraw 209 */ 210 void redraw(); 211 212 /** 213 * Triggers a layout refresh and redraw 214 */ 215 void layout(); 216 217 /** 218 * Converts a pixel to a dp (device independent pixel) for the current screen density 219 * 220 * @param px the pixel dimension 221 * @return the corresponding dp dimension 222 */ 223 public int pxToDp(int px); 224 225 /** 226 * Converts a device independent pixel to a screen pixel for the current screen density 227 * 228 * @param dp the device independent pixel dimension 229 * @return the corresponding pixel dimension 230 */ 231 public int dpToPx(int dp); 232 233 /** 234 * Converts an IDE screen pixel distance to the corresponding layout distance. This 235 * can be used to draw annotations on the graphics object that should be unaffected by 236 * the zoom, or handle mouse events within a certain pixel distance regardless of the 237 * screen zoom. 238 * 239 * @param pixels the size in IDE screen pixels 240 * @return the corresponding pixel distance in the layout coordinate system 241 */ 242 public int screenToLayout(int pixels); 243 244 /** 245 * Measure the preferred or actual ("wrap_content") size of the given nodes. 246 * 247 * @param parent the parent whose children should be measured 248 * @param filter a filter to change attributes in the process of measuring, for 249 * example forcing the layout_width to wrap_content or the layout_weight to 250 * unset 251 * @return the corresponding bounds of the nodes, or null if a rendering error occurs 252 */ 253 @Nullable 254 Map<INode, Rect> measureChildren(@NonNull INode parent, @Nullable AttributeFilter filter); 255 256 /** 257 * The {@link AttributeFilter} allows a client of 258 * {@link IClientRulesEngine#measureChildren} to modify the actual XML values of the 259 * nodes being rendered, for example to force width and height values to wrap_content 260 * when measuring preferred size. 261 */ 262 public interface AttributeFilter { 263 /** 264 * Returns the attribute value for the given node and attribute name. This filter 265 * allows a client to adjust the attribute values that a node presents to the 266 * layout library. 267 * <p> 268 * Returns "" to unset an attribute. Returns null to return the unfiltered value. 269 * 270 * @param node the node for which the attribute value should be returned 271 * @param namespace the attribute namespace 272 * @param localName the attribute local name 273 * @return an override value, or null to return the unfiltered value 274 */ 275 @Nullable 276 String getAttribute( 277 @NonNull INode node, 278 @Nullable String namespace, 279 @NonNull String localName); 280 } 281 282 /** 283 * Given a UI root node and a potential XML node name, returns the first available id 284 * that matches the pattern "prefix%d". 285 * <p/> 286 * TabWidget is a special case and the method will always return "@android:id/tabs". 287 * 288 * @param fqcn The fully qualified class name of the view to generate a unique id for 289 * @return A suitable generated id in the attribute form needed by the XML id tag 290 * (e.g. "@+id/something") 291 */ 292 @NonNull 293 public String getUniqueId(@NonNull String fqcn); 294 295 /** 296 * Returns the namespace URI for attributes declared and used inside the 297 * app. (This is not the Android namespace.) 298 * 299 * @return the namespace URI 300 */ 301 @NonNull 302 public String getAppNameSpace(); 303 } 304 305
