IDM PowerTips

Integrated scripting engine tutorial

Scripting in UltraEdit/UEStudio is enabled through embedding of the JavaScript engine. This allows users to enjoy the power and flexibility of the JavaScript language while using the UltraEdit/UEStudio Application Object commands to interact with the editor or documents open in the editor (Document Object commands).

The scripting engine supports the core functionality of JavaScript 1.7. Further information on JavaScript 1.7 may be found on the associated Mozilla site.

Using the Integrated Scripting Engine

Step 1: Create the Script

Create your (JavaScript) script using UltraEdit/UEStudio. As mentioned above, you may use JavaScript 1.7 and the UltraEdit/UEStudio Application Object commands and Document Object Commands.

There is extensive information in the Help regarding the commands available, however we have a few sample scripts below.

The script we’ve created above is a simple “Hello World” script which will write “Hello World” to the active document.

Step 2: Add the Script

Once you’ve created (and saved) your script you will need to add it in the Scripting : Scripts dialog.

Click on the “Add” button to add the script to the list. You will need to browse to the location of the script and, if you would like, type a description of the script. The description will display in the Description field in the scripting dialog.

Once the script has been added, you can define a hotkey/chord for a quick and easy execution of the script. Note: You’ll need to create a hotkey first before you can set up a chord.

When you are done, you may click OK.

Step 3: Execute the Script

To execute the script go to the Scripting menu. You will see your script name at the bottom of the “Scripts” menu. Click on the script name to execute it. You can also use the Hotkey/Chord if you have defined them.

After executing the above script, you should see the following results:

Note: As the scripting does take advantage of the JavaScript language, you may also write this as a function:

// Hello World Example Script

function hello() {
  UltraEdit.activeDocument.write("Hello World!")
}
hello();

Example Script – Retrieving String User Input

The scripting support allows you to prompt the user for String or Integer data, capture that data in a variable, then use the variable accordingly. The methods used to retrieve the data are “UltraEdit.getValue” and “UltraEdit.getString”.

Prompt for String Input

To prompt for String input use the “UltraEdit.getString” command. An example of prompting for input and capturing the input as a variable is as follows:

var str = UltraEdit.getString(“Please Enter a String:”,1);

Capture Input:
In order to capture the data, and NOT write it immediately to the document, you must use the ‘1‘ parameter in the getString method.

Write Input:
If you would like to write the user input immediately to the file use ‘0‘ as the parameter value.

Sample Capture String Input Script

The example below prompts the user for a String and captures it in the variable “str”. It will then write “You Entered user input (str)” to the active document. It will write a different response depending on whether “UltraEdit” or “UEStudio” was entered.

If you would like, you may copy the script below and expand upon it.

function strInput() {

  //Get user input
  var str = UltraEdit.getString("Please Enter a String:",1);

  //Output what was entered
  UltraEdit.activeDocument.write("You Entered " + str + "\r\n");

  //Conditional responses
  if (str == "UltraEdit") {
    UltraEdit.activeDocument.write(str + " has an integrated scripting engine.\r\n");
    UltraEdit.activeDocument.write(str + " is a very powerful editor.\r\n");
    UltraEdit.activeDocument.write("\r\n");
  } else if (str == "UEStudio") {
    UltraEdit.activeDocument.write(str + " also has integrated scripting\r\n");
    UltraEdit.activeDocument.write(str + " includes all the functionality of UltraEdit and more.\r\n");
    UltraEdit.activeDocument.write("\r\n");
  } else {
    UltraEdit.activeDocument.write("Sorry, there is no defined output for " + str + "\r\n");
    UltraEdit.activeDocument.write("\r\n");
  }

} //end strInput

strInput();

Note: The command used to write to the active document is “UltraEdit.activeDocument.write”

The results after entering “Data“, “UltraEdit“, and “UEStudio” is as follows:

Example Script – Retrieving Integer User Input

The scripting support allows you to prompt the user for String or Integer data, capture that data in a variable, then use the variable accordingly. The methods used to retrieve the data are “UltraEdit.getValue” and “UltraEdit.getString”.

Prompt for Integer Input

To prompt for Integer input use the “UltraEdit.getValue” command. An example of prompting for integer input and capturing the input as a variable is as follows:

var num = UltraEdit.getValue(“Please enter an integer”,1);

Capture Input:
In order to capture the data, and NOT write it immediately to the document, you must use the ‘1‘ parameter in the getValue method.

Write Input:
If you would like to write the user input immediately to the file use ‘0‘ as the parameter value.

Sample Capture Integer Input Script

The example below prompts the user for an integer value and captures it in the variable “num”. It will write “You Entered user input (str)” to the active document. It will then enter a loop in which it will write “i” number of lines, and number each line.

If you would like, you may copy the script below and expand upon it.

function intInput() {

  //Get user input
  var num = UltraEdit.getValue("How Many Lines:",1);

  //Output what was entered
  UltraEdit.activeDocument.write("You Entered " + num + "\r\n\r\n");

  //Loop
  var i = 1;
  while (i <= num) {
    UltraEdit.activeDocument.write(i + " \r\n");
    i = ++i;
  }

} //end strInput

intInput();

Note: The command used to write to the active document is “UltraEdit.activeDocument.write”

The result after entering “5” is as follows:

Example Script – Enumerate Through All Open Files

Using the Document Object commands, you may access/reference the files that currently open in the editor. If you would like to perform an action/run a script against all open files you would need to retrieve the number of open files, and then loop through each file.

As an example, if you need to find out how many files are open in the editor, you could use the following:

var num_of_docs = UltraEdit.document.length;

If you need to reference a specific file, based on what it was opened, you can do so using UltraEdit.document[x]; where x is the number of the document.

Sample Enumerate Through All Open Files

The script below will Enumerate through each open file and write a simple header to each file.

If you would like, you may copy the script below and expand upon it.

// Hello welcome to the UltraEdit scripting environment. Normally you would
// put a header comment at the top of a javascript file to be used in UltraEdit
// in order to indicate the version of the UltraEdit scripting API like so:
// Version = 1.00
// However, this is currently not necessary since the API will default to 1.00.

// ----------------------------------------------------------------------------
// header.js
// This script creates a header for all open documents
// ----------------------------------------------------------------------------
// UltraEdit is our application object. All UltraEdit operations will use this
// object.

// Get the num of open documents.
var num_of_docs = UltraEdit.document.length;

var dashes = "// ------------------------------------------------------------";
dashes += "----------------\r\n";

// Enumerate through all open documents and add the header.
var index;
for (index = 0; index < num_of_docs; index++) {
  UltraEdit.document[index].top();
  UltraEdit.document[index].write(dashes);
  UltraEdit.document[index].write("// Script Name: \r\n");
  UltraEdit.document[index].write("// Creation Date: \r\n");
  UltraEdit.document[index].write("// Last Modified: \r\n");
  UltraEdit.document[index].write("// Copyright (c)20XX\r\n");
  UltraEdit.document[index].write("// Purpose: \r\n");
  UltraEdit.document[index].write(dashes);
} //end for loop

After running the above script, every open file now has the following header:

Enjoy the power of the integrated scripting engine!