# Usage
## Command line
Usage: DOjS.EXE [-r] [-s <p>:<i>:<d>] <script>
    -r             : Do not invoke the editor, just run the script.
    -w <width>     : Screen width: 320 or 640, Default: 640.
    -b <bbp>       : Bit per pixel:8, 16, 24, 32. Default: 24.
    -s <p>:<i>:<d> : Override sound card detection with given values.
                        p := Port (220h - 280h).
                        i := IRQ  (2 - 11).
                        d := DMA  (0 - 7).
                        Example: -s 220:5:1

## Editor keys
    F1  : Open/Close help
    F3  : Save script
    F4  : Run script
    F7  : Find text
    F9  : Show/Close logfile
    F10 : Quit

    Shift-F7   : Find again
    CTRL-D     : Delete current line
    CTRL-LEFT  : Previous word
    CTRL-RIGHT : Next word
    PAGE-UP    : One page up.
    PAGE-DOWN  : One page down.
    HOME       : Go to start of line
    END        : Go to end of line
    CTRL-HOME  : Go to start of line
    CTRL-END   : Go to end of line

    TAB size is 4.
    The help viewer will remember the current position.

    The logfile can be truncated by pressing DEL in the log viewer.

# JS API description
A very minimal API documentation.

## Script format
Scripts need to provide three functions: `Setup()`, `Loop()` and `Input()`. Scripts are loaded and executed top-own. After that `Setup()` is called once and then `Loop()` repeatedly. `Input()` is called whenever mouse of keyboard input happens.

### Setup()
This function is called once at startup. It can initialize variables, setup hardware, etc.

### Loop()
This function is called after setup repeatedly until `Stop()` is called. After calling `Stop()` the program ends when `Loop()` exits.

### Input(event: {x:number, y:number, flags:number, buttons:number, key:number, kbstat:number, dtime:number})
This function is called whenever mouse/keyboard input happens. The parameter is an event object with the following fields: `{x:number, y:number, flags:number, buttons:number, key:number, kbstat:number, dtime:number}`. The definitions for the `flags` and `key` field can be found in `jsboot/func.js`.

## File
### f = new File(filename:string, mode:string)
Open a file, for file modes see `jsboot/file.js`. Files can only either be read or written, never both. Writing to a closed file throws an exception.

### f.ReadByte():number
Read a single byte from file and return it as number.

### f.WriteByte(ch:number)
Write a single byte to a file.

### f.ReadLine():string
Read a line of text from file. The maximum line length is 4096 byte.

### f.WriteLine(txt:string)
Write a NEWLINE terminated string to a file.

### f.WriteString(txt:string)
Write a string to a file.

### f.Close()
Close the file.

## IPX networking
DOjS supports IPX networking. Node addresses are arrays of 6 numbers between 0-255. Default socket number and broadcast address definitions can be found in `jsboot/ipx.js`.

### IpxSocketOpen(num:number)
Open an IPX socket.

### IpxSocketClose()
Close IPX socket (if any).

### IpxSendPacket(data:string, dest:array[6:number])
Send packet via IPX. Max length 79 byte.

### IpxCheckPacket():boolean
Check for packet in receive buffer.

### IpxGetPacket():{data:string, source:array[6:number]}
Get packet from receive buffer (or NULL).

### IpxGetLocalAddress():array[6:number]
Get the local address.

## Color
See `jsboot/color.js` for predefined EGA colors. Use `NO_COLOR` for the transparent color.

### c = new Color(red:number, green:number, blue:number[, mask:number])
Create a RGB color with optional mask (see `jsboot/color.js`).

### c.value
24bit value with the actual color

### c.GetRed()
get the red part of a color.

### c.GetGreen()
get the green part of a color.

### c.GetBlue()
get the blue part of a color.

## Bitmap
### bm = new Bitmap(filename:string)
Load a BMP or PNG image.

### bm.filename
Name of the file.

### bm.width
Width in pixels

### bm.height
Height in pixels

### bm.Draw(x:number, y:number)
Draw the image to the canvas at given coordinates.

## Font
See `jsboot/font.js` for direction and alignment values.

### f = new Font(filename:string)
Load a .FNT file for GRX.

### f.filename
Name of the FNT file.

### f.minwidth
Width of smallest character

### f.maxwidth
Width of widest character

### f.DrawString(x:number, y:number, text:string, foreground:Color, background: Color, direction:number, alignX:number, alignY:number)
Draw a string to the canvas.

### f.StringWidth(text:string):number
Calculate string width for this font.

### f.StringHeight(text:string):number
Calculate string height for this font.

### f.Resize(w:number, h:number)
Resize font to new width/height.

## Midi
### mid = new Midi(filename:string)
Load a midi file.

### mid.Play()
Play the midi file.

### MidiIsPlaying():boolean
Check if the file is still playing

### MidiStop()
Stop playing midi.

## Sound
### snd = new Sound(filename:string)
Load a WAV (11025Hz, 8bit, mono). Different sample rates are accepted (and create a warning in the log), but are not converted and will sound weird.

### snd.filename
Name of the WAV

### snd.length
Sound length.

### snd.format
Sound format.

### snd.channels
Number of channels.

### snd.rate
Sampling rate.

### snd.num_bits
Number of bits/sample.

### snd.Play()
Play the WAV once.

## FM Music
See `jsboot/fmmusic.js` for pre-defined instruments and notes.

### SetInstrument(voice:number, instrument:object)
Convert the contents of a JS object into an instrument and set the parameters to the given voice.

### NoteOn(voice:number, note:number, octave: number)
Start playing a note.

### NoteOff(voice:number, note:number, octave: number)
Stop playing a note.

## GRX Drawing functions
Please take a look a the GRX [documentation](http://grx.gnu.de/grx249um.html) for details of the drawing functions.
See `jsboot/func.js` for constants.

### NumColors():number
Get number of possible colors.

### NumFreeColors():number
Get number of remaining free colors.

### SizeX():number
get the width of the drawing area.

### SizeY():number
get the height of the drawing area.

### MaxX():number
get the max X coordinate on the drawing area.

### MaxY():number
get the max Y coordinate on the drawing area.

### ClearScreen(c:Color)
clear the screen with given color.

### Plot(x:number, y:number, c:Color)
draw a point.

### Line(x1:number, y1:number, x2:number, y2:number, c:Color)
draw a line.

### Box(x1:number, y1:number, x2:number, y2:number, c:Color)
draw a box.

### Circle(x1:number, y1:number, r:number, c:Color)
draw a circle.

### Ellipse(xc:number, yc:number, xa:number, ya:number, c:Color)
draw an ellipse.

### CircleArc(x:number, y:number, r:number, start:number, end:number, style:number, c:Color):{"centerX":XXX,"centerY":XXX,"endX":XXX,"endY":XXX,"startX":XXX,"startY":XXX}
Draw a circle arc. Returns an object with coordinates of the drawn arc: `{"centerX":XXX,"centerY":XXX,"endX":XXX,"endY":XXX,"startX":XXX,"startY":XXX}`.

### EllipseArc(xc:number, yc:number, xa:number, ya:number, start:number, end:number, style:number, c:Color):{"centerX":XXX,"centerY":XXX,"endX":XXX,"endY":XXX,"startX":XXX,"startY":XXX}
Draw an ellipse arc. Returns an object with coordinates of the drawn arc: `{"centerX":XXX,"centerY":XXX,"endX":XXX,"endY":XXX,"startX":XXX,"startY":XXX}`.

### FilledBox(x1:number, y1:number, x2:number, y2:number, c:Color)
draw a filled box.

### FramedBox(x1:number, y1:number, x2:number, y2:number, wdt:number, [intcolor:Color, topcolor:Color, rightcolor:Color, bottomcolor:Color, leftcolor:Color])
draw a framed box (3D effect box). The last parameter is an array with the colors to use for the borders.

### FilledCircle(x1:number, y1:number, r:number, c:Color)
draw a filled circle.

### FilledEllipse(xc:number, yc:number, xa:number, ya:number, c:Color)
draw an ellipse.

### FilledCircleArc(x:number, y:number, r:number, start:number, end:number, style:number, c:Color):{"centerX":XXX,"centerY":XXX,"endX":XXX,"endY":XXX,"startX":XXX,"startY":XXX}
Draw a filled circle arc. Returns an object with coordinates of the drawn arc: `{"centerX":XXX,"centerY":XXX,"endX":XXX,"endY":XXX,"startX":XXX,"startY":XXX}`.

### FilledEllipseArc(xc:number, yc:number, xa:number, start:number, end:number, style:number, c:Color):{"centerX":XXX,"centerY":XXX,"endX":XXX,"endY":XXX,"startX":XXX,"startY":XXX}
Draw a filled ellipse arc. Returns an object with coordinates of the drawn arc: `{"centerX":XXX,"centerY":XXX,"endX":XXX,"endY":XXX,"startX":XXX,"startY":XXX}`.

### FloodFill(x:number, y:number, border:Color, c:Color)
do a flood fill.

### FloodSpill(x1:number, y1:number, x2:number, y2:number, border:Color, c:Color)
do a flood spill.

### FloodSpill2(x1:number, y1:number, x2:number, y2:number, old1:Color, new1:Color, old2:Color, new2:Color)
do a flood spill2.

### PolyLine([[x1, x2], [..], [xN, yN]], c:Color)
draw a polyline.

### Polygon([[x1, x2], [..], [xN, yN]], c:Color)
draw a polygon.

### FilledPolygon([[x1, x2], [..], [xN, yN]], c:Color)
draw a filled polygon.

### FilledConvexPolygon([[x1, x2], [..], [xN, yN]], c:Color)
draw a filled convex polygon.

### MouseSetSpeed(spmul:number, spdiv:number)
set mouse speed

### MouseSetAccel(thresh:number, accel:number)
set mouse acceleration

### MouseSetLimits(x1:number, y1:number, x2:number, y2:number)
set mouse limits

### MouseGetLimits():{"x1":XXX, "y1":XXX, "x2":XXX, "y2":XXX}
get mouse limits

### MouseWarp(x:number, y:number)
move mouse cursor

### MouseShowCursor(b:boolean)
show hide mouse cursor

### MouseCursorIsDisplayed():boolean
check if the cursor is visible

### MouseSetColors(fg:Color, bg:Color)
Set mouse pointer colors.

## MouseSetCursorMode(mode:int, ...)
change mode of the cursor.
`MouseSetCursorMode(MOUSE.Mode.NORMAL)` or
`MouseSetCursorMode(MOUSE.Mode.RUBBER,xanchor,yanchor,GrColor)` or
`MouseSetCursorMode(MOUSE.Mode.LINE,xanchor,yanchor,GrColor)` or
`MouseSetCursorMode(MOUSE.Mode.BOX,dx1,dy1,dx2,dy2,GrColor)`

### TextXY(x:number, y:number, text:string, fg:Color, bg:Color)
Draw a text with the default font.

### SaveBmpImage(fname:string)
Save current screen to file.

### SavePngImage(fname:string)
Save current screen to file.

## Other functions/properties
### SOUND_AVAILABLE: boolean
`true` if WAV sound is available.

### SYNTH_AVAILABLE: boolean
`true` if FM sound is available.

### MOUSE_AVAILABLE: boolean
`true` if mouse is available.

### MIDI_AVAILABLE: boolean
`true` if midi is available.

### Print(a, ...)
Write data to `JSLOG.TXT` logfile.

### Println(a, ...)
Write data to `JSLOG.TXT` logfile.

### Stop()
DOjS will exit after the current call to `Loop()`.

### Sleep(ms:number)
Sleep for the given number of ms.

### Read(filename:string):string
Load the contents of a file into a string.

### List(dname:string):[f1:string, f1:string, ...]
Get directory listing.

### Stat(name:string):{"atime":string,"blksize":number,"ctime":string,"drive":string,"is_blockdev":bool,"is_chardev":bool,"is_directory":bool,"is_regular":bool,"mtime":string,"nlink":number,"size":number}
Get information about a file/directory.

### Require(filename:string):module
Used to load a module. The functions exported from this module can be accessed using the returned value.

### Gc(info:boolean)
Run garbage collector, print statistics to logfile if `info==true`.

### MemoryInfo():{"used":XXX, "available":XXX}
Get memory statistics.

### SetFramerate(rate:number)
Set maximum frame rate. If `Loop()` takes longer than `1/rate` seconds then the framerate will not be reached.

### GetFramerate():number
Current frame rate.

### SetExitKey(key:number)
Change the exit key from ESCAPE to any other keycode from `jsboot/func.js`.

### CharCode(c:string)
Can be used to obtain the key code for `SetExitKey()` for a character, e.g. `SetExitKey(CharCode('q'))`.
