Scripting API

From Freeplane - free mind mapping and knowledge management software
Revision as of 18:55, 5 October 2010 by Boercher (talk | contribs)

This page describes the current Freeplane's Scripting API. For the newest development version see Scripting API (Pre-Release). The Scripting API is in some sense extended by Freeplane's utility classes and by the Libraries included in Freeplane. There is a special page that lists Changes of the Scripting API.

Entry Points

Each script is given two variables:

<groovy> final Proxy.Node node; final Proxy.Controller c; </groovy>

Interface

<groovy> package org.freeplane.plugin.script.proxy;

import groovy.lang.Closure;

import java.awt.Color; import java.io.File; import java.util.Collection; import java.util.Date; import java.util.List;

import javax.swing.Icon;

import org.freeplane.core.filter.condition.ICondition; import org.freeplane.features.common.edge.EdgeStyle; import org.freeplane.features.common.link.ArrowType;

public interface Proxy {

   /** Attributes are name - value pairs assigned to a node. A node may have multiple attributes
    * with the same name. */
   interface Attributes {
       /** returns the first value of an attribute with the given name or null otherwise.
        * @deprecated use {@link #get(int)} or {@link #getAll(String)} instead. */
       @Deprecated
       String get(final String name);
       /** returns all values for the attribute name. */
       List<String> getAll(final String name);
       /** returns all attribute names in the proper sequence.

*

         *   // rename attribute
         *   int i = 0;
         *   for (String name : attributes.getAttributeNames()) {
         *       if (name.equals("xy"))
         *           attributes.set(i, "xyz", attributes.get(i));
         *       ++i;
         *   }
         * 

*/

       public List<String> getAttributeNames();
       /** returns the attribute value at the given index.
        * @throws IndexOutOfBoundsException if index is out of range (index
        *         < 0 || index >= size()).*/
       String get(final int index);
       /** sets the value of the attribute at an index. This method will not create new attributes.
        * @throws IndexOutOfBoundsException if index is out of range (index
        *         < 0 || index >= size()). */
       void set(final int index, final String value);
       /** sets name and value of the attribute at the given index. This method will not create new attributes.
        * @throws IndexOutOfBoundsException if index is out of range (index
        *         < 0 || index >= size()). */
       void set(final int index, final String name, final String value);
       /** returns the index of the first attribute with the given name if one exists or -1 otherwise.
                * For searches for all attributes with a given name getAttributeNames()
                * must be used. */
       public int findAttribute(final String name);
       /** removes the first attribute with this name.
        * @returns true on removal of an existing attribute and false otherwise.
        * @deprecated use {@link #remove(int)} or {@link #removeAll(String)} instead. */
       @Deprecated
       boolean remove(final String name);
       /** removes all attributes with this name.
        * @returns true on removal of an existing attribute and false otherwise. */
       boolean removeAll(final String name);
       /** removes the attribute at the given index.
        * @throws IndexOutOfBoundsException if index is out of range (index
        *         < 0 || index >= size()). */
       void remove(final int index);
       /** adds an attribute if there is no attribute with the given name or changes
        * the value of the first attribute with the given name. */
       void set(final String name, final String value);
       /** adds an attribute no matter if an attribute with the given name already exists. */
       void add(final String name, final String value);
       /** the number of attributes. It is size() == getAttributeNames().size(). */
       int size();
   }
   interface Connector {
       Color getColor();
       ArrowType getEndArrow();
       String getMiddleLabel();
       Node getSource();
       String getSourceLabel();
       ArrowType getStartArrow();
       Node getTarget();
       String getTargetLabel();
       void setColor(Color color);
       void setEndArrow(ArrowType arrowType);
       void setMiddleLabel(String label);
       void setSimulatesEdge(boolean simulatesEdge);
       void setSourceLabel(String label);
       void setStartArrow(ArrowType arrowType);
       void setTargetLabel(String label);
       boolean simulatesEdge();
   }
   interface Controller {
       void centerOnNode(Node center);
       /** if multiple nodes are selected returns one (arbitrarily chosen)
        * selected node or the selected node for a single node selection. */
       Node getSelected();
       List<Node> getSelecteds();
       /** returns List<Node> of Node objects sorted on Y
        *
        * @param differentSubtrees if true
        *   children/grandchildren/grandgrandchildren/... nodes of selected
        *   parent nodes are excluded from the result. */
       List<Node> getSortedSelection(boolean differentSubtrees);
       void select(Node toSelect);
       /** selects branchRoot and all children */
       void selectBranch(Node branchRoot);
       /** toSelect is a List<Node> of Node objects */
       void selectMultipleNodes(List<Node> toSelect);
       /** reset undo / redo lists and deactivate Undo for current script */
       void deactivateUndo();
       /** The main info for the status line, null to remove*/
       public void setStatusInfo(String info);
       /** Info for status line, null to remove*/
       public void setStatusInfo(String key, String info);
       /** Info for status line, null to remove*/
       public void setStatusInfo(String key, Icon icon);
       /** Starting from the root node, recursively searches for nodes for which
        * condition.checkNode(node) returns true.
        * @see Node.find(ICondition) for searches on subtrees */
       public List<Node> find(ICondition condition);
       /**
        * Starting from the root node, recursively searches for nodes for which closure.call(node)
        * returns true.

*

* A find method that uses a Groovy closure ("block") for simple custom searches. As this closure * will be called with a node as an argument (to be referenced by it) the search can * evaluate every node property, like attributes, icons, node text or notes. *

* Examples: *

         *    def nodesWithNotes = c.find{ it.noteText != null }
         *    
         *    def matchingNodes = c.find{ it.text.matches(".*\\d.*") }
         *    def texts = matchingNodes.collect{ it.text }
         *    print "node texts containing numbers:\n " + texts.join("\n ")
         * 
        * @param closure a Groovy closure that returns a boolean value. The closure will receive
        *        a NodeModel as an argument which can be tested for a match.
        * @return all nodes for which closure.call(NodeModel) returns true.
        * @see Node.find(Closure) for searches on subtrees
        */
       public List<Node> find(Closure closure);
   }
   interface Edge {
       Color getColor();
       EdgeStyle getType();
       int getWidth();
       void setColor(Color color);
       void setType(EdgeStyle type);
       /** can be -1 for default, 0 for thin, >0 */
       void setWidth(int width);
   }
   interface ExternalObject {
       /** empty string means that there's no external object */
       String getURI();
       float getZoom();
       /** setting empty String uri means remove external object (as for Links); */
       void setURI(String uri);
       void setZoom(float zoom);
   }
   interface Font {
       String getName();
       int getSize();
       boolean isBold();
       boolean isBoldSet();
       boolean isItalic();
       boolean isItalicSet();
       boolean isNameSet();
       boolean isSizeSet();
       void resetBold();
       void resetItalic();
       void resetName();
       void resetSize();
       void setBold(boolean bold);
       void setItalic(boolean italic);
       void setName(String name);
       void setSize(int size);
   }
   interface Icons {
       void addIcon(String name);
       /** returns List<Node> of Strings (corresponding to iconID above);
        * iconID is one of "Idea","Question","Important", etc. */
       List<String> getIcons();
       /** deletes first occurence of icon with name iconID, returns true if
        * success (icon existed); */
       boolean removeIcon(String iconID);
   }
   interface Link {
       String get();
       /** target is a URI.
        * An empty String will remove the link.
        * To get a local link (i.e. to another node) target should be: "#" + nodeID */
       boolean set(String target);
   }
   interface Map {
       Node getRootNode();
       /** returns the node if the map contains it or null otherwise. */
       Node node(String id);
       /** returns the physical location of the map if available or null otherwise. */
       File getFile();
   }
   interface Node {
       Connector addConnectorTo(Node target);
       /** adds a new Connector object to List<Node> connectors and returns
        * reference for optional further editing (style); also enlists the
        * Connector on the target Node object. */
       Connector addConnectorTo(String targetNodeID);
       /** inserts *new* node as child, takes care of all construction work and
        * internal stuff inserts as last child. */
       Node createChild();
       /** inserts *new* node as child, takes care of all construction work and
        * internal stuff */
       Node createChild(int position);
       void delete();
       Attributes getAttributes();
       /** returns the index (0..) of this node in the (by Y coordinate sorted)
        * list of this node's children. Returns -1 if childNode is not a child
        * of this node. */
       int getChildPosition(Node childNode);
       /** returns the children of this node ordered by Y coordinate. */
       List<Node> getChildren();
       Collection<Connector> getConnectorsIn();
       Collection<Connector> getConnectorsOut();
       ExternalObject getExternalObject();
       Icons getIcons();
       Link getLink();
       /** the map this node belongs to. */
       Map getMap();
       String getNodeID();
       /** if countHidden is false then only nodes that are matched by the
        * current filter are counted. */
       int getNodeLevel(boolean countHidden);
       String getNoteText();
       Node getParentNode();
       /** use this method to remove all tags from an HTML node. */
       String getPlainTextContent();
       NodeStyle getStyle();
       String getText();
       boolean isDescendantOf(Node p);
       boolean isFolded();
       boolean isLeaf();
       boolean isLeft();
       boolean isRoot();
       boolean isVisible();
       /** removes connector from List<Node> connectors; does the corresponding
        * on the target Node object referenced by connectorToBeRemoved */
       void moveTo(Node parentNode);
       void moveTo(Node parentNode, int position);
       /** as above, using String nodeID instead of Node object to establish the connector*/
       void removeConnector(Connector connectorToBeRemoved);
       void setFolded(boolean folded);
       void setNoteText(String text);
       void setText(String text);
       /** Starting from this node, recursively searches for nodes for which
        * condition.checkNode(node) returns true. */
       List<Node> find(ICondition condition);
       /** Starting from this node, recursively searches for nodes for which closure.call(node)
        * returns true. See {@link Controller#find(Closure)} for details. */
       List<Node> find(Closure closure);
       Date getLastModifiedAt();
       void setLastModifiedAt(Date date);
       Date getCreatedAt();
       void setCreatedAt(Date date);
   }
   interface NodeStyle {
       void applyPattern(String patternName);
       Color getBackgroundColor();
       Edge getEdge();
       Font getFont();
       Color getNodeTextColor();
       void setBackgroundColor(Color color);
       void setNodeTextColor(Color color);
   }

} </groovy>