### Navigation

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

# `app_terminal.py` - Gate One Terminal Application

A Gate One Application (`GOApplication`) that provides a terminal emulator.

`app_terminal.``kill_session`(session, kill_dtach=False)

  Terminates all the terminal processes associated with session. If kill_dtach is True, the dtach processes associated with the session will also be killed.

  Note

  This function gets appended to the `SESSIONS[session]["kill_session_callbacks"]` list inside of `TerminalApplication.authenticate()`.

`app_terminal.``timeout_session`(session)

  Attached to Gate One's 'timeout_callbacks'; kills the given session.

  If 'dtach' support is enabled the dtach processes associated with the session will also be killed.

class `app_terminal.``SharedTermHandler`(application, request, **kwargs)

  Renders shared.html which allows an anonymous user to view a shared terminal.

class `app_terminal.``TermStaticFiles`(application, request, **kwargs)

  Serves static files in the `gateone/applications/terminal/static` directory.

  Note

  This is configured via the `web_handlers` global (a feature inherent to Gate One applications).

class `app_terminal.``TerminalApplication`(ws)

  A Gate One Application (`GOApplication`) that handles creating and controlling terminal applications running on the Gate One server.

  `initialize`()

    Called when the WebSocket is instantiated, sets up our WebSocket actions, security policies, and attaches all of our plugin hooks/events.

  `open`()

    This gets called at the end of `ApplicationWebSocket.open()` when the WebSocket is opened.

  `send_client_files`()

    Sends the client our standard CSS and JS.

  `authenticate`()

    This gets called immediately after the user is authenticated successfully at the end of `ApplicationWebSocket.authenticate()`. Sends all plugin JavaScript files to the client and triggers the 'terminal:authenticate' event.

  `on_close`()

    Removes all attached callbacks and triggers the `terminal:on_close` event.

  `enumerate_fonts`()

    Returns a JSON-encoded object containing the installed fonts.

  `enumerate_colors`()

    Returns a JSON-encoded object containing the installed text color schemes.

  `save_term_settings`(term, settings)

    Saves whatever settings (must be JSON-encodable) are provided in the user's session directory; associated with the given term.

    The `restore_term_settings` function can be used to restore the provided settings.

    Note

    This method is primarily to aid dtach support.

  `restore_term_settings`(term)

    Reads the settings associated with the given term that are stored in the user's session directory and applies them to `self.loc_terms[term]`

  `clear_term_settings`(term)

    Removes any settings associated with the given term in the user's term_settings.json file (in their session directory).

  `term_ended`(term)

    Sends the 'term_ended' message to the client letting it know that the given term is no more.

  `add_terminal_callbacks`(term, multiplex, callback_id)

    Sets up all the callbacks associated with the given term, multiplex instance and callback_id.

  `remove_terminal_callbacks`(multiplex, callback_id)

    Removes all the Multiplex and terminal emulator callbacks attached to the given multiplex instance and callback_id.

  `new_multiplex`(cmd, term_id, logging=True, encoding=u'utf-8', debug=False)

    Returns a new instance of `termio.Multiplex` with the proper global and client-specific settings.

    > cmd: | The command to execute inside of Multiplex.
    > term_id: | The terminal to associate with this Multiplex or a descriptive identifier (it's only used for logging purposes).
    > logging: | If `False`, logging will be disabled for this instance of Multiplex (even if it would otherwise be enabled).
    > encoding: | The default encoding that will be used when reading or writing to the Multiplex instance.
    > debug: | If `True`, will enable debugging on the created Multiplex instance.

  `highest_term_num`(location=None)

    Returns the highest terminal number at the given location (so we can figure out what's next). If location is omitted, uses `self.ws.location`.

  `send_term_encoding`(term, encoding)

    Sends a message to the client indicating the encoding of term (in the event that a terminal is reattached or when sharing a terminal).

  `send_term_keyboard_mode`(term, mode)

    Sends a message to the client indicating the mode of term (in the event that a terminal is reattached or when sharing a terminal).

  `set_terminal`(term)

    Sets `self.current_term = *term*` so we can determine where to send keystrokes.

  `reset_client_terminal`(term)

    Tells the client to reset the terminal (clear the screen and remove scrollback).

  `set_title`(term, force=False, save=True)

    Sends a message to the client telling it to set the window title of term to whatever comes out of:

        self.loc_terms[term]['multiplex'].term.get_title() # Whew! Say that three times fast!

    Example message:

        {'set_title': {'term': 1, 'title': "user@host"}}

    If force resolves to True the title will be sent to the cleint even if it matches the previously-set title.

    if save is `True` (the default) the title will be saved via the `TerminalApplication.save_term_settings` function so that it may be restored later (in the event of a server restart--if you've got dtach support enabled).

    Note

    Why the complexity on something as simple as setting the title? Many prompts set the title. This means we'd be sending a 'title' message to the client with nearly every screen update which is a pointless waste of bandwidth if the title hasn't changed.

  `bell`(term)

    Sends a message to the client indicating that a bell was encountered in the given terminal (term). Example message:

        {'bell': {'term': 1}}

  `mode_handler`(term, setting, boolean)

    Handles mode settings that require an action on the client by pasing it a message like:

        {
            'terminal:set_mode': {
                'mode': setting,
                'bool': True,
                'term': term
            }
        }

  `dsr`(term, response)

    Handles Device Status Report (DSR) calls from the underlying program that get caught by the terminal emulator. response is what the terminal emulator returns from the CALLBACK_DSR callback.

    Note

    This also handles the CSI DSR sequence.

  `_send_refresh`(term, full=False)

    Sends a screen update to the client.

  `refresh_screen`(term, full=False, stream=None)

    Writes the state of the given terminal's screen and scrollback buffer to the client using `_send_refresh()`. Also ensures that screen updates don't get sent too fast to the client by instituting a rate limiter that also forces a refresh every 150ms. This keeps things smooth on the client side and also reduces the bandwidth used by the application (CPU too).

    If full, send the whole screen (not just the difference).

  `full_refresh`(term)

    Calls `self.refresh_screen(*term*, full=True)`

  `opt_esc_handler`(term, multiplex, chars)

    Calls whatever function is attached to the 'terminal:opt_esc_handler:<name>' event; passing it the text (second item in the tuple) that is returned by `utils.process_opt_esc_sequence()`. Such functions are usually attached via the 'Escape' plugin hook but may also be registered via the usual event method, :meth`self.on`:

        self.on('terminal:opt_esc_handler:somename', some_function)

    The above example would result in `some_function()` being called whenever a matching optional escape sequence handler is encountered. For example:

        $ echo -e "\033]_;somename|Text passed to some_function()\007"

    Which would result in `some_function()` being called like so:

        some_function(
            self, "Text passed to some_function()", term, multiplex)

    In the above example, term will be the terminal number that emitted the event and multiplex will be the `termio.Multiplex` instance that controls the terminal.

  `get_bell`()

    Sends the bell sound data to the client in in the form of a data::URI.

  `get_webworker`()

    Sends the text of our term_ww.js to the client in order to get around the limitations of loading remote Web Worker URLs (for embedding Gate One into other apps).

  `get_colors`(settings)

    Sends the text color stylesheet matching the properties specified in settings to the client. settings must contain the following:

    > colors: | The name of the CSS text color scheme to be retrieved.

  `remove_viewer`(term, upn=None)

    Disconnects all callbacks attached to the given term for the given upn and notifies that user that the terminal is no longer shared (so it can be shown to be disconnected at the client).

    If upn is `None` all users (broadcast viewers included) will have the given term disconnected.

  `notify_permissions`()

    Sends clients the list of shared terminals if they have been granted access to any shared terminal.

    Note

    Normally this only gets called from `permissions` after something changed.

  `_shared_terminals_dict`(user=None)

    Returns a dict containing information about all shared terminals that the given user has access to. If no user is given `self.current_user` will be used.

  `render_256_colors`()

    Renders the CSS for 256 color support and saves the result as '256_colors.css' in Gate One's configured `cache_dir`. If that file already exists and has not been modified since the last time it was generated rendering will be skipped.

    Returns the path to that file as a string.

  `send_256_colors`()

    Sends the client the CSS to handle 256 color support.

  `send_print_stylesheet`()

    Sends the 'templates/printing/printing.css' stylesheet to the client using `ApplicationWebSocket.ws.send_css` with the "media" set to "print".

`app_terminal.``apply_cli_overrides`(settings)

  Updates settings in-place with values given on the command line and updates the `options` global with the values from settings if not provided on the command line.

`app_terminal.``init`(settings)

  Checks to make sure 50terminal.conf is created if terminal-specific settings are not found in the settings directory.

  Also checks to make sure that the logviewer.py script is executable.

### Navigation

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