node_modules/xterm/typings/xterm.d.ts

   1 /**
   2  * @license MIT
   3  *
   4  * This contains the type declarations for the xterm.js library. Note that
   5  * some interfaces differ between this file and the actual implementation in
   6  * src/, that's because this file declares the *public* API which is intended
   7  * to be stable and consumed by external programs.
   8  */
   9
  10 /// <reference lib="dom"/>
  11
  12 declare module 'xterm' {
  13   /**
  14    * A string representing text font weight.
  15    */
  16   export type FontWeight = 'normal' | 'bold' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
  17
  18   /**
  19    * A string representing log level.
  20    */
  21   export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'off';
  22
  23   /**
  24    * A string representing a renderer type.
  25    */
  26   export type RendererType = 'dom' | 'canvas';
  27
  28   /**
  29    * An object containing start up options for the terminal.
  30    */
  31   export interface ITerminalOptions {
  32     /**
  33      * Whether background should support non-opaque color. It must be set before
  34      * executing the `Terminal.open()` method and can't be changed later without
  35      * executing it again. Note that enabling this can negatively impact
  36      * performance.
  37      */
  38     allowTransparency?: boolean;
  39
  40     /**
  41      * A data uri of the sound to use for the bell when `bellStyle = 'sound'`.
  42      */
  43     bellSound?: string;
  44
  45     /**
  46      * The type of the bell notification the terminal will use.
  47      */
  48     bellStyle?: 'none' /*| 'visual'*/ | 'sound' /*| 'both'*/;
  49
  50     /**
  51      * When enabled the cursor will be set to the beginning of the next line
  52      * with every new line. This equivalent to sending '\r\n' for each '\n'.
  53      * Normally the termios settings of the underlying PTY deals with the
  54      * translation of '\n' to '\r\n' and this setting should not be used. If you
  55      * deal with data from a non-PTY related source, this settings might be
  56      * useful.
  57      */
  58     convertEol?: boolean;
  59
  60     /**
  61      * The number of columns in the terminal.
  62      */
  63     cols?: number;
  64
  65     /**
  66      * Whether the cursor blinks.
  67      */
  68     cursorBlink?: boolean;
  69
  70     /**
  71      * The style of the cursor.
  72      */
  73     cursorStyle?: 'block' | 'underline' | 'bar';
  74
  75     /**
  76      * Whether input should be disabled.
  77      */
  78     disableStdin?: boolean;
  79
  80     /**
  81      * Whether to draw bold text in bright colors. The default is true.
  82      */
  83     drawBoldTextInBrightColors?: boolean;
  84
  85     /**
  86      * The modifier key hold to multiply scroll speed.
  87      */
  88     fastScrollModifier?: 'alt' | 'ctrl' | 'shift' | undefined;
  89
  90     /**
  91      * The scroll speed multiplier used for fast scrolling.
  92      */
  93     fastScrollSensitivity?: number;
  94
  95     /**
  96      * The font size used to render text.
  97      */
  98     fontSize?: number;
  99
 100     /**
 101      * The font family used to render text.
 102      */
 103     fontFamily?: string;
 104
 105     /**
 106      * The font weight used to render non-bold text.
 107      */
 108     fontWeight?: FontWeight;
 109
 110     /**
 111      * The font weight used to render bold text.
 112      */
 113     fontWeightBold?: FontWeight;
 114
 115     /**
 116      * The spacing in whole pixels between characters..
 117      */
 118     letterSpacing?: number;
 119
 120     /**
 121      * The line height used to render text.
 122      */
 123     lineHeight?: number;
 124
 125     /**
 126      * What log level to use, this will log for all levels below and including
 127      * what is set:
 128      *
 129      * 1. debug
 130      * 2. info (default)
 131      * 3. warn
 132      * 4. error
 133      * 5. off
 134      */
 135     logLevel?: LogLevel;
 136
 137     /**
 138      * Whether to treat option as the meta key.
 139      */
 140     macOptionIsMeta?: boolean;
 141
 142     /**
 143      * Whether holding a modifier key will force normal selection behavior,
 144      * regardless of whether the terminal is in mouse events mode. This will
 145      * also prevent mouse events from being emitted by the terminal. For
 146      * example, this allows you to use xterm.js' regular selection inside tmux
 147      * with mouse mode enabled.
 148      */
 149     macOptionClickForcesSelection?: boolean;
 150
 151     /**
 152      * The type of renderer to use, this allows using the fallback DOM renderer
 153      * when canvas is too slow for the environment. The following features do
 154      * not work when the DOM renderer is used:
 155      *
 156      * - Letter spacing
 157      * - Cursor blink
 158      */
 159     rendererType?: RendererType;
 160
 161     /**
 162      * Whether to select the word under the cursor on right click, this is
 163      * standard behavior in a lot of macOS applications.
 164      */
 165     rightClickSelectsWord?: boolean;
 166
 167     /**
 168      * The number of rows in the terminal.
 169      */
 170     rows?: number;
 171
 172     /**
 173      * Whether screen reader support is enabled. When on this will expose
 174      * supporting elements in the DOM to support NVDA on Windows and VoiceOver
 175      * on macOS.
 176      */
 177     screenReaderMode?: boolean;
 178
 179     /**
 180      * The amount of scrollback in the terminal. Scrollback is the amount of
 181      * rows that are retained when lines are scrolled beyond the initial
 182      * viewport.
 183      */
 184     scrollback?: number;
 185
 186     /**
 187      * The scrolling speed multiplier used for adjusting normal scrolling speed.
 188      */
 189     scrollSensitivity?: number;
 190
 191     /**
 192      * The size of tab stops in the terminal.
 193      */
 194     tabStopWidth?: number;
 195
 196     /**
 197      * The color theme of the terminal.
 198      */
 199     theme?: ITheme;
 200
 201     /**
 202      * Whether "Windows mode" is enabled. Because Windows backends winpty and
 203      * conpty operate by doing line wrapping on their side, xterm.js does not
 204      * have access to wrapped lines. When Windows mode is enabled the following
 205      * changes will be in effect:
 206      *
 207      * - Reflow is disabled.
 208      * - Lines are assumed to be wrapped if the last character of the line is
 209      *   not whitespace.
 210      */
 211     windowsMode?: boolean;
 212
 213     /**
 214      * A string containing all characters that are considered word separated by the
 215      * double click to select work logic.
 216     */
 217     wordSeparator?: string;
 218   }
 219
 220   /**
 221    * Contains colors to theme the terminal with.
 222    */
 223   export interface ITheme {
 224     /** The default foreground color */
 225     foreground?: string;
 226     /** The default background color */
 227     background?: string;
 228     /** The cursor color */
 229     cursor?: string;
 230     /** The accent color of the cursor (fg color for a block cursor) */
 231     cursorAccent?: string;
 232     /** The selection background color (can be transparent) */
 233     selection?: string;
 234     /** ANSI black (eg. `\x1b[30m`) */
 235     black?: string;
 236     /** ANSI red (eg. `\x1b[31m`) */
 237     red?: string;
 238     /** ANSI green (eg. `\x1b[32m`) */
 239     green?: string;
 240     /** ANSI yellow (eg. `\x1b[33m`) */
 241     yellow?: string;
 242     /** ANSI blue (eg. `\x1b[34m`) */
 243     blue?: string;
 244     /** ANSI magenta (eg. `\x1b[35m`) */
 245     magenta?: string;
 246     /** ANSI cyan (eg. `\x1b[36m`) */
 247     cyan?: string;
 248     /** ANSI white (eg. `\x1b[37m`) */
 249     white?: string;
 250     /** ANSI bright black (eg. `\x1b[1;30m`) */
 251     brightBlack?: string;
 252     /** ANSI bright red (eg. `\x1b[1;31m`) */
 253     brightRed?: string;
 254     /** ANSI bright green (eg. `\x1b[1;32m`) */
 255     brightGreen?: string;
 256     /** ANSI bright yellow (eg. `\x1b[1;33m`) */
 257     brightYellow?: string;
 258     /** ANSI bright blue (eg. `\x1b[1;34m`) */
 259     brightBlue?: string;
 260     /** ANSI bright magenta (eg. `\x1b[1;35m`) */
 261     brightMagenta?: string;
 262     /** ANSI bright cyan (eg. `\x1b[1;36m`) */
 263     brightCyan?: string;
 264     /** ANSI bright white (eg. `\x1b[1;37m`) */
 265     brightWhite?: string;
 266   }
 267
 268   /**
 269    * An object containing options for a link matcher.
 270    */
 271   export interface ILinkMatcherOptions {
 272     /**
 273      * The index of the link from the regex.match(text) call. This defaults to 0
 274      * (for regular expressions without capture groups).
 275      */
 276     matchIndex?: number;
 277
 278     /**
 279      * A callback that validates whether to create an individual link, pass
 280      * whether the link is valid to the callback.
 281      */
 282     validationCallback?: (uri: string, callback: (isValid: boolean) => void) => void;
 283
 284     /**
 285      * A callback that fires when the mouse hovers over a link for a moment.
 286      */
 287     tooltipCallback?: (event: MouseEvent, uri: string, location: IViewportRange) => boolean | void;
 288
 289     /**
 290      * A callback that fires when the mouse leaves a link. Note that this can
 291      * happen even when tooltipCallback hasn't fired for the link yet.
 292      */
 293     leaveCallback?: () => void;
 294
 295     /**
 296      * The priority of the link matcher, this defines the order in which the
 297      * link matcher is evaluated relative to others, from highest to lowest. The
 298      * default value is 0.
 299      */
 300     priority?: number;
 301
 302     /**
 303      * A callback that fires when the mousedown and click events occur that
 304      * determines whether a link will be activated upon click. This enables
 305      * only activating a link when a certain modifier is held down, if not the
 306      * mouse event will continue propagation (eg. double click to select word).
 307      */
 308     willLinkActivate?: (event: MouseEvent, uri: string) => boolean;
 309   }
 310
 311   /**
 312    * An object that can be disposed via a dispose function.
 313    */
 314   export interface IDisposable {
 315     dispose(): void;
 316   }
 317
 318   /**
 319    * An event that can be listened to.
 320    * @returns an `IDisposable` to stop listening.
 321    */
 322   export interface IEvent<T> {
 323     (listener: (e: T) => any): IDisposable;
 324   }
 325
 326   /**
 327    * Represents a specific line in the terminal that is tracked when scrollback
 328    * is trimmed and lines are added or removed. This is a single line that may
 329    * be part of a larger wrapped line.
 330    */
 331   export interface IMarker extends IDisposable {
 332     /**
 333      * A unique identifier for this marker.
 334      */
 335     readonly id: number;
 336
 337     /**
 338      * Whether this marker is disposed.
 339      */
 340     readonly isDisposed: boolean;
 341
 342     /**
 343      * The actual line index in the buffer at this point in time. This is set to
 344      * -1 if the marker has been disposed.
 345      */
 346     readonly line: number;
 347   }
 348
 349   /**
 350    * The set of localizable strings.
 351    */
 352   export interface ILocalizableStrings {
 353     /**
 354      * The aria label for the underlying input textarea for the terminal.
 355      */
 356     promptLabel: string;
 357
 358     /**
 359      * Announcement for when line reading is suppressed due to too many lines
 360      * being printed to the terminal when `screenReaderMode` is enabled.
 361      */
 362     tooMuchOutput: string;
 363   }
 364
 365   /**
 366    * The class that represents an xterm.js terminal.
 367    */
 368   export class Terminal implements IDisposable {
 369     /**
 370      * The element containing the terminal.
 371      */
 372     readonly element: HTMLElement | undefined;
 373
 374     /**
 375      * The textarea that accepts input for the terminal.
 376      */
 377     readonly textarea: HTMLTextAreaElement | undefined;
 378
 379     /**
 380      * The number of rows in the terminal's viewport. Use
 381      * `ITerminalOptions.rows` to set this in the constructor and
 382      * `Terminal.resize` for when the terminal exists.
 383      */
 384     readonly rows: number;
 385
 386     /**
 387      * The number of columns in the terminal's viewport. Use
 388      * `ITerminalOptions.cols` to set this in the constructor and
 389      * `Terminal.resize` for when the terminal exists.
 390      */
 391     readonly cols: number;
 392
 393     /**
 394      * (EXPERIMENTAL) The terminal's current buffer, this might be either the
 395      * normal buffer or the alt buffer depending on what's running in the
 396      * terminal.
 397      */
 398     readonly buffer: IBuffer;
 399
 400     /**
 401      * (EXPERIMENTAL) Get all markers registered against the buffer. If the alt
 402      * buffer is active this will always return [].
 403      */
 404     readonly markers: ReadonlyArray<IMarker>;
 405
 406     /**
 407      * (EXPERIMENTAL) Get the parser interface to register
 408      * custom escape sequence handlers.
 409      */
 410     readonly parser: IParser;
 411
 412     /**
 413      * Natural language strings that can be localized.
 414      */
 415     static strings: ILocalizableStrings;
 416
 417     /**
 418      * Creates a new `Terminal` object.
 419      *
 420      * @param options An object containing a set of options.
 421      */
 422     constructor(options?: ITerminalOptions);
 423
 424     /**
 425      * Adds an event listener for the cursor moves.
 426      * @returns an `IDisposable` to stop listening.
 427      */
 428     onCursorMove: IEvent<void>;
 429
 430     /**
 431      * Adds an event listener for when a data event fires. This happens for
 432      * example when the user types or pastes into the terminal. The event value
 433      * is whatever `string` results, in a typical setup, this should be passed
 434      * on to the backing pty.
 435      * @returns an `IDisposable` to stop listening.
 436      */
 437     onData: IEvent<string>;
 438
 439     /**
 440      * Adds an event listener for a key is pressed. The event value contains the
 441      * string that will be sent in the data event as well as the DOM event that
 442      * triggered it.
 443      * @returns an `IDisposable` to stop listening.
 444      */
 445     onKey: IEvent<{ key: string, domEvent: KeyboardEvent }>;
 446
 447     /**
 448      * Adds an event listener for when a line feed is added.
 449      * @returns an `IDisposable` to stop listening.
 450      */
 451     onLineFeed: IEvent<void>;
 452
 453     /**
 454      * Adds an event listener for when a scroll occurs. The event value is the
 455      * new position of the viewport.
 456      * @returns an `IDisposable` to stop listening.
 457      */
 458     onScroll: IEvent<number>;
 459
 460     /**
 461      * Adds an event listener for when a selection change occurs.
 462      * @returns an `IDisposable` to stop listening.
 463      */
 464     onSelectionChange: IEvent<void>;
 465
 466     /**
 467      * Adds an event listener for when rows are rendered. The event value
 468      * contains the start row and end rows of the rendered area (ranges from `0`
 469      * to `Terminal.rows - 1`).
 470      * @returns an `IDisposable` to stop listening.
 471      */
 472     onRender: IEvent<{ start: number, end: number }>;
 473
 474     /**
 475      * Adds an event listener for when the terminal is resized. The event value
 476      * contains the new size.
 477      * @returns an `IDisposable` to stop listening.
 478      */
 479     onResize: IEvent<{ cols: number, rows: number }>;
 480
 481     /**
 482      * Adds an event listener for when an OSC 0 or OSC 2 title change occurs.
 483      * The event value is the new title.
 484      * @returns an `IDisposable` to stop listening.
 485      */
 486     onTitleChange: IEvent<string>;
 487
 488     /**
 489      * Unfocus the terminal.
 490      */
 491     blur(): void;
 492
 493     /**
 494      * Focus the terminal.
 495      */
 496     focus(): void;
 497
 498     /**
 499      * Resizes the terminal. It's best practice to debounce calls to resize,
 500      * this will help ensure that the pty can respond to the resize event
 501      * before another one occurs.
 502      * @param x The number of columns to resize to.
 503      * @param y The number of rows to resize to.
 504      */
 505     resize(columns: number, rows: number): void;
 506
 507     /**
 508      * Opens the terminal within an element.
 509      * @param parent The element to create the terminal within. This element
 510      * must be visible (have dimensions) when `open` is called as several DOM-
 511      * based measurements need to be performed when this function is called.
 512      */
 513     open(parent: HTMLElement): void;
 514
 515     /**
 516      * Attaches a custom key event handler which is run before keys are
 517      * processed, giving consumers of xterm.js ultimate control as to what keys
 518      * should be processed by the terminal and what keys should not.
 519      * @param customKeyEventHandler The custom KeyboardEvent handler to attach.
 520      * This is a function that takes a KeyboardEvent, allowing consumers to stop
 521      * propagation and/or prevent the default action. The function returns
 522      * whether the event should be processed by xterm.js.
 523      */
 524     attachCustomKeyEventHandler(customKeyEventHandler: (event: KeyboardEvent) => boolean): void;
 525
 526     /**
 527      * (EXPERIMENTAL) Registers a link matcher, allowing custom link patterns to
 528      * be matched and handled.
 529      * @param regex The regular expression to search for, specifically this
 530      * searches the textContent of the rows. You will want to use \s to match a
 531      * space ' ' character for example.
 532      * @param handler The callback when the link is called.
 533      * @param options Options for the link matcher.
 534      * @return The ID of the new matcher, this can be used to deregister.
 535      */
 536     registerLinkMatcher(regex: RegExp, handler: (event: MouseEvent, uri: string) => void, options?: ILinkMatcherOptions): number;
 537
 538     /**
 539      * (EXPERIMENTAL) Deregisters a link matcher if it has been registered.
 540      * @param matcherId The link matcher's ID (returned after register)
 541      */
 542     deregisterLinkMatcher(matcherId: number): void;
 543
 544     /**
 545      * (EXPERIMENTAL) Registers a character joiner, allowing custom sequences of
 546      * characters to be rendered as a single unit. This is useful in particular
 547      * for rendering ligatures and graphemes, among other things.
 548      *
 549      * Each registered character joiner is called with a string of text
 550      * representing a portion of a line in the terminal that can be rendered as
 551      * a single unit. The joiner must return a sorted array, where each entry is
 552      * itself an array of length two, containing the start (inclusive) and end
 553      * (exclusive) index of a substring of the input that should be rendered as
 554      * a single unit. When multiple joiners are provided, the results of each
 555      * are collected. If there are any overlapping substrings between them, they
 556      * are combined into one larger unit that is drawn together.
 557      *
 558      * All character joiners that are registered get called every time a line is
 559      * rendered in the terminal, so it is essential for the handler function to
 560      * run as quickly as possible to avoid slowdowns when rendering. Similarly,
 561      * joiners should strive to return the smallest possible substrings to
 562      * render together, since they aren't drawn as optimally as individual
 563      * characters.
 564      *
 565      * NOTE: character joiners are only used by the canvas renderer.
 566      *
 567      * @param handler The function that determines character joins. It is called
 568      * with a string of text that is eligible for joining and returns an array
 569      * where each entry is an array containing the start (inclusive) and end
 570      * (exclusive) indexes of ranges that should be rendered as a single unit.
 571      * @return The ID of the new joiner, this can be used to deregister
 572      */
 573     registerCharacterJoiner(handler: (text: string) => [number, number][]): number;
 574
 575     /**
 576      * (EXPERIMENTAL) Deregisters the character joiner if one was registered.
 577      * NOTE: character joiners are only used by the canvas renderer.
 578      * @param joinerId The character joiner's ID (returned after register)
 579      */
 580     deregisterCharacterJoiner(joinerId: number): void;
 581
 582     /**
 583      * (EXPERIMENTAL) Adds a marker to the normal buffer and returns it. If the
 584      * alt buffer is active, undefined is returned.
 585      * @param cursorYOffset The y position offset of the marker from the cursor.
 586      */
 587     addMarker(cursorYOffset: number): IMarker;
 588
 589     /**
 590      * Gets whether the terminal has an active selection.
 591      */
 592     hasSelection(): boolean;
 593
 594     /**
 595      * Gets the terminal's current selection, this is useful for implementing
 596      * copy behavior outside of xterm.js.
 597      */
 598     getSelection(): string;
 599
 600     /**
 601      * Gets the selection position or undefined if there is no selection.
 602      */
 603     getSelectionPosition(): ISelectionPosition | undefined;
 604
 605     /**
 606      * Clears the current terminal selection.
 607      */
 608     clearSelection(): void;
 609
 610     /**
 611      * Selects text within the terminal.
 612      * @param column The column the selection starts at..
 613      * @param row The row the selection starts at.
 614      * @param length The length of the selection.
 615      */
 616     select(column: number, row: number, length: number): void;
 617
 618     /**
 619      * Selects all text within the terminal.
 620      */
 621     selectAll(): void;
 622
 623     /**
 624      * Selects text in the buffer between 2 lines.
 625      * @param start The 0-based line index to select from (inclusive).
 626      * @param end The 0-based line index to select to (inclusive).
 627      */
 628     selectLines(start: number, end: number): void;
 629
 630     /*
 631      * Disposes of the terminal, detaching it from the DOM and removing any
 632      * active listeners.
 633      */
 634     dispose(): void;
 635
 636     /**
 637      * Scroll the display of the terminal
 638      * @param amount The number of lines to scroll down (negative scroll up).
 639      */
 640     scrollLines(amount: number): void;
 641
 642     /**
 643      * Scroll the display of the terminal by a number of pages.
 644      * @param pageCount The number of pages to scroll (negative scrolls up).
 645      */
 646     scrollPages(pageCount: number): void;
 647
 648     /**
 649      * Scrolls the display of the terminal to the top.
 650      */
 651     scrollToTop(): void;
 652
 653     /**
 654      * Scrolls the display of the terminal to the bottom.
 655      */
 656     scrollToBottom(): void;
 657
 658     /**
 659      * Scrolls to a line within the buffer.
 660      * @param line The 0-based line index to scroll to.
 661      */
 662     scrollToLine(line: number): void;
 663
 664     /**
 665      * Clear the entire buffer, making the prompt line the new first line.
 666      */
 667     clear(): void;
 668
 669     /**
 670      * Write data to the terminal.
 671      * @param data The data to write to the terminal. This can either be raw
 672      * bytes given as Uint8Array from the pty or a string. Raw bytes will always
 673      * be treated as UTF-8 encoded, string data as UTF-16.
 674      * @param callback Optional callback that fires when the data was processed
 675      * by the parser.
 676      */
 677     write(data: string | Uint8Array, callback?: () => void): void;
 678
 679     /**
 680      * Writes data to the terminal, followed by a break line character (\n).
 681      * @param data The data to write to the terminal. This can either be raw
 682      * bytes given as Uint8Array from the pty or a string. Raw bytes will always
 683      * be treated as UTF-8 encoded, string data as UTF-16.
 684      * @param callback Optional callback that fires when the data was processed
 685      * by the parser.
 686      */
 687     writeln(data: string | Uint8Array, callback?: () => void): void;
 688
 689     /**
 690      * Write UTF8 data to the terminal.
 691      * @param data The data to write to the terminal.
 692      * @param callback Optional callback when data was processed.
 693      * @deprecated use `write` instead
 694      */
 695     writeUtf8(data: Uint8Array, callback?: () => void): void;
 696
 697     /**
 698      * Writes text to the terminal, performing the necessary transformations for pasted text.
 699      * @param data The text to write to the terminal.
 700      */
 701     paste(data: string): void;
 702
 703     /**
 704      * Retrieves an option's value from the terminal.
 705      * @param key The option key.
 706      */
 707     getOption(key: 'bellSound' | 'bellStyle' | 'cursorStyle' | 'fontFamily' | 'fontWeight' | 'fontWeightBold' | 'logLevel' | 'rendererType' | 'termName' | 'wordSeparator'): string;
 708     /**
 709      * Retrieves an option's value from the terminal.
 710      * @param key The option key.
 711      */
 712     getOption(key: 'allowTransparency' | 'cancelEvents' | 'convertEol' | 'cursorBlink' | 'disableStdin' | 'macOptionIsMeta' | 'rightClickSelectsWord' | 'popOnBell' | 'screenKeys' | 'useFlowControl' | 'visualBell' | 'windowsMode'): boolean;
 713     /**
 714      * Retrieves an option's value from the terminal.
 715      * @param key The option key.
 716      */
 717     getOption(key: 'colors'): string[];
 718     /**
 719      * Retrieves an option's value from the terminal.
 720      * @param key The option key.
 721      */
 722     getOption(key: 'cols' | 'fontSize' | 'letterSpacing' | 'lineHeight' | 'rows' | 'tabStopWidth' | 'scrollback'): number;
 723     /**
 724      * Retrieves an option's value from the terminal.
 725      * @param key The option key.
 726      */
 727     getOption(key: 'handler'): (data: string) => void;
 728     /**
 729      * Retrieves an option's value from the terminal.
 730      * @param key The option key.
 731      */
 732     getOption(key: string): any;
 733
 734     /**
 735      * Sets an option on the terminal.
 736      * @param key The option key.
 737      * @param value The option value.
 738      */
 739     setOption(key: 'fontFamily' | 'termName' | 'bellSound' | 'wordSeparator', value: string): void;
 740     /**
 741     * Sets an option on the terminal.
 742     * @param key The option key.
 743     * @param value The option value.
 744     */
 745     setOption(key: 'fontWeight' | 'fontWeightBold', value: null | 'normal' | 'bold' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900'): void;
 746     /**
 747     * Sets an option on the terminal.
 748     * @param key The option key.
 749     * @param value The option value.
 750     */
 751     setOption(key: 'logLevel', value: LogLevel): void;
 752     /**
 753      * Sets an option on the terminal.
 754      * @param key The option key.
 755      * @param value The option value.
 756      */
 757     setOption(key: 'bellStyle', value: null | 'none' | 'visual' | 'sound' | 'both'): void;
 758     /**
 759      * Sets an option on the terminal.
 760      * @param key The option key.
 761      * @param value The option value.
 762      */
 763     setOption(key: 'cursorStyle', value: null | 'block' | 'underline' | 'bar'): void;
 764     /**
 765      * Sets an option on the terminal.
 766      * @param key The option key.
 767      * @param value The option value.
 768      */
 769     setOption(key: 'allowTransparency' | 'cancelEvents' | 'convertEol' | 'cursorBlink' | 'disableStdin' | 'macOptionIsMeta' | 'popOnBell' | 'rightClickSelectsWord' | 'screenKeys' | 'useFlowControl' | 'visualBell' | 'windowsMode', value: boolean): void;
 770     /**
 771      * Sets an option on the terminal.
 772      * @param key The option key.
 773      * @param value The option value.
 774      */
 775     setOption(key: 'colors', value: string[]): void;
 776     /**
 777      * Sets an option on the terminal.
 778      * @param key The option key.
 779      * @param value The option value.
 780      */
 781     setOption(key: 'fontSize' | 'letterSpacing' | 'lineHeight' | 'tabStopWidth' | 'scrollback', value: number): void;
 782     /**
 783      * Sets an option on the terminal.
 784      * @param key The option key.
 785      * @param value The option value.
 786      */
 787     setOption(key: 'handler', value: (data: string) => void): void;
 788     /**
 789      * Sets an option on the terminal.
 790      * @param key The option key.
 791      * @param value The option value.
 792      */
 793     setOption(key: 'theme', value: ITheme): void;
 794     /**
 795      * Sets an option on the terminal.
 796      * @param key The option key.
 797      * @param value The option value.
 798      */
 799     setOption(key: 'cols' | 'rows', value: number): void;
 800     /**
 801      * Sets an option on the terminal.
 802      * @param key The option key.
 803      * @param value The option value.
 804      */
 805     setOption(key: string, value: any): void;
 806
 807     /**
 808      * Tells the renderer to refresh terminal content between two rows
 809      * (inclusive) at the next opportunity.
 810      * @param start The row to start from (between 0 and this.rows - 1).
 811      * @param end The row to end at (between start and this.rows - 1).
 812      */
 813     refresh(start: number, end: number): void;
 814
 815     /**
 816      * Perform a full reset (RIS, aka '\x1bc').
 817      */
 818     reset(): void;
 819
 820     /**
 821      * Loads an addon into this instance of xterm.js.
 822      * @param addon The addon to load.
 823      */
 824     loadAddon(addon: ITerminalAddon): void;
 825   }
 826
 827   /**
 828    * An addon that can provide additional functionality to the terminal.
 829    */
 830   export interface ITerminalAddon extends IDisposable {
 831     /**
 832      * This is called when the addon is activated.
 833      */
 834     activate(terminal: Terminal): void;
 835   }
 836
 837   /**
 838    * An object representing a selection within the terminal.
 839    */
 840   interface ISelectionPosition {
 841     /**
 842      * The start column of the selection.
 843      */
 844     startColumn: number;
 845
 846     /**
 847      * The start row of the selection.
 848      */
 849     startRow: number;
 850
 851     /**
 852      * The end column of the selection.
 853      */
 854     endColumn: number;
 855
 856     /**
 857      * The end row of the selection.
 858      */
 859     endRow: number;
 860   }
 861
 862   /**
 863    * An object representing a range within the viewport of the terminal.
 864    */
 865   export interface IViewportRange {
 866     /**
 867      * The start of the range.
 868      */
 869     start: IViewportRangePosition;
 870
 871     /**
 872      * The end of the range.
 873      */
 874     end: IViewportRangePosition;
 875   }
 876
 877   /**
 878    * An object representing a cell position within the viewport of the terminal.
 879    */
 880   interface IViewportRangePosition {
 881     /**
 882      * The x position of the cell. This is a 0-based index that refers to the
 883      * space in between columns, not the column itself. Index 0 refers to the
 884      * left side of the viewport, index `Terminal.cols` refers to the right side
 885      * of the viewport. This can be thought of as how a cursor is positioned in
 886      * a text editor.
 887      */
 888     x: number;
 889
 890     /**
 891      * The y position of the cell. This is a 0-based index that refers to a
 892      * specific row.
 893      */
 894     y: number;
 895   }
 896
 897   /**
 898    * Represents a terminal buffer.
 899    */
 900   interface IBuffer {
 901     /**
 902      * The y position of the cursor. This ranges between `0` (when the
 903      * cursor is at baseY) and `Terminal.rows - 1` (when the cursor is on the
 904      * last row).
 905      */
 906     readonly cursorY: number;
 907
 908     /**
 909      * The x position of the cursor. This ranges between `0` (left side) and
 910      * `Terminal.cols - 1` (right side).
 911      */
 912     readonly cursorX: number;
 913
 914     /**
 915      * The line within the buffer where the top of the viewport is.
 916      */
 917     readonly viewportY: number;
 918
 919     /**
 920      * The line within the buffer where the top of the bottom page is (when
 921      * fully scrolled down);
 922      */
 923     readonly baseY: number;
 924
 925     /**
 926      * The amount of lines in the buffer.
 927      */
 928     readonly length: number;
 929
 930     /**
 931      * Gets a line from the buffer, or undefined if the line index does not
 932      * exist.
 933      *
 934      * Note that the result of this function should be used immediately after
 935      * calling as when the terminal updates it could lead to unexpected
 936      * behavior.
 937      *
 938      * @param y The line index to get.
 939      */
 940     getLine(y: number): IBufferLine | undefined;
 941   }
 942
 943   /**
 944    * Represents a line in the terminal's buffer.
 945    */
 946   interface IBufferLine {
 947     /**
 948      * Whether the line is wrapped from the previous line.
 949      */
 950     readonly isWrapped: boolean;
 951
 952     /**
 953      * Gets a cell from the line, or undefined if the line index does not exist.
 954      *
 955      * Note that the result of this function should be used immediately after
 956      * calling as when the terminal updates it could lead to unexpected
 957      * behavior.
 958      *
 959      * @param x The character index to get.
 960      */
 961     getCell(x: number): IBufferCell | undefined;
 962
 963     /**
 964      * Gets the line as a string. Note that this is gets only the string for the
 965      * line, not taking isWrapped into account.
 966      *
 967      * @param trimRight Whether to trim any whitespace at the right of the line.
 968      * @param startColumn The column to start from (inclusive).
 969      * @param endColumn The column to end at (exclusive).
 970      */
 971     translateToString(trimRight?: boolean, startColumn?: number, endColumn?: number): string;
 972   }
 973
 974   /**
 975    * Represents a single cell in the terminal's buffer.
 976    */
 977   interface IBufferCell {
 978     /**
 979      * The character within the cell.
 980      */
 981     readonly char: string;
 982
 983     /**
 984      * The width of the character. Some examples:
 985      *
 986      * - This is `1` for most cells.
 987      * - This is `2` for wide character like CJK glyphs.
 988      * - This is `0` for cells immediately following cells with a width of `2`.
 989      */
 990     readonly width: number;
 991   }
 992
 993   /**
 994    * (EXPERIMENTAL) Data type to register a CSI, DCS or ESC callback in the parser
 995    * in the form:
 996    *    ESC I..I F
 997    *    CSI Prefix P..P I..I F
 998    *    DCS Prefix P..P I..I F data_bytes ST
 999    *
1000    * with these rules/restrictions:
1001    * - prefix can only be used with CSI and DCS
1002    * - only one leading prefix byte is recognized by the parser
1003    *   before any other parameter bytes (P..P)
1004    * - intermediate bytes are recognized up to 2
1005    *
1006    * For custom sequences make sure to read ECMA-48 and the resources at
1007    * vt100.net to not clash with existing sequences or reserved address space.
1008    * General recommendations:
1009    * - use private address space (see ECMA-48)
1010    * - use max one intermediate byte (technically not limited by the spec,
1011    *   in practice there are no sequences with more than one intermediate byte,
1012    *   thus parsers might get confused with more intermediates)
1013    * - test against other common emulators to check whether they escape/ignore
1014    *   the sequence correctly
1015    *
1016    * Notes: OSC command registration is handled differently (see addOscHandler)
1017    *        APC, PM or SOS is currently not supported.
1018    */
1019   export interface IFunctionIdentifier {
1020     /**
1021      * Optional prefix byte, must be in range \x3c .. \x3f.
1022      * Usable in CSI and DCS.
1023      */
1024     prefix?: string;
1025     /**
1026      * Optional intermediate bytes, must be in range \x20 .. \x2f.
1027      * Usable in CSI, DCS and ESC.
1028      */
1029     intermediates?: string;
1030     /**
1031      * Final byte, must be in range \x40 .. \x7e for CSI and DCS,
1032      * \x30 .. \x7e for ESC.
1033      */
1034     final: string;
1035   }
1036
1037   /**
1038    * (EXPERIMENTAL) Parser interface.
1039    */
1040   export interface IParser {
1041     /**
1042      * Adds a handler for CSI escape sequences.
1043      * @param id Specifies the function identifier under which the callback
1044      * gets registered, e.g. {final: 'm'} for SGR.
1045      * @param callback The function to handle the sequence. The callback is
1046      * called with the numerical params. If the sequence has subparams the
1047      * array will contain subarrays with their numercial values.
1048      * Return true if the sequence was handled; false if we should try
1049      * a previous handler (set by addCsiHandler or setCsiHandler).
1050      * The most recently-added handler is tried first.
1051      * @return An IDisposable you can call to remove this handler.
1052      */
1053     addCsiHandler(id: IFunctionIdentifier, callback: (params: (number | number[])[]) => boolean): IDisposable;
1054
1055     /**
1056      * Adds a handler for DCS escape sequences.
1057      * @param id Specifies the function identifier under which the callback
1058      * gets registered, e.g. {intermediates: '$' final: 'q'} for DECRQSS.
1059      * @param callback The function to handle the sequence. Note that the
1060      * function will only be called once if the sequence finished sucessfully.
1061      * There is currently no way to intercept smaller data chunks, data chunks
1062      * will be stored up until the sequence is finished. Since DCS sequences
1063      * are not limited by the amount of data this might impose a problem for
1064      * big payloads. Currently xterm.js limits DCS payload to 10 MB
1065      * which should give enough room for most use cases.
1066      * The function gets the payload and numerical parameters as arguments.
1067      * Return true if the sequence was handled; false if we should try
1068      * a previous handler (set by addDcsHandler or setDcsHandler).
1069      * The most recently-added handler is tried first.
1070      * @return An IDisposable you can call to remove this handler.
1071      */
1072     addDcsHandler(id: IFunctionIdentifier, callback: (data: string, param: (number | number[])[]) => boolean): IDisposable;
1073
1074     /**
1075      * Adds a handler for ESC escape sequences.
1076      * @param id Specifies the function identifier under which the callback
1077      * gets registered, e.g. {intermediates: '%' final: 'G'} for
1078      * default charset selection.
1079      * @param callback The function to handle the sequence.
1080      * Return true if the sequence was handled; false if we should try
1081      * a previous handler (set by addEscHandler or setEscHandler).
1082      * The most recently-added handler is tried first.
1083      * @return An IDisposable you can call to remove this handler.
1084      */
1085     addEscHandler(id: IFunctionIdentifier, handler: () => boolean): IDisposable;
1086
1087     /**
1088      * Adds a handler for OSC escape sequences.
1089      * @param ident The number (first parameter) of the sequence.
1090      * @param callback The function to handle the sequence. Note that the
1091      * function will only be called once if the sequence finished sucessfully.
1092      * There is currently no way to intercept smaller data chunks, data chunks
1093      * will be stored up until the sequence is finished. Since OSC sequences
1094      * are not limited by the amount of data this might impose a problem for
1095      * big payloads. Currently xterm.js limits OSC payload to 10 MB
1096      * which should give enough room for most use cases.
1097      * The callback is called with OSC data string.
1098      * Return true if the sequence was handled; false if we should try
1099      * a previous handler (set by addOscHandler or setOscHandler).
1100      * The most recently-added handler is tried first.
1101      * @return An IDisposable you can call to remove this handler.
1102      */
1103     addOscHandler(ident: number, callback: (data: string) => boolean): IDisposable;
1104   }
1105 }