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