Scripts are installed in the Monkey menu by placing them in "*.em" files in a top-level "monkey" folder of any project (obviously, scripts are un-installed by renaming or moving them). The complete set of scripts is the union of the scripts in all the top-level monkey folders in the workspace.
Scripts include metadata that specifiy how a script is to be run and additional resources required for successful operation. Metadata consists of keyword values pairs. These are placed in the first comment block of the script. This must be a /* ... */ style comment. Only recognized keywords are processed. For example, only Menu: and DOM: keywords are processed in the following script.
The Menu: metadata tag specifies that this script is to be included in the Monkey menu. If more than one script specifies the same menu item, the menu item will appear more than once. Submenus are created using the Eclipse standard notation "Menu > SubMenu" or "Menu > SubMenu > SubSubMenu" (etc.) in the metadata string.
The Key: metadata tag specifies the single keystroke to be assigned to the script.
The format of keystrokes is described in the org.eclipse.ui.bindings extension point documentation for the sequence attribute which is reproduced below.
The recognized modifiers keys are M1
, M2
, M3
, M4
, ALT
, COMMAND
, CTRL
, and SHIFT
. The "M" modifier keys are a platform-independent way of representing keys, and these are generally preferred. M1
is the COMMAND
key on MacOS X, and the CTRL
key on most other platforms. M2
is the SHIFT
key. M3
is the Option
key on MacOS X, and the ALT
key on most other platforms. M4
is the CTRL
key on MacOS X, and is undefined on other platforms.
The actual key is generally specified simply as the ASCII character, in uppercase. So, for example F
or ,
are examples of such keys. However, there are some special keys; keys that have no printable ASCII representation. The following is a list of the current special keys: ARROW_DOWN
, ARROW_LEFT
, ARROW_RIGHT
, ARROW_UP
, BREAK
, BS
, CAPS_LOCK
, CR
, DEL
, END
, ESC
, F1
, F2
, F3
, F4
, F5
, F6
, F7
, F8
, F9
, F10
, F11
, F12
, F13
, F14
, F15
, FF
, HOME
, INSERT
, LF
, NUL
, NUM_LOCK
, NUMPAD_0
, NUMPAD_1
, NUMPAD_2
, NUMPAD_3
, NUMPAD_4
, NUMPAD_5
, NUMPAD_6
, NUMPAD_7
, NUMPAD_8
, NUMPAD_9
, NUMPAD_ADD
, NUMPAD_DECIMAL
, NUMPAD_DIVIDE
, NUMPAD_ENTER
, NUMPAD_EQUAL
, NUMPAD_MULTIPLY
, NUMPAD_SUBTRACT
, PAGE_UP
, PAGE_DOWN
, PAUSE
, PRINT_SCREEN
, SCROLL_LOCK
, SPACE
, TAB
and VT
.
We also understand some alternative names for some common special keys. For example, we accept both ESC
and ESCAPE
, and CR
, ENTER
and RETURN
are all the same.
The Listener: metadata tag specifies that the script subscribes to events which are handled by functions in the script. The tag's value is of the form:
<function-name>().<add-method-name>(this)The <function-name> names a function in the current script that answers the object to which the script will listen. The <add-method-name> names the method that will be used to register as a listener of that object. The add method implies a corresponding remove method as well as the appropriate handling functions that will be called, if present, when an update happens. The following script listens for and prints resource change events.
The Scope: metadata tag specifies which shared outer scope this scrip shares with others. The value of the tag is a name that is used for no other purpose than identifying scopes. Without the scope tag a script will have its own annonymous scope that lasts until the script is recompiled.
Scripts manipulate script objects such as strings and arrays, native Java objects including native Eclipse objects, and special DOM objects made specifically to simplify scripting.
Native Java objects can be accessed through their fully qualified class names. Eclipse objects require that the fully qualified name be prepended with the additional name "Packages". Here are some valid scripting expressions that show how this works
java.lang.System.out.println("hello world");
Packages.org.eclipse.jface.dialogs.MessageDialog.openInformation(
window.getShell(),
"Monkey Dialog",
"Hello World"
)
One of the challenges in scripting for Eclipse is dealing with the restricted namespaces of the various plug-ins. The classes and packages that are directly referencable are those in the plug-in pre-requisites of the org.eclipse.eclipsemonkey plug-in such as org.eclipse.ui and org.eclipse.jface.text. To use other packages and classes, you must use a DOM (see below).
DOM objects appear as globals in the script namespace. Some DOMs are primitively supported, others are supplied by DOM plug-ins (standard Eclipse plug-ins that contribute an org.eclipse.eclipsemonkey.dom extensions). The built-in DOMs available with this release are:
window
-- direct access to the Eclipse IWorkbenchWindow object.
http://<update-site>/<dom-plugin-ID>The <update-site> refers to a normal Eclipse Update Manager update site. The <dom-plugin-ID> is the unique ID of the plug-in that supplies the DOM (via the org.eclipse.eclipsemonkey.dom extension point). Eclipse Monkey checks to be sure that all specified DOMs are loaded and notifies you if they aren't.
If you ask, Eclipse Monkey will open an approximately configured update dialog to load missing DOMs:
The following DOMs are contributed by the org.eclipse.dash.doms
plug-in
workspace
-- direct acccess to the Eclipse IWorkspace object.
resources
-- indirect access to Eclipse IResources through custom wrappers: Resources, File and Line.
Learn about these DOM through the examples or by reading the source code of the Eclipse Monkey Standard DOMs plug-in (org.eclipse.dash.doms).