| /* |
| * 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. |
| * <p/> |
| * Rules are implemented by builtin layout helpers, or 3rd party layout rule implementations |
| * provided with or for a given 3rd party widget. |
| * <p/> |
| * 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. |
| * <p/> |
| * 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. |
| * <p/> |
| * <b>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.</b> |
| * </p> |
| */ |
| 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. |
| * <p/> |
| * 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 the <code>fqcn</code> 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. |
| * <p> |
| * The order of the menu items is determined by the sort priority set on |
| * the actions. |
| * <p/> |
| * Most rules should consider calling super.{@link #addContextMenuActions(List, INode)} |
| * as well. |
| * <p/> |
| * 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<RuleAction> actions, @NonNull INode node); |
| |
| /** |
| * Returns the id of the default action to invoke for this view, typically when the |
| * user presses F2. The id should correspond to the {@link RuleAction#getId()} returned |
| * by one of the actions added by {@link #addContextMenuActions(List, INode)}. |
| * |
| * @param node the primary selected node |
| * @return the id of default action, or null if none is default |
| */ |
| @Nullable |
| String getDefaultActionId(@NonNull INode node); |
| |
| /** |
| * Invoked by the Rules Engine to ask the parent layout for the set of layout actions |
| * to display in the layout bar. The layout rule should add these into the provided |
| * list. The order the items are added in does not matter; the |
| * {@link RuleAction#getSortPriority()} values will be used to sort the actions prior |
| * to display, which makes it easier for parent rules and deriving rules to interleave |
| * their respective actions. |
| * |
| * @param actions the list of actions to add newly registered actions into |
| * @param parentNode the parent of the selection, or the selection itself if the root |
| * @param targets the targeted/selected nodes, if any |
| */ |
| void addLayoutActions( |
| @NonNull List<RuleAction> actions, |
| @NonNull INode parentNode, |
| @NonNull List<? extends INode> targets); |
| |
| // ==== Selection ==== |
| |
| /** |
| * Returns a list of strings that will be displayed when a single child is being |
| * selected in a layout corresponding to this rule. This gives the container a chance |
| * to describe the child's layout attributes or other relevant information. |
| * <p/> |
| * Note that this is called only for single selections. |
| * <p/> |
| * |
| * @param parentNode The parent of the node selected. Never null. |
| * @param childNode The child node that was selected. Never null. |
| * @return a list of strings to be displayed, or null or empty to display nothing |
| */ |
| @Nullable |
| List<String> getSelectionHint(@NonNull INode parentNode, @NonNull INode childNode); |
| |
| /** |
| * Paints any layout-specific selection feedback for the given parent layout. |
| * |
| * @param graphics the graphics context to paint into |
| * @param parentNode the parent layout node |
| * @param childNodes the child nodes selected in the parent layout |
| * @param view An instance of the view to be painted (may be null) |
| */ |
| void paintSelectionFeedback( |
| @NonNull IGraphics graphics, |
| @NonNull INode parentNode, |
| @NonNull List<? extends INode> childNodes, |
| @Nullable Object view); |
| |
| // ==== Drag & drop support ==== |
| |
| /** |
| * Called when the d'n'd starts dragging over the target node. If |
| * interested, returns a DropFeedback passed to onDrop/Move/Leave/Paint. If |
| * not interested in drop, return null. Followed by a paint. |
| * |
| * @param targetNode the {@link INode} for the target layout receiving a |
| * drop event |
| * @param targetView the corresponding View object for the target layout, or |
| * null if not known |
| * @param elements an array of {@link IDragElement} element descriptors for |
| * the dragged views. When there are more than one element, the |
| * first element will always be the "primary" element (e.g. the |
| * one that the mouse is actively dragging.) |
| * @return a {@link DropFeedback} object with drop state (which will be |
| * supplied to a follow-up {@link #onDropMove} call), or null if the |
| * drop should be ignored |
| */ |
| @Nullable |
| DropFeedback onDropEnter(@NonNull INode targetNode, @Nullable Object targetView, |
| @Nullable IDragElement[] elements); |
| |
| /** |
| * Called after onDropEnter. Returns a DropFeedback passed to |
| * onDrop/Move/Leave/Paint (typically same as input one). Returning null |
| * will invalidate the drop workflow. |
| * |
| * @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. When there are more than one element, the |
| * first element will always be the "primary" element (e.g. the |
| * one that the mouse is actively dragging.) |
| * @param feedback the {@link DropFeedback} object created by |
| * {@link #onDropEnter(INode, Object, IDragElement[])} |
| * @param where the current mouse drag position |
| * @return a {@link DropFeedback} (which is usually just the same one passed |
| * into this method) |
| */ |
| @Nullable |
| DropFeedback onDropMove( |
| @NonNull INode targetNode, |
| @NonNull IDragElement[] elements, |
| @Nullable DropFeedback feedback, |
| @NonNull Point where); |
| |
| /** |
| * Called when drop leaves the target without actually dropping. |
| * <p/> |
| * When switching between views, onDropLeave is called on the old node *after* onDropEnter |
| * is called after a new node that returned a non-null feedback. The feedback received here |
| * is the one given by the previous onDropEnter on the same target. |
| * <p/> |
| * E.g. call order is: |
| * <pre> |
| * - onDropEnter(node1) => feedback1 |
| * <i>...user moves to new view...</i> |
| * - onDropEnter(node2) => feedback2 |
| * - onDropLeave(node1, feedback1) |
| * <i>...user leaves canvas...</i> |
| * - onDropLeave(node2, feedback2) |
| * </pre> |
| * @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. When there are more than one element, the |
| * first element will always be the "primary" element (e.g. the |
| * one that the mouse is actively dragging.) |
| * @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. |
| * <p> |
| * 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. When there are more than one element, the |
| * first element will always be the "primary" element (e.g. the |
| * one that the mouse is actively dragging.) |
| * @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 <code>DialerFilterRule</code> 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. |
| * <p> |
| * 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.) |
| * <p> |
| * Note that when children are moved (such as when you drag a child within a |
| * LinearLayout to move it from one position among the children to another), |
| * that will also result in a |
| * {@link #onChildInserted(INode, INode, InsertType)} (with the |
| * {@code InsertType} set to {@link InsertType#MOVE_WITHIN}) and a remove |
| * via this {@link #onRemovingChildren(List, INode, boolean)} method. When |
| * the deletion is occurring as part of a local move (insert + delete), the |
| * {@code moved} parameter to this method is set to true. |
| * |
| * @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) |
| * @param moved when true, the nodes are being deleted as part of a local |
| * move (where copies are inserted elsewhere) |
| */ |
| void onRemovingChildren(@NonNull List<INode> deleted, @NonNull INode parent, |
| boolean moved); |
| |
| /** |
| * Called by the IDE on the parent layout when a child widget is being resized. This |
| * is called once at the beginning of the resizing operation. A horizontal edge, |
| * or a vertical edge, or both, can be resized simultaneously. |
| * |
| * @param child the widget being resized |
| * @param parent the layout containing the child |
| * @param horizEdge The horizontal edge being resized, or null |
| * @param verticalEdge the vertical edge being resized, or null |
| * @param childView an instance of the resized node view, or null if not known |
| * @param parentView an instance of the parent layout view object, or null if not known |
| * @return a {@link DropFeedback} object which performs an update painter callback |
| * etc. |
| */ |
| @Nullable |
| DropFeedback onResizeBegin( |
| @NonNull INode child, |
| @NonNull INode parent, |
| @Nullable SegmentType horizEdge, |
| @Nullable SegmentType verticalEdge, |
| @Nullable Object childView, |
| @Nullable Object parentView); |
| |
| /** |
| * Called by the IDE on the parent layout when a child widget is being resized. This |
| * is called repeatedly during the resize as the mouse is dragged to update the drag |
| * bounds, recompute guidelines, etc. The resize has not yet been "committed" so the |
| * XML should not be edited yet. |
| * |
| * @param feedback the {@link DropFeedback} object created in {@link #onResizeBegin} |
| * @param child the widget being resized |
| * @param parent the layout containing the child |
| * @param newBounds the new bounds the user has chosen to resize the widget to, |
| * in absolute coordinates |
| * @param modifierMask The modifier keys currently pressed by the user, as a bitmask |
| * of the constants {@link DropFeedback#MODIFIER1}, {@link DropFeedback#MODIFIER2} |
| * and {@link DropFeedback#MODIFIER3}. |
| */ |
| void onResizeUpdate( |
| @Nullable DropFeedback feedback, |
| @NonNull INode child, |
| @NonNull INode parent, |
| @NonNull Rect newBounds, |
| int modifierMask); |
| |
| /** |
| * Called by the IDE on the parent layout when a child widget is being resized. This |
| * is called once at the end of the resize operation, if it was not canceled. |
| * This method can call {@link INode#editXml} to update the node to reflect the |
| * new bounds. |
| * |
| * @param feedback the {@link DropFeedback} object created in {@link #onResizeBegin} |
| * @param child the widget being resized |
| * @param parent the layout containing the child |
| * @param newBounds the new bounds the user has chosen to resize the widget to, |
| * in absolute coordinates |
| */ |
| void onResizeEnd( |
| @Nullable DropFeedback feedback, |
| @NonNull INode child, |
| @NonNull INode parent, |
| @NonNull Rect newBounds); |
| } |
