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