Scripting

Since Release 0.9.0, FreeMind has a scripting facility using Groovy programming language, an imperative language syntactically resembling Java but with some syntactic sugar added such as optional declaration of types. The best way to get started is perhaps by reading Scripting/Mind map documentation, the wiki version of the mind map documentation originally written by Christian Foltin. What follows here is less informative and consolidated than the mind map documentation. Another source is the dedicated page User-contributed example scripts for scripts supplied by FreeMind users.

Security vulnerabilities

A bug report: A malicious script can cause harm by escaping the security sandbox.

Remedy for the end user: Do not open mind maps from untrustworthy/untrusted sources at all. And to be safe, do not set the FreeMind user property "startup_groovy_script". I, Dan Polansky, have performed an initial analysis of the issue and have not yet finished a more comprehensive analysis of this issue (23 Aug 2026).

Using

When stored in a mind map, each script is stored in a named attribute of a node, named for example as "script1" or "script2". One node can have multiple scripts attached.

Moreover, a script can be stored outside of a mind map in the following locations:

• In a physical style/pattern.
• In a file bound to a menu item.
• In a file set up in (or passed to) the user property startup_groovy_script and run on the FreeMind startup.

To add a new script to a node:

• Use the script editor, available from the menu Tools > Script Editor. A window pops up. There, choose menu Action > New script. A new script name appears in the top left pane, starting with "script", followed by "1" or higher if there already are scripts attached to the node blocking that name. Enter the script source code into the top right pane. Then you can choose menu Actions > Save and Exit to save the script, or you can immediately run it via menu Actions > Run.
• Alternatively, you can create an attribute whose name starts with "script" such as "script1" or "scriptA"; such an attribute is understood by FreeMind to be a script. This you can do via menu Edit > Edit Attributes (Alt + F9). However, this is rather inconvenient as the field for the attribute value is small.

To run a single script:

• Use the script editor (Tools > Script Editor), and its menu item Actions > Run.
• The Run function of the script editor shows the results of the execution in the pane at the bottom, and it shows error messages there, if any.

To run all the scripts in a mind map:

• Use the menu Tools > Evaluate or press Alt + F8. By default, the function asks for confirmation, for security reasons.

To delete a script:

• There is no menu in the script editor to do that. You can delete the corresponding attribute, by placing the cursor over the attribute, and in the context menu choosing Delete.

To add a script to a physical style (pattern), to be run on a node when the physical style is applied:

• Use Format > Physical Style > Manage Patterns..., navigate to the physical style (pattern) you want to extend with a script, scroll to the Scripting section, indicate that you want to change the script, and click on the rectangle next to the "Script" label. (See also Scripting/Mind map documentation.)

To store a script in a file once for the whole FreeMind application and add it to a menu item:

• See Scripting/Mind map documentation.

For more detail, see the FreeMind documentation available from the menu Help > Documentation, the section "New features in version 0.9.0" and the subsection "Scripting support".

Access points

Access points to scripting functionality, for reference:

• Menu: Tools > Script Editor
• In Script Editor
  • Menu: Actions > New Script
  • Menu: Actions > Run
  • Menu: Actions > Sign Script...
  • Menu: Dismiss Changes and Exit
  • Menu: Save and Exit
• Menu: Tools > Evaluate: run all the scripts in a mind map; keyboard shortcut: Alt + F8
• Menu: Tools > Preferences > pane Scripting
  • Checkbox: Permit File Operations
  • Checkbox: Permit Network Operations
  • Checkbox: Permit To Execute Other Applicatios
  • Checkbox: Trust Signed Scripts
  • Input field: Optional User Key Alias for Signing
• Menu: Edit > Edit Attributes; keyboard shortcut Alt + F9

Reservation/limitation: this section is incomplete.

Examples

Some example scripts follow. They take advantage of 1) = for assignment of the result of a calculation, 2) c for controller, and 3) node for the script node.

One-liner examples:

• Setting a new text of a node: =12 * 14. Scripts starting with "=" replace the text of a node with their results. A shorthand.
• Setting a new attribute value: myattribute=5 * 6. Another shorthand.
• Changing the text of a node: c.setNodeText(node, node.getText() + " - appended text")
• Setting the text color of a node: c.setNodeColor(node, java.awt.Color.RED)
• Setting the background color of a node: c.setNodeBackgroundColor(node, java.awt.Color.YELLOW)
• Setting the value of an attribute: c.editAttribute(node, "myresult", "new value")
• Setting the value of an attribute: c.editAttribute(node, "myresult", (String)(12*14)). Uses "(String)" to convert/cast the numerical result into a string. The bracket around 12*14 is mandatory.
• Make bold: c.setBold(node, true);
• Make italic: c.setItalic(node, true);
• Set cloud: c.setCloud(node, true);
• Set cloud color: c.setCloudColor(node, new java.awt.Color(0xEE, 0xEE, 0x99));. If there is no cloud, sets it; thus, c.setCloud() does not need to be called beforehand.
• Add icon as the rightmost icon: c.addIcon(node, freemind.modes.MindIcon.factory("pencil")); The icon list is in Icons page.
• Remove all icons: c.removeAllIcons(node);
• Remove last icon: c.removeLastIcon(node);
• Make node bold if folded: c.setBold(node, node.isFolded()) If not folded, make it non-bold.
• Set hyperlink: c.setLink(node, "http://www.google.com/");
• Make the currently selected node bold (not the script node): c.setBold(c.getSelected(), true);

Short multiline examples:

Turn currently selected nodes bold:

selectedNodesIt = c.getSelecteds().iterator();
while (selectedNodesIt.hasNext()) {
   selNode = selectedNodesIt.next(); 
   c.setBold(selNode, true);   
}

Count descendants, exluding the node itself:

nodeCount = 0;
def stack = new java.util.Stack();
stack.push(node);
while (stack.size() > 0) {
    def currNode = stack.pop();
    if (node != currNode)   
        nodeCount += 1;
    stack.addAll(currNode.getChildren());
}
c.editAttribute(node, "mynodecount", (String)nodeCount);

Sum the values of cost attribute of descendants, storing the result to costTotal attribute:

costTotal = 0;
def stack = new java.util.Stack();
stack.push(node);
while (stack.size() > 0) {   
    def currNode = stack.pop();
    if (node != currNode) {
       costTotal += Integer.parseInt(currNode.getAttribute("cost"));
    }
    stack.addAll(currNode.getChildren());
}
c.editAttribute(node, "costTotal", (String)costTotal);

See also Example scripts.

For another set of examples, see the FreeMind documentation available from the menu Help > Documentation, the section "New features in version 0.9.0" and the subsection "Scripting support"; this is also available here: Scripting/Mind map documentation.

Script editor

FreeMind has a very simplistic script editor, available from menu Tools > Script Editor. The editor has no color highlighting of code, and no specific support for writing Groovy scripts: it is basically a plain text editor like Notepad.

The editor has three panes: left one, right one, and bottom one. The left pane shows a list of scripts attached to a node. The right pane shows the script selected in the left pane. The bottom pane shows the results of the execution of a script.

The actions available in the menu Action of the script editor are New Script, Run, Sign Script, Dismiss Changes and Exit, and Save and Exit.

The action Action > New Script adds a new script to the left pane, named as "script1", "script2", etc. The newly created script can be edited in the right pane once the name of the script is selected in the left pane.

The action Action > Run runs the script selected in the left pane, and shows the result of running the script in the bottom pane, including any error messages.

The action Action > Sign Script makes it possible to sign a script. [To be documented].

API

The scripts can access FreeMind's scripting API--application programming interface. Above all, the scripts would typically make use of the methods of MindMapController. The mind map controller is available to scripts as 'c'.

The variables made available to scripts, with their types:

• MindMapController c: the controller
• MindMapNode node: the node the script is stored in, not the currently selected one
• HashMap cookies sScriptCookies: a hashmap of key-value pairs. There is more information on cookies at Scripting/Mind map documentation.

We suggest you use the FreeMind source code and an Integrate Development Environment (IDE) to explore the types and methods available.

Java sources exposing the API:

• MindMapController.java in Git, sourceforge.net
• MindMapNode.java in Git, sourceforge.net
• NodeAdapter.java in Git, sourceforge.net
• MindMapNodeModel.java in Git, sourceforge.net

Security

By default, FreeMind scripts are restricted in what they can do on the local computer. The restrictions include those of file operations, network operations and execution of applications. These restrictions can be lifted in user preferences, from the menu Tools > Preferences..., and the section "Scripting".

The available security options for scripting, in the section "Scripting" and subsection "Permissions":

• Permit File Operations
• Permit Network Operations
• Permit to Execute Other Applications
• Trust Signed Scripts
• Optional User Key Alias for Signing

Moreover, as per Scripting/Mind map documentation:

"A last word on security: before scripts is evaluated for the first time in FreeMind, the user is asked whether or not he allows it. The answer can be stored for every script but observe that a malicious script is able to perform every action on your computer that your users rights allow up to delete all files or send them to pirates.ru. This said, be careful and don't allow scripts when you don't know that the author is trusted. Finally, scripts are never evaluated automatically in FreeMind for these reasons. Thus, you can open a map without problems and have a look at the scripts it contains."

Further notes, including those on implementation:

• The above restrictions (on file operations, on network operations and on execution of other applications) were implemented using Java security sandbox[1], in dependence on Java's SecurityManager class. That class and the associated functionality was deprecated[2] and then removed/permanently disabled[3][4] from Java Runtime Environment (JRE). The deprecation took place in Java 17 from 14 Sep 2021[5]; the removal/disablement took place in Java 24 from 18 Mar 2025[6].
• FreeMind 0.9.0 and later (with scripting) can still be run using the JRE versions that have only deprecated but not removed the functionality, e.g. by modifying the freemind.bat file by adding a switch as the first parameter to the java invocation[7]:

  -Djava.security.manager=allow

  The security manager was removed/disabled in Java 24[8], released on 18 Mar 2025[9]; FreeMind cannot run on this version or later versions, until someone implements a removal of the above restriction functionality or until someone implements it in a different way.

Groovy

The scripting engine and language of FreeMind is Groovy. To find out about Groovy, you can check the following web resources:

• Apache Groovy, en.wikipedia.org
• groovy-lang.org
• Groovy, Java's New Scripting Language, 2004-09-29, onjava.com
• Your Thoughts on the Groovy Scripting Language?, 2006-04-17, Slashdot - a review and a discussion thread on pros and cons of Groovy
• Groovy homepage, groovy.codehaus.org (dead link)

Implementation

Scripts can be stored at the following locations/location types:

• In a mind map in a node attribute (in the "attribute" XML element).
• In a physical style (pattern), in patterns.xml file.
• In a script file that is bound to a menu item (see also Scripting/Mind map documentation).
• In a script file that is set in the startup_groovy_script user property, to be run on the startup (see also history.txt).

Reservation/limitation: the above was put together by Daniel Polansky and not reviewed by Christian Foltin.

When stored in a mind map, scripts are stored in attributes whose names starts with "script", meaning in the attribute of the attribute function, not in the attribute of XML. Thus, the script attribute can be called "script1", "script_A", or "script_sum_calculation". Attributes created via Actions > New Script menu in the script editor are of the form "scriptN", where N is a positive integer (1, 2, ...).

The script attributes are probably distinguished from non-script attributes by their starting with "script".

An example of storage in XML:

<node TEXT="hello">
<attribute NAME="script1" VALUE="=node.getNodeLevel() + &quot; &quot; + node.getText()"/>
</node>

Scripting is implemented as an external plugin.

Package: freemind/plugins/script/ (deadlink to CVS).

Limitations

• Having the scripts associated with a particular node rather than the whole mind map is not necessarily ideal. It is uncustomary from the perspective of an office application.
• Storing scripts in user-defined attributes is arguably not so nice; this is not what attributes are for.
• No way to run a single script from a mind map outside of the script editor (but see "startup" below). It is only within the script editor that one can run a single selected script. Outside of the script editor, there is the function to run all scripts stored in the nodes of the mind map. As a result, if there are multiple scripts in the mind map, there is not way to run a single script on the currently selected node, given that the currently selected node is in general distinct from the node in which the script is stored.
• No way to rename a script in the script editor. (But you, the user, can rename the corresponding user attribute.)
• No way to delete a script in the script editor. (But you, the user, can delete the corresponding user attribute.)
• No way to run a script upon mind map opening or mind map closing ("hooks"). However, from a security standpoint, this is a bonus.
• In FreeMind 0.9.0, there is no way to run a Groovy script when FreeMind starts. In FreeMind 1.0.0 (and 1.0.1), FreeMind reads the "startup_groovy_script" property to find what script to run, if any. An example given in history.txt is by using the -D switch of java runtime: "java -Dstartup_groovy_script=accessories/ExportToPdf.groovy -jar lib/freemind.jar". Keyword: "start-up".
• The built-in script editor is very simple/spartan: for instance, there is no syntax highlighting and no API exploration, let alone debugging like in Microsoft Office.
• There is no user interface option, not even a property in user properties, to disable scripting altogether, merely to restrict access the scripts have to file system, etc.

Freeplane

You can find inspiration in the scripts published for Freeplane, FreeMind's fork; however, they are not guaranteed to work with FreeMind.

Links:

• Scripting, docs.freeplane.org
• Scripts collection, docs.freeplane.org

Changes in FreeMind 1.0.0

The following feature was added (see also history.txt):

• User property startup_groovy_script was added to indicate which script, if any, is to be run when FreeMind starts (upon startup). (For implementation, see e.g. ScriptingRegistration.java class and possibly others.)

Disabling scripting altogether

Deleting/erasing the plugins/script directory from the FreeMind installation directory disables the scripting functionality: the Groovy jar file is in that directory as well as other jar files supporting the scripting functionality. It is a workaround to be on the completely safe side. Whether this does not break anything else is not perfectly clear to me (Dan Polansky).

See also

• Scripting/Mind map documentation – the mind map (.mm) documentation that came with FreeMind 0.9.0 converted to wiki
• User-contributed example scripts
• FreeMind 0.9.0: The New Features – an outdated description of new features, with an outdated description of the scripting functionality