eclipse/plugins/com.android.ide.eclipse.adt/src/com/android/ide/eclipse/adt/gscripts/IViewRule.java

   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.gscripts;
  18
  19 import java.util.ArrayList;
  20 import java.util.LinkedHashMap;
  21 import java.util.Map;
  22
  23
  24 /**
  25  * An {@link IViewRule} describes the GLE rules that apply to a given Layout or View object
  26  * in the Graphical Layout Editor (GLE).
  27  * <p/>
  28  * Such a rule is implemented using a Groovy script located in the
  29  * com.android.ide.eclipse.adt.internal.editors.layout.gre package or in a
  30  * projects' /gscript folder for custom views.
  31  * <p/>
  32  * The Groovy script must be named using the fully qualified class name of the View or Layout,
  33  * e.g. "android.widget.LinearLayout.groovy". If the rule engine can't find a groovy script
  34  * for a given element, it will use the closest matching parent (e.g. View instead of ViewGroup).
  35  * <p/>
  36  * Rule instances are stateless. They are created once per View class to handle and are shared
  37  * across platforms or editor instances. As such, rules methods should never cache editor-specific
  38  * arguments that they might receive.
  39  */
  40 public interface IViewRule {
  41
  42     /**
  43      * This method is called by the rule engine when the script is first loaded.
  44      * It gives the rule a chance to initialize itself.
  45      *
  46      * @param fqcn The fully qualified class name of the Layout or View that will be managed by
  47      *   this rule. This can be cached as it will never change for the lifetime of this rule
  48      *   instance. This may or may not match the script's filename as it may be the fqcn of a
  49      *   class derived from the one this rule can handle.
  50      * @return True if this rule can handle the given FQCN. False if the rule can't handle the
  51      *   given FQCN, in which case the rule engine will find another rule matching a parent clas.
  52      */
  53     boolean onInitialize(String fqcn);
  54
  55     /**
  56      * This method is called by the rules engine just before the script is unloaded.
  57      */
  58     void onDispose();
  59
  60     /**
  61      * Returns the class name to display when an element is selected in the GLE.
  62      * <p/>
  63      * If null is returned, the GLE will automatically shorten the class name using its
  64      * own heuristic, which is to keep the first 2 package components and the class name.
  65      * The class name is the <code>fqcn</code> argument that was given
  66      * to {@link #onInitialize(String)}.
  67      *
  68      * @return Null for the default behavior or a shortened string.
  69      */
  70     String getDisplayName();
  71
  72
  73     // ==== XML Creation ====
  74
  75
  76     /**
  77      * Returns the default attributes that a new XML element of this type should have
  78      * when added to an XML layout file. Note that these defaults can be overridden by the
  79      * specific code performing the insertion.
  80      *
  81      * @return A map of attribute:values for a new element of this type. Can be null or empty.
  82      */
  83     Map<?, ?> getDefaultAttributes();
  84
  85
  86
  87     // ==== Drag'n'drop support ====
  88
  89
  90     /**
  91      * Called when a drop operation starts, whilst the d'n'd is dragging the cursor over the
  92      * views. The purpose of the drop operation will be to create a new element.
  93      * <p/>
  94      * Drop targets that can't accept child views should always return null, in which case
  95      * the rule engine will ask the parent view (typically a layout).
  96      * <p/>
  97      * Drop targets that can accept child views must return a non-empty list of drop zones,
  98      * customized to the actual bounds of the target.
  99      * The drop zones will be visually shown to the user. Once the user releases the mouse
 100      * in one of the drop zone, the dropAccept/dropFinish methods will be called.
 101      * <p/>
 102      * Note that at this stage, the drop operation does not offer a way to know what is going
 103      * to be dropped. We just know it's a view descriptor, typically from the layout palette,
 104      * but we don't know which view class yet.
 105      *
 106      * @param targetNode The XML view that is currently the target of the drop.
 107      * @return Null or an empty list if the rule rejects the drop, or a list of usable drop zones.
 108      */
 109     ArrayList<DropZone> dropStart(INodeProxy targetNode);
 110
 111     /**
 112      * Called after the user selects to drop the given source into one of the drop zones.
 113      * <p/>
 114      * This method should use the methods from the {@link INodeProxy} to actually create the
 115      * new XML matching the source descriptor.
 116      *
 117      * @param sourceFqcn The FQCN of the view being dropped.
 118      * @param targetNode The XML view that is currently the target of the drop.
 119      * @param selectedZone One of the drop zones returned by {@link #dropStart(INodeProxy)}.
 120      * @param where The location, in the selected zone, of the drop.
 121      */
 122     void dropFinish(
 123             String sourceFqcn,
 124             INodeProxy targetNode,
 125             DropZone selectedZone,
 126             Point where);
 127
 128     ArrayList<DropZone> moveStart(INodeProxy sourceNode, INodeProxy targetNode, boolean copy);
 129     void moveFinish(INodeProxy sourceNode, INodeProxy targetNode, boolean copy, DropZone selectedZone);
 130 }