/* * Copyright (C) 2009 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 java.util.List; /** * An {@link IViewRule} describes the rules that apply to a given Layout or View object * in the Graphical Layout Editor. *
* Rules are implemented by builtin layout helpers, or 3rd party layout rule implementations * provided with or for a given 3rd party widget. * * A 3rd party layout rule should use the same fully qualified class name as the layout it * represents, plus "Rule" as a suffix. For example, the layout rule for the * LinearLayout class is LinearLayoutRule, in the same package. * * Rule instances are stateless. They are created once per View class to handle and are shared * across platforms or editor instances. As such, rules methods should never cache editor-specific * arguments that they might receive. * * 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. * */ public interface IViewRule { /** * This method is called by the rule engine when the script is first loaded. * It gives the rule a chance to initialize itself. * * @param fqcn The fully qualified class name of the Layout or View that will be managed by * this rule. This can be cached as it will never change for the lifetime of this rule * instance. This may or may not match the script's filename as it may be the fqcn of a * class derived from the one this rule can handle. * @param engine The engine that is managing the rules. A rule can store a reference to * the engine during initialization and then use it later to invoke some of the * {@link IClientRulesEngine} methods for example to request user input. * @return True if this rule can handle the given FQCN. False if the rule can't handle the * given FQCN, in which case the rule engine will find another rule matching a parent class. */ boolean onInitialize(@NonNull String fqcn, @NonNull IClientRulesEngine engine); /** * This method is called by the rules engine just before the script is unloaded. */ void onDispose(); /** * Returns the class name to display when an element is selected in the layout editor. * * If null is returned, the layout editor will automatically shorten the class name using its * own heuristic, which is to keep the first 2 package components and the class name. * The class name is thefqcn
argument that was given
* to {@link #onInitialize(String,IClientRulesEngine)}.
*
* @return Null for the default behavior or a shortened string.
*/
@Nullable
String getDisplayName();
/**
* Invoked by the Rules Engine to produce a set of actions to customize
* the context menu displayed for this view. The result is not cached and the
* method is invoked every time the context menu is about to be shown.
* * The order of the menu items is determined by the sort priority set on * the actions. *
* Most rules should consider calling super.{@link #addContextMenuActions(List, INode)} * as well. * * Menu actions are either toggles or fixed lists with one currently-selected * item. It is expected that the rule will need to recreate the actions with * different selections when a menu is going to shown, which is why the result * is not cached. However rules are encouraged to cache some or all of the result * to speed up following calls if it makes sense. * * @param actions a list of actions to add new context menu actions into. The order * of the actions in this list is not important; it will be sorted by * {@link RuleAction#getSortPriority()} later. * @param node the node to add actions for. */ void addContextMenuActions(@NonNull List* - onDropEnter(node1) => feedback1 * ...user moves to new view... * - onDropEnter(node2) => feedback2 * - onDropLeave(node1, feedback1) * ...user leaves canvas... * - onDropLeave(node2, feedback2) ** @param targetNode the {@link INode} for the target layout receiving a * drop event * @param elements an array of {@link IDragElement} element descriptors for * the dragged views * @param feedback the {@link DropFeedback} object created by * {@link #onDropEnter(INode, Object, IDragElement[])} */ void onDropLeave( @NonNull INode targetNode, @NonNull IDragElement[] elements, @Nullable DropFeedback feedback); /** * Called when drop is released over the target to perform the actual drop. *
* TODO: Document that this method will be called under an edit lock so you can
* directly manipulate the nodes without wrapping it in an
* {@link INode#editXml(String, INodeHandler)} call.
*
* @param targetNode the {@link INode} for the target layout receiving a
* drop event
* @param elements an array of {@link IDragElement} element descriptors for
* the dragged views
* @param feedback the {@link DropFeedback} object created by
* {@link #onDropEnter(INode, Object, IDragElement[])}
* @param where the mouse drop position
*/
void onDropped(
@NonNull INode targetNode,
@NonNull IDragElement[] elements,
@Nullable DropFeedback feedback,
@NonNull Point where);
/**
* Called when pasting elements in an existing document on the selected target.
*
* @param targetNode The first node selected.
* @param targetView the corresponding View object for the target layout, or
* null if not known
* @param pastedElements The elements being pasted.
*/
void onPaste(@NonNull INode targetNode, @Nullable Object targetView,
@NonNull IDragElement[] pastedElements);
// ==== XML Creation ====
/**
* Called when a view for this rule is being created. This allows for the rule to
* customize the newly created object. Note that this method is called not just when a
* view is created from a palette drag, but when views are constructed via a drag-move
* (where views are created in the destination and then deleted from the source), and
* even when views are constructed programmatically from other view rules. The
* {@link InsertType} parameter can be used to distinguish the context for the
* insertion. For example, the DialerFilterRule
will insert EditText children
* when a DialerFilter is first created, but not during a copy/paste or a move.
*
* @param node the newly created node (which will always be a View that applies to
* this {@link IViewRule})
* @param parent the parent of the node (which may not yet contain the newly created
* node in its child list)
* @param insertType whether this node was created as part of a newly created view, or
* as a copy, or as a move, etc.
*/
void onCreate(@NonNull INode node, @NonNull INode parent, @NonNull InsertType insertType);
/**
* Called when a child for this view has been created and is being inserted into the
* view parent for which this {@link IViewRule} applies. Allows the parent to perform
* customizations of the object. As with {@link #onCreate}, the {@link InsertType}
* parameter can be used to handle new creation versus moves versus copy/paste
* operations differently.
*
* @param child the newly created node
* @param parent the parent of the newly created node (which may not yet contain the
* newly created node in its child list)
* @param insertType whether this node was created as part of a newly created view, or
* as a copy, or as a move, etc.
*/
void onChildInserted(@NonNull INode child, @NonNull INode parent,
@NonNull InsertType insertType);
/**
* Called when one or more children are about to be deleted by the user. Note that
* children deleted programmatically from view rules (via
* {@link INode#removeChild(INode)}) will not notify about deletion.
*
* Note that this method will be called under an edit lock, so rules can directly
* add/remove nodes and attributes as part of the deletion handling (and their
* actions will be part of the same undo-unit.)
*
* @param deleted a nonempty list of children about to be deleted
* @param parent the parent of the deleted children (which still contains the children
* since this method is called before the deletion is performed)
*/
void onRemovingChildren(@NonNull List