Termlib

**** mass:werk termlib.js - JS-WebTerminal Object v1.66 ****

(c) Norbert Landsteiner 2003-2015 mass:werk - media environments http://www.masswerk.at

COMPATIBILITY WARNING

Dropped support of Netscape 4 (layers) with version 1.5! Netscape 4 is now outdated for more than 10 years. Any further support of this browser would be of academic nature. As a benefit this step allows us to include the socket extension in the main library, so there are no additional files to load anymore.

For the first time there is a backward compatibility issue from version 1.3 to version 1.4: The following applies to the style vector for the `type()' method while using colors:

while with version 1.3 a color was encoded using the color code times 16 (0xf), e.g.:

  myTerm.type( 'This is red.', 2*16 );

this changed with version 1.4 to the color code times 256 (0xff), e.g.:

  myTerm.type( 'This is red.', 2*256 );

All other style encodings or color API remain unchanged. Since this feature was only introduced in version 1.3 and there are no known applications that would use a statement like the above (since you would usually use the `write()' method for complex output), this seems to be good bargain for some codes for custom styles. C.f.: sect 7.5 "TermGlobals.assignStyle()"

Mac OS X Dead-Keys

(Dead-keys: combinations of accents and characters that are built by two consecutively pressed keys.) Mac OS X 10.5 and later doesn't fire a keyboard event for dead keys anymore. It's possible to fix this for Safari by a custom dead keys emulation, but not for Chrome or Firefox. "termlib.js" provides automatic translations of common dead-keys for Safari in German (de-de). In case you would need dead-keys for another language, please contact me via http://www.masswerk.at/.

Contents:

1 About 2 Creating a new Terminal Instance 2.1 Configuration Values 3 Using the Terminal 3.1 The Default Handler 3.2 Input Modes 3.2.1 Normal Line Input (Command Line Mode) 3.2.1.2 Special Keys (ctrlHandler) 3.2.2 Raw Mode 3.2.3 Character Mode 3.3 Other Handlers 3.3.1 initHandler 3.3.2 exitHandler 3.4 Flags for Behaviour Control 4 Output Methods 4.1 Terminal.type() 4.2 Terminal.write() 4.3 Terminal.typeAt() 4.4 Terminal.setChar() 4.5 Terminal.newLine() 4.6 Terminal.clear() 4.7 Terminal.statusLine() 4.8 Terminal.printRowFromString() 4.9 Terminal.redraw() 4.10 Using Color 4.11 Text Wrap - Terminal.wrapOn(), Terminal.wrapOff() 4.12 ANSI Support 5 Cursor Methods and Editing 5.1 Terminal.cursorOn() 5.2 Terminal.cursorOff() 5.3 Terminal.cursorSet() 5.4 Terminal.cursorLeft() 5.5 Terminal.cursorRight() 5.6 Terminal.backspace() 5.7 Terminal.fwdDelete() 5.8 Terminal.isPrintable() 6 Other Methods of the Terminal Object 6.1 Terminal.prompt() 6.2 Terminal.reset() 6.3 Terminal.open() 6.4 Terminal.close() 6.5 Terminal.focus() 6.6 Terminal.moveTo() 6.7 Terminal.resizeTo() 6.8 Terminal.getDimensions() 6.9 Terminal.rebuild() 6.10 Terminal.backupScreen() 6.11 Terminal.restoreScreen() 6.12 Terminal.swapBackup() 6.13 Terminal.setTextColor() 6.14 Terminal.setTextBlur() 7 Global Static Methods (TermGlobals) 7.1 TermGlobals.setFocus() 7.2 TermGlobals.keylock (Global Locking Flag) 7.3 TermGlobals Text Methods 7.3.1 TermGlobals.normalize() 7.3.2 TermGlobals.fillLeft() 7.3.3 TermGlobals.center() 7.3.4 TermGlobals.stringReplace() 7.4 TermGlobals Import Methods 7.4.1 TermGlobals.insertText() 7.4.2 TermGlobals.importEachLine() 7.4.3 TermGlobals.importMultiLine() 7.5 TermGlobals.assignStyle() 8 Localization 9 The Socket Extension (Remote Communication) 9.1 A First Example 9.2 The send() API 9.3 Global Config Settings 9.4 The Callback (Response Handling) 9.5 Error Codes 9.6 Note on Compatibly / Browser Requirements 9.7 termlib_socket.js Version History 10 Cross Browser Functions 11 Architecture, Internals 11.1 Global Entities 11.2 I/O Architecture 11.3 Compatibility 12 History 13 Example for a Command Line Parser 14 License 15 Disclaimer 16 Donations 17 References

1 About

The Terminal library "termlib.js" provides an object oriented constructor and control methods for a terminal-like DHTML interface.

"termlib.js" features direct keyboard input and powerful output methods for multiple instances of the `Terminal' object (including focus control). "termlib.js" also comprises methods for a transparent handling of client-server com- munications via XMLHttpRequests (see sect. 9 "The Socket Extension").

The library was written with the aim of simple usage and a maximum of compatibility with minimal foot print in the global namespace.

A simple example:

// creating a terminal and using it

var term = new Terminal( {handler: termHandler} ); term.open();

function termHandler() { var line = this.lineBuffer; this.newLine(); if (line == "help") { this.write(helpPage) } else if (line == "exit") { this.close(); return; } else if (line != "") { this.write("You typed: "+line); } this.prompt(); }

var helpPage = [ "This is the monstrous help page for my groovy terminal.", "Commands available:", " help ... print this monstrous help page", " exit ... leave this groovy terminal", " ", "Have fun!" ];

You should provide CSS font definitions for the classes ".term" (normal video) and ".termReverse" (reverse video) in a monospaced font. A sample stylesheet "term_styles.css" comes with this library.

See the sample application "multiterm_test.html" for a demo of multiple terminals.

v.1.01: If you configure to use another font class (see 2.1 Configuration Values), you must provide a subclass ".termReverse" for reversed video.

    p.e.: .myFontClass .termReverse {
            /* your definitions for reverse video here */
          }
    
    With the addition of `conf.fontClass' you can now create multiple
    instances with independend appearences.

2 Creating a new Terminal Instance

Use the new' constructor to create a new instance of the Terminal object. You will want to supply a configuration object as an argument to the constructor. If the new' constructor is called without an object as its first argument, default values are used.

p.e.:

// creating a new instance of Terminal

var conf= { x: 100, y: 100, cols: 80, rows: 24 }

var term = new Term(conf); term.open();

`Terminal.open()' initializes the terminal and makes it visible to the user. This is handled in by separate method to allow the re-initilization of instances previously closed.

NOTE: The division or HTML-element that holds the terminal must be present when calling `Terminal.open()'. So you must not call this method from the header of a HTML-document at compile time.

2.1 Configuration Values

Set any of these values in your configuration object to override:

LABEL DEFAULT VALUE COMMENT

x 100 terminal's position x in px y 100 terminal's position y in px termDiv 'termDiv' id of terminals CSS division bgColor '#181818' background color (HTML hex value) frameColor '#555555' frame color (HTML hex value) frameWidth 1 frame border width in px fontClass 'term' class name of CSS font definition to use cols 80 number of cols per row rows 24 number of rows rowHeight 15 a row's line-height in px blinkDelay 500 delay for cursor blinking in milliseconds crsrBlinkMode false true for blinking cursor crsrBlockMode true true for block-cursor else underscore DELisBS false handle <DEL> as <BACKSPACE> printTab true handle <TAB> as printable (prints as space) printEuro true handle unicode 0x20AC (Euro sign) as printable catchCtrlH true handle ^H as <BACKSPACE> closeOnESC true close terminal on <ESC> historyUnique false prevent consecutive and identical entries in history id 0 terminal id ps '>' prompt string greeting '%+r Terminal ready. %-r' string for greeting if no initHandler is used handler defaultHandler reference to handler for command interpretation ctrlHandler null reference to handler called on uncatched special keys initHandler null reference to handler called at end of init() exitHandler null reference to handler called on close() wrapping false text wrapping for `write()' on/off mapANSI false enable mapping of ANSI escape sequences (SGR