src/SelectionManager.ts

   1 /**
   2  * @license MIT
   3  */
   4
   5 import { CharMeasure } from './utils/CharMeasure';
   6 import { CircularList } from './utils/CircularList';
   7 import { EventEmitter } from './EventEmitter';
   8 import * as Mouse from './utils/Mouse';
   9 import { ITerminal } from './Interfaces';
  10 import { SelectionModel } from './SelectionModel';
  11
  12 /**
  13  * The number of pixels the mouse needs to be above or below the viewport in
  14  * order to scroll at the maximum speed.
  15  */
  16 const DRAG_SCROLL_MAX_THRESHOLD = 100;
  17
  18 /**
  19  * The maximum scrolling speed
  20  */
  21 const DRAG_SCROLL_MAX_SPEED = 5;
  22
  23 /**
  24  * The number of milliseconds between drag scroll updates.
  25  */
  26 const DRAG_SCROLL_INTERVAL = 100;
  27
  28 /**
  29  * The amount of time before mousedown events are no longer stacked to create
  30  * double/triple click events.
  31  */
  32 const CLEAR_MOUSE_DOWN_TIME = 400;
  33
  34 /**
  35  * The number of pixels in each direction that the mouse must move before
  36  * mousedown events are no longer stacked to create double/triple click events.
  37  */
  38 const CLEAR_MOUSE_DISTANCE = 10;
  39
  40 // TODO: Move these constants elsewhere, they belong in a buffer or buffer
  41 //       data/line class.
  42 const LINE_DATA_CHAR_INDEX = 1;
  43 const LINE_DATA_WIDTH_INDEX = 2;
  44
  45 export class SelectionManager extends EventEmitter {
  46   protected _model: SelectionModel;
  47
  48   /**
  49    * The amount to scroll every drag scroll update (depends on how far the mouse
  50    * drag is above or below the terminal).
  51    */
  52   private _dragScrollAmount: number;
  53
  54   /**
  55    * The last time the mousedown event fired, this is used to track double and
  56    * triple clicks.
  57    */
  58   private _lastMouseDownTime: number;
  59
  60   /**
  61    * The last position the mouse was clicked [x, y].
  62    */
  63   private _lastMousePosition: [number, number];
  64
  65   /**
  66    * The number of clicks of the mousedown event. This is used to keep track of
  67    * double and triple clicks.
  68    */
  69   private _clickCount: number;
  70
  71   /**
  72    * Whether line select mode is active, this occurs after a triple click.
  73    */
  74   private _isLineSelectModeActive: boolean;
  75
  76   /**
  77    * A setInterval timer that is active while the mouse is down whose callback
  78    * scrolls the viewport when necessary.
  79    */
  80   private _dragScrollIntervalTimer: NodeJS.Timer;
  81
  82   private _bufferTrimListener: any;
  83   private _mouseMoveListener: EventListener;
  84   private _mouseDownListener: EventListener;
  85   private _mouseUpListener: EventListener;
  86
  87   constructor(
  88     private _terminal: ITerminal,
  89     private _buffer: CircularList<any>,
  90     private _rowContainer: HTMLElement,
  91     private _charMeasure: CharMeasure
  92   ) {
  93     super();
  94     this._initListeners();
  95     this.enable();
  96
  97     this._model = new SelectionModel(_terminal);
  98     this._lastMouseDownTime = 0;
  99     this._isLineSelectModeActive = false;
 100   }
 101
 102   /**
 103    * Initializes listener variables.
 104    */
 105   private _initListeners() {
 106     this._bufferTrimListener = (amount: number) => this._onTrim(amount);
 107     this._mouseMoveListener = event => this._onMouseMove(<MouseEvent>event);
 108     this._mouseDownListener = event => this._onMouseDown(<MouseEvent>event);
 109     this._mouseUpListener = event => this._onMouseUp(<MouseEvent>event);
 110   }
 111
 112   /**
 113    * Disables the selection manager. This is useful for when terminal mouse
 114    * are enabled.
 115    */
 116   public disable() {
 117     this._model.selectionStart = null;
 118     this._model.selectionEnd = null;
 119     this.refresh();
 120     this._buffer.off('trim', this._bufferTrimListener);
 121     this._rowContainer.removeEventListener('mousedown', this._mouseDownListener);
 122     this._rowContainer.ownerDocument.removeEventListener('mousemove', this._mouseMoveListener);
 123     this._rowContainer.ownerDocument.removeEventListener('mouseup', this._mouseUpListener);
 124     clearInterval(this._dragScrollIntervalTimer);
 125   }
 126
 127   /**
 128    * Enable the selection manager.
 129    */
 130   public enable() {
 131     // Only adjust the selection on trim, shiftElements is rarely used (only in
 132     // reverseIndex) and delete in a splice is only ever used when the same
 133     // number of elements was just added. Given this is could actually be
 134     // beneficial to leave the selection as is for these cases.
 135     this._buffer.on('trim', this._bufferTrimListener);
 136     this._rowContainer.addEventListener('mousedown', this._mouseDownListener);
 137   }
 138
 139   /**
 140    * Gets the text currently selected.
 141    */
 142   public get selectionText(): string {
 143     const start = this._model.finalSelectionStart;
 144     const end = this._model.finalSelectionEnd;
 145     if (!start || !end) {
 146       return '';
 147     }
 148
 149     // Get first row
 150     const startRowEndCol = start[1] === end[1] ? end[0] : null;
 151     let result: string[] = [];
 152     result.push(this._translateBufferLineToString(this._buffer.get(start[1]), true, start[0], startRowEndCol));
 153
 154     // Get middle rows
 155     for (let i = start[1] + 1; i <= end[1] - 1; i++) {
 156       result.push(this._translateBufferLineToString(this._buffer.get(i), true));
 157     }
 158
 159     // Get final row
 160     if (start[1] !== end[1]) {
 161       result.push(this._translateBufferLineToString(this._buffer.get(end[1]), true, 0, end[0]));
 162     }
 163
 164     return result.join('\n');
 165   }
 166
 167   /**
 168    * Translates a buffer line to a string, with optional start and end columns.
 169    * Wide characters will count as two columns in the resulting string. This
 170    * function is useful for getting the actual text underneath the raw selection
 171    * position.
 172    * @param line The line being translated.
 173    * @param trimRight Whether to trim whitespace to the right.
 174    * @param startCol The column to start at.
 175    * @param endCol The column to end at.
 176    */
 177   private _translateBufferLineToString(line: any, trimRight: boolean, startCol: number = 0, endCol: number = null): string {
 178     // TODO: This function should live in a buffer or buffer line class
 179
 180     // Get full line
 181     let lineString = '';
 182     let widthAdjustedStartCol = startCol;
 183     let widthAdjustedEndCol = endCol;
 184     for (let i = 0; i < line.length; i++) {
 185       const char = line[i];
 186       lineString += char[LINE_DATA_CHAR_INDEX];
 187       // Adjust start and end cols for wide characters if they affect their
 188       // column indexes
 189       if (char[LINE_DATA_WIDTH_INDEX] === 0) {
 190         if (startCol >= i) {
 191           widthAdjustedStartCol--;
 192         }
 193         if (endCol >= i) {
 194           widthAdjustedEndCol--;
 195         }
 196       }
 197     }
 198
 199     // Calculate the final end col by trimming whitespace on the right of the
 200     // line if needed.
 201     let finalEndCol = widthAdjustedEndCol || line.length;
 202     if (trimRight) {
 203       const rightWhitespaceIndex = lineString.search(/\s+$/);
 204       if (rightWhitespaceIndex !== -1) {
 205         finalEndCol = Math.min(finalEndCol, rightWhitespaceIndex);
 206       }
 207       // Return the empty string if only trimmed whitespace is selected
 208       if (finalEndCol <= widthAdjustedStartCol) {
 209         return '';
 210       }
 211     }
 212
 213     return lineString.substring(widthAdjustedStartCol, finalEndCol);
 214   }
 215
 216   /**
 217    * Redraws the selection.
 218    */
 219   public refresh(): void {
 220     this.emit('refresh', { start: this._model.finalSelectionStart, end: this._model.finalSelectionEnd });
 221   }
 222
 223   /**
 224    * Selects all text within the terminal.
 225    */
 226   public selectAll(): void {
 227     this._model.isSelectAllActive = true;
 228     this.refresh();
 229   }
 230
 231   /**
 232    * Handle the buffer being trimmed, adjust the selection position.
 233    * @param amount The amount the buffer is being trimmed.
 234    */
 235   private _onTrim(amount: number) {
 236     const needsRefresh = this._model.onTrim(amount);
 237     if (needsRefresh) {
 238       this.refresh();
 239     }
 240   }
 241
 242   /**
 243    * Gets the 0-based [x, y] buffer coordinates of the current mouse event.
 244    * @param event The mouse event.
 245    */
 246   private _getMouseBufferCoords(event: MouseEvent): [number, number] {
 247     const coords = Mouse.getCoords(event, this._rowContainer, this._charMeasure, this._terminal.cols, this._terminal.rows);
 248     // Convert to 0-based
 249     coords[0]--;
 250     coords[1]--;
 251     // Convert viewport coords to buffer coords
 252     coords[1] += this._terminal.ydisp;
 253     return coords;
 254   }
 255
 256   /**
 257    * Gets the amount the viewport should be scrolled based on how far out of the
 258    * terminal the mouse is.
 259    * @param event The mouse event.
 260    */
 261   private _getMouseEventScrollAmount(event: MouseEvent): number {
 262     let offset = Mouse.getCoordsRelativeToElement(event, this._rowContainer)[1];
 263     const terminalHeight = this._terminal.rows * this._charMeasure.height;
 264     if (offset >= 0 && offset <= terminalHeight) {
 265       return 0;
 266     }
 267     if (offset > terminalHeight) {
 268       offset -= terminalHeight;
 269     }
 270
 271     offset = Math.min(Math.max(offset, -DRAG_SCROLL_MAX_THRESHOLD), DRAG_SCROLL_MAX_THRESHOLD);
 272     offset /= DRAG_SCROLL_MAX_THRESHOLD;
 273     return (offset / Math.abs(offset)) + Math.round(offset * (DRAG_SCROLL_MAX_SPEED - 1));
 274   }
 275
 276   /**
 277    * Handles te mousedown event, setting up for a new selection.
 278    * @param event The mousedown event.
 279    */
 280   private _onMouseDown(event: MouseEvent) {
 281     // Only action the primary button
 282     if (event.button !== 0) {
 283       return;
 284     }
 285
 286     this._setMouseClickCount(event);
 287
 288     if (event.shiftKey) {
 289       this._onShiftClick(event);
 290     } else {
 291       if (this._clickCount === 1) {
 292           this._onSingleClick(event);
 293       } else if (this._clickCount === 2) {
 294           this._onDoubleClick(event);
 295       } else if (this._clickCount === 3) {
 296           this._onTripleClick(event);
 297       }
 298     }
 299
 300     // Listen on the document so that dragging outside of viewport works
 301     this._rowContainer.ownerDocument.addEventListener('mousemove', this._mouseMoveListener);
 302     this._rowContainer.ownerDocument.addEventListener('mouseup', this._mouseUpListener);
 303     this._dragScrollIntervalTimer = setInterval(() => this._dragScroll(), DRAG_SCROLL_INTERVAL);
 304     this.refresh();
 305   }
 306
 307   /**
 308    * Performs a shift click, setting the selection end position to the mouse
 309    * position.
 310    * @param event The mouse event.
 311    */
 312   private _onShiftClick(event: MouseEvent): void {
 313     if (this._model.selectionStart) {
 314       this._model.selectionEnd = this._getMouseBufferCoords(event);
 315     }
 316   }
 317
 318   /**
 319    * Performs a single click, resetting relevant state and setting the selection
 320    * start position.
 321    * @param event The mouse event.
 322    */
 323   private _onSingleClick(event: MouseEvent): void {
 324     this._model.selectionStartLength = 0;
 325     this._model.isSelectAllActive = false;
 326     this._isLineSelectModeActive = false;
 327     this._model.selectionStart = this._getMouseBufferCoords(event);
 328     if (this._model.selectionStart) {
 329       this._model.selectionEnd = null;
 330       // If the mouse is over the second half of a wide character, adjust the
 331       // selection to cover the whole character
 332       const char = this._buffer.get(this._model.selectionStart[1])[this._model.selectionStart[0]];
 333       if (char[LINE_DATA_WIDTH_INDEX] === 0) {
 334         this._model.selectionStart[0]++;
 335       }
 336     }
 337   }
 338
 339   /**
 340    * Performs a double click, selecting the current work.
 341    * @param event The mouse event.
 342    */
 343   private _onDoubleClick(event: MouseEvent): void {
 344     const coords = this._getMouseBufferCoords(event);
 345     if (coords) {
 346       this._selectWordAt(coords);
 347     }
 348   }
 349
 350   /**
 351    * Performs a triple click, selecting the current line and activating line
 352    * select mode.
 353    * @param event The mouse event.
 354    */
 355   private _onTripleClick(event: MouseEvent): void {
 356     const coords = this._getMouseBufferCoords(event);
 357     if (coords) {
 358       this._isLineSelectModeActive = true;
 359       this._selectLineAt(coords[1]);
 360     }
 361   }
 362
 363   /**
 364    * Sets the number of clicks for the current mousedown event based on the time
 365    * and position of the last mousedown event.
 366    * @param event The mouse event.
 367    */
 368   private _setMouseClickCount(event: MouseEvent): void {
 369     let currentTime = (new Date()).getTime();
 370     if (currentTime - this._lastMouseDownTime > CLEAR_MOUSE_DOWN_TIME || this._distanceFromLastMousePosition(event) > CLEAR_MOUSE_DISTANCE) {
 371       this._clickCount = 0;
 372     }
 373     this._lastMouseDownTime = currentTime;
 374     this._lastMousePosition = [event.pageX, event.pageY];
 375     this._clickCount++;
 376   }
 377
 378   /**
 379    * Gets the maximum number of pixels in each direction the mouse has moved.
 380    * @param event The mouse event.
 381    */
 382   private _distanceFromLastMousePosition(event: MouseEvent): number {
 383     const result = Math.max(
 384         Math.abs(this._lastMousePosition[0] - event.pageX),
 385         Math.abs(this._lastMousePosition[1] - event.pageY));
 386     return result;
 387   }
 388
 389   /**
 390    * Handles the mousemove event when the mouse button is down, recording the
 391    * end of the selection and refreshing the selection.
 392    * @param event The mousemove event.
 393    */
 394   private _onMouseMove(event: MouseEvent) {
 395     // Record the previous position so we know whether to redraw the selection
 396     // at the end.
 397     const previousSelectionEnd = this._model.selectionEnd ? [this._model.selectionEnd[0], this._model.selectionEnd[1]] : null;
 398
 399     // Set the initial selection end based on the mouse coordinates
 400     this._model.selectionEnd = this._getMouseBufferCoords(event);
 401
 402     // Select the entire line if line select mode is active.
 403     if (this._isLineSelectModeActive) {
 404       if (this._model.selectionEnd[1] < this._model.selectionStart[1]) {
 405         this._model.selectionEnd[0] = 0;
 406       } else {
 407         this._model.selectionEnd[0] = this._terminal.cols;
 408       }
 409     }
 410
 411     // Determine the amount of scrolling that will happen.
 412     this._dragScrollAmount = this._getMouseEventScrollAmount(event);
 413
 414     // If the cursor was above or below the viewport, make sure it's at the
 415     // start or end of the viewport respectively.
 416     if (this._dragScrollAmount > 0) {
 417       this._model.selectionEnd[0] = this._terminal.cols - 1;
 418     } else if (this._dragScrollAmount < 0) {
 419       this._model.selectionEnd[0] = 0;
 420     }
 421
 422     // If the character is a wide character include the cell to the right in the
 423     // selection. Note that selections at the very end of the line will never
 424     // have a character.
 425     if (this._model.selectionEnd[1] < this._buffer.length) {
 426       const char = this._buffer.get(this._model.selectionEnd[1])[this._model.selectionEnd[0]];
 427       if (char && char[2] === 0) {
 428         this._model.selectionEnd[0]++;
 429       }
 430     }
 431
 432     // Only draw here if the selection changes.
 433     if (!previousSelectionEnd ||
 434         previousSelectionEnd[0] !== this._model.selectionEnd[0] ||
 435         previousSelectionEnd[1] !== this._model.selectionEnd[1]) {
 436       this.refresh();
 437     }
 438   }
 439
 440   /**
 441    * The callback that occurs every DRAG_SCROLL_INTERVAL ms that does the
 442    * scrolling of the viewport.
 443    */
 444   private _dragScroll() {
 445     if (this._dragScrollAmount) {
 446       this._terminal.scrollDisp(this._dragScrollAmount, false);
 447       // Re-evaluate selection
 448       if (this._dragScrollAmount > 0) {
 449         this._model.selectionEnd = [this._terminal.cols - 1, this._terminal.ydisp + this._terminal.rows];
 450       } else {
 451         this._model.selectionEnd = [0, this._terminal.ydisp];
 452       }
 453       this.refresh();
 454     }
 455   }
 456
 457   /**
 458    * Handles the mouseup event, removing the mousemove listener when
 459    * appropriate.
 460    * @param event The mouseup event.
 461    */
 462   private _onMouseUp(event: MouseEvent) {
 463     this._dragScrollAmount = 0;
 464     if (!this._model.selectionStart) {
 465       return;
 466     }
 467     this._rowContainer.ownerDocument.removeEventListener('mousemove', this._mouseMoveListener);
 468     this._rowContainer.ownerDocument.removeEventListener('mouseup', this._mouseUpListener);
 469   }
 470
 471   /**
 472    * Converts a viewport column to the character index on the buffer line, the
 473    * latter takes into account wide characters.
 474    * @param coords The coordinates to find the 2 index for.
 475    */
 476   private _convertViewportColToCharacterIndex(bufferLine: any, coords: [number, number]): number {
 477     let charIndex = coords[0];
 478     for (let i = 0; coords[0] >= i; i++) {
 479       const char = bufferLine[i];
 480       if (char[LINE_DATA_WIDTH_INDEX] === 0) {
 481         charIndex--;
 482       }
 483     }
 484     return charIndex;
 485   }
 486
 487   /**
 488    * Selects the word at the coordinates specified. Words are defined as all
 489    * non-whitespace characters.
 490    * @param coords The coordinates to get the word at.
 491    */
 492   protected _selectWordAt(coords: [number, number]): void {
 493     const bufferLine = this._buffer.get(coords[1]);
 494     const line = this._translateBufferLineToString(bufferLine, false);
 495
 496     // Get actual index, taking into consideration wide characters
 497     let endIndex = this._convertViewportColToCharacterIndex(bufferLine, coords);
 498     let startIndex = endIndex;
 499
 500     // Record offset to be used later
 501     const charOffset = coords[0] - startIndex;
 502     let leftWideCharCount = 0;
 503     let rightWideCharCount = 0;
 504
 505     if (line.charAt(startIndex) === ' ') {
 506       // Expand until non-whitespace is hit
 507       while (startIndex > 0 && line.charAt(startIndex - 1) === ' ') {
 508         startIndex--;
 509       }
 510       while (endIndex < line.length && line.charAt(endIndex + 1) === ' ') {
 511         endIndex++;
 512       }
 513     } else {
 514       // Expand until whitespace is hit. This algorithm works by scanning left
 515       // and right from the starting position, keeping both the index format
 516       // (line) and the column format (bufferLine) in sync. When a wide
 517       // character is hit, it is recorded and the column index is adjusted.
 518       let startCol = coords[0];
 519       let endCol = coords[0];
 520       // Consider the initial position, skip it and increment the wide char
 521       // variable
 522       if (bufferLine[startCol][LINE_DATA_WIDTH_INDEX] === 0) {
 523         leftWideCharCount++;
 524         startCol--;
 525       }
 526       if (bufferLine[endCol][LINE_DATA_WIDTH_INDEX] === 2) {
 527         rightWideCharCount++;
 528         endCol++;
 529       }
 530       // Expand the string in both directions until a space is hit
 531       while (startIndex > 0 && line.charAt(startIndex - 1) !== ' ') {
 532         if (bufferLine[startCol - 1][LINE_DATA_WIDTH_INDEX] === 0) {
 533           // If the next character is a wide char, record it and skip the column
 534           leftWideCharCount++;
 535           startCol--;
 536         }
 537         startIndex--;
 538         startCol--;
 539       }
 540       while (endIndex + 1 < line.length && line.charAt(endIndex + 1) !== ' ') {
 541         if (bufferLine[endCol + 1][LINE_DATA_WIDTH_INDEX] === 2) {
 542           // If the next character is a wide char, record it and skip the column
 543           rightWideCharCount++;
 544           endCol++;
 545         }
 546         endIndex++;
 547         endCol++;
 548       }
 549     }
 550
 551     // Record the resulting selection
 552     this._model.selectionStart = [startIndex + charOffset - leftWideCharCount, coords[1]];
 553     this._model.selectionStartLength = Math.min(endIndex - startIndex + leftWideCharCount + rightWideCharCount + 1/*include endIndex char*/, this._terminal.cols);
 554   }
 555
 556   /**
 557    * Selects the line specified.
 558    * @param line The line index.
 559    */
 560   protected _selectLineAt(line: number): void {
 561     this._model.selectionStart = [0, line];
 562     this._model.selectionStartLength = this._terminal.cols;
 563   }
 564 }