eclipse/plugins/com.android.ide.eclipse.adt/src/com/android/ide/eclipse/adt/editors/layout/gscripts/INodeProxy.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
  18 package com.android.ide.eclipse.adt.editors.layout.gscripts;
  19
  20 import groovy.lang.Closure;
  21
  22
  23
  24 public interface INodeProxy {
  25
  26     /**
  27      * Returns the bounds of this node.
  28      * <p/>
  29      * The bounds are valid when this node maps a view that is already rendered.
  30      * Typically, if the node is the target of a drag'n'drop operation then you can be
  31      * guaranteed that its bounds are known and thus are valid.
  32      * <p/>
  33      * However the bounds are invalid (e.g. not known yet) for new XML elements
  34      * that have just been created by the {@link #createChild(String)} method.
  35      *
  36      * @return A non-null rectangle, in canvas coordinates.
  37      */
  38     Rect getBounds();
  39
  40     // ---- XML Editing ---
  41
  42     /**
  43      * Absolutely <em>all</em> calls that are going to edit the XML must be wrapped
  44      * by an editXml() call. This call creates both an undo context wrapper and an
  45      * edit-XML wrapper.
  46      *
  47      * @param undoName The UI name that will be given to the undo action.
  48      * @param closure The code to execute.
  49      */
  50     void editXml(String undoName, final Closure closure);
  51
  52     // TODO define an exception that methods below will throw if editXml() is not wrapping
  53     // these calls.
  54
  55     /**
  56      * Creates a new XML element as a child of this node's XML element.
  57      * <p/>
  58      * For this to work, the editor must have a descriptor for the given FQCN.
  59      * <p/>
  60      * This call must be done in the context of editXml().
  61      *
  62      * @param viewFqcn The FQCN of the element to create. The actual XML local name will
  63      *  depend on whether this is an Android view or a custom project view.
  64      * @return The node for the newly created element. Can be null if we failed to create it.
  65      */
  66     INodeProxy createChild(String viewFqcn);
  67
  68     /**
  69      * Sets an attribute for the underlying XML element.
  70      * Attributes are not written immediately -- instead the XML editor batches edits and
  71      * then commits them all together at once later.
  72      * <p/>
  73      * The attribute will only be set if the underlying element's descriptor is aware of
  74      * this attribute.
  75      * <p/>
  76      * This call must be done in the context of editXml().
  77      *
  78      * @param attributeName The XML local name of the attribute to set.
  79      * @param value It's value. Cannot be null.
  80      * @return Whether the attribute was actually set or not.
  81      */
  82     boolean setAttribute(String attributeName, String value);
  83
  84
  85
  86     // -----------
  87
  88     /** TODO: this is a hack. Shouldn't be here but instead part of some kind of helper
  89      *  given to IViewRule implementations.
  90      */
  91     void debugPrintf(String msg, Object...params);
  92 }