Project nJES-lib (not-JES)

Purpose: to create a replacement module for JES (Jython Environment for Students) written in
CPython that, in addition to being 100% compatible with pre-existing JES code without modification,
exposes additional functionality at the same time (e.g.: image/pixel alphas, non-blocking sounds, etc..).

Reason: Anyone who has used JES for any period of time will have, without a doubt, immediately
noticed its incredible sluggishness; even the initial startup takes quite a bit of patience. It, therefore, is
the primary goal of this project to create a library that not only enables a user to distribute their
application written in JES without being forced to distribute the entire library, but also in that,
inherently, given that nJES is written in CPython rather than Jython, programs written in JES will
inherently receive immense performance bonuses by simply using nJES instead without requiring any
modification of the JES code thus liberating JES users from their poorly coded, “learning”-oriented,
and all around POS-”academic” native programming environment.

How: nJES will receive its large performance benefit, at a minimum, from CPython being inherently
faster than Jython (in addition to, possibly, better programming practices and more optimized/cleaner
code).

JES anti-thesis: Because nJES will be written in CPython with the highly cross-platform wxPython,
any performance penalty created in the name of cross-platform compatibility will be negated (this is
further amplified by the fact that most students use Windows with JES in any case)

Primary Target Platforms: Windows NT 5.0+, Linux, [and probably Mac OSX]

Coding Conventions:

It would make sense to me if each of the JES's alleged “objects” were actually implemented
internally as such, and then a “wrapper”/“compatibility” library of sorts would be created to wrap JES
functions to nJES methods. This way, depending on what the user wanted, they could either directly
run native JES code, or, optionally, write native nJES code which will allow for dot notations. For
instance, instead of, for example, getPixel(Picture) (native JES), Picture.getPixel() would be legal
nJES (and both conventions would be legal in nJES).

Furthermore, of course, instead of doing something like “from nJES import *” to setup nJES in JES-
compatible mode, a simple “import nJES” would be legal. In that case, object instantiation like wx's
would be possible. Instead of makePicture(path), the nJES convention would be
nJES.makePicture(path), for example (and of course both would be legal at the same time depending
on how nJES was imported).
 Proposed nJES “JES-Compatible” API:

File Manipulation

pickAFile([title])
Creates a dialog allowing the user to pick a file, returning the path of that file upon
confirmation. Specifying a title is optional.

setMediaPath([directory[, title]])
When directory is unspecified, show a dialog allowing the user to set the current working
directory. The dialog is skipped and the directory is set if directory is specified. Specifying a
title is optional.

getMediaPath([filename])
Given the relative filename, if it exists, return the full path (assuming it's relative to the “media
path”). Otherwise, simply return the current working directory.

Picture Manipulation

makePicture(path)
Given the path to a picture, create and return a picture object

makeEmptyPicture(width, height)
Create and return a white picture with the given width and height.

show(picture)
Create a frame showing the given picture object

getPixels(picture)
Given the picture object, return a list of color tuples (RGBA) (“color tuples” will be called
“pixel objects” henceforth) that directly reference the picture object, whose values are not
mutually exclusive.

getPixel(picture, x, y)
Given the picture object and coordinates, return a pixel object whose manipulation is not
independent of the source picture data.

getWidth(picture)
Given the picture object, return it's width

getHeight(picture)
Given the picture object, return its height

writePictureTo(picture, path)
Write a picture to the given path (where the format/container is dependent on the extension
given in the path)

Drawing Primitives
addText(picture, x, y, string)
Draw the string and the given x and y coordinates on the given picture.

addLine(picture, x1, y1, x2, y2)

Draw a line from (x1, y1 ) to (x2, y2 ) on the given picture.

addRect(picture, x1, y1, width, height[, color])

Draw the outline of a rectangle with the given color (defaulting to black) starting at the upper
right hand corner given by (x1, y1) with the given width and height on the given picture.

addRectFilled(picture, x1, y1, width, height, color)

Similar functionality to addRect with the exception that the drawn rectangle is filled rather than
outlined.

Pixel Manipulation

getRed(pixel), getGreen(pixel), getBlue(pixel), setAlpha(pixel)

Given the pixel object, return it's red, green, blue or alpha value, respectively.

setRed(pixel, value), setGreen(pixel, value), setBlue(pixel, value), setAlpha(pixel, value)

Given the pixel object, set it's red, green, blue or alpha value, respectively (leaving other values
untouched.)

getColor(pixel)
Returns the “color” object for the given pixel.

setColor(pixel, color)
Sets the color of the given pixel object.

getX(pixel), getY(pixel)
Return the x or y coordinate, respectively, of the given pixel object.

Color Manipulation

makeColor(red, green, blue[, alpha])

Given the red, green, blue, and alpha values, create a color “object” (possibly just a list of
values internally)

pickAColor()
Displays a color picker, returning the value when closed (blocking).

makeDarker(color), makeLighter(color)
Make the given color darker or lighter (respectively).

Sound Manipulation

makeSound(path)
 Given the path, create and return a sound object.

play(sound)
Play the provided sound object (nonblocking).

blockingPlay(sound)
Similar functionality to the play function, but it instead blocks program execution while the
sound is playing.

getLength(sound)
Return the length of the given sound (the number of indicies/samples).

playAtRate(sound, multiplier)
Play the given sound object, multiplying it's speed AND length by the given multiplier.

playAtRateDur(sound, multiplier, samples)

Play the given sound object up to the number of specified samples, multiplying it's speed by the
given multiplier.

writeSoundTo(sound, filename)
Write the given sound object to the given filename, where the format is dependent on the
extension present in the filename (defaulting to wav when unspecified).

getSamplingRate(sound)
Return the number of samples played per second for the given sound object.

Sample Manipulation

getSampleValueAt(sound, index)
Return the value of the sound object at the given index.

setSampleValueAt(sound, index, value)

Set the given index of the given sound object to the given value.

getSampleObjectAt(sound, index)
Return a sample object from the given sound at the given index with properties such that the
parent sound is mutually dependent on the state of the sample object.

getSampleValue(sample)
Return the value of the given sample object.

setSampleValue(sample, value)
Sets the given sample object to the given value (changing both the sample and the sound from
which it originates.

getSound(sample)
Returns the sound object from which the given sample object is derived.

Sound Primitives
playNote(note, duration[, intensity])
Using the given note, duration, and, optionally, intensity, play the note on the computer's
speaker if a sound object is not specified. If the sound object has already been created, the note
will be appended to the end of the sound, otherwise a new sound object will be created. Note is
a value from 0 to 127 where each note represents a chromatic half-step. Duration is in seconds;
intensity defaults to 64 and ranges from 0 to 127.

appendNote(sound, note, duration[, intensity])

Similar functionality to playNote with the exception that the note, instead of being played on
the computer's speaker, is instead appended to the given sound object (new in nJES).

Misc Functions

printNow(string)
Purpose/implementation is largely unknown; it appears that JES seems to cause normal print
statements to be delayed “until the program finishes executing” for some unusual reason; it is
expected that this have the exact same functionality as python's print builtin.

requestString([title, answer])
Display a dialog box with a text-entry field allowing the user to enter anything, blocking
execution until the user confirms his entry, returning the result. The title is optional; the default
answer can be set optionally as well.

showVars()
Display a dialog box with a list widget displaying all existing variables and their values (how to
implement?)