1 /* 2 * Copyright (C) 2009 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 package com.android.ide.eclipse.adt.editors.layout.gscripts; 18 19 import java.util.Map; 20 21 22 /** 23 * An {@link IViewRule} describes the GLE rules that apply to a given Layout or View object 24 * in the Graphical Layout Editor (GLE). 25 * <p/> 26 * Such a rule is implemented using a Groovy script located in the 27 * com.android.ide.eclipse.adt.internal.editors.layout.gre package or in a 28 * projects' /gscript folder for custom views. 29 * <p/> 30 * The Groovy script must be named using the fully qualified class name of the View or Layout, 31 * e.g. "android.widget.LinearLayout.groovy". If the rule engine can't find a groovy script 32 * for a given element, it will use the closest matching parent (e.g. View instead of ViewGroup). 33 * <p/> 34 * Rule instances are stateless. They are created once per View class to handle and are shared 35 * across platforms or editor instances. As such, rules methods should never cache editor-specific 36 * arguments that they might receive. 37 */ 38 public interface IViewRule { 39 40 /** 41 * This method is called by the rule engine when the script is first loaded. 42 * It gives the rule a chance to initialize itself. 43 * 44 * @param fqcn The fully qualified class name of the Layout or View that will be managed by 45 * this rule. This can be cached as it will never change for the lifetime of this rule 46 * instance. This may or may not match the script's filename as it may be the fqcn of a 47 * class derived from the one this rule can handle. 48 * @return True if this rule can handle the given FQCN. False if the rule can't handle the 49 * given FQCN, in which case the rule engine will find another rule matching a parent clas. 50 */ onInitialize(String fqcn)51 boolean onInitialize(String fqcn); 52 53 /** 54 * This method is called by the rules engine just before the script is unloaded. 55 */ onDispose()56 void onDispose(); 57 58 /** 59 * Returns the class name to display when an element is selected in the GLE. 60 * <p/> 61 * If null is returned, the GLE will automatically shorten the class name using its 62 * own heuristic, which is to keep the first 2 package components and the class name. 63 * The class name is the <code>fqcn</code> argument that was given 64 * to {@link #onInitialize(String)}. 65 * 66 * @return Null for the default behavior or a shortened string. 67 */ getDisplayName()68 String getDisplayName(); 69 70 71 // ==== Selection ==== 72 73 /** 74 * Called by the canvas when a view is being selected. 75 * <p/> 76 * Before the method is called, the canvas' Graphic Context is initialized 77 * with a foreground color already set to the desired selection color, fully 78 * opaque and with the default adequate font. 79 * 80 * @param gc An {@link IGraphics} instance, to perform drawing operations. 81 * @param selectedNode The node selected. Never null. 82 * @param displayName The name to display, as returned by {@link #getDisplayName()}. 83 * @param isMultipleSelection A boolean set to true if more than one element is selected. 84 */ onSelected(IGraphics gc, INode selectedNode, String displayName, boolean isMultipleSelection)85 void onSelected(IGraphics gc, 86 INode selectedNode, 87 String displayName, 88 boolean isMultipleSelection); 89 90 /** 91 * Called by the canvas when a single child view is being selected. 92 * <p/> 93 * Note that this is called only for single selections. 94 * <p/> 95 * This allows a parent to draw stuff around its children, for example to display 96 * layout attributes graphically. 97 * 98 * @param gc An {@link IGraphics} instance, to perform drawing operations. 99 * @param parentNode The parent of the node selected. Never null. 100 * @param childNode The child node that was selected. Never null. 101 */ onChildSelected(IGraphics gc, INode parentNode, INode childNode)102 void onChildSelected(IGraphics gc, 103 INode parentNode, 104 INode childNode); 105 106 107 // ==== XML Creation ==== 108 109 /** 110 * Returns the default attributes that a new XML element of this type should have 111 * when added to an XML layout file. Note that these defaults can be overridden by the 112 * specific code performing the insertion. 113 * 114 * TODO: 115 * - added=>created 116 * - list tuple(uri, local name, str: value) 117 * - gen id 118 * 119 * @return A map of attribute:values for a new element of this type. Can be null or empty. 120 */ getDefaultAttributes()121 Map<?, ?> getDefaultAttributes(); 122 123 124 // ==== Drag'n'drop support ==== 125 126 /** 127 * Called when the d'n'd starts dragging over the target node. 128 * If interested, returns a DropFeedback passed to onDrop/Move/Leave/Paint. 129 * If not interested in drop, return null. 130 * Followed by a paint. 131 */ onDropEnter(INode targetNode, IDragElement[] elements)132 DropFeedback onDropEnter(INode targetNode, 133 IDragElement[] elements); 134 135 /** 136 * Called after onDropEnter. 137 * Returns a DropFeedback passed to onDrop/Move/Leave/Paint (typically same 138 * as input one). 139 * Returning null will invalidate the drop workflow. 140 */ onDropMove(INode targetNode, IDragElement[] elements, DropFeedback feedback, Point where)141 DropFeedback onDropMove(INode targetNode, 142 IDragElement[] elements, 143 DropFeedback feedback, 144 Point where); 145 146 /** 147 * Called when drop leaves the target without actually dropping. 148 * <p/> 149 * When switching between views, onDropLeave is called on the old node *after* onDropEnter 150 * is called after a new node that returned a non-null feedback. The feedback received here 151 * is the one given by the previous onDropEnter on the same target. 152 * <p/> 153 * E.g. call order is: 154 * <pre> 155 * - onDropEnter(node1) => feedback1 156 * <i>...user moves to new view...</i> 157 * - onDropEnter(node2) => feedback2 158 * - onDropLeave(node1, feedback1) 159 * <i>...user leaves canvas...</i> 160 * - onDropLeave(node2, feedback2) 161 * </pre> 162 */ onDropLeave(INode targetNode, IDragElement[] elements, DropFeedback feedback)163 void onDropLeave(INode targetNode, 164 IDragElement[] elements, 165 DropFeedback feedback); 166 167 /** 168 * Called when drop is released over the target to perform the actual drop. 169 */ onDropped(INode targetNode, IDragElement[] elements, DropFeedback feedback, Point where)170 void onDropped(INode targetNode, 171 IDragElement[] elements, 172 DropFeedback feedback, 173 Point where); 174 175 } 176