@xterm/xterm 6.1.0-beta.9 → 6.1.0-beta.90

package/typings/xterm.d.ts

@@ -58,7 +58,9 @@ declare module '@xterm/xterm' {
     convertEol?: boolean;
 
     /**
-     * Whether the cursor blinks.
+     * Whether the cursor blinks. The blinking will stop after 5 minutes of idle
+     * time (refreshed by clicking, focusing or the cursor moving). The default
+     * is false.
      */
     cursorBlink?: boolean;
 
@@ -77,22 +79,6 @@ declare module '@xterm/xterm' {
      */
     cursorInactiveStyle?: 'outline' | 'block' | 'bar' | 'underline' | 'none';
 
-    /**
-     * Whether to draw custom glyphs instead of using the font for the following
-     * unicode ranges:
-     *
-     * - Box Drawing (U+2500-U+257F)
-     * - Box Elements (U+2580-U+259F)
-     * - Powerline Symbols (U+E0A0–U+E0BF)
-     * - Symbols for Legacy Computing (U+1FB00–U+1FBFF)
-     *
-     * This will typically result in better rendering with continuous lines,
-     * even when line height and letter spacing is used. Note that this doesn't
-     * work with the DOM renderer which renders all characters using the font.
-     * The default is true.
-     */
-    customGlyphs?: boolean;
-
     /**
      * Whether input should be disabled.
      */
@@ -213,10 +199,17 @@ declare module '@xterm/xterm' {
      */
     minimumContrastRatio?: number;
 
+    /**
+     * Control various quirks features that are either non-standard or standard
+     * in but generally rejected in modern terminals.
+     */
+    quirks?: ITerminalQuirks;
+
     /**
      * Whether to reflow the line containing the cursor when the terminal is
      * resized. Defaults to false, because shells usually handle this
-     * themselves.
+     * themselves. Note that this will not move the cursor position, only the
+     * line contents.
      */
     reflowCursorLine?: boolean;
 
@@ -367,17 +360,17 @@ declare module '@xterm/xterm' {
     selectionInactiveBackground?: string;
     /**
      * The scrollbar slider background color. Defaults to
-     * {@link ITerminalOptions.foreground foreground} with 20% opacity.
+     * {@link ITheme.foreground} with 20% opacity.
      */
     scrollbarSliderBackground?: string;
     /**
      * The scrollbar slider background color when hovered. Defaults to
-     * {@link ITerminalOptions.foreground foreground} with 40% opacity.
+     * {@link ITheme.foreground} with 40% opacity.
      */
     scrollbarSliderHoverBackground?: string;
     /**
      * The scrollbar slider background color when clicked. Defaults to
-     * {@link ITerminalOptions.foreground foreground} with 50% opacity.
+     * {@link ITheme.foreground} with 50% opacity.
      */
     scrollbarSliderActiveBackground?: string;
     /**
@@ -422,6 +415,21 @@ declare module '@xterm/xterm' {
     extendedAnsi?: string[];
   }
 
+  /**
+   * Control various quirks features that are either non-standard or standard
+   * in but generally rejected in modern terminals.
+   */
+  export interface ITerminalQuirks {
+    /**
+     * Enables support for DECSET 12 and DECRST 12 which controls cursor blink.
+     * Programs such as `vim` may use this to set the cursor blink state but may
+     * not change it back when exiting. Generally the terminal emulator should
+     * be in control of whether the cursor blinks or not and the application in
+     * modern terminals. Note that DECRQM works regardless of this option.
+     */
+    allowSetCursorBlink?: boolean;
+  }
+
   /**
    * Pty information for Windows.
    */
@@ -848,8 +856,8 @@ declare module '@xterm/xterm' {
     readonly buffer: IBufferNamespace;
 
     /**
-     * (EXPERIMENTAL) Get all markers registered against the buffer. If the alt
-     * buffer is active this will always return [].
+     * Get all markers registered against the buffer. If the alt buffer is
+     * active this will always return [].
      */
     readonly markers: ReadonlyArray<IMarker>;
 
@@ -859,8 +867,8 @@ declare module '@xterm/xterm' {
     readonly parser: IParser;
 
     /**
-     * (EXPERIMENTAL) Get the Unicode handling interface
-     * to register and switch Unicode version.
+     * (EXPERIMENTAL) Get the Unicode handling interface to register and switch
+     * Unicode version.
      */
     readonly unicode: IUnicodeHandling;
 
@@ -869,6 +877,12 @@ declare module '@xterm/xterm' {
      */
     readonly modes: IModes;
 
+    /**
+     * The dimensions of the terminal. This will be undefined before
+     * {@link open} is called.
+     */
+    readonly dimensions: IRenderDimensions | undefined;
+
     /**
      * Gets or sets the terminal options. This supports setting multiple
      * options.
@@ -1009,6 +1023,12 @@ declare module '@xterm/xterm' {
      */
     onTitleChange: IEvent<string>;
 
+    /**
+     * Adds an event listener for when the terminal's dimensions change.
+     * @returns an `IDisposable` to stop listening.
+     */
+    onDimensionsChange: IEvent<IRenderDimensions>;
+
     /**
      * Unfocus the terminal.
      */
@@ -1109,9 +1129,9 @@ declare module '@xterm/xterm' {
     registerLinkProvider(linkProvider: ILinkProvider): IDisposable;
 
     /**
-     * (EXPERIMENTAL) Registers a character joiner, allowing custom sequences of
-     * characters to be rendered as a single unit. This is useful in particular
-     * for rendering ligatures and graphemes, among other things.
+     * Registers a character joiner, allowing custom sequences of characters to
+     * be rendered as a single unit. This is useful in particular for rendering
+     * ligatures and graphemes, among other things.
      *
      * Each registered character joiner is called with a string of text
      * representing a portion of a line in the terminal that can be rendered as
@@ -1129,8 +1149,6 @@ declare module '@xterm/xterm' {
      * render together, since they aren't drawn as optimally as individual
      * characters.
      *
-     * NOTE: character joiners are only used by the webgl renderer.
-     *
      * @param handler The function that determines character joins. It is called
      * with a string of text that is eligible for joining and returns an array
      * where each entry is an array containing the start (inclusive) and end
@@ -1140,8 +1158,8 @@ declare module '@xterm/xterm' {
     registerCharacterJoiner(handler: (text: string) => [number, number][]): number;
 
     /**
-     * (EXPERIMENTAL) Deregisters the character joiner if one was registered.
-     * NOTE: character joiners are only used by the webgl renderer.
+     * Deregisters the character joiner if one was registered. Note that
+     * character joiners are only used by the webgl renderer.
      * @param joinerId The character joiner's ID (returned after register)
      */
     deregisterCharacterJoiner(joinerId: number): void;
@@ -1154,7 +1172,7 @@ declare module '@xterm/xterm' {
     registerMarker(cursorYOffset?: number): IMarker;
 
     /**
-     * (EXPERIMENTAL) Adds a decoration to the terminal using
+     * Registers a decoration to the terminal.
      * @param decorationOptions, which takes a marker and an optional anchor,
      * width, height, and x offset from the anchor. Returns the decoration or
      * undefined if the alt buffer is active or the marker has already been
@@ -1846,7 +1864,7 @@ declare module '@xterm/xterm' {
      * @param id Specifies the function identifier under which the callback gets
      * registered, e.g. {intermediates: '%' final: 'G'} for default charset
      * selection.
-     * @param callback The function to handle the sequence.
+     * @param handler The function to handle the sequence.
      * Return `true` if the sequence was handled, `false` if the parser should
      * try a previous handler. The most recently added handler is tried first.
      * @returns An IDisposable you can call to remove this handler.
@@ -1949,6 +1967,10 @@ declare module '@xterm/xterm' {
      * Send FocusIn/FocusOut events: `CSI ? 1 0 0 4 h`
      */
     readonly sendFocusMode: boolean;
+    /**
+     * Show Cursor (DECTCEM): `CSI ? 2 5 h`
+     */
+    readonly showCursor: boolean;
     /**
      * Synchronized Output Mode: `CSI ? 2 0 2 6 h`
      *
@@ -1961,4 +1983,113 @@ declare module '@xterm/xterm' {
      */
     readonly wraparoundMode: boolean;
   }
+
+  /**
+   * An object containing a width and height in pixels.
+   */
+  export interface IDimensions {
+    width: number;
+    height: number;
+  }
+
+  /**
+   * An object containing a top and left offset.
+   */
+  export interface IOffset {
+    top: number;
+    left: number;
+  }
+
+  /**
+   * The dimensions of the terminal.
+   */
+  export interface IRenderDimensions {
+    /**
+     * Dimensions measured in CSS pixels (ie. device pixels / device pixel
+     * ratio).
+     */
+    css: {
+      /**
+       * The dimensions of the canvas.
+       */
+      canvas: IDimensions;
+      /**
+       * The dimensions of a single cell.
+       */
+      cell: IDimensions;
+    };
+    /**
+     * Dimensions measured in actual pixels as rendered to the device.
+     */
+    device: {
+      /**
+       * The dimensions of the canvas.
+       */
+      canvas: IDimensions;
+      /**
+       * The dimensions of a single cell.
+       */
+      cell: IDimensions;
+      /**
+       * The dimensions of a single character within a cell, including its
+       * offset within the cell.
+       */
+      char: IDimensions & IOffset;
+    };
+  }
+
+  /**
+   * An object containing a width and height in pixels.
+   */
+  export interface IDimensions {
+    width: number;
+    height: number;
+  }
+
+  /**
+   * An object containing a top and left offset.
+   */
+  export interface IOffset {
+    top: number;
+    left: number;
+  }
+
+  /**
+   * The dimensions of the terminal, this is constructed and available after
+   * {@link Terminal.open} is called.
+   */
+  export interface IRenderDimensions {
+    /**
+     * Dimensions measured in CSS pixels (ie. device pixels / device pixel
+     * ratio).
+     */
+    css: {
+      /**
+       * The dimensions of the canvas which is the full terminal size.
+       */
+      canvas: IDimensions;
+      /**
+       * The dimensions of a single cell.
+       */
+      cell: IDimensions;
+    };
+    /**
+     * Dimensions measured in actual pixels as rendered to the device.
+     */
+    device: {
+      /**
+       * The dimensions of the canvas which is the full terminal size.
+       */
+      canvas: IDimensions;
+      /**
+       * The dimensions of a single cell.
+       */
+      cell: IDimensions;
+      /**
+       * The dimensions of a single character within a cell, including its
+       * offset within the cell.
+       */
+      char: IDimensions & IOffset;
+    };
+  }
 }