### Navigation

- index
- modules |
- next |
- previous |
- Gate One Documentation »
- Gate One Applications »
- Terminal »
- Terminal Developer Documentation »

# terminal.js

Gate One's bundled Terminal application JavaScript (source).

`GateOne.Terminal.``__new__`(settings[, where])

  Called when a user clicks on the Terminal Application in the New Workspace Workspace (or anything that happens to call __new__()).

  Settings: | An object containing the settings that will control how the new terminal is created. Typically contains the application's 'info' data from the server.
  Where: | An optional querySelector-like string or DOM node where the new Terminal should be placed. If not given a new workspace will be created to contain the Terminal.

`GateOne.Terminal.``hasVoiceExt`()

  This function returns `true` if an extension is detected that converts phone numbers into clickable links (e.g. Google Voice). Such browser extensions can have a severe negative performance impact while using terminals (every screen update requires a re-scan of the entire page!).

`GateOne.Terminal.``dbReady`(db)

  Sets `GateOne.Terminal.dbReady = true` so that we know when the 'terminal' database is available & ready (indexedDB databases are async).

`GateOne.Terminal.``createPrefsPanel`()

  Creates the terminal preferences and adds them to the global preferences panel.

`GateOne.Terminal.``enumerateCommandsAction`(messageObj)

  Attached to the 'terminal:commands_list' WebSocket action; stores messageObj['commands'] in `GateOne.Terminal.commandsList`.

`GateOne.Terminal.``enumerateFontsAction`(messageObj)

  Attached to the 'terminal:fonts_list' WebSocket action; updates the preferences panel with the list of fonts stored on the server and stores the list in `GateOne.Terminal.fontsList`.

`GateOne.Terminal.``enumerateColorsAction`(messageObj)

  Attached to the 'terminal:colors_list' WebSocket action; updates the preferences panel with the list of text color schemes stored on the server.

`GateOne.Terminal.``onResizeEvent`()

  Attached to the `go:update_dimensions` event; calls `GateOne.Terminal.sendDimensions()` for all terminals to ensure the new dimensions get applied.

`GateOne.Terminal.``reconnectEvent`()

  Attached to the `go:connnection_established` event; closes all open terminals so that `GateOne.Terminal.reattachTerminalsAction()` can do its thing.

`GateOne.Terminal.``connectionError`()

  This function gets attached to the "go:connection_error" event; closes all open terminals.

`GateOne.Terminal.``getOpenTerminals`()

  Requests a list of open terminals on the server via the 'terminal:get_terminals' WebSocket action. The server will respond with a 'terminal:terminals' WebSocket action message which calls `GateOne.Terminal.reattachTerminalsAction()`.

`GateOne.Terminal.``sendString`(chars[, term])

  Like sendChars() but for programmatic use. chars will be sent to term on the server.

  If term is not given the currently-selected terminal will be used.

`GateOne.Terminal.``killTerminal`(term)

  Tells the server got close the given term and kill the underlying process.

`GateOne.Terminal.``refresh`(term)

  Tells the Gate One server to send a screen refresh (using the diff method).

  Note

  This function is only here for debugging purposes. Under normal circumstances difference-based screen refreshes are initiated at the server.

`GateOne.Terminal.``fullRefresh`(term)

  Tells the Gate One server to send a full screen refresh to the client for the given term.

`GateOne.Terminal.``loadFont`(font[, size])

  Tells the server to perform a sync of the given font with the client. If font is not given, will load the font set in `GateOne.prefs.font`.

  Optionally, a size may be chosen. It must be a valid CSS 'font-size' value such as '0.9em', '90%', '12pt', etc.

`GateOne.Terminal.``loadTextColors`(colors)

  Tells the server to perform a sync of the given colors (terminal text colors) with the client. If colors is not given, will load the colors set in `GateOne.prefs.colors`.

`GateOne.Terminal.``displayTermInfo`(term)

  Displays the given term's information as a psuedo tooltip that eventually fades away.

`GateOne.Terminal.``sendDimensions`([term[, ctrl_l]])

  Detects and sends the given term's dimensions (rows/columns) to the server.

  If no term is given it will send the dimensions of the currently-selected terminal to the server which will be applied to all terminals.

`GateOne.Terminal.``setTitle`(term, text)

  Sets the visible title of term to text appropriately based on whether or not this is a popup terminal or just a regular one.

  Note

  This function does not set the 'title' or 'X11Title' attributes of the `GateOne.Terminal.terminals[term]` object. That is handled by `GateOne.Terminal.setTitleAction()`.

`GateOne.Terminal.``setTitleAction`(titleObj)

  Sets the title of titleObj.term to titleObj.title.

`GateOne.Terminal.``resizeAction`(message)

  Called when the server sends the `terminal:resize` WebSocket action. Sets the 'rows' and 'columns' values inside `GateOne.Terminal.terminals[message.term]` and sets the same values inside the Info & Tools panel.

`GateOne.Terminal.``paste`(e)

  This gets attached to Shift-Insert (KEY_INSERT) as a shortcut in order to support pasting.

`GateOne.Terminal.``writeScrollback`(term, scrollback)

  Writes the given scrollback buffer for the given term to localStorage.

`GateOne.Terminal.``applyScreen`(screen[, term[, noUpdate]])

  Uses screen (array of HTML-formatted lines) to update term.

  If term is omitted `localStorage[prefix+selectedTerminal]` will be used.

  If noUpdate is `true` the array that holds the current screen in `GateOne.Terminal.terminals` will not be updated (useful for temporary screen replacements).

  Note

  Lines in screen that are empty strings or null will be ignored (so it is safe to pass a full array with only a single updated line).

`GateOne.Terminal.``alignTerminal`(term)

  Uses a CSS3 transform to move the terminal <pre> element upwards just a bit so that the scrollback buffer isn't visislbe unless you actually scroll. This improves the terminal's overall appearance considerably because the bottoms of characters in the scollback buffer tend to look like graphical glitches.

`GateOne.Terminal.``termUpdateFromWorker`(e)

  This function gets assigned to the `termUpdatesWorker.onmessage()` event; Whenever the WebWorker completes processing of the incoming screen it posts the result to this function. It takes care of updating the terminal on the page, storing the scrollback buffer, and finally triggers the "terminal:term_updated" event passing the terminal number as the only argument.

`GateOne.Terminal.``loadWebWorkerAction`(source)

  Loads our Web Worker given it's source (which is sent to us over the WebSocket which is a clever workaround to the origin limitations of Web Workers =).

`GateOne.Terminal.``updateTerminalAction`(termUpdateObj)

  Takes the updated screen information from termUpdateObj and posts it to the 'term_ww.js' Web Worker to be processed.

  Note

  The Web Worker is important because it allows offloading of CPU-intensive tasks like linkification and text transforms so they don't block screen updates

`GateOne.Terminal.``notifyInactivity`(term)

  Notifies the user of inactivity in term.

`GateOne.Terminal.``notifyActivity`(term)

  Notifies the user of activity in term.

`GateOne.Terminal.``newPastearea`()

  Returns a 'pastearea' (textarea) element meant for placement above terminals for the purpose of enabling proper copy & paste.

`GateOne.Terminal.``newTerminal`([term[, settings[, where]]])

  Adds a new terminal to the grid and starts updates with the server.

  If term is provided, the created terminal will use that number.

  If settings (associative array) are provided the given parameters will be applied to the created terminal's parameters in GateOne.Terminal.terminals[term] as well as sent as part of the 'terminal:new_terminal' WebSocket action. This mechanism can be used to spawn terminals using different 'commands' that have been configured on the server. For example:

      > // Creates a new terminal that spawns whatever command is set as 'login' in Gate One's settings:
      > GateOne.Terminal.newTerminal(null, {'command': 'login'});

  If where is provided, the new terminal element will be appended like so: where.appendChild(<new terminal element>); Otherwise the terminal will be added to the grid.

  Terminal types are sent from the server via the 'terminal_types' action which sets up GateOne.terminalTypes. This variable is an associative array in the form of: {'term type': {'description': 'Description of terminal type', 'default': true/false, <other, yet-to-be-determined metadata>}}.

`GateOne.Terminal.``closeTerminal`(term[, noCleanup[, message[, sendKill]]])

  Arguments:

  - term (number) -- The terminal to close.
  - noCleanup (boolean) -- If `true` the terminal's metadata in localStorage/IndexedDB (i.e. scrollback buffer) will not be removed.
  - message (string) -- An optional message to display to the user after the terminal is close.
  - sendKill (boolean) -- If undefined or `true`, will tell the server to kill the process associated with the given term (i.e. close it for real).

  Closes the given terminal (term) and tells the server to end its running process.

`GateOne.Terminal.``popupTerm`([term])

  Opens a dialog with a terminal contained within. If term is given the created terminal will use that number.

  The options argument may contain the following:

  > global: | If `true` the dialog will be appended to `GateOne.node` (e.g. #gateone) instead of the current workspace.
  > where: | If provided the popup terminal will be placed within the given element.

  If the terminal inside the dialog ends it will be closed automatically. If the user closes the dialog the terminal will be closed automatically as well.

`GateOne.Terminal.``setTerminal`(term)

  Sets the 'selectedTerminal' value in `localStorage` and sends the 'terminal:set_terminal' WebSocket action to the server to let it know which terminal is currently active.

  This function triggers the 'terminal:set_terminal' event passing the terminal number as the only argument.

`GateOne.Terminal.``switchTerminal`(term)

  Calls `GateOne.Terminal.setTerminal(*term*)` then triggers the 'terminal:switch_terminal' event passing term as the only argument.

`GateOne.Terminal.``setActive`([term])

  Removes the '✈inactive' class from the given term.

  If term is not given the currently-selected terminal will be used.

`GateOne.Terminal.``isActive`()

  Returns `true` if a terminal is the current application (selected by the user)

`GateOne.Terminal.``switchTerminalEvent`(term)

  This gets attached to the 'terminal:switch_terminal' event in `GateOne.Terminal.init()`; performs a number of actions whenever the user changes the current terminal.

`GateOne.Terminal.``switchWorkspaceEvent`(workspace)

  Called whenever Gate One switches to a new workspace; checks whether or not this workspace is home to a terminal and calls switchTerminalEvent() on said terminal (to make sure input is enabled and it is scrolled to the bottom).

`GateOne.Terminal.``workspaceClosedEvent`(workspace)

  Attached to the `go:close_workspace` event; closes any terminals that are attached to the given workspace.

`GateOne.Terminal.``swappedWorkspacesEvent`(ws1, ws2)

  Attached to the `go:swapped_workspaces` event; updates `GateOne.Terminal.terminals` with the correct workspace attributes if either contains terminals.

`GateOne.Terminal.``printScreen`(term)

  Prints just the screen (no scrollback) of the given term. If term is not provided the currently-selected terminal will be used.

`GateOne.Terminal.``hideIcons`()

  Hides the Terminal's toolbar icons (i.e. when another application is running).

`GateOne.Terminal.``showIcons`()

  Shows (unhides) the Terminal's toolbar icons (i.e. when another application is running).

`GateOne.Terminal.``bellAction`(bellObj)

  Attached to the 'terminal:bell' WebSocket action; plays a bell sound and pops up a message indiciating which terminal issued a bell.

`GateOne.Terminal.``playBell`()

  Plays the bell sound without any visual notification.

`GateOne.Terminal.``updateDimensions`()

  This gets attached to the "go:update_dimensions" event which gets called whenever the window is resized. It makes sure that all the terminal containers are of the correct dimensions.

`GateOne.Terminal.``enableScrollback`([term])

  Replaces the contents of the selected/active terminal scrollback buffer with the complete latest scrollback buffer from `GateOne.Terminal.terminals[*term*]`.

  If term is given, only ensable scrollback for that terminal.

`GateOne.Terminal.``toggleScrollback`()

  Enables or disables the scrollback buffer (to hide or show the scrollbars).

`GateOne.Terminal.``clearScrollback`(term)

  Empties the scrollback buffer for the given term in memory, in localStorage, and in the DOM.

`GateOne.Terminal.``clearScreen`(term)

  Clears the screen of the given term in memory and in the DOM.

  Note

  The next incoming screen update from the server will likely re-populate most if not all of the screen.

`GateOne.Terminal.``getLocations`()

  Sends the `terminal:get_locations` WebSocket action to the server. This will ultimately trigger the `GateOne.Terminal.locationsAction()` function.

`GateOne.Terminal.``locationsAction`(locations)

  Attached to the `terminal:term_locations` WebSocket action, triggers the `terminal:term_locations` event (in case someone wants to do something with that information).

`GateOne.Terminal.``relocateWorkspaceEvent`(workspace, location)

  Attached to the `go:relocate_workspace` event; calls `GateOne.Terminal.relocateTerminal()` if the given workspace has a terminal contained within it.

`GateOne.Terminal.``relocateTerminal`(term, location)

  Arguments:

  - term (number) -- The number of the terminal to move (e.g. 1).
  - location (string) -- The 'location' where the terminal will be moved (e.g. 'window2').

  Moves the given term to the given location (aka window) by sending the appropriate message to the Gate One server.

`GateOne.Terminal.``changeLocation`(location[, settings])

  Attached to the `go:set_location` event, removes all terminals from the current view and opens up all the terminals at the new location. If there are currently no terminals at location a new terminal will be opened automatically.

  To neglect opening a new terminal automatically provide a settings object like so:

      >>> GateOne.Terminal.changeLocation('window2', {'new_term': false}`);

`GateOne.Terminal.``reconnectTerminalAction`(message)

  Called when the server reports that the terminal number supplied via the `terminal:new_terminal` WebSocket action already exists.

  This method also gets called when a terminal is moved from one 'location' to another.

`GateOne.Terminal.``moveTerminalAction`(obj)

  Attached to the `terminal:term_moved` WebSocket Action, closes the given term with a slightly different message than closeTerminal().

`GateOne.Terminal.``reattachTerminalsAction`(terminals)

  Called after we authenticate to the server, this function is attached to the `terminal:terminals` WebSocket action which is the server's way of notifying the client that there are existing terminals.

  If we're reconnecting to an existing session, running terminals will be recreated/reattached.

  If this is a new session (and we're not in embedded mode), a new terminal will be created.

`GateOne.Terminal.``recordPanePositions`()

  Records the position of each terminal in each `GateOne.Visual.Pane()` that exists on the page (so they can be resumed properly).

`GateOne.Terminal.``resumePanePosition`(term)

  Uses `GateOne.Terminal.terminals[term].metadata.panePosition` to create a new terminal in that exact spot. New :js:meth`GateOne.Visual.Pane` objects will be created as necessary to ensure the terminal winds up where it was previously.

`GateOne.Terminal.``setModeAction`(modeObj)

  Set the given terminal mode (e.g. application cursor mode aka appmode). modeObj is expected to be something like this:

      {'mode': '1', 'term': '1', 'bool': true}

`GateOne.Terminal.``registerTextTransform`(name, pattern, newString)

  Adds a new or replaces an existing text transformation to GateOne.Terminal.textTransforms using pattern and newString with the given name. Example:

      var pattern = /(\bIM\d{9,10}\b)/g,
          newString = "<a href='https://support.company.com/tracker?ticket=$1' target='new'>$1</a>";
      GateOne.Terminal.registerTextTransform("ticketIDs", pattern, newString);

  Would linkify text matching that pattern in the terminal.

  For example, if you typed "Ticket number: IM123456789" into a terminal it would be transformed thusly:

      "Ticket number: <a href='https://support.company.com/tracker?ticket=IM123456789' target='new'>IM123456789</a>"

  Alternatively, a function may be provided instead of pattern. In this case, each line will be transformed like so:

      line = pattern(line);

  Note

  name is only used for reference purposes in the textTransforms object (so it can be removed or replaced later).

  Tip

  To match the beginning of a line use '\n' instead of '^'. This is necessary because the entire screen is matched at once as opposed to line-by-line.

`GateOne.Terminal.``unregisterTextTransform`(name)

  Removes the given text transform from `GateOne.Terminal.textTransforms`.

`GateOne.Terminal.``resetTerminalAction`(term)

  Clears the screen and the scrollback buffer of the given term (in memory, localStorage, and in the DOM).

`GateOne.Terminal.``termEncodingAction`(message)

  Handles the 'terminal:encoding' WebSocket action that tells us the encoding that is set for a given terminal. The expected message format:

  Arguments:

  - message.term (string) -- The terminal in question.
  - message['encoding'] (string) -- The encoding to set on the given terminal.

  Note

  The encoding value here is only used for informational purposes. No encoding/decoding happens at the client.

`GateOne.Terminal.``termKeyboardModeAction`(message)

  Handles the 'terminal:keyboard_mode' WebSocket action that tells us the keyboard mode that is set for a given terminal. The expected message format:

  Arguments:

  - message.term (string) -- The terminal in question.
  - message['mode'] (string) -- The keyboard mode to set on the given terminal. E.g. 'default', 'sco', 'xterm', 'linux', etc

  Note

  The keyboard mode value is only used by the client. There's no server-side functionality related to keyboard modes other than the fact that it remembers the setting.

`GateOne.Terminal.``xtermEncode`(number)

  Encodes the given number into a single character using xterm's encoding scheme. e.g. to convert mouse coordinates for use in an escape sequence.

  The xterm encoding scheme takes the ASCII value of (number + 32). So the number one would be ! (exclamation point), the number two would be " (double-quote), the number three would be # (hash), and so on.

  Note

  This encoding mechansim has the unfortunate limitation of only being able to encode up to the number 233.

`GateOne.Terminal.``highlight`(text[, term])

  Highlights all occurrences of the given text inside the given term by wrapping it in a span like so:

      <span class="✈highlight">text</span>

  If term is not provided the currently-selected terminal will be used.

`GateOne.Terminal.``unHighlight`()

  Undoes the results of `GateOne.Terminal.highlight()`.

`GateOne.Terminal.``highlightTexts`

  An object that holds all the words the user wishes to stay persistently highlighted (even after screen updates and whatnot) across all terminals.

  Note

  Word highlighting that is specific to individual terminals is stored in `GateOne.Terminal.terminals[term]`.

`GateOne.Terminal.``highlightDialog`()

  Opens a dialog where users can add/remove text they would like to be highlighted on a semi-permanent basis (e.g. even after a screen update).

`GateOne.Terminal.``showSuspended`()

  Displays a little widget in the terminal that indicates that output has been suspended.

`GateOne.Terminal.``scrollPageUp`([term])

  Scrolls the given term one page up. If term is not given the currently-selected terminal will be used.

`GateOne.Terminal.``scrollPageDown`([term])

  Scrolls the given term one page up. If term is not given the currently-selected terminal will be used.

`GateOne.Terminal.``chooser`()

  Pops up a dialog where the user can immediately switch to any terminal in any 'location'.

  Note

  If the terminal is in a different location the current location will be changed along with all terminals before the switch is made.

`GateOne.Terminal.``sharePermissions`(term, permissions)

  Sets the sharing permissions of the given term. The permissions must be an object that contains one or both of the following:

  > read: | An array of users that will be given read-only access to the given term.
  > write: | An array of users that will be given write access to the given term.

  Note

  read and write may be given as a string if only one user's permissions are being modified.

  Example:

      >>> GateOne.Terminal.sharePermissions(1, {'read': 'AUTHENTICATED', 'write': ["bob@company", "joe@company"]);

  Note

  If a user is granted write permission to a terminal they will automatically be granted read permission.

`GateOne.Terminal.``shareDialog`(term)

  Opens a dialog where the user can share a terminal or modify the permissions on a terminal that is already shared.

`GateOne.Terminal.``setShareID`(term[, shareID])

  Sets the share ID of the given term. If a shareID is not provided one will be generated automatically (by the server).

`GateOne.Terminal.``attachSharedTerminal`(shareID[, password[, metadata]])

  Opens the terminal associated with the given shareID.

  If a password is given it will be used to attach to the shared terminal.

  If metadata is given it will be passed to the server to be used for extra logging and providing additional details about who is connecting to shared terminals.

`GateOne.Terminal.``detachSharedTerminal`(term)

  Tells the server that we no longer wish to view the terminal associated with the given term (local terminal number).

`GateOne.Terminal.``listSharedTerminals`()

  Sens the `terminal:list_shared_terminals` WebSocket action to the server which will reply with the `terminal:shared_terminals` WebSocket action (if the user is allowed to list shared terminals).

`GateOne.Terminal.``sharedTerminalsAction`(message)

  Attached to the `terminal:shared_terminals` WebSocket action; stores the list of terminals that have been shared with the user in `GateOne.Terminal.sharedTerminals` and triggers the `terminal:shared_terminals` event.

`GateOne.Terminal.``sharedTerminalsDialog`()

  Opens up a dialog where the user can open terminals that have been shared with them.

`GateOne.Terminal.``shareInfo`(term)

  Displays a dialog that lists the current viewers (along with their permissions) of a given term.

`GateOne.Terminal.``shareWidget`(term)

  Adds a terminal sharing widget to the given term (number) that provides sharing controls and information (e.g. number of viewers).

`GateOne.Terminal.``sharedTermObj`(term)

  Returns the object matching the given term from `GateOne.Terminal.sharedTerminals`.

`GateOne.Terminal.``shareID`(term)

  Returns the share ID for the given term (if any).

`GateOne.Terminal.``shareBroadcastURL`(term)

  Returns the broadcast URL for the given term (if any).

`GateOne.Terminal.``_trimmedScreen`(screen)

  Returns screen with all trailing empty lines removed.

`GateOne.Terminal.``lastLines`([n[, term]])

  Returns the last n non-blank (trimmed) line in the terminal. Useful for pattern matching.

  If term is not given the `localStorage[prefix+'selectedTerminal']` will be used.

### Navigation

- index
- modules |
- next |
- previous |
- Gate One Documentation »
- Gate One Applications »
- Terminal »
- Terminal Developer Documentation »