Working with Scripts

What is a Script?

A script is a special file used to automate a task on a computer. In essence, a script is a simplified computer program. Jarte integrates with the popular (and free) AutoHotkey program to allow automation of tasks within Jarte via AutoHotkey script files created by the user.

Scripts are great for automating tasks that involve a set of manual steps that are always the same and that you find yourself performing frequently. For example, suppose you frequently need to apply yellow highlighting to every occurrence of a particular phrase in a document. Doing this manually would be tedious and time consuming. But you can create a script that will do the same task instantly and then assign that script to a custom shortcut key or Quick Bar button.

Scripting with Jarte vs Jarte Plus

AutoHotkey is general purpose scripting tool and can be used be used with any Windows program, including both Jarte and Jarte Plus. However, Jarte Plus provides special features that allow you integrate your AutoHotkey scripts seamlessly into Jarte Plus. Specifically, Jarte Plus allows you to do the following:

AutoHotkey Installation

AutoHotkey needs to be installed (but not necessarily running) in order to run Jarte scripts. Normally, Jarte can find the AutoHotkey program on your computer automatically. However, if AutoHotkey is installed as a portable program then you may need to assign AutoHotkey's program file path to advanced setting AutoHotkey Path to help Jarte find it.

How to Write a Script

This quickest way to learn how to write scripts is to walk through some simple example scripts. However, you will also want to refer to the AutoHotkey documentation which provides far more information and detail about AutoHotkey scripts than can be provided in the few basic examples shown here.

Example 1: Enter Simple Text

For our first example, we will write a script that enters the simple phrase "Hello World!" wherever the text cursor is currently positioned in the currently open document. Start by creating a new document and switch its format to plain text (go to File > File Options > Document Format > Plain Format, or just click the format indicator in the status bar). Now, enter the following text in the document:

#Include %A_ScriptDir%

#Include Jarte Script Helpers.ahk

SendRaw Hello World!

JarteScriptEnd()

Anatomy of a script

First, let's look at the two top lines. Those two lines should always appear at the top of any Jarte script file. They provide your script with access to special Jarte helper functions that allow you to easily use Jarte's built-in scripting API. Later examples will demonstrate use of the helper functions. The top two lines allow Jarte to recognize the document as being a Jarte script file.

The SendRaw line is where the real action occurs. The script will enter whatever text appears after the SendRaw command into the current Jarte document. The text is entered as a series of keystrokes just as if they were being typed from te keyboard.

The JarteScriptEnd line let's Jarte know the script has completed its run. This should always be the last line of your Jarte scripts.

Save the script

Save the script document to Jarte's Scripts folder. Note that Jarte's Save dialog window will automatically navigate to Jarte's Scripts folder when you are saving a Jarte script. You can also access the Scripts folder at any time from Jarte by going to Help > System Information > Data Folder > Scripts. All Jarte script files must reside in that folder.

It is a good practice to use script file names that include the word "Script" within the file name. This makes it easy to find and distinguish scripts from the other Jarte commands when assigning custom shortcut keys or custom Quick Bar buttons. Also note the appropriate file name extension for script files is ".ahk". For this example, name your script Test Script.ahk.

Assign the script to a shortcut key

Now that you have created the script and saved it to the Scripts folder you need to either assign it to a custom shortcut key, or a custom Quick Bar button, in order to run the script from within Jarte. For this example, assign key F12 as the shortcut key for the script. The script will appear in the list of Jarte commands as "Test Script" (i.e., the chosen script file name). When the F12 key is pressed Jarte will recognize the key is assigned to an AutoHotkey script. Jarte will then pass that script to the installed AutoHotkey program which will execute the commands in the script.

Run the script

Start a new document in Jarte and then press the F12 key to execute your script. You should now see "Hello World!" appear in the document. Congratulations, you have just created and run your first Jarte script!

Example 2: Enter Formatted Text

In our next script we will send the phrase "Scripting is really cool!" to the current Jarte document. However, we will split the phrase so the words "Scripting is" appear on one line and the words "really cool!" appear on the next line. We will also bold the word "really". Edit your test script so that it now appears as follows:

#Include %A_ScriptDir%

#Include Jarte Script Helpers.ahk

; Enter the phrase "Scripting is really cool!" into the current Jarte document.

;

SendInput Scripting is{Enter}^breally^b cool{!}

JarteScriptEnd()

Comment lines

Note the two new lines that begin with semicolons. Those are called comment lines and they have no affect on the script. A semicolon, and everything that appears to the right of the semicolon, is ignored by the AutoHotkey program when the script is run. Comment lines can be included in your scripts to provide useful commentary without changing the functionality of the script.

SendInput

SendInput is similar to SendRaw except SendInput can send special keys such as shortcut keys, carriage returns, tabs, etc. SendRaw can only send letters, digits, punctuation, and symbols. Keys, such as carriage returns and tabs, are designated by enclosing them in braces. In our example, the carriage return key is specified as {Enter} and causes any following text to begin on a new line. A complete list special key names is available in the AutoHotkey documentation.

It is important to note that unlike SendRaw, SendInput reserves the following characters for special use: ^+!#{}. If you want to use SendInput to send any of those keys as text to Jarte then the key must be enclosed in braces. As an example, note the exclamation point after the word "cool" in our script is now enclosed in braces.

SendInput allows you to send shortcut keys to Jarte using the reserved characters as follows:

These reserved characters are applied to first non-reserved character which follows them. In our example, the word "really" was bolded by sending the Ctrl+B shortcut key to Jarte immediately before and after sending the keys for the word "really". The Ctrl+B shortcut is represented as ^b in the  script. As further examples:

Example 3: Color Text Red

SendInput is powerful enough to perform many of the automation tasks you might have without learning much else about AutoHotkey. Here is a script that uses SendInput to apply the color red to the currently selected text:

#Include %A_ScriptDir%

#Include Jarte Script Helpers.ahk

SendInput !nl

Sleep 100

SendInput {Down}{Down}{Right}{Right}{Enter}

JarteScriptEnd()

Menu navigation

SendInput !nl sends shortcut key Alt+N and then key L which accesses Jarte's "Font Color" menu selection (assumes the default Compact Layout and no main menu) to display the font color selector dialog. If you have Jarte's main menu displayed then change the line to SendInput !ofl instead.

Sleep

Sleep 100 causes a short delay in the script to give Jarte time to display the font color selector before more keys are sent. This is necessary because SendInput can send keystrokes faster than Jarte can handle them in certain situations. In this example, without the Sleep 100, AutoHotkey would send the rest of the keys (i.e., {Down}{Down}{Right}{Right}{Enter}) without waiting for the color selector to appear first. That could cause some of the sent keys to be lost leading to unexpected results. The number following Sleep indicates the number of milliseconds AutoHotkey should wait before proceeding (in this example, 100 milliseconds or one tenth of a second). In general, Sleep should always be used when a script displays a dialog window to give Jarte time to display the window before proceeding. You will find it handy to use in other situations as well to slow your script down in order to make it run more reliably.

Navigating a dialog window

SendInput {Down}{Down}{Right}{Right} uses the arrow keys to navigate to the color red in the font color selector dialog. {Enter} chooses the selected color (i.e., red) and applies it to the current text selection.

Example 4: Color Text Red Redux

This example is the same as the previous example except we replace SendInput !nl with JarteRunCommand("Font Color"):

#Include %A_ScriptDir%

#Include Jarte Script Helpers.ahk

JarteRunCommand("Font Color")

Sleep 100

SendInput {Down}{Down}{Right}{Right}{Enter}

JarteScriptEnd()

The difference is SendInput !nl displays the font color selector by sending menu navigation keys whereas JarteRunCommand("Font Color") is a Jarte script helper function that executes the font color command directly. JarteRunCommand can be used to run any command that appears in the custom shortcut keys dialog's list of Jarte commands.

Both example scripts perform exactly the same task, but we generally recommend using JarteRunCommand to execute Jarte commands since it is more intuitive and easier to read in the script.

Example 5: Replace

SendRaw and SendInput work well but they can be a little slow when entering larger phrases since they type out the characters one at a time. In this example we will use Jarte script helper function JarteReplaceSel to enter the phrase "Hello World!" similarly to example 1:

#Include %A_ScriptDir%

#Include Jarte Script Helpers.ahk

JarteReplaceSel("Hello World!")

JarteScriptEnd()

The advantage of using JarteReplaceSel is that it enters the entire phrase instantly. If you want your phrase to contain double quote marks then each double quote character will need to specified twice in order to make it appear once in the resulting phrase. For example:

#Include %A_ScriptDir%

#Include Jarte Script Helpers.ahk

JarteReplaceSel("I said ""Hello World!""")

JarteScriptEnd()

Running this script will enter the phrase I said "Hello World!" into the current document. You may also use {Enter} to represent a carriage return and {Tab} to represent a tab. For example:

#Include %A_ScriptDir%

#Include Jarte Script Helpers.ahk

JarteReplaceSel("Hello{Enter}World!")

JarteScriptEnd()

This script will place "Hello" on the current line and then "World!" on the next line.

Note: JarteReplaceSel can only be used to enter phrases that are no more than 255 characters in length.

Example 6: Replace All

Replacing all occurrences of a particular word or phrase is a common task that can be easily automated. Although this task can be automated using only SendInput, in this example we will use a Jarte helper function to accomplish the task much more easily:

#Include %A_ScriptDir%

#Include Jarte Script Helpers.ahk

JarteReplaceAll("dna", "deoxyribonucleic acid")

JarteScriptEnd()

This script uses Jarte helper function JarteReplaceAll to replace all occurrences of "dna" in the current document with "deoxyribonucleic acid". Of course, you can modify "dna" and "deoxyribonucleic acid" to be whatever search and replacement terms you wish. Note the need to enclose both the search and replacement terms within double quotes.

Some word processors have a feature known as a "Join Lines" feature which replaces all of the carriage returns in a document with spaces. Jarte does not have that feature but you can use this script example to do the same thing by modifying the search and replacement as follows:

#Include %A_ScriptDir%

#Include Jarte Script Helpers.ahk

JarteReplaceAll("{Enter}", " ")

JarteScriptEnd()

The search term is a carriage return the replacement term is a space character. Note that in general, {Enter} represents a carriage return and {Tab} represents a tab character, and {Enter} and {Tab} can be used in both the search and replacement terms.

There are several other Jarte helper functions available. Read the comment lines in file Jarte Script Helpers.ahk in Jarte's Scripts folder for information about those functions. The following example will demonstrate most of them.

Note: Both the search term and the replacement term specified for JarteReplaceAll must be no more than 255 characters in length.

Example 7: Highlight All

Now that you have seen how to write basic Jarte scripts, let's look at an example script that's a bit more advanced. The following script applies yellow  highlighter to all occurrences of the currently selected word or phrase in the current document. The comment lines in the script provide a brief explanation of how the script works. This script can be taken and changed to perform similar search-and-modify type tasks in Jarte.

#Include %A_ScriptDir%

#Include Jarte Script Helpers.ahk

; Retrieve and store the length of the current text selection.

;

length := JarteGetSelLength()

; Check to ensure text has been selected before proceeding.

;

if (length = 0) {

  MsgBox Select text to be highlighted and try again.

  Exit

}

; Retrieve and store the currently selected text and its

; start position.

;

mySelectedText := JarteGetSelText()

mark1 := JarteGetSelPos()

; Display the highlighter tool's color selector.

;

JarteRunCommand("Highlight")

Sleep 100

; Select yellow as the desired color and then cancel the highlighter.

; Yellow will now be established as the most recently chosen

; highlighter color.

;

SendInput {Left}{Up}{Up}{Up}{Left}{Left}{Enter}{Escape}

; Find the first occurrence of the text that was selected by the

; user, store its position in variable "mark2", and then select

; the first occurrence of the text in the document.

;

mark2 := JarteFind(mySelectedText, 0, true)

; Repeat the highlighter tool for as long as "mark2" is not equal

; to -1 (-1 means Jarte did not find any further occurrences of

; the selected text).

;

While(mark2 <> -1) {

  ; Repeat the highlighter tool on the current text selection.

  ;

  JarteRunCommand("Repeat Brush/Highlighter")

  ; Find the next occurrence of the selected text, store its

  ; position, and select the text.

  ;

  mark2 := JarteFind(mySelectedText, mark2 + length, true)

}

; Move the text cursor back to its original position.

;

JarteSetSel(mark1, 0)

JarteScriptEnd()

Final Remarks

The script examples provided here are meant to quickly provide you with the bare bone basics of creating AutoHotkey scripts for use with Jarte. AutoHotkey is a very powerful tool that can be used to automate many sophisticated tasks. You will want to read the excellent AutoHotkey documentation to learn more about how AutoHotkey works and what it can help you accomplish.

If you have questions regarding writing AutoHotkey scripts then try asking those questions at the AutoHotkey forums. If you would like to have Jarte Support create a custom script for you for a fee then contact us with a detailed description of what you need and we will provide you with a price quote.