com.frinika.project.scripting.javascript
Class JavascriptScope

java.lang.Object
  extended by org.mozilla.javascript.ScriptableObject
      extended by com.frinika.project.scripting.javascript.JavascriptScope
All Implemented Interfaces:
java.io.Serializable, org.mozilla.javascript.ConstProperties, org.mozilla.javascript.debug.DebuggableObject, org.mozilla.javascript.Scriptable

public class JavascriptScope
extends org.mozilla.javascript.ScriptableObject

This class provides the bridge between Frinika and the Rhino Javascript engine. It maps important parts of Frinika's object structure and features to Javascript variables and functions.

JavaScript Reference

The Frinika scripting engine uses a JavaScript engine which implements the ECMAScript for XML (E4X). For detailed information on the ECMA-script standard and provided language features, refer to the documentation available at JavaScript Language Resources: As addition to the core language capabilities provided by the ECMA-script standard, the following functions, objects and variables are provided as specific additions to interface between Frinika and JavaScript.

Global Functions

Some built-in top-level functions specific to Frinika are available within JavaScript. Top-level funcitons are not bound to any object, which means they can be invoked directly using statement as "myfunction(args1, args2)", without any priop object reference (such as "myObject.myfunction(arg)").

print(string)

Prints a string to the scripting console.

println(string)

Prints a string to the scripting console, and issues a line-feed afterwards. Note: due to internal limitations it is not possible to print the string "undefined" using println(). If you expect a variable x to carry the value undefined, use print(x); println(); instead.

println()

Issues a line-feed to the scripting console.

message(string)

Displays a message in a pop-up-dialog.

error(string)

Displays an error-message in a pop-up-dialog.

confirm(string) (= boolean)

Displays a pop-up-dialog and asks the user to click either "Ok" or "Cancel". If Ok is clicked, the return value will be true.

prompt(string) (= string)

Displays a pop-up-dialog and asks the user to enter a string.

promptFile(defaultFilename, suffices, saveMode) (= string)

Asks the user to select a filename or directory.
defaultFilename may be undefined.
suffices (optional) is a semicolon-seperated string containing possible file suffices to select plus optional textual description (e.g. "jpg JPEG Picture,png Portable Network Graphics,gif,svg Scalable Vector Graphics"). If saveMode is true and the user chooses a non-existing file without any of these suffices, the first one will automatically be added. In a special mode, suffices can be set to "<dir>" to indicate the selection of a directory instead of a file.
saveMode (boolean, optional) specifies wether the file requester should be opened for loading or for saving a file, false for loading, true for saving.

formatTime(ticks) (= string)

Returns the a string representing the number of ticks in a human-readable manner, e.g. "4:02.064".

parseTime(barBeatsTicksString) (= int)

Returns the number of ticks specified by the formatted string. The string's format is e.g. "4:02.064".

wait(ms)

Waits the specified amount of milliseconds.

waitTicks(ticks)

Waits the specified amount of ticks.

type(string) (= int)

Returns the type number for a corresponding type name, 1 for "Midi", 2 for "Audio", 4 for "Text".

typeName(int) (= string)

Returns the type name of a type number, "Midi" for 1, "Audio" for 2, "Text" for 4.

note(string) (= int)

Returns the number of a note as derived from the specified name. Example names are: c3, f#5, Gb2, D3

noteName(int) (= string)

Returns the name of a note.

fileRead(filename) (= string)

Reads a whole file as string. If the file doesn't exist something goes wrong reading, the result is "undefined".

fileWrite(filename, string) (= string)

Writes a whole string to a file. If the file previously exists, it will be overwritten.
Returns true if writing was successful, otherwise false.

fileLen(filename) (= int)

Returns the length of a file in bytes.

fileExists(filename) (= boolean)

Tests whether a file exists.

fileDelete(filename) (= boolean)

Deletes a file.
Returns true if deleting was successful, otherwise false.

shellExecute(cmd[, fork]) (= int)

Executes a shell command. If fork remains unspecified or is false, this waits until the onvoked application exits and the corresponding return-code is delivered as result. If fork is true, this returns immediately after spawning the shell-command and returns 0.

panic()

Send full range of notes-off events to all channels on all devices.

Objects

An interface to Frinika's currently loaded project is given some top-level objects.

Song

The song object represents the current project from which the script is run (called "song", although not every piece of acoustic material created with a Frinika will of course necessarily be song). Type values are: MIDI = 1, AUDIO = 2, TEXT = 4.

Object Variables

song.filename (read-only)

song.beatsPerMinute

song.ticksPerBeat (read-only)

song.lanes[] (read-only)

song.lanes[x].name (read-only)

song.lanes[x].type (read-only)

song.lanes[x].parts[] (read-only)

song.lanes[x].parts[x].name (read-only)

song.lanes[x].parts[x].type (read-only)

song.lanes[x].parts[x].events[] (read-only)

song.lanes[x].parts[x].notes[] (read-only)

song.lanes[x].parts[x].controllers[] (read-only)

song.lanes[x].parts[x].sysex[] (read-only)

song.lanes[x].parts[x].ghost (read-only)

Object Functions

song.play()

song.playUntil(tick)

song.stop()

song.save()

song.newLane(name, type)

song.getLane(name) (= lane)

song.lane[x].remove()

song.lane[x].newPart(tick, duration)

song.lane[x].newPartOfType(tick, duration, type)

song.lane[x].part[y].remove()

song.createNew()

Selection

The selection object represents the current selection inside Frinika's project at the time when the script is run.

Object Variables

selection.events[]

Array of all currently selected events. Usually, a script will not use this because it will be interested i events of a certain type only.

selection.notes[]

Array of currently selected Midi notes. If no notes are selected, the array has 0 entries. Typically, a set of selected notes can be changed in a loop like this: for (i = 0; i < selection.notes.length; i++) { selection.notes[i].note = ... selection.notes[i].velocity = ... selection.notes[i].duration = ... selection.notes[i].startTick = ... } Note that notes from the selection-object may be changed by a script as in the above example (while those accessed via song.lane[x].part[y].note[z] are read-only).

selection.controllers[]

Array of currently selected Midi controllers. If no controllers are selected, the array has 0 entries.

selection.sysex[]

Array of currently selected Midi system exclusive events. If no system exclusive events are selected, the array has 0 entries.

Object Functions

selection.clear()

Clears the current selections so that no elements remain selected afterwards.

Menu

The menu object represents the menu-bar of Frinika's project- window.

Object Variables

menu[menuIndex][itemIndex]

menu[a][b].label (read-only)

Object Functions

menu[x][y].execute()

Persistent

The persistent object allows to store values that will be saved together with the project.

Object Functions

persistent.put(key, value)

persistent.get(key)

Global

The global object allows to store values that will be saved in the user's homedir as file .frinika-script-global.properties. These values can be shared across project, i.e. one project can set a value, another project can read it.
Note that setting a value is a costy operation (will cause file-write with each put-operation).

Object Functions

global.put(key, value)

global.get(key)

Author:
Jens Gulden
See Also:
Serialized Form

Nested Class Summary
 class JavascriptScope.Lane
           
 class JavascriptScope.Menu
           
 class JavascriptScope.Part
           
 class JavascriptScope.PropertiesWrapper
           
 class JavascriptScope.Selection
           
 class JavascriptScope.Song
           
 
Field Summary
 java.lang.Object global
           
 java.lang.Object[][] menu
           
 java.lang.Object persistent
           
 java.lang.Object selection
           
 java.lang.Object song
           
static int TYPE_AUDIO
           
static int TYPE_MIDI
           
static int TYPE_TEXT
           
static int TYPE_UNKNOWN
           
 
Fields inherited from class org.mozilla.javascript.ScriptableObject
CONST, DONTENUM, EMPTY, PERMANENT, READONLY, UNINITIALIZED_CONST
 
Fields inherited from interface org.mozilla.javascript.Scriptable
NOT_FOUND
 
Constructor Summary
JavascriptScope(org.mozilla.javascript.Context context, ProjectFrame frame, java.util.SortedSet<MultiEvent> events, ScriptingDialog dialog)
          Createsa a JavascriptContext.
 
Method Summary
 void _wait(int ms)
           
 boolean confirm(java.lang.String s)
           
 void error(java.lang.String s)
           
 boolean fileDelete(java.lang.String filename)
           
 boolean fileExists(java.lang.String filename)
           
 int fileLen(java.lang.String filename)
           
 java.lang.String fileRead(java.lang.String filename)
           
 boolean fileWrite(java.lang.String filename, java.lang.String data)
           
 java.lang.String formatTime(int ticks)
           
 java.lang.String getClassName()
           
protected  void initMenu()
           
 void message(java.lang.String s)
           
 int note(java.lang.String name)
           
 java.lang.String noteName(int note)
           
 void panic()
           
 void print(java.lang.String s)
           
 void println(java.lang.String s)
           
 java.lang.String prompt(java.lang.String s)
           
 java.lang.String promptFile(java.lang.String defaultFilename, java.lang.String suffices, boolean saveMode)
           
 int shellExecute(java.lang.String cmd, boolean fork)
           
 int time(java.lang.String s)
           
 int type(java.lang.String name)
           
 java.lang.String typeName(int type)
           
 void waitTicks(int ticks)
           
 
Methods inherited from class org.mozilla.javascript.ScriptableObject
associateValue, avoidObjectDetection, callMethod, callMethod, defineClass, defineClass, defineClass, defineConst, defineConstProperty, defineFunctionProperties, defineProperty, defineProperty, defineProperty, defineProperty, delete, delete, deleteProperty, deleteProperty, equivalentValues, get, get, getAllIds, getAssociatedValue, getAttributes, getAttributes, getAttributes, getAttributes, getClassPrototype, getDefaultValue, getDefaultValue, getFunctionPrototype, getGetterOrSetter, getIds, getObjectPrototype, getParentScope, getProperty, getProperty, getPropertyIds, getPrototype, getTopLevelScope, getTopScopeValue, has, has, hasInstance, hasProperty, hasProperty, isConst, isGetterOrSetter, isSealed, put, put, putConst, putConstProperty, putProperty, putProperty, redefineProperty, sealObject, setAttributes, setAttributes, setAttributes, setAttributes, setGetterOrSetter, setParentScope, setPrototype
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

TYPE_UNKNOWN

public static final int TYPE_UNKNOWN
See Also:
Constant Field Values

TYPE_MIDI

public static final int TYPE_MIDI
See Also:
Constant Field Values

TYPE_AUDIO

public static final int TYPE_AUDIO
See Also:
Constant Field Values

TYPE_TEXT

public static final int TYPE_TEXT
See Also:
Constant Field Values

song

public java.lang.Object song

selection

public java.lang.Object selection

menu

public java.lang.Object[][] menu

persistent

public java.lang.Object persistent

global

public java.lang.Object global
Constructor Detail

JavascriptScope

public JavascriptScope(org.mozilla.javascript.Context context,
                       ProjectFrame frame,
                       java.util.SortedSet<MultiEvent> events,
                       ScriptingDialog dialog)
Createsa a JavascriptContext. This is a bridge between JavaScript and Java, application-specific to Frinika.

Parameters:
frame -
events -
Method Detail

getClassName

public java.lang.String getClassName()
Specified by:
getClassName in interface org.mozilla.javascript.Scriptable
Specified by:
getClassName in class org.mozilla.javascript.ScriptableObject

print

public void print(java.lang.String s)

println

public void println(java.lang.String s)

message

public void message(java.lang.String s)

error

public void error(java.lang.String s)

confirm

public boolean confirm(java.lang.String s)

prompt

public java.lang.String prompt(java.lang.String s)

promptFile

public java.lang.String promptFile(java.lang.String defaultFilename,
                                   java.lang.String suffices,
                                   boolean saveMode)

time

public int time(java.lang.String s)

formatTime

public java.lang.String formatTime(int ticks)

_wait

public void _wait(int ms)

waitTicks

public void waitTicks(int ticks)

type

public int type(java.lang.String name)

typeName

public java.lang.String typeName(int type)

note

public int note(java.lang.String name)

noteName

public java.lang.String noteName(int note)

fileRead

public java.lang.String fileRead(java.lang.String filename)

fileWrite

public boolean fileWrite(java.lang.String filename,
                         java.lang.String data)

fileLen

public int fileLen(java.lang.String filename)

fileExists

public boolean fileExists(java.lang.String filename)

fileDelete

public boolean fileDelete(java.lang.String filename)

panic

public void panic()

shellExecute

public int shellExecute(java.lang.String cmd,
                        boolean fork)

initMenu

protected void initMenu()