From 3ba3638ab7ae16c8eb8e6bf2dc1984f7cb155308 Mon Sep 17 00:00:00 2001 From: Daniel Imms Date: Fri, 18 Aug 2017 17:25:40 -0700 Subject: [PATCH] Include all APIs from website --- src/Terminal.ts | 24 +-- typings/xterm.d.ts | 454 +++++++++++++++++++++++++++------------------ 2 files changed, 284 insertions(+), 194 deletions(-) diff --git a/src/Terminal.ts b/src/Terminal.ts index 8edb406d..96aced25 100644 --- a/src/Terminal.ts +++ b/src/Terminal.ts @@ -524,9 +524,10 @@ export class Terminal extends EventEmitter implements ITerminal, IInputHandlingT }; /** - * Blur the terminal. Delegates blur handling to the terminal's DOM element. + * Blur the terminal, calling the blur function on the terminal's underlying + * textarea. */ - private blur(): void { + public blur(): void { return this.textarea.blur(); } @@ -1225,9 +1226,9 @@ export class Terminal extends EventEmitter implements ITerminal, IInputHandlingT /** * Scroll the display of the terminal - * @param {number} disp The number of lines to scroll down (negatives scroll up). + * @param {number} disp The number of lines to scroll down (negative scroll up). * @param {boolean} suppressScrollEvent Don't emit the scroll event as scrollDisp. This is used - * to avoid unwanted events being handled by the veiwport when the event was triggered from the + * to avoid unwanted events being handled by the viewport when the event was triggered from the * viewport originally. */ public scrollDisp(disp: number, suppressScrollEvent?: boolean): void { @@ -1347,12 +1348,13 @@ export class Terminal extends EventEmitter implements ITerminal, IInputHandlingT } /** - * Attaches a custom key event handler which is run before keys are processed, giving consumers of - * xterm.js ultimate control as to what keys should be processed by the terminal and what keys - * should not. - * @param {function} customKeyEventHandler The custom KeyboardEvent handler to attach. This is a - * function that takes a KeyboardEvent, allowing consumers to stop propogation and/or prevent - * the default action. The function returns whether the event should be processed by xterm.js. + * Attaches a custom key event handler which is run before keys are processed, + * giving consumers of xterm.js ultimate control as to what keys should be + * processed by the terminal and what keys should not. + * @param customKeyEventHandler The custom KeyboardEvent handler to attach. + * This is a function that takes a KeyboardEvent, allowing consumers to stop + * propogation and/or prevent the default action. The function returns whether + * the event should be processed by xterm.js. */ public attachCustomKeyEventHandler(customKeyEventHandler: CustomKeyEventHandler): void { this.customKeyEventHandler = customKeyEventHandler; @@ -2051,7 +2053,7 @@ export class Terminal extends EventEmitter implements ITerminal, IInputHandlingT } /** - * Clears the entire buffer, making the prompt line the new first line. + * Clear the entire buffer, making the prompt line the new first line. */ public clear(): void { if (this.buffer.ybase === 0 && this.buffer.y === 0) { diff --git a/typings/xterm.d.ts b/typings/xterm.d.ts index a64f132c..5e942ad5 100644 --- a/typings/xterm.d.ts +++ b/typings/xterm.d.ts @@ -1,194 +1,282 @@ /** * @license MIT + * + * This contains the type declarations for the xterm.js library. Note that + * some interfaces differ between this file and the actual implementation in + * src/, that's because this file declares the *public* API which is intended + * to be stable and consumed by external programs. */ -declare module 'xterm' { - type LinkMatcherHandler = (event: MouseEvent, uri: string) => boolean | void; +/** + * An object containing start up options for the terminal. + */ +interface ITerminalOptions { + /** + * The number of columns in the terminal. + */ + cols?: number; - export class Terminal { - cols: number; - rows: number; - ydisp: number; - element: HTMLElement; - textarea: HTMLTextAreaElement; + /** + * Whether the cursor blinks. + */ + cursorBlink?: boolean; - /** - * Creates a new `Terminal` object. - * - * @param {object} options An object containing a set of options. - */ - constructor(options?: any); + /** + * The style of the cursor. + */ + cursorStyle?: 'block' | 'underline' | 'bar'; - /** - * Registers an event listener. - * @param eventName The name of the event. - * @param callback The callback. - */ - on(eventName: string, callback: (data: any) => void): void; + /** + * Whether input should be disabled. + */ + disableStdin?: boolean; - /** - * Resizes the terminal. - * - * @param x The number of columns to resize to. - * @param y The number of rows to resize to. - */ - resize(columns: number, rows: number): void; + /** + * The number of rows in the terminal. + */ + rows?: number; - /** - * Emits an event. - * @param eventName The name of the event. - * @param data The data attached to the event. - */ - emit(eventName: string, data: any): void; + /** + * The amount of scrollback in the terminal. Scrollback is the amount of rows + * that are retained when lines are scrolled beyond the initial viewport. + */ + scrollback?: number; - /** - * Writes text to the terminal, followed by a break line character (\n). - * @param data The text to write to the terminal. - */ - writeln(data: string): void; - - /** - * Opens the terminal within an element. - * @param parent The element to create the terminal within. - * @param focus Focus the terminal, after it gets instantiated in the - * DOM. - */ - open(parent: HTMLElement, focus: boolean): void; - - /** - * Attaches a custom key event handler which is run before keys are - * processed, giving consumers of xterm.js ultimate control as to what - * keys should be processed by the terminal and what keys should not. - * @param customKeyEventHandler The custom KeyboardEvent handler to - * attach. This is a function that takes a KeyboardEvent, allowing - * consumers to stop propogation and/or prevent the default action. The - * function returns whether the event should be processed by xterm.js. - */ - attachCustomKeyEventHandler(customKeyEventHandler: (...any) => boolean); - - /** - * Retrieves an option's value from the terminal. - * @param key The option key. - */ - getOption(key: string): any; - - /** - * Registers a link matcher, allowing custom link patterns to be matched and - * handled. - * @param {RegExp} regex The regular expression to search for, specifically - * this searches the textContent of the rows. You will want to use \s to match - * a space ' ' character for example. - * @param {LinkMatcherHandler} handler The callback when the link is called. - * @param {LinkMatcherOptions} [options] Options for the link matcher. - * @return {number} The ID of the new matcher, this can be used to deregister. - */ - registerLinkMatcher(regex: RegExp, handler: LinkMatcherHandler , options?: any); - - /** - * Deregisters a link matcher if it has been registered. - * @param matcherId The link matcher's ID (returned after register) - */ - deregisterLinkMatcher(matcherId: number): void; - - /** - * Gets whether the terminal has an active selection. - */ - hasSelection(): boolean; - - /** - * Gets the terminal's current selection, this is useful for implementing copy - * behavior outside of xterm.js. - */ - getSelection(): string; - - /** - * Clears the current terminal selection. - */ - clearSelection(): void; - - /** - * Selects all text within the terminal. - */ - selectAll(): void; - - /** - * Focus the terminal. Delegates focus handling to the terminal's DOM element. - */ - focus(): void; - - /** - * Find the next instance of the term, then scroll to and select it. If it - * doesn't exist, do nothing. - * @param term Tne search term. - * @return Whether a result was found. - */ - findNext(term: string): boolean; - - /** - * Find the previous instance of the term, then scroll to and select it. If it - * doesn't exist, do nothing. - * @param term Tne search term. - * @return Whether a result was found. - */ - findPrevious(term: string): boolean; - - /** - * Destroys the terminal. - */ - destroy(): void; - - /** - * Scroll the display of the terminal - * @param disp The number of lines to scroll down (negatives scroll up). - */ - scrollDisp(disp: number): void; - - /** - * Scroll the display of the terminal by a number of pages. - * @param {number} pageCount The number of pages to scroll (negative scrolls up). - */ - scrollPages(pageCount: number): void; - - /** - * Scrolls the display of the terminal to the top. - */ - scrollToTop(): void; - - /** - * Scrolls the display of the terminal to the bottom. - */ - scrollToBottom(): void; - - /** - * Clears the entire buffer, making the prompt line the new first line. - */ - clear(): void; - - /** - * Writes text to the terminal. - * @param data The text to write to the terminal. - */ - write(data: string): void; - - /** - * Sets an option on the terminal. - * @param key The option key. - * @param value The option value. - */ - setOption(key: string, value: any): void; - - /** - * Tells the renderer to refresh terminal content between two rows (inclusive) at the next - * opportunity. - * @param start The row to start from (between 0 and this.rows - 1). - * @param end The row to end at (between start and this.rows - 1). - */ - refresh(start: number, end: number): void; - - /** - * Loads an addon, attaching it to the Terminal prototype. - * @param addon The addon to load. - */ - static loadAddon(addon: string): void; - } + /** + * The size of tab stops in the terminal. + */ + tabStopWidth?: number; +} + + +type Option = BooleanOption | StringOption | StringArrayOption | NumberOption | GeometryOption | HandlerOption; +type BooleanOption = + 'cancelEvents' | + 'convertEol' | + 'cursorBlink' | + 'debug' | + 'disableStdin' | + 'popOnBell' | + 'screenKeys' | + 'useFlowControl' | + 'visualBell'; +type StringOption = + 'cursorStyle' | + 'termName'; +type StringArrayOption = 'colors'; +type NumberOption = + 'cols' | + 'rows' | + 'tabStopWidth' | + 'scrollback'; +type GeometryOption = 'geometry'; +type HandlerOption = 'handler'; + +declare module 'xterm' { + /** + * The class that represents an xterm.js terminal. + */ + export class Terminal { + element: HTMLElement; + textarea: HTMLTextAreaElement; + + /** + * Creates a new `Terminal` object. + * + * @param options An object containing a set of options. + */ + constructor(options?: ITerminalOptions); + + /** + * Unfocus the terminal. + */ + blur(): void; + + /** + * Focus the terminal. + */ + focus(): void; + + /** + * Registers an event listener. + * @param type The type of the event. + * @param listener The listener. + */ + on(type: string, listener: (data: any) => void): void; + + /** + * Deregisters an event listener. + * @param type The type of the event. + * @param listener The listener. + */ + on(type: string, listener: (data: any) => void): void; + + /** + * Resizes the terminal. + * @param x The number of columns to resize to. + * @param y The number of rows to resize to. + */ + resize(columns: number, rows: number): void; + + /** + * Writes text to the terminal, followed by a break line character (\n). + * @param data The text to write to the terminal. + */ + writeln(data: string): void; + + /** + * Opens the terminal within an element. + * @param parent The element to create the terminal within. + */ + open(parent: HTMLElement): void; + + /** + * Attaches a custom key event handler which is run before keys are + * processed, giving consumers of xterm.js ultimate control as to what keys + * should be processed by the terminal and what keys should not. + * @param customKeyEventHandler The custom KeyboardEvent handler to attach. + * This is a function that takes a KeyboardEvent, allowing consumers to stop + * propogation and/or prevent the default action. The function returns + * whether the event should be processed by xterm.js. + */ + attachCustomKeyEventHandler(customKeyEventHandler: (event: KeyboardEvent) => boolean); + + /** + * Retrieves an option's value from the terminal. + * @param key The option key. + */ + getOption(key: StringOption): string; + getOption(key: BooleanOption): boolean; + getOption(key: StringArrayOption): number[]; + getOption(key: NumberOption): number; + getOption(key: GeometryOption): [number, number]; + getOption(key: HandlerOption): (data: string) => void; + getOption(key: Option): any; + + // /** + // * Registers a link matcher, allowing custom link patterns to be matched and + // * handled. + // * @param {RegExp} regex The regular expression to search for, specifically + // * this searches the textContent of the rows. You will want to use \s to match + // * a space ' ' character for example. + // * @param {LinkMatcherHandler} handler The callback when the link is called. + // * @param {LinkMatcherOptions} [options] Options for the link matcher. + // * @return {number} The ID of the new matcher, this can be used to deregister. + // */ + // registerLinkMatcher(regex: RegExp, handler: LinkMatcherHandler , options?: any); + + // /** + // * Deregisters a link matcher if it has been registered. + // * @param matcherId The link matcher's ID (returned after register) + // */ + // deregisterLinkMatcher(matcherId: number): void; + + /** + * Gets whether the terminal has an active selection. + */ + hasSelection(): boolean; + + /** + * Gets the terminal's current selection, this is useful for implementing + * copy behavior outside of xterm.js. + */ + getSelection(): string; + + /** + * Clears the current terminal selection. + */ + clearSelection(): void; + + /** + * Selects all text within the terminal. + */ + selectAll(): void; + + // /** + // * Find the next instance of the term, then scroll to and select it. If it + // * doesn't exist, do nothing. + // * @param term Tne search term. + // * @return Whether a result was found. + // */ + // findNext(term: string): boolean; + + // /** + // * Find the previous instance of the term, then scroll to and select it. If it + // * doesn't exist, do nothing. + // * @param term Tne search term. + // * @return Whether a result was found. + // */ + // findPrevious(term: string): boolean; + + /** + * Destroys the terminal and detaches it from the DOM. + */ + destroy(): void; + + /** + * Scroll the display of the terminal + * @param amount The number of lines to scroll down (negative scroll up). + */ + scrollDisp(amount: number): void; + + /** + * Scroll the display of the terminal by a number of pages. + * @param pageCount The number of pages to scroll (negative scrolls up). + */ + scrollPages(pageCount: number): void; + + /** + * Scrolls the display of the terminal to the top. + */ + scrollToTop(): void; + + /** + * Scrolls the display of the terminal to the bottom. + */ + scrollToBottom(): void; + + /** + * Clear the entire buffer, making the prompt line the new first line. + */ + clear(): void; + + /** + * Writes text to the terminal. + * @param data The text to write to the terminal. + */ + write(data: string): void; + + /** + * Sets an option on the terminal. + * @param key The option key. + * @param value The option value. + */ + setOption(key: StringOption, value: string): void; + setOption(key: BooleanOption, value: boolean): void; + setOption(key: StringArrayOption, value: number[]): void; + setOption(key: NumberOption, value: number): void; + setOption(key: GeometryOption, value: [number, number]): void; + setOption(key: HandlerOption, value: (data: string) => void): void; + setOption(key: Option, value: any): void; + + /** + * Tells the renderer to refresh terminal content between two rows + * (inclusive) at the next opportunity. + * @param start The row to start from (between 0 and this.rows - 1). + * @param end The row to end at (between start and this.rows - 1). + */ + refresh(start: number, end: number): void; + + /** + * Perform a full reset (RIS, aka '\x1bc'). + */ + reset(): void + + /** + * Loads an addon, attaching it to the Terminal prototype and making it + * available to all newly created Terminals. + * @param addon The addon to load. + */ + static loadAddon(addon: string): void; + } }