Package org.freeplane.api

# Interface Node

All Superinterfaces:
  `NodeRO`

All Known Subinterfaces:
  `Proxy.Node`

public interface Node extends NodeRO
The currently selected node: `node` - read-write.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Connector`
  `addConnectorTo(String targetNodeId)`
  as above, using String targetNodeId instead of Node object to establish the connector.
  `Connector`
  `addConnectorTo(Node target)`
  adds a new Connector to the given target node and returns the new connector for optional further editing (style); also enlists the Connector on the target Node object.
  `Node`
  `appendAsCloneWithoutSubtree(NodeRO toBeCloned)`
  inserts the node as a clone of toBeCloned without its current and/or future subtree.
  `Node`
  `appendAsCloneWithSubtree(NodeRO toBeCloned)`
  inserts the node as a clone of toBeCloned including its current and/or future subtree.
  `Node`
  `appendBranch(NodeRO node)`
  inserts a copy of the branch starting with node as a new child branch.
  `Node`
  `appendChild(NodeRO node)`
  inserts a copy of node as a new child.
  `void`
  `appendTextOutlineAsBranch(String outline)`
  `Node`
  `createChild()`
  inserts *new* node as child, takes care of all construction work and internal stuff inserts as last child.
  `Node`
  `createChild(int position)`
  inserts *new* node as child, takes care of all construction work and internal stuff
  `Node`
  `createChild(Object value)`
  like `createChild()` but sets the node text to the given text.
  `void`
  `decrypt(String password)`
  decrypts a node without removing the encryption.
  `void`
  `delete()`
  `void`
  `encrypt(String password)`
  encrypts a node.
  `NodeGeometry`
  `getGeometry()`
  `Tags`
  `getTags()`
  `boolean`
  `hasEncryption()`
  Returns true if the node is password protected, no matter if currently accessible (password entered) or not.
  `boolean`
  `isEncrypted()`
  Returns true if the node has password protection and is currently unaccessible (password has to be entered).
  `void`
  `moveTo(Node parentNode)`
  `void`
  `moveTo(Node parentNode, int position)`
  `void`
  `pasteAsClone()`
  inserts the node(s) copied from clipboard as clone(s).
  `Object`
  `putAt(String attributeName, Object value)`
  Allows to set and to change attribute like array (or map) elements.
  `void`
  `removeBookmark()`
  Removes the bookmark for this node if one exists.
  `void`
  `removeConnector(Connector connectorToBeRemoved)`
  removes the given connector on both sides.
  `void`
  `removeEncryption(String password)`
  decrypts a node and remove the password protection.
  `void`
  `setAlias(String alias)`
  Sets alias of the node
  `void`
  `setAttributes(Map<String,Object> attributes)`
  allows to set all attributes at once:
  `void`
  `setBaseDistanceToChildren(int baseDistance)`
  `void`
  `setBaseDistanceToChildren(String baseDistance)`
  `void`
  `setBaseDistanceToChildren(Quantity<LengthUnit> baseDistance)`
  `void`
  `setBinary(byte[] data)`
  Converts data to a BASE64 encoded string and sets it as this node's text.
  `void`
  `setBookmark(String name, String bookmarkType)`
  Sets a bookmark for this node with the given name and type.
  `void`
  `setBookmark(String name, BookmarkType bookmarkType)`
  Sets a bookmark for this node with the given name and type.
  `void`
  `setChildNodesLayout(ChildNodesLayout layout)`
  `void`
  `setCreatedAt(Date date)`
  `void`
  `setDateTime(Date date)`
  sets the node text to a default formatted datetime object.
  `void`
  `setDetails(Object details)`
  A node's text is String valued.
  `void`
  `setDetailsContentType(String contentType)`
  Sets details content type.
  `void`
  `setDetailsText(String html)`
  Sets the raw (HTML) note text.
  `void`
  `setFolded(boolean folded)`
  `void`
  `setFormat(String format)`
  sets the format string of the formatter.
  `void`
  `setFree(boolean free)`
  set to true if this node should be freely positionable:
  `void`
  `setHideDetails(boolean hide)`
  use node.hideDetails = true/false to control visibility of details.
  `void`
  `setHorizontalShift(int horizontalShift)`
  `void`
  `setHorizontalShift(String verticalShift)`
  use length units like "1 cm" or "6 pt"
  `void`
  `setHorizontalShift(Quantity<LengthUnit> verticalShift)`
  `void`
  `setIsGlobal(boolean value)`
  Sets if the node can be accessed using global accessor, see `NodeRO.at(String)`
  `void`
  `setLastModifiedAt(Date date)`
  `void`
  `setLeft(boolean isTopOrLeft)`
  Deprecated.
  since 1.10.4 - use `setSideAtRoot(Side)` instead.
  `void`
  `setMinimalDistanceBetweenChildren(int minimalDistance)`
  `void`
  `setMinimalDistanceBetweenChildren(String minimalDistance)`
  use length units like "1 cm" or "6 pt"
  `void`
  `setMinimalDistanceBetweenChildren(Quantity<LengthUnit> minimalDistance)`
  `void`
  `setMinimized(boolean shortened)`
  `void`
  `setNote(Object value)`
  Set the note text: This methods provides automatic conversion to String in a way that node.getNote().getXyz() methods will be able to convert the string properly to the wanted type.
  `void`
  `setNoteContentType(String contentType)`
  Sets note content type.
  `void`
  `setNoteText(String html)`
  Sets the raw (HTML) note text.
  `void`
  `setObject(Object value)`
  A node's text object is normally String valued but it can be of any type since every Object can be converted to String for display.
  `void`
  `setSideAtRoot(Side side)`
  `void`
  `setText(Object value)`
  If `value` is a String the node object is set to it verbatim.
  `void`
  `setVerticalShift(int verticalShift)`
  `void`
  `setVerticalShift(String verticalShift)`
  use length units like "1 cm" or "6 pt"
  `void`
  `setVerticalShift(Quantity<LengthUnit> verticalShift)`
  `void`
  `sortChildrenBy(NodeToComparableMapper comparable)`
  A sort method that uses the result of the lambda ("block") for comparison.

  ### Methods inherited from interface org.freeplane.api.NodeRO

  `allAt, at, find, find, findAll, findAllDepthFirst, getAlias, getAt, getAttributes, getBaseDistanceToChildrenAsLength, getBinary, getBookmark, getBranchAsTextOutline, getChildNodesLayout, getChildPosition, getChildren, getCloud, getConditionalStyles, getConnectorsIn, getConnectorsOut, getCountNodesSharingContent, getCountNodesSharingContentAndSubtree, getCreatedAt, getDependents, getDetails, getDetailsContentType, getDetailsText, getDisplayedText, getExternalObject, getFormat, getHideDetails, getHorizontalShift, getHorizontalShiftAsLength, getHorizontalShiftInScreenPixels, getHtmlText, getIcons, getId, getIsGlobal, getLastModifiedAt, getLayoutOrientation, getLink, getMap, getMindMap, getMinimalDistanceBetweenChildren, getMinimalDistanceBetweenChildrenAsLength, getMinimalDistanceBetweenChildrenInScreenPixels, getNext, getNodeID, getNodeLevel, getNodesSharingContent, getNodesSharingContentAndSubtree, getNote, getNoteContentType, getNoteText, getObject, getParent, getParentNode, getPathToRoot, getPlainText, getPlainTextContent, getPrecedents, getPrevious, getReminder, getShortText, getSideAtRoot, getStyle, getText, getTo, getTransformedText, getValue, getVerticalShift, getVerticalShiftAsLength, getVerticalShiftInScreenPixels, hasStyle, isDescendantOf, isFolded, isFree, isLeaf, isLeft, isLeftOnViewsWithRoot, isMinimized, isRoot, isTopOrLeft, isTopOrLeftOnViewsWithRoot, isVisible, isVisibleOnViewsWithRoot`

- ## Method Details

  - ### addConnectorTo

    Connector addConnectorTo(Node target)
    adds a new Connector to the given target node and returns the new connector for optional further editing (style); also enlists the Connector on the target Node object.

  - ### addConnectorTo

    Connector addConnectorTo(String targetNodeId)
    as above, using String targetNodeId instead of Node object to establish the connector.

  - ### createChild

    Node createChild()
    inserts *new* node as child, takes care of all construction work and internal stuff inserts as last child.

  - ### createChild

    Node createChild(Object value)
    like `createChild()` but sets the node text to the given text.

         // instead of
         def child = node.createChild(); child.setObject(value);
         // use
         def child = node.createChild(value);

    Since:
      1.2

  - ### createChild

    Node createChild(int position)
    inserts *new* node as child, takes care of all construction work and internal stuff

  - ### appendChild

    Node appendChild(NodeRO node)
    inserts a copy of node as a new child.
    Since:
      1.2

  - ### appendBranch

    Node appendBranch(NodeRO node)
    inserts a copy of the branch starting with node as a new child branch.
    Since:
      1.2

  - ### appendAsCloneWithSubtree

    Node appendAsCloneWithSubtree(NodeRO toBeCloned)
    inserts the node as a clone of toBeCloned including its current and/or future subtree. That is all changes of descendent nodes of toBeCloned are reflected in the subtree of the new node and vice versa.
    Note: Cloning works symmetrically so we could better speak of two shared nodes instead of clone and cloned since none of both is privileged.
    Returns:
      the new child node
    Throws:
      `IllegalArgumentException` - if a) this node (the to-be-parent) is contained in the subtree of toBeCloned, b) toBeCloned is the root node, c) toBeCloned comes from a different map.
    Since:
      1.5

  - ### appendAsCloneWithoutSubtree

    Node appendAsCloneWithoutSubtree(NodeRO toBeCloned)
    inserts the node as a clone of toBeCloned without its current and/or future subtree. That is toBeCloned and the new node have children of their own.
    Note: Cloning works symmetrically so we could better speak of two shared nodes instead of clone and cloned since none of both is privileged.
    Returns:
      the new child node
    Throws:
      `IllegalArgumentException` - if a) this node (the to-be-parent) is contained in the subtree of toBeCloned, b) toBeCloned is the root node, c) toBeCloned comes from a different map.
    Since:
      1.5

  - ### appendTextOutlineAsBranch

    void appendTextOutlineAsBranch(String outline)
    Since:
      1.11.3

  - ### pasteAsClone

    void pasteAsClone()
    inserts the node(s) copied from clipboard as clone(s). Errors like if the clipboard doesn't contain proper content will only be reported to the log. You should prefer `appendAsCloneWithSubtree(Proxy.NodeRO)` or `appendAsCloneWithoutSubtree(Proxy.NodeRO)` instead if possible - they give you more control.
    Since:
      1.5

  - ### delete

    void delete()

  - ### moveTo

    void moveTo(Node parentNode)

  - ### moveTo

    void moveTo(Node parentNode, int position)

  - ### removeConnector

    void removeConnector(Connector connectorToBeRemoved)
    removes the given connector on both sides.

  - ### setDetails

    void setDetails(Object details)
    A node's text is String valued. This methods provides automatic conversion to String in the same way as for `setText(Object)`, that is special conversion is provided for dates and calendars, other types are converted via value.toString(). If the conversion result is not valid HTML it will be automatically converted to HTML.
    Parameters:
      `details` - An object for conversion to String. Use null to unset the details. Works well for all types that `Convertible` handles, particularly `Convertible`s itself.
    Since:
      1.2

  - ### setDetailsText

    void setDetailsText(String html)
    Sets the raw (HTML) note text.

  - ### setDetailsContentType

    void setDetailsContentType(String contentType)
    Sets details content type. Use null to remove.
    Since:
      1.9.0

  - ### setHideDetails

    void setHideDetails(boolean hide)
    use node.hideDetails = true/false to control visibility of details.
    Since:
      1.2

  - ### setFolded

    void setFolded(boolean folded)

  - ### setFree

    void setFree(boolean free)
    set to true if this node should be freely positionable:

           node.free = true
           node.style.floating = true

    Since:
      1.2

  - ### setMinimized

    void setMinimized(boolean shortened)

  - ### setNote

    void setNote(Object value)
    Set the note text:
    - This methods provides automatic conversion to String in a way that node.getNote().getXyz() methods will be able to convert the string properly to the wanted type.
    - Special conversion is provided for dates and calendars: They will be converted in a way that node.note.date and node.note.calendar will work. All other types are converted via value.toString().
    - If the conversion result is not valid HTML it will be automatically converted to HTML.

           // converts numbers and other stuff with toString()
           node.note = 1.2
           assert node.note.text == "<html><body><p>1.2"
           assert node.note.plain == "1.2"
           assert node.note.num == 1.2d
           // == dates
           // a date in some non-UTC time zone
           def date = new java.text.SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSSZ").
               parse("1970-01-01 00:00:00.000-0200")
           // converts to "1970-01-01T02:00:00.000+0000" (GMT)
           // - note the shift due to the different time zone
           // - the missing end tags don't matter for rendering
           node.note = date
           assert node.note == "<html><body><p>1970-01-01T02:00:00.000+0000"
           assert node.note.plain == "1970-01-01T02:00:00.000+0000"
           assert node.note.date == date
           // == remove note
           node.note = null
           assert node.note.text == null

    Parameters:
      `value` - An object for conversion to String. Works well for all types that `Convertible` handles, particularly `Convertible`s itself.
    Since:
      1.2 (note that the old setNoteText() did not support non-String arguments.

  - ### setNoteText

    void setNoteText(String html)
    Sets the raw (HTML) note text.

  - ### setNoteContentType

    void setNoteContentType(String contentType)
    Sets note content type. Use null to remove.
    Since:
      1.9.0

  - ### setText

    void setText(Object value)
    If `value` is a String the node object is set to it verbatim. For all other argument types it's an alias for `setObject(Object)`.

         node.text = '006'
         assert node.object.class.simpleName == "String"
         node.object = '006'
         assert node.text == '6'
         assert node.object.class.simpleName == "Long"

    Since:
      1.2, semantics changed for Strings with 1.2.17
    See Also:
      - `setObject(Object)`

  - ### setObject

    void setObject(Object value)
    A node's text object is normally String valued but it can be of any type since every Object can be converted to String for display. This methods provides automatic conversion to String in a way that node.to.getXyz() methods will be able to convert the string properly to the wanted type.

    Special support is provided for numbers, dates and calendars that are stored unconverted. For display of them a standard formatter is used (use #setFormat() to change it). You may also pass `IFormattedObject` instances (`FormattedDate`, `FormattedNumber` or `FormattedObject`) directly to determine the format in one pass.

    All other types are converted via value.toString().

    Numbers

         double number = 1.2222222d
         node.object = number
         // to enable math with node.object its type is not FormattedNumber
         assert node.object.class.simpleName == "Double"
         assert node.to.object.class.simpleName == "Double"
         // use globally bound TextUtils object
         def defaultNumberFormat = textUtils.defaultNumberFormat
         assert node.format != null
         // e.g. "1.22"
         assert node.text == defaultNumberFormat.format(number)
         assert node.to.num == number
         assert node.to.num + 1.0 == number + 1.0
         assert node.object + 1.0 == number + 1.0

    Dates

         def date = new Date(0) // when Unix time began
         node.object = date
         assert node.object.class.simpleName == "FormattedDate"
         assert node.to.object.class.simpleName == "FormattedDate"
         // use globally bound TextUtils object
         def defaultDateFormat = textUtils.defaultDateFormat
         assert node.object.toString() == defaultDateFormat.format(date)
         assert node.format == defaultDateFormat.pattern
         // e.g. "01/01/1970"
         assert node.text == defaultDateFormat.format(date)
         assert node.to.date == date

    Date/Time

         def date = new Date(0) // when Unix time began
         // the default format for dates does not contain a time component. Use node.dateTime to override it.
         node.dateTime = date
         assert node.object.class.simpleName == "FormattedDate"
         assert node.to.object.class.simpleName == "FormattedDate"
         // use globally bound TextUtils object
         def defaultDateFormat = textUtils.defaultDateTimeFormat
         assert node.object.toString() == defaultDateFormat.format(date)
         assert node.format == defaultDateFormat.pattern
         // e.g. "01/01/1970 01:00"
         assert node.text == defaultDateFormat.format(date)
         assert node.to.date == date

    Parameters:
      `value` - A not-null object.
    Since:
      1.2

  - ### setDateTime

    void setDateTime(Date date)
    sets the node text to a default formatted datetime object. (After setObject(Date) no time component is displayed so use this method if you want the time to be displayed.)
    Since:
      1.2
    See Also:
      - `setObject(Object)`

  - ### setBinary

    void setBinary(byte[] data)
    Converts data to a BASE64 encoded string and sets it as this node's text. Long lines are folded to a length a bit less than 80.
    Since:
      1.2

  - ### setFormat

    void setFormat(String format)
    sets the format string of the formatter. It has to be appropriate for the data type of the contained object, otherwise the format is simply ignored. For instance use "dd.MM.yyyy" for dates but not for numbers:

         node.object = new Date()
         node.format = "dd.MMM.yyyy"  // ok: "13.07.2011"
         node.format = "#.00"  // still "13.07.2011". See log: "cannot format 13.07.2011 with #.00: multiple points"

    Numbers:

         node.object = 1.122
         node.format = "#.##"   // ok: "1.12" (US, GB, ...) or "1,12" (Germany, ...)
         node.format = "#.0000" // ok: "1.1220" (US, GB, ...) or "1,1220" (Germany, ...)

    Since:
      1.2
    See Also:
      - `setObject(Object)`

  - ### setLastModifiedAt

    void setLastModifiedAt(Date date)

  - ### setCreatedAt

    void setCreatedAt(Date date)

  - ### putAt

    Object putAt(String attributeName, Object value)
    Allows to set and to change attribute like array (or map) elements. See description of `Attributes` for details.
    Parameters:
      `value` - An object for conversion to String. Works well for all types that `Convertible` handles, particularly `Convertible`s itself. Use null to unset an attribute.
    Returns:
      the new value

  - ### setAttributes

    void setAttributes(Map<String,Object> attributes)
    allows to set all attributes at once:

           node.attributes = [:] // clear the attributes
           assert node.attributes.size() == 0
           node.attributes = ["1st" : "a value", "2nd" : "another value"] // create 2 attributes
           assert node.attributes.size() == 2
           node.attributes = ["one attrib" : new Double(1.22)] // replace all attributes
           assert node.attributes.size() == 1
           assert node.attributes.getFirst("one attrib") == "1.22" // note the type conversion
           assert node["one attrib"] == "1.22" // here we compare Convertible with String

  - ### setLeft

    void setLeft(boolean isTopOrLeft)
    Deprecated.
    since 1.10.4 - use `setSideAtRoot(Side)` instead.
    Parameters:
      `isTopOrLeft` -

  - ### setSideAtRoot

    void setSideAtRoot(Side side)
    Since:
      1.10.4

  - ### hasEncryption

    boolean hasEncryption()
    Returns true if the node is password protected, no matter if currently accessible (password entered) or not.
    Since:
      1.3.6

  - ### removeEncryption

    void removeEncryption(String password)
    decrypts a node and remove the password protection.
    Since:
      1.3.6

  - ### isEncrypted

    boolean isEncrypted()
    Returns true if the node has password protection and is currently unaccessible (password has to be entered).
    Since:
      1.3.6

  - ### encrypt

    void encrypt(String password)
    encrypts a node. If the node has child nodes the branch is folded.
    Since:
      1.3.6

  - ### decrypt

    void decrypt(String password)
    decrypts a node without removing the encryption.
    Since:
      1.3.6

  - ### setHorizontalShift

    void setHorizontalShift(int horizontalShift)
    Since:
      1.3.7

  - ### setHorizontalShift

    void setHorizontalShift(String verticalShift)
    use length units like "1 cm" or "6 pt"
    Since:
      1.5.6

  - ### setVerticalShift

    void setVerticalShift(int verticalShift)
    Since:
      1.3.7

  - ### setVerticalShift

    void setVerticalShift(String verticalShift)
    use length units like "1 cm" or "6 pt"
    Since:
      1.5.6

  - ### setMinimalDistanceBetweenChildren

    void setMinimalDistanceBetweenChildren(int minimalDistance)
    Since:
      1.3.7

  - ### setBaseDistanceToChildren

    void setBaseDistanceToChildren(int baseDistance)
    Since:
      1.11.1

  - ### setMinimalDistanceBetweenChildren

    void setMinimalDistanceBetweenChildren(String minimalDistance)
    use length units like "1 cm" or "6 pt"
    Since:
      1.5.6

  - ### setBaseDistanceToChildren

    void setBaseDistanceToChildren(String baseDistance)
    Since:
      1.11.1

  - ### setVerticalShift

    void setVerticalShift(Quantity<LengthUnit> verticalShift)
    Since:
      1.5.6

  - ### setMinimalDistanceBetweenChildren

    void setMinimalDistanceBetweenChildren(Quantity<LengthUnit> minimalDistance)
    Since:
      1.5.6

  - ### setBaseDistanceToChildren

    void setBaseDistanceToChildren(Quantity<LengthUnit> baseDistance)
    Since:
      1.11.1

  - ### setHorizontalShift

    void setHorizontalShift(Quantity<LengthUnit> verticalShift)
    Since:
      1.5.6

  - ### setChildNodesLayout

    void setChildNodesLayout(ChildNodesLayout layout)
    Since:
      1.11.1

  - ### sortChildrenBy

    void sortChildrenBy(NodeToComparableMapper comparable)
    A sort method that uses the result of the lambda ("block") for comparison. 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:

            // sort by details text
            node.sortChildrenBy{ it.details.to.plain }
            // sort numerically
            node.sortChildrenBy{ it.to.num0 }

    Parameters:
      `comparable` - a lambda that returns a Comparable value like a String. The closure will receive a NodeModel as an argument.
    Since:
      1.4.1

  - ### setAlias

    void setAlias(String alias)
    Sets alias of the node
    Since:
      1.7.1

  - ### setIsGlobal

    void setIsGlobal(boolean value)
    Sets if the node can be accessed using global accessor, see `NodeRO.at(String)`
    Since:
      1.7.1

  - ### getGeometry

    NodeGeometry getGeometry()
    Specified by:
      `getGeometry` in interface `NodeRO`
    Since:
      1.8.11

  - ### getTags

    Tags getTags()
    Specified by:
      `getTags` in interface `NodeRO`
    Since:
      1.12.1

  - ### setBookmark

    void setBookmark(String name, BookmarkType bookmarkType)
    Sets a bookmark for this node with the given name and type. If a bookmark already exists for this node, it will be replaced. Bookmarks allow quick navigation to important nodes in the map.

    Examples:

         // Create a bookmark that opens as a regular selection
         node.setBookmark("Important Node", BookmarkType.SELECT)

         // Create a bookmark that opens this node as the root view
         node.setBookmark("View From Here", BookmarkType.ROOT)

    Parameters:
      `name` - the display name for the bookmark
      `bookmarkType` - the type of bookmark - SELECT for normal navigation, ROOT to open as root view
    Since:
      1.12.12

  - ### setBookmark

    void setBookmark(String name, String bookmarkType)
    Sets a bookmark for this node with the given name and type. Convenience overload that accepts bookmark type as a string for easier scripting. If a bookmark already exists for this node, it will be replaced.

    Examples:

         // Create a bookmark that opens as a regular selection
         node.setBookmark("Important Node", "SELECT")

         // Create a bookmark that opens this node as the root view
         node.setBookmark("View From Here", "ROOT")

    Parameters:
      `name` - the display name for the bookmark
      `bookmarkType` - the type of bookmark as string - "SELECT" or "ROOT" (case insensitive)
    Throws:
      `IllegalArgumentException` - if bookmarkType is not a valid BookmarkType value
    Since:
      1.12.12

  - ### removeBookmark

    void removeBookmark()
    Removes the bookmark for this node if one exists. Has no effect if the node is not bookmarked.
    Since:
      1.12.12