/* * Copyright (C) 2010 The Android Open Source Project * * Licensed under the Eclipse Public License, Version 1.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.eclipse.org/org/documents/epl-v10.php * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package com.android.ide.common.api; import com.android.annotations.NonNull; import com.android.annotations.Nullable; import com.google.common.annotations.Beta; import java.util.Collection; import java.util.Map; /** * A Client Rules Engine is a set of methods that {@link IViewRule}s can use to * access the client public API of the Rules Engine. *
* NOTE: This is not a public or final API; if you rely on this be prepared * to adjust your code for the next tools release. *
*/ @Beta public interface IClientRulesEngine { /** * Returns the FQCN for which the rule was loaded. * * @return the fully qualified name of the rule */ @NonNull String getFqcn(); /** * Prints a debug line in the Eclipse console using the ADT formatter. * * @param msg A String format message. * @param params Optional parameters for the message. */ void debugPrintf(@NonNull String msg, Object...params); /** * Loads and returns an {@link IViewRule} for the given FQCN. * * @param fqcn A non-null, non-empty FQCN for the rule to load. * @return The rule that best matches the given FQCN according to the * inheritance chain. Rules are cached and requesting the same FQCN twice * is fast and will return the same rule instance. */ @Nullable IViewRule loadRule(@NonNull String fqcn); /** * Returns the metadata associated with the given fully qualified class name. Note that * this will always return an {@link IViewMetadata} instance, even when the class name * is unknown to the layout editor, such as for custom views. In that case, some * heuristics will be applied to return metadata information such as guesses for * what the most common attribute is, and so on. * * @param fqcn a fully qualified class name for an Android view class * @return the metadata associated with the given fully qualified class name. */ @NonNull IViewMetadata getMetadata(@NonNull String fqcn); /** * Displays the given message string in an alert dialog with an "OK" button. * * @param message the message to be shown */ void displayAlert(@NonNull String message); /** * Displays a simple input alert dialog with an OK and Cancel buttons. * * @param message The message to display in the alert dialog. * @param value The initial value to display in the input field. Can be null. * @param filter An optional filter to validate the input. Specify null (or * a validator which always returns true) if you do not want * input validation. * @return Null if canceled by the user. Otherwise the possibly-empty input string. */ @Nullable String displayInput(@NonNull String message, @Nullable String value, @Nullable IValidator filter); /** * Returns the minimum API level that the current Android project is targeting. * * @return the minimum API level to be supported, or -1 if it cannot be determined */ int getMinApiLevel(); /** * Returns a resource name validator for the current project * * @return an {@link IValidator} for validating new resource name in the current * project */ @NonNull IValidator getResourceValidator(); /** * Displays an input dialog where the user can enter an Android reference value * * @param currentValue the current reference to select * @return the reference selected by the user, or null */ @Nullable String displayReferenceInput(String currentValue); /** * Displays an input dialog where the user can enter an Android resource name of the * given resource type ("id", "string", "drawable", and so on.) * * @param currentValue the current reference to select * @param resourceTypeName resource type, such as "id", "string", and so on (never * null) * @return the margins selected by the user in the same order as the input arguments, * or null */ @Nullable String displayResourceInput(@NonNull String resourceTypeName, @Nullable String currentValue); /** * Displays an input dialog tailored for editing margin properties. * * @param all The current, initial value display for "all" margins (applied to all * sides) * @param left The current, initial value to display for the "left" margin * @param right The current, initial value to display for the "right" margin * @param top The current, initial value to display for the "top" margin * @param bottom The current, initial value to display for the "bottom" margin * @return an array of length 5 containing the user entered values for the all, left, * right, top and bottom margins respectively, or null if canceled */ @Nullable String[] displayMarginInput( @Nullable String all, @Nullable String left, @Nullable String right, @Nullable String top, @Nullable String bottom); /** * Displays an input dialog tailored for inputing the source of an {@code* Returns "" to unset an attribute. Returns null to return the unfiltered value. * * @param node the node for which the attribute value should be returned * @param namespace the attribute namespace * @param localName the attribute local name * @return an override value, or null to return the unfiltered value */ @Nullable String getAttribute( @NonNull INode node, @Nullable String namespace, @NonNull String localName); } /** * Given a UI root node and a potential XML node name, returns the first available id * that matches the pattern "prefix%d". *
* TabWidget is a special case and the method will always return "@android:id/tabs". * * @param fqcn The fully qualified class name of the view to generate a unique id for * @return A suitable generated id in the attribute form needed by the XML id tag * (e.g. "@+id/something") */ @NonNull public String getUniqueId(@NonNull String fqcn); /** * Returns the namespace URI for attributes declared and used inside the * app. (This is not the Android namespace.) * * @return the namespace URI */ @NonNull public String getAppNameSpace(); }