Add initial decorations API

addons/xterm-addon-webgl/src/WebglRenderer.ts

@@ -204,6 +204,10 @@ export class WebglRenderer extends Disposable implements IRenderer {
     this._onRequestRedraw.fire({ start: 0, end: this._terminal.rows - 1 });
   }
 
+  public onDecorationsChanged(): void {
+    // TBD
+  }
+
   public onCursorMove(): void {
     for (const l of this._renderLayers) {
       l.onCursorMove(this._terminal);

demo/client.ts

@@ -52,6 +52,7 @@ let protocol;
 let socketURL;
 let socket;
 let pid;
+let decorationHandle;
 
 type AddonType = 'attach' | 'fit' | 'search' | 'serialize' | 'unicode11' | 'web-links' | 'webgl' | 'ligatures';
 
@@ -147,6 +148,7 @@ if (document.location.pathname === '/test') {
   createTerminal();
   document.getElementById('dispose').addEventListener('click', disposeRecreateButtonHandler);
   document.getElementById('serialize').addEventListener('click', serializeButtonHandler);
+  document.getElementById('decorations').addEventListener('click', decorationsButtonHandler);
 }
 
 function createTerminal(): void {
@@ -431,3 +433,17 @@ function serializeButtonHandler(): void {
     term.write(output);
   }
 }
+
+function decorationsButtonHandler(): void {
+  if (decorationHandle) {
+    term.removeDeoration(decorationHandle);
+    decorationHandle = null;
+  } else {
+    decorationHandle = term.addDecoration({
+      startColumn: 3, endColumn: 13,
+      startRow: 3, endRow: 8,
+      fillStyle: 'rgba(255, 0, 0, 0.7)',
+      strokeStyle: 'rgba(0, 0, 255, 0.7)',
+    });
+  }
+}

demo/index.html

@@ -22,6 +22,7 @@ <h3>Options</h3>
       <div id="options-container"></div>
     </div>
     <div>
+      <button id="decorations">Toggle decorations</button>
       <h3>Addons</h3>
       <p>Addons can be loaded and unloaded on a particular terminal to extend its functionality.</p>
       <div id="addons-container"></div>

src/browser/Terminal.ts

@@ -39,13 +39,13 @@ import { MouseZoneManager } from 'browser/MouseZoneManager';
 import { AccessibilityManager } from './AccessibilityManager';
 import { ITheme, IMarker, IDisposable, ISelectionPosition, ILinkProvider } from 'xterm';
 import { DomRenderer } from 'browser/renderer/dom/DomRenderer';
-import { IKeyboardEvent, KeyboardResultType, CoreMouseEventType, CoreMouseButton, CoreMouseAction, ITerminalOptions, ScrollSource, IAnsiColorChangeEvent } from 'common/Types';
+import { IKeyboardEvent, KeyboardResultType, CoreMouseEventType, CoreMouseButton, CoreMouseAction, ITerminalOptions, ScrollSource, IAnsiColorChangeEvent, IDecorationElement, IDecorationHandle } from 'common/Types';
 import { evaluateKeyboardEvent } from 'common/input/Keyboard';
 import { EventEmitter, IEvent, forwardEvent } from 'common/EventEmitter';
 import { DEFAULT_ATTR_DATA } from 'common/buffer/BufferLine';
 import { ColorManager } from 'browser/ColorManager';
 import { RenderService } from 'browser/services/RenderService';
-import { ICharSizeService, IRenderService, IMouseService, ISelectionService, ISoundService, ICoreBrowserService, ICharacterJoinerService } from 'browser/services/Services';
+import { ICharSizeService, IRenderService, IMouseService, ISelectionService, ISoundService, ICoreBrowserService, ICharacterJoinerService, IDecorationService } from 'browser/services/Services';
 import { CharSizeService } from 'browser/services/CharSizeService';
 import { IBuffer } from 'common/buffer/Types';
 import { MouseService } from 'browser/services/MouseService';
@@ -55,6 +55,7 @@ import { CoreTerminal } from 'common/CoreTerminal';
 import { ITerminalOptions as IInitializedTerminalOptions } from 'common/services/Services';
 import { rgba } from 'browser/Color';
 import { CharacterJoinerService } from 'browser/services/CharacterJoinerService';
+import { DecorationService } from 'browser/services/DecorationService';
 
 // Let it work inside Node.js for automated testing purposes.
 const document: Document = (typeof window !== 'undefined') ? window.document : null as any;
@@ -86,6 +87,7 @@ export class Terminal extends CoreTerminal implements ITerminal {
   private _characterJoinerService: ICharacterJoinerService | undefined;
   private _selectionService: ISelectionService | undefined;
   private _soundService: ISoundService | undefined;
+  private _decorationService: IDecorationService | undefined;
 
   /**
    * Records whether the keydown event has already been handled and triggered a data event, if so
@@ -456,6 +458,9 @@ export class Terminal extends CoreTerminal implements ITerminal {
     this._characterJoinerService = this._instantiationService.createInstance(CharacterJoinerService);
     this._instantiationService.setService(ICharacterJoinerService, this._characterJoinerService);
 
+    this._decorationService = this.register(this._instantiationService.createInstance(DecorationService));
+    this._instantiationService.setService(IDecorationService, this._decorationService);
+
     const renderer = this._createRenderer();
     this._renderService = this.register(this._instantiationService.createInstance(RenderService, renderer, this.rows, this.screenElement));
     this._instantiationService.setService(IRenderService, this._renderService);
@@ -515,6 +520,7 @@ export class Terminal extends CoreTerminal implements ITerminal {
         this.viewport!.syncScrollArea();
       }
       this._selectionService!.refresh();
+      this._renderService!.onDecorationsChanged();
     }));
     this.register(addDisposableDomListener(this._viewportElement, 'scroll', () => this._selectionService!.refresh()));
 
@@ -1280,6 +1286,22 @@ export class Terminal extends CoreTerminal implements ITerminal {
     // return this.options.bellStyle === 'sound' ||
     //     this.options.bellStyle === 'both';
   }
+
+  public addDecoration(element: IDecorationElement): IDecorationHandle | undefined{
+    const ret = this._decorationService?.addDecoration(element);
+    this._renderService?.onDecorationsChanged();
+    return ret;
+  }
+  public removeDeoration(handle: IDecorationHandle): boolean {
+    const ret = !!(this._decorationService?.removeDeoration(handle));
+    this._renderService?.onDecorationsChanged();
+    return ret;
+  }
+  public clearDecorations(): number {
+    const ret = this._decorationService?.clearDecorations() || 0;
+    this._renderService?.onDecorationsChanged();
+    return ret;
+  }
 }
 
 /**

src/browser/TestUtils.test.ts

@@ -9,7 +9,7 @@ import { ICharacterJoinerService, ICharSizeService, IMouseService, IRenderServic
 import { IRenderDimensions, IRenderer, IRequestRedrawEvent } from 'browser/renderer/Types';
 import { IColorSet, ILinkMatcherOptions, ITerminal, ILinkifier, ILinkifier2, IBrowser, IViewport, IColorManager, ICompositionHelper, CharacterJoinerHandler } from 'browser/Types';
 import { IBuffer, IBufferStringIterator, IBufferSet } from 'common/buffer/Types';
-import { IBufferLine, ICellData, IAttributeData, ICircularList, XtermListener, ICharset, ITerminalOptions } from 'common/Types';
+import { IBufferLine, ICellData, IAttributeData, ICircularList, XtermListener, ICharset, ITerminalOptions, IDecorationElement } from 'common/Types';
 import { Buffer } from 'common/buffer/Buffer';
 import * as Browser from 'common/Platform';
 import { Terminal } from 'browser/Terminal';
@@ -198,6 +198,15 @@ export class MockTerminal implements ITerminal {
   }
   public registerCharacterJoiner(handler: CharacterJoinerHandler): number { return 0; }
   public deregisterCharacterJoiner(joinerId: number): void { }
+  public addDecoration(element: IDecorationElement): number | undefined {
+    throw new Error('Method not implemented.');
+  }
+  public removeDeoration(handle: number): boolean {
+    throw new Error('Method not implemented.');
+  }
+  public clearDecorations(): number {
+    throw new Error('Method not implemented.');
+  }
 }
 
 export class MockBuffer implements IBuffer {
@@ -280,6 +289,7 @@ export class MockRenderer implements IRenderer {
   public onBlur(): void { }
   public onFocus(): void { }
   public onSelectionChanged(start: [number, number], end: [number, number]): void { }
+  public onDecorationsChanged(): void { }
   public onCursorMove(): void { }
   public onOptionsChanged(): void { }
   public onDevicePixelRatioChange(): void { }
@@ -402,6 +412,9 @@ export class MockRenderService implements IRenderService {
   public onSelectionChanged(start: [number, number], end: [number, number], columnSelectMode: boolean): void {
     throw new Error('Method not implemented.');
   }
+  public onDecorationsChanged(): void {
+    throw new Error('Method not implemented.');
+  }
   public onCursorMove(): void {
     throw new Error('Method not implemented.');
   }

src/browser/Types.d.ts

@@ -5,7 +5,7 @@
 
 import { IDisposable, IMarker, ISelectionPosition } from 'xterm';
 import { IEvent } from 'common/EventEmitter';
-import { ICoreTerminal, CharData, ITerminalOptions } from 'common/Types';
+import { ICoreTerminal, CharData, ITerminalOptions, IDecorationElement, IDecorationHandle } from 'common/Types';
 import { IMouseService, IRenderService } from './services/Services';
 import { IBuffer, IBufferSet } from 'common/buffer/Types';
 import { IFunctionIdentifier, IParams } from 'common/parser/Types';
@@ -81,6 +81,9 @@ export interface IPublicTerminal extends IDisposable {
   paste(data: string): void;
   refresh(start: number, end: number): void;
   reset(): void;
+  addDecoration(element: IDecorationElement): IDecorationHandle | undefined;
+  removeDeoration(handle: IDecorationHandle): boolean;
+  clearDecorations(): number;
 }
 
 export type CustomKeyEventHandler = (event: KeyboardEvent) => boolean;

src/browser/public/Terminal.ts

@@ -5,7 +5,7 @@
 
 import { Terminal as ITerminalApi, ITerminalOptions, IMarker, IDisposable, ILinkMatcherOptions, ITheme, ILocalizableStrings, ITerminalAddon, ISelectionPosition, IBuffer as IBufferApi, IBufferNamespace as IBufferNamespaceApi, IBufferLine as IBufferLineApi, IBufferCell as IBufferCellApi, IParser, IFunctionIdentifier, ILinkProvider, IUnicodeHandling, IUnicodeVersionProvider, FontWeight } from 'xterm';
 import { ITerminal } from 'browser/Types';
-import { IBufferLine, ICellData } from 'common/Types';
+import { IBufferLine, ICellData, IDecorationElement, IDecorationHandle } from 'common/Types';
 import { IBuffer, IBufferSet } from 'common/buffer/Types';
 import { CellData } from 'common/buffer/CellData';
 import { Terminal as TerminalCore } from '../Terminal';
@@ -175,6 +175,16 @@ export class Terminal implements ITerminalApi {
   public paste(data: string): void {
     this._core.paste(data);
   }
+  public addDecoration(element: IDecorationElement): IDecorationHandle | undefined {
+    return this._core.addDecoration(element);
+  }
+  public removeDeoration(handle: IDecorationHandle): boolean {
+    return this._core.removeDeoration(handle);
+  }
+  public clearDecorations(): number {
+    return this._core.clearDecorations();
+  }
+
   public getOption(key: 'bellSound' | 'bellStyle' | 'cursorStyle' | 'fontFamily' | 'logLevel' | 'rendererType' | 'termName' | 'wordSeparator'): string;
   public getOption(key: 'allowTransparency' | 'altClickMovesCursor' | 'cancelEvents' | 'convertEol' | 'cursorBlink' | 'disableStdin' | 'macOptionIsMeta' | 'rightClickSelectsWord' | 'popOnBell' | 'visualBell'): boolean;
   public getOption(key: 'cols' | 'fontSize' | 'letterSpacing' | 'lineHeight' | 'rows' | 'tabStopWidth' | 'scrollback'): number;

src/browser/renderer/BaseRenderLayer.ts

@@ -79,6 +79,7 @@ export abstract class BaseRenderLayer implements IRenderLayer {
   public onCursorMove(): void {}
   public onGridChanged(startRow: number, endRow: number): void {}
   public onSelectionChanged(start: [number, number] | undefined, end: [number, number] | undefined, columnSelectMode: boolean = false): void {}
+  public onDecorationsChanged(): void {}
 
   public setColors(colorSet: IColorSet): void {
     this._refreshCharAtlas(colorSet);

src/browser/renderer/DecorationRenderLayer.ts

@@ -0,0 +1,60 @@
+/**
+ * Copyright (c) 2017 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { IRenderDimensions } from 'browser/renderer/Types';
+import { BaseRenderLayer } from 'browser/renderer/BaseRenderLayer';
+import { IColorSet } from 'browser/Types';
+import { IBufferService, IOptionsService } from 'common/services/Services';
+import { IDecorationService } from 'browser/services/Services';
+
+
+export class DecorationRenderLayer extends BaseRenderLayer {
+
+  private _decorationService: IDecorationService;
+
+  constructor(
+    container: HTMLElement,
+    zIndex: number,
+    colors: IColorSet,
+    rendererId: number,
+    @IDecorationService decorationService: IDecorationService,
+    @IBufferService bufferService: IBufferService,
+    @IOptionsService optionsService: IOptionsService,
+  ) {
+    super(container, 'decorations', zIndex, true, colors, rendererId, bufferService, optionsService);
+    this._decorationService = decorationService;
+  }
+
+  public reset(): void {
+    this._clearAll();
+  }
+
+  public onDecorationsChanged(): void {
+    // Remove all decorations
+    this._clearAll();
+
+    this._decorationService.forEachDecoration((element) => {
+      // Translate from buffer position to viewport position
+      const viewportStartRow = element.startRow - this._bufferService.buffer.ydisp;
+      const viewportEndRow = element.endRow - this._bufferService.buffer.ydisp;
+      const viewportCappedStartRow = Math.max(viewportStartRow, 0);
+      const viewportCappedEndRow = Math.min(viewportEndRow, this._bufferService.rows - 1);
+      const width = element.endColumn - element.startColumn;
+      const height = viewportCappedEndRow - viewportCappedStartRow + 1;
+      if (viewportStartRow <= viewportEndRow) {
+        if (element.fillStyle) {
+          this._ctx.fillStyle = element.fillStyle;
+          this._fillCells(element.startColumn, viewportCappedStartRow, width, height);
+        }
+        if (element.strokeStyle) {
+          this._ctx.strokeStyle = element.strokeStyle;
+          this._strokeRectAtCell(element.startColumn, viewportCappedStartRow, width, height);
+        }
+      }
+      return false;
+    });
+  }
+
+}

src/browser/renderer/Renderer.ts

@@ -14,6 +14,7 @@ import { ICharSizeService, ICoreBrowserService } from 'browser/services/Services
 import { IBufferService, IOptionsService, ICoreService, IInstantiationService } from 'common/services/Services';
 import { removeTerminalFromCache } from 'browser/renderer/atlas/CharAtlasCache';
 import { EventEmitter, IEvent } from 'common/EventEmitter';
+import { DecorationRenderLayer } from 'browser/renderer/DecorationRenderLayer';
 
 let nextRendererId = 1;
 
@@ -36,15 +37,16 @@ export class Renderer extends Disposable implements IRenderer {
     @IInstantiationService instantiationService: IInstantiationService,
     @IBufferService private readonly _bufferService: IBufferService,
     @ICharSizeService private readonly _charSizeService: ICharSizeService,
-    @IOptionsService private readonly _optionsService: IOptionsService
+    @IOptionsService private readonly _optionsService: IOptionsService,
   ) {
     super();
     const allowTransparency = this._optionsService.options.allowTransparency;
     this._renderLayers = [
       instantiationService.createInstance(TextRenderLayer, this._screenElement, 0, this._colors, allowTransparency, this._id),
       instantiationService.createInstance(SelectionRenderLayer, this._screenElement, 1, this._colors, this._id),
       instantiationService.createInstance(LinkRenderLayer, this._screenElement, 2, this._colors, this._id, linkifier, linkifier2),
-      instantiationService.createInstance(CursorRenderLayer, this._screenElement, 3, this._colors, this._id, this._onRequestRedraw)
+      instantiationService.createInstance(DecorationRenderLayer, this._screenElement, 3, this._colors, this._id),
+      instantiationService.createInstance(CursorRenderLayer, this._screenElement, 4, this._colors, this._id, this._onRequestRedraw),
     ];
     this.dimensions = {
       scaledCharWidth: 0,
@@ -121,6 +123,10 @@ export class Renderer extends Disposable implements IRenderer {
     this._runOperation(l => l.onSelectionChanged(start, end, columnSelectMode));
   }
 
+  public onDecorationsChanged(): void {
+    this._runOperation(l => l.onDecorationsChanged());
+  }
+
   public onCursorMove(): void {
     this._runOperation(l => l.onCursorMove());
   }

src/browser/renderer/Types.d.ts

@@ -48,6 +48,7 @@ export interface IRenderer extends IDisposable {
   onBlur(): void;
   onFocus(): void;
   onSelectionChanged(start: [number, number] | undefined, end: [number, number] | undefined, columnSelectMode: boolean): void;
+  onDecorationsChanged(): void;
   onCursorMove(): void;
   onOptionsChanged(): void;
   clear(): void;
@@ -91,6 +92,11 @@ export interface IRenderLayer extends IDisposable {
    */
   onSelectionChanged(start: [number, number] | undefined, end: [number, number] | undefined, columnSelectMode: boolean): void;
 
+  /**
+   * Called when decorations change
+   */
+  onDecorationsChanged(): void;
+
   /**
    * Resize the render layer.
    */

src/browser/renderer/dom/DomRenderer.ts

@@ -337,6 +337,10 @@ export class DomRenderer extends Disposable implements IRenderer {
     return element;
   }
 
+  public onDecorationsChanged(): void {
+    // TBD
+  }
+
   public onCursorMove(): void {
     // No-op, the cursor is drawn when rows are drawn
   }