Home | History | Annotate | Download | only in gscripts 
      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      */
     51     boolean onInitialize(String fqcn);
     52 
     53     /**
     54      * This method is called by the rules engine just before the script is unloaded.
     55      */
     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      */
     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      */
     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      */
    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      */
    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      */
    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      */
    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      */
    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      */
    170     void onDropped(INode targetNode,
    171             IDragElement[] elements,
    172             DropFeedback feedback,
    173             Point where);
    174 
    175 }
    176