From 107d1a1496f766fad5ec7047e752dbcf88056544 Mon Sep 17 00:00:00 2001 From: Paris Date: Sun, 19 Jun 2016 22:02:20 +0300 Subject: [PATCH] First chunk of documentation --- src/xterm.js | 132 ++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 93 insertions(+), 39 deletions(-) diff --git a/src/xterm.js b/src/xterm.js index 8633ff9..2b00b3d 100644 --- a/src/xterm.js +++ b/src/xterm.js @@ -149,6 +149,8 @@ * - cursorBlink (boolean): Whether the terminal cursor blinks * * @public + * @class Xterm Xterm + * @alias module:xterm/src/xterm */ function Terminal(options) { var self = this; @@ -314,7 +316,12 @@ inherits(Terminal, EventEmitter); - // back_color_erase feature for xterm. + /** + * + * back_color_erase feature for xterm. + * + * @public + */ Terminal.prototype.eraseAttr = function() { // if (this.is('screen')) return this.defAttr; return (this.defAttr & ~0x1ff) | (this.curAttr & 0x1ff); @@ -480,6 +487,8 @@ /** * Initialize default behavior + * + * @public */ Terminal.prototype.initGlobal = function() { Terminal.bindKeys(this); @@ -584,8 +593,11 @@ }; - /* + /** * Apply key handling to the terminal + * + * @param {Xterm} term The terminal on which to bind key handling + * @static */ Terminal.bindKeys = function(term) { on(term.element, 'keydown', function(ev) { @@ -637,7 +649,9 @@ }; /** - * Cancel the cut event completely + * Cancel the cut event completely. + * @param {Xterm} term The terminal on which to bind the cut event handling functionality. + * @static */ Terminal.bindCut = function(term) { on(term.element, 'cut', function (ev) { @@ -646,31 +660,34 @@ }; + /** + * Do not perform the "drop" event. Altering the contents of the + * terminal with drag n drop is unwanted behavior. + * @param {Xterm} term The terminal on which to bind the drop event handling functionality. + * @static + */ Terminal.bindDrop = function (term) { - /* - * Do not perform the "drop" event. Altering the contents of the - * terminal with drag n drop is unwanted behavior. - */ on(term.element, 'drop', function (ev) { term.cancel(ev, true); }); }; - + /** + * Cancel click handling on the given terminal + * @param {Xterm} term The terminal on which to bind the click event handling functionality. + * @static + */ Terminal.click = function (term) { - /* - * Do not perform the "drop" event. Altering the contents of the - * terminal with drag n drop is unwanted behavior. - */ on(term.element, 'click', function (ev) { term.cancel(ev, true); }); }; - /* + /** * Insert the given row to the terminal or produce a new one * if no row argument is passed. Return the inserted row. + * @param {HTMLElement} row (optional) The row to append to the terminal. */ Terminal.prototype.insertRow = function (row) { if (typeof row != 'object') { @@ -688,7 +705,6 @@ * Opens the terminal within an element. * * @param {HTMLElement} parent The element to create the terminal within. - * * @public */ Terminal.prototype.open = function(parent) { @@ -808,22 +824,19 @@ }; - // XTerm mouse events - // http://invisible-island.net/xterm/ctlseqs/ctlseqs.html#Mouse%20Tracking - // To better understand these - // the xterm code is very helpful: - // Relevant files: - // button.c, charproc.c, misc.c - // Relevant functions in xterm/button.c: - // BtnCode, EmitButtonCode, EditorButton, SendMousePosition + /** + * XTerm mouse events + * http://invisible-island.net/xterm/ctlseqs/ctlseqs.html#Mouse%20Tracking + * To better understand these + * the xterm code is very helpful: + * Relevant files: + * button.c, charproc.c, misc.c + * Relevant functions in xterm/button.c: + * BtnCode, EmitButtonCode, EditorButton, SendMousePosition + */ Terminal.prototype.bindMouse = function() { - var el = this.element - , self = this - , pressed = 32; - - var wheelEvent = 'onmousewheel' in this.context - ? 'mousewheel' - : 'DOMMouseScroll'; + var el = this.element, self = this, pressed = 32; + var wheelEvent = ('onmousewheel' in this.context) ? 'mousewheel' : 'DOMMouseScroll'; // mouseup, mousedown, mousewheel // left click: ^[[M 3<^[[M#3< @@ -1149,7 +1162,6 @@ /** * Destroys the terminal. - * * @public */ Terminal.prototype.destroy = function() { @@ -1196,8 +1208,6 @@ * @param {number} start The row to start from (between 0 and terminal's height terminal - 1) * @param {number} end The row to end at (between fromRow and terminal's height terminal - 1) * @param {boolean} queue Whether the refresh should ran right now or be queued - * - * @public */ Terminal.prototype.refresh = function(start, end, queue) { var self = this; @@ -1400,6 +1410,9 @@ this.emit('refresh', {element: this.element, start: start, end: end}); }; + /** + * Display the cursor element + */ Terminal.prototype.showCursor = function() { if (!this.cursorState) { this.cursorState = 1; @@ -1407,6 +1420,9 @@ } }; + /** + * Scroll the terminal + */ Terminal.prototype.scroll = function() { var row; @@ -1447,6 +1463,10 @@ this.updateRange(this.scrollBottom); }; + /** + * Scroll the display of the terminal + * @param {number} disp + */ Terminal.prototype.scrollDisp = function(disp) { this.ydisp += disp; @@ -1461,10 +1481,7 @@ /** * Writes text to the terminal. - * * @param {string} text The text to write to the terminal. - * - * @public */ Terminal.prototype.write = function(data) { var l = data.length, i = 0, j, cs, ch, code, low, ch_width, row; @@ -2513,12 +2530,20 @@ this.refresh(this.refreshStart, this.refreshEnd); }; + /** + * Writes text to the terminal, followed by a break line character (\n). + * @param {string} text The text to write to the terminal. + */ Terminal.prototype.writeln = function(data) { this.write(data + '\r\n'); }; - // Key Resources: - // https://developer.mozilla.org/en-US/docs/DOM/KeyboardEvent + /** + * Handle a keydown event + * Key Resources: + * - https://developer.mozilla.org/en-US/docs/DOM/KeyboardEvent + * @param {KeyboardEvent} ev The keydown event to be handled. + */ Terminal.prototype.keyDown = function(ev) { var self = this; var result = this.evaluateKeyEscapeSequence(ev); @@ -2554,6 +2579,7 @@ * returned value is the new key code to pass to the PTY. * * Reference: http://invisible-island.net/xterm/ctlseqs/ctlseqs.html + * @param {KeyboardEvent} ev The keyboard event to be translated to key escape sequence. */ Terminal.prototype.evaluateKeyEscapeSequence = function(ev) { var result = { @@ -2742,11 +2768,20 @@ return result; }; + /** + * Set the G level of the terminal + * @param g + */ Terminal.prototype.setgLevel = function(g) { this.glevel = g; this.charset = this.charsets[g]; }; + /** + * Set the charset for the given G level of the terminal + * @param g + * @param charset + */ Terminal.prototype.setgCharset = function(g, charset) { this.charsets[g] = charset; if (this.glevel === g) { @@ -2754,6 +2789,12 @@ } }; + /** + * Handle a keypress event. + * Key Resources: + * - https://developer.mozilla.org/en-US/docs/DOM/KeyboardEvent + * @param {KeyboardEvent} ev The keypress event to be handled. + */ Terminal.prototype.keyPress = function(ev) { var key; @@ -2793,6 +2834,10 @@ return false; }; + /** + * Send data for handling to the terminal + * @param {string} data + */ Terminal.prototype.send = function(data) { var self = this; @@ -2806,6 +2851,10 @@ this.queue += data; }; + /** + * Ring the bell. + * Note: We could do sweet things with webaudio here + */ Terminal.prototype.bell = function() { if (!this.visualBell) return; var self = this; @@ -2816,6 +2865,9 @@ if (this.popOnBell) this.focus(); }; + /** + * Log the current state to the console. + */ Terminal.prototype.log = function() { if (!this.debug) return; if (!this.context.console || !this.context.console.log) return; @@ -2823,6 +2875,9 @@ this.context.console.log.apply(this.context.console, args); }; + /** + * Log the current state as error to the console. + */ Terminal.prototype.error = function() { if (!this.debug) return; if (!this.context.console || !this.context.console.error) return; @@ -2835,8 +2890,6 @@ * * @param {number} x The number of columns to resize to. * @param {number} y The number of rows to resize to. - * - * @public */ Terminal.prototype.resize = function(x, y) { var line @@ -4868,5 +4921,6 @@ Terminal.off = off; Terminal.cancel = cancel; + return Terminal; }); -- 2.39.5