Terminal Selection

This section is about the selection functionality of the Terminal (get the selection range, move the selection...)

From/To vs Anchor/Focus

The concept of anchor and focus (obtained from getTerminalSelection) is very useful, as it allows us to use forward and backward selection as needed.

When you create the selection, the anchor position is where you start creating the selection, and the focus position is the end of the selection and the current cursor position. For editing operations, however, the direction of the selection doesn't matter. In this case, it is more appropriate to think in terms of from and to position (obtained from getTerminalSelectionRange).

This example includes the following selection values:

  • Has selection: false

  • Selected text:

    • anchor.line: 1

    • anchor.column: 2

    • focus.line: 1

    • focus.column: 2

makeSelection.js

Copy 
import React from 'react';

export default ({ uiHelper, selectorsHelper, terminalId }) => {
  const connect = uiHelper.posConnect;

  const Selection = ({ hasSelection, selectedText, selection }) => (
    <div style={{ color: 'white' }}>
      <strong>Has selection: {`${hasSelection}`}</strong>
      <ul
        style={{
          padding: '5px',
          margin: '0',
          color: 'white',
          listStyle: 'none',
        }}
      >
        <li>Selected text: {selectedText}</li>
        <li>anchor.line: {selection.anchor.line}</li>
        <li>anchor.column: {selection.anchor.column}</li>
        <li>focus.line: {selection.focus.line}</li>
        <li>focus.column: {selection.focus.column}</li>
      </ul>
    </div>
  );

  const mapStateToPropsFactory = () => {
    const getTerminalSelection = selectorsHelper.make('getTerminalSelection');
    const hasTerminalSelection = selectorsHelper.make('hasTerminalSelection');
    const getTerminalSelectionText = selectorsHelper.make('getTerminalSelectionText');

    return (state) => ({
      hasSelection: hasTerminalSelection(state, { terminalId }),
      selectedText: getTerminalSelectionText(state, { terminalId }),
      selection: getTerminalSelection(state, { terminalId }),
    });
  };

  return connect(mapStateToPropsFactory)(Selection);
};

POSWebPluginMain.js

Copy 
import React from 'react';
import makeSelection from './makeSelection.js';

export default class Plugin {
  constructor({ uiHelper, dispatchersHelper, diHelper }) {
    this._uiHelper = uiHelper;
    this._dispatchersHelper = dispatchersHelper;
    this._diHelper = diHelper;

    diHelper.useValues({
      terminalId: '1',
    });
    diHelper.useFactories({
      Selection: makeSelection,
    });
  }

  onInit() {
    this._diHelper.invoke(this._createTerminal);
    this._diHelper.invoke(this._putComponents);
  }

  _createTerminal = ({ dispatchersHelper, terminalId }) => {
    dispatchersHelper.dispatch('createTerminal', {
      terminal: { id: terminalId },
    });
  };

  _putComponents = ({ uiHelper, Selection, terminalId }) => {
    const { putComponent, POSComponent } = uiHelper;

    putComponent('Example', () => (
      <div style={{ background: '#555', lineHeight: 1.1 }}>
        <POSComponent componentName="Terminal" terminalId={terminalId} />
        <Selection />
      </div>
    ));
  };
}

index.js

Copy 
import POSWebPluginMain from './POSWebPluginMain.js';

export default POSWebPluginMain;

package.json

Copy 
{
  "name": "plugin-test",
  "version": "1.0.0",
  "orion": {
    "dispatchersHelper": {
      "actionCreators": {
        "consumes": {
          "@orion/terminals": [
            "createTerminal"
          ]
        }
      }
    },
    "selectorsHelper": {
      "selectorFactories": {
        "consumes": {
          "@orion/terminals": [
            "getTerminalSelection",
            "hasTerminalSelection",
            "getTerminalSelectionText"
          ]
        }
      }
    }
  }
}

getTerminalSelection

Returns the selection of the specified terminal. The selection is an object with anchor and focus. See the difference between selection and range.

Usage
Copy 
getTerminalSelection(state: Object, { terminalId: String }): {
anchor: { line: Number, column: Number },
focus: { line: Number, column: Number },
};

  • state Object

    Required. The global state of the application.

  • terminalId String

    Required. The ID of the terminal to get the selection.

Returns

  • Object

    Returns an object with the selection of the terminal.

Example
Copy 
const state = storeHelper.getState();
const getTerminalSelection = selectorsHelper.make('getTerminalSelection');
const selection = getTerminalSelection(state, { terminalId });
const { anchor, focus } = selection;

getTerminalSelectionRange

Returns the selection range of the specified terminal. The range is an object with from and to. See the difference between range and selection.

Usage
Copy 
getTerminalSelectionRange(state: Object, { terminalId: String }): {
from: { line: Number, column: Number },
to: { line: Number, column: Number },
};

  • state Object

    Required. The global state of the application.

  • terminalId String

    Required. The ID of the terminal to get the selection range.

Returns

  • Object

    Returns an object with the selection of the terminal.

Example
Copy 
const state = storeHelper.getState();
const getTerminalSelectionRange = selectorsHelper.make('getTerminalSelectionRange');
const selectionRange = getTerminalSelectionRange(state, { terminalId });
const { from, to } = selectionRange;

hasTerminalSelection

Check if the specified terminal has a selection.

Usage
Copy 
hasTerminalSelection(state: Object, { terminalId: String }): Boolean;

  • state Object

    Required. The global state of the application.

  • terminalId String

    Required. The ID of the terminal to check if it has a selection.

Returns

  • Boolean

    Returns true if the specified terminal has a selection. False if not.

Example
Copy 
const state = storeHelper.getState();
const hasTerminalSelection = selectorsHelper.make('hasTerminalSelection');
const hasSelection = hasTerminalSelection(state, { terminalId });

moveTerminalSelectionFocus

Move the focus of the selection of the specifies terminal.

Note: Dispatches an action with the type @orion/terminals-helper/MOVE_TERMINAL_SELECTION_FOCUS which can be handled.
Usage
Copy 
dispatchersHelper.dispatch('moveTerminalSelectionFocus', {
terminalId: String,
to: Object,
offset: Object,
});

  • terminalId String

    Required. The ID of the terminal to move the focus of the selection.

  • to String

    Optional. Move the focus to the specified column or line.

  • offset String

    Optional. Move the focus along with the specified offset of columns or lines.

Example
Copy 
dispatchersHelper.dispatch('moveTerminalSelectionFocus', {
terminalId: 'terminal-1',
offset: { columns: 1, lines: 2 },
});
dispatchersHelper.dispatch('moveTerminalSelectionFocus', {
terminalId: 'terminal-1',
offset: { columns: -2 },
});
dispatchersHelper.dispatch('moveTerminalSelectionFocus', {
terminalId: 'terminal-1',
offset: { columns: 1, lines: -2 },
});
dispatchersHelper.dispatch('moveTerminalSelectionFocus', {
terminalId: 'terminal-1',
to: { line: 4, column: 7 },
});
dispatchersHelper.dispatch('moveTerminalSelectionFocus', {
terminalId: 'terminal-1',
to: { line: 'first', column: 'afterLastChar' },
});
dispatchersHelper.dispatch('moveTerminalSelectionFocus', {
terminalId: 'terminal-1',
to: { line: 1, column: 'last' },
});
dispatchersHelper.dispatch('moveTerminalSelectionFocus', {
terminalId: 'terminal-1',
to: { line: 'last', column: 'lastChar' },
});

getTerminalSelectionText

Returns the selected text of the specified terminal.

Usage
Copy 
getTerminalSelectionText(state: Object, { terminalId: String }): String;

  • state Object

    Required. The global state of the application.

  • terminalId String

    Required. The ID of the terminal to get the selected text.

Returns

  • String

    Returns the selected text of the specified terminal.

Example
Copy 
const state = storeHelper.getState();
const getTerminalSelectionText = selectorsHelper.make('getTerminalSelectionText');
const text = getTerminalSelectionText(state, { terminalId });

setTerminalSelection

Set the selection of the specified terminal.

Move the focus of the selection of the specifies terminal.

Note: Dispatches an action with the type @orion/terminals-helper/SET_TERMINAL_SELECTION which can be handled.
Usage
Copy 
dispatchersHelper.dispatch('setTerminalSelection', {
terminalId: String,
anchor: Object,
focus: Object,
});

  • terminalId String

    Required. The ID of the terminal to set the selection.

  • anchor Object

    Optional. The new position of the anchor.

  • focus Object

    Optional. The new position of the focus.

Example
Copy 
dispatchersHelper.dispatch('setTerminalSelection', {
terminalId: 'terminal-1',
anchor: { line: 1, column: 1 },
focus: { line: 2, column: 1 },
});
dispatchersHelper.dispatch('setTerminalSelection', {
terminalId: 'terminal-1',
anchor: { line: 1, column: 1 },
});
dispatchersHelper.dispatch('setTerminalSelection', {
terminalId: 'terminal-1',
focus: { line: 2, column: 1 },
});