* 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. *
*/ @Beta public interface INode { /** * Returns the FQCN of the view class represented by this node. */ @NonNull String getFqcn(); /** * Returns the bounds of this node. * * The bounds are valid when this node maps a view that is already rendered. * Typically, if the node is the target of a drag'n'drop operation then you can be * guaranteed that its bounds are known and thus are valid. * * However the bounds are invalid (e.g. not known yet) for new XML elements * that have just been created, e.g. by the {@link #appendChild(String)} method. * * @return A non-null rectangle, in canvas coordinates. */ @NonNull Rect getBounds(); /** * Returns the margins for this node. * * @return the margins for this node, never null */ @NonNull Margins getMargins(); /** * Returns the baseline of this node, or -1 if it has no baseline. * The baseline is the distance from the top down to the baseline. * * @return the baseline, or -1 if not applicable */ int getBaseline(); // ---- Hierarchy handling ---- /** * Returns the root element of the view hierarchy. * * When a node is not attached to a hierarchy, it is its own root node. * This may return null if the {@link INode} was not created using a correct UiNode, * which is unlikely. */ @Nullable INode getRoot(); /** * Returns the parent node of this node, corresponding to the parent view in the layout. * The returned parent can be null when the node is the root element, or when the node is * not yet or no longer attached to the hierarchy. */ @Nullable INode getParent(); /** * Returns the list of valid children nodes. The list can be empty but not null. */ @NonNull INode[] getChildren(); // ---- XML Editing --- /** * Absolutely all calls that are going to edit the XML must be wrapped * by an editXml() call. This call creates both an undo context wrapper and an * edit-XML wrapper. * * @param undoName The UI name that will be given to the undo action. * @param callback The code to execute. */ void editXml(@NonNull String undoName, @NonNull INodeHandler callback); // TODO define an exception that methods below will throw if editXml() is not wrapping // these calls. /** * Creates a new XML element as a child of this node's XML element. * * For this to work, the editor must have a descriptor for the given FQCN. * * This call must be done in the context of editXml(). * * @param viewFqcn The FQCN of the element to create. The actual XML local name will * depend on whether this is an Android view or a custom project view. * @return The node for the newly created element. Can be null if we failed to create it. */ @NonNull INode appendChild(@NonNull String viewFqcn); /** * Creates a new XML element as a child of this node's XML element and inserts * it at the specified position in the children list. * * For this to work, the editor must have a descriptor for the given FQCN. * * This call must be done in the context of editXml(). * * @param viewFqcn The FQCN of the element to create. The actual XML local name will * depend on whether this is an Android view or a custom project view. * @param index Index of the child to insert before. If the index is out of bounds * (less than zero or larger that current last child), appends at the end. * @return The node for the newly created element. Can be null if we failed to create it. */ @NonNull INode insertChildAt(@NonNull String viewFqcn, int index); /** * Removes the given XML element child from this node's list of children. * * This call must be done in the context of editXml(). * * @param node The child to be deleted. */ void removeChild(@NonNull INode node); /** * Sets an attribute for the underlying XML element. * Attributes are not written immediately -- instead the XML editor batches edits and * then commits them all together at once later. * * Custom attributes will be created on the fly. * * Passing an empty value actually removes an attribute from the XML. * * This call must be done in the context of editXml(). * * @param uri The XML namespace URI of the attribute. * @param localName The XML local name of the attribute to set. * @param value It's value. Cannot be null. An empty value removes the attribute. * @return Whether the attribute was actually set or not. */ boolean setAttribute(@Nullable String uri, @NonNull String localName, @Nullable String value); /** * Returns a given XML attribute. * * This looks up an attribute in the current XML source, not the in-memory model. * That means that if called in the context of {@link #editXml(String, INodeHandler)}, the value * returned here is not affected by {@link #setAttribute(String, String, String)} until * the editXml closure is completed and the actual XML is updated. * * @param uri The XML name-space URI of the attribute. * @param attrName The local name of the attribute. * @return the attribute as a {@link String}, if it exists, ornull.
*/
@Nullable
String getStringAttr(@Nullable String uri, @NonNull String attrName);
/**
* Returns the {@link IAttributeInfo} for a given attribute.
*
* The information is useful to determine the format of an attribute (e.g. reference, string,
* float, enum, flag, etc.) and in the case of enums and flags also gives the possible values.
*
* Note: in Android resources, an enum can only take one of the possible values (e.g.
* "visibility" can be either "visible" or "none"), whereas a flag can accept one or more
* value (e.g. "align" can be "center_vertical|center_horizontal".)
*
* Note that this method does not handle custom non-android attributes. It may either
* return null for these or it may return a synthetic "string" format attribute depending
* on how the attribute was loaded.
*
* @param uri The XML name-space URI of the attribute.
* @param attrName The local name of the attribute.
* @return the {@link IAttributeInfo} if the attribute is known, or null.
*/
@Nullable
public IAttributeInfo getAttributeInfo(@Nullable String uri, @NonNull String attrName);
/**
* Returns the list of all attributes declared by this node's descriptor.
*
* This returns a fixed list of all attributes known to the view or layout descriptor.
* This list does not depend on whether the attributes are actually used in the
* XML for this node.
*
* Note that for views, the list of attributes also includes the layout attributes
* inherited from the parent view. This means callers must not cache this list based
* solely on the type of the node, as its attribute list changes depending on the place
* of the view in the view hierarchy.
*
* If you want attributes actually written in the XML and their values, please use
* {@link #getStringAttr(String, String)} or {@link #getLiveAttributes()} instead.
*
* @return A non-null possibly-empty list of {@link IAttributeInfo}.
*/
@NonNull
public IAttributeInfo[] getDeclaredAttributes();
/**
* Returns the list of classes (fully qualified class names) that are
* contributing properties to the {@link #getDeclaredAttributes()} attribute
* list, in order from most specific to least specific (in other words,
* android.view.View will be last in the list.) This is usually the same as
* the super class chain of a view, but it skips any views that do not
* contribute attributes.
*
* @return a list of views classes that contribute attributes to this node,
* which is never null because at least android.view.View will
* contribute attributes.
*/
@NonNull
public List