from __future__ import annotations
#-----------------------------------------------------------------------------
# Company : SLAC National Accelerator Laboratory
#-----------------------------------------------------------------------------
# Description:
# PyRogue PyDM Embedded Linux Terminal Widget
#-----------------------------------------------------------------------------
# This file is part of the rogue software platform. It is subject to
# the license terms in the LICENSE.txt file found in the top-level directory
# of this distribution and at:
# https://confluence.slac.stanford.edu/display/ppareg/LICENSE.html.
# No part of the rogue software platform, including this file, may be
# copied, modified, propagated, or distributed except according to the terms
# contained in the LICENSE.txt file.
#-----------------------------------------------------------------------------
import errno
import os
import re
import pyte
import pyte.graphics
from qtpy.QtCore import QSocketNotifier, QTimer, Qt
from qtpy.QtGui import (
QColor,
QFont,
QFontDatabase,
QFontMetricsF,
QPalette,
QTextCharFormat,
QTextCursor,
)
from qtpy.QtWidgets import (
QApplication,
QHBoxLayout,
QPlainTextEdit,
QPushButton,
QTabWidget,
QTextEdit,
QVBoxLayout,
QWidget,
)
from pyrogue.pydm.widgets.terminal_core import (
SCROLLBACK_LINES,
TerminalScreen,
closeShell,
computeGrid,
screenRuns,
setWinSize,
spawnShell,
)
# Repaint coalescing interval in milliseconds. A shell dumping output arrives as
# many small reads; without coalescing each one would trigger a full repaint.
_REPAINT_MS = 30
# Resize debounce. Every TIOCSWINSZ raises SIGWINCH and an interactive shell
# redraws its prompt, so dragging a window edge would otherwise storm the pty.
_RESIZE_MS = 50
_READ_CHUNK = 8192
# Ceiling on bytes absorbed per readable notification. pyte's feed() is pure
# Python, so an unbounded drain of `cat bigfile` would stall the event loop for
# seconds. QSocketNotifier is level triggered, so the remainder simply re-fires
# on the next event loop turn and the GUI stays responsive.
_MAX_BYTES_PER_POLL = 64 * 1024
# pyte stores DEC private modes shifted left by 5. 2004 is bracketed paste,
# which bash enables by default from 5.1 onward.
_BRACKETED_PASTE = 2004 << 5
# Size of the detached terminal window, used only when it has no better hint.
_DETACHED_SIZE = (900, 600)
# A shell that exits without the user having typed anything was not exited on
# purpose, it failed to start. After this many such exits in a row the terminal
# stops restarting, so a shell that cannot run does not spawn in a loop.
#
# Elapsed time is deliberately not used to make this distinction. Exiting twice
# in quick succession is something a user can easily do, and treating that as a
# failure would dead-end the terminal exactly as it did before it restarted.
_MAX_STARTUP_FAILURES = 3
# Dark theme. A terminal is read as a terminal, so it keeps its own colors
# rather than following the surrounding PyDM palette.
_COLOR_BG = '#1e1e1e'
_COLOR_FG = '#d4d4d4'
_COLOR_SELECTION = '#264f78'
# pyte names the eight base colors after the SGR 30-37 order, so a name maps
# straight onto an index into its own 256 color table. Entries 0-7 are the
# normal shades and 8-15 the bright ones, which keeps the palette in one place
# instead of a hand-maintained copy.
_COLOR_INDEX = {name: index for index, name in enumerate(
('black', 'red', 'green', 'brown', 'blue', 'magenta', 'cyan', 'white'))}
# 256 color and 24 bit values arrive from pyte already as six hex digits.
_HEX_COLOR = re.compile(r'[0-9a-fA-F]{6}')
[docs]
def resolveColor(value: str, bright: bool = False) -> QColor | None:
"""Map a ``pyte`` color to a ``QColor``.
Parameters
----------
value : str
Colour as pyte reports it: ``'default'``, one of the eight base names,
a ``bright``-prefixed name, or six hex digits for 256 colour and 24 bit.
bright : bool, optional
Select the bright shade of a base name. Bold text is rendered in the
bright shade, which is the convention every colorizing tool assumes.
Returns
-------
QColor | None
``None`` when the value is the default or is not recognised, so the
caller can fall back to the theme colour. pyte's own tables contain at
least one misspelled name, so unrecognised input has to be tolerated.
"""
if not value or value == 'default':
return None
name = value[6:] if value.startswith('bright') else value
index = _COLOR_INDEX.get(name)
if index is not None:
if bright or value.startswith('bright'):
index += 8
return QColor('#' + pyte.graphics.FG_BG_256[index])
if _HEX_COLOR.fullmatch(value):
return QColor('#' + value)
return None
[docs]
def keyToBytes(key: int, modifiers: int, text: str) -> bytes:
"""Translate a Qt key press into the byte sequence a terminal expects.
Kept free of ``QKeyEvent`` so it can be unit tested without constructing a
``QApplication``. The sequences follow the ``xterm`` conventions, matching
the ``TERM`` value exported to the child shell. Changing one requires
changing the other.
Parameters
----------
key : int
Qt key code, for example ``Qt.Key_Up``.
modifiers : int
Qt keyboard modifier flags.
text : str
Text the key event produced, used for ordinary printable input.
Returns
-------
bytes
Bytes to write to the pty, or ``b''`` when the key produces no input.
Notes
-----
Ctrl-C has to reach the shell as ``ETX`` so it can interrupt the foreground
job, so copy and paste are bound to Ctrl+Shift+C and Ctrl+Shift+V. Those
two chords return ``b''`` here and are handled as clipboard actions by the
widget.
"""
ctrl = bool(modifiers & Qt.ControlModifier)
shift = bool(modifiers & Qt.ShiftModifier)
alt = bool(modifiers & Qt.AltModifier)
if ctrl and shift and key in (Qt.Key_C, Qt.Key_V):
return b''
if key in (Qt.Key_Shift, Qt.Key_Control, Qt.Key_Alt, Qt.Key_Meta,
Qt.Key_CapsLock, Qt.Key_NumLock, Qt.Key_ScrollLock):
return b''
# Control characters are computed rather than taken from text(), which Qt
# populates for Ctrl+A..Z on some platforms but not for Ctrl+Space or the
# bracket group.
if ctrl and not alt:
if key == Qt.Key_Space:
return b'\x00'
if Qt.Key_A <= key <= Qt.Key_Underscore:
return bytes([key & 0x1f])
simple = {
Qt.Key_Return: b'\r',
Qt.Key_Enter: b'\r',
Qt.Key_Backspace: b'\x7f',
Qt.Key_Tab: b'\t',
Qt.Key_Backtab: b'\x1b[Z',
Qt.Key_Escape: b'\x1b',
Qt.Key_Up: b'\x1b[A',
Qt.Key_Down: b'\x1b[B',
Qt.Key_Right: b'\x1b[C',
Qt.Key_Left: b'\x1b[D',
Qt.Key_Home: b'\x1b[H',
Qt.Key_End: b'\x1b[F',
Qt.Key_Insert: b'\x1b[2~',
Qt.Key_Delete: b'\x1b[3~',
Qt.Key_PageUp: b'\x1b[5~',
Qt.Key_PageDown: b'\x1b[6~',
Qt.Key_F1: b'\x1bOP',
Qt.Key_F2: b'\x1bOQ',
Qt.Key_F3: b'\x1bOR',
Qt.Key_F4: b'\x1bOS',
Qt.Key_F5: b'\x1b[15~',
Qt.Key_F6: b'\x1b[17~',
Qt.Key_F7: b'\x1b[18~',
Qt.Key_F8: b'\x1b[19~',
Qt.Key_F9: b'\x1b[20~',
Qt.Key_F10: b'\x1b[21~',
Qt.Key_F11: b'\x1b[23~',
Qt.Key_F12: b'\x1b[24~',
}
# Named keys are matched before text() because Qt reports text() as '\x08'
# for Backspace and '\r' for Return, and readline wants DEL for Backspace.
seq = simple.get(key)
if seq is not None:
return (b'\x1b' + seq) if alt else seq
if text:
data = text.encode('utf-8', errors='replace')
return (b'\x1b' + data) if alt else data
return b''
[docs]
class LinuxTerminal(QPlainTextEdit):
"""Interactive local shell rendered into a read-only text view.
A shell is spawned on a pseudo-terminal, its output is fed to a ``pyte``
screen emulator, and that screen is painted into this widget.
The shell is a child of the GUI process, so it runs on the machine
displaying the GUI as the user who launched it, **not** on the Rogue server.
Anyone who can reach the GUI window gets an interactive shell with that
user's privileges, which is why the feature is opt-in.
The shell starts on first display rather than on construction, so enabling
the feature costs nothing until the tab is actually opened.
The view is dark themed and keeps a bounded scrollback above the live
screen, so output can be scrolled back through. Scrolling up pins the view
in place; new output only follows the bottom when the view is already there.
Rendering is monochrome. ``pyte`` does not implement the alternate screen
buffer, so full screen programs such as ``vim`` and ``htop`` work but leave
their last frame behind on exit instead of restoring the previous screen.
Parameters
----------
parent : QWidget | None, optional
Parent Qt widget.
argv : list[str] | None, optional
Program to run on the pseudo-terminal. Defaults to the user's login
shell. Restarting reuses this, so a program that exits is replaced by
the same program rather than by a shell.
"""
def __init__(self, parent: QWidget | None = None, *,
argv: list[str] | None = None) -> None:
QPlainTextEdit.__init__(self, parent)
self._argv = argv
self._masterFd = -1
self._proc = None
self._readNotifier = None
self._writeNotifier = None
self._writeBuf = bytearray()
self._spawned = False
self._finished = False
self._sawInput = False
self._startupFailures = 0
# Number of blocks at the end of the document holding the live screen.
# Everything before them is committed scrollback and never rewritten.
self._liveRows = 0
font = QFontDatabase.systemFont(QFontDatabase.FixedFont)
font.setStyleHint(QFont.Monospace)
font.setFixedPitch(True)
self.setFont(font)
self.document().setDefaultFont(font)
self.document().setDocumentMargin(0.0)
self.setReadOnly(True)
self.setUndoRedoEnabled(False)
self.setLineWrapMode(QPlainTextEdit.NoWrap)
self.setFocusPolicy(Qt.StrongFocus)
# Always on rather than as-needed: an as-needed bar appears and
# disappears as content crosses the viewport height, and because the bar
# takes horizontal space that changes the column count, which can
# oscillate.
self.setVerticalScrollBarPolicy(Qt.ScrollBarAlwaysOn)
self.setHorizontalScrollBarPolicy(Qt.ScrollBarAlwaysOff)
self._applyDarkTheme()
self._cellWidth, self._cellHeight = self._measureCell()
self._themeFg = QColor(_COLOR_FG)
self._themeBg = QColor(_COLOR_BG)
# Keyed on the pyte attribute tuple. Real output uses only a handful of
# distinct combinations, so this stays tiny.
self._formatCache = {}
cols, rows = computeGrid(self.viewport().width(), self.viewport().height(),
self._cellWidth, self._cellHeight)
self._screen = TerminalScreen(cols, rows, self.writeBytes)
self._stream = pyte.ByteStream(self._screen)
self._setBlockLimit(rows)
self._repaintTimer = QTimer(self)
self._repaintTimer.setSingleShot(True)
self._repaintTimer.timeout.connect(self._repaint)
self._resizeTimer = QTimer(self)
self._resizeTimer.setSingleShot(True)
self._resizeTimer.timeout.connect(self._applyGeometry)
# Qt does not deliver a close event to a non-window child widget when
# its parent is destroyed, so the shell is reaped from application
# shutdown instead.
app = QApplication.instance()
if app is not None:
app.aboutToQuit.connect(self.shutdown)
def _applyDarkTheme(self) -> None:
"""Give the view its own dark palette.
Both a palette and a style sheet are set. The palette keeps derived
colors such as the selection consistent, and the style sheet makes the
result survive an application-wide PyDM style sheet, which would
otherwise win over the palette.
"""
palette = self.palette()
palette.setColor(QPalette.Base, QColor(_COLOR_BG))
palette.setColor(QPalette.Text, QColor(_COLOR_FG))
palette.setColor(QPalette.Highlight, QColor(_COLOR_SELECTION))
palette.setColor(QPalette.HighlightedText, QColor(_COLOR_FG))
self.setPalette(palette)
self.setStyleSheet(
'QPlainTextEdit {'
f' background-color: {_COLOR_BG};'
f' color: {_COLOR_FG};'
f' selection-background-color: {_COLOR_SELECTION};'
f' selection-color: {_COLOR_FG};'
' border: none; }'
)
def _colors(self, fg: str, bg: str, bold: bool, reverse: bool) -> tuple[QColor, QColor]:
"""Resolve a cell's foreground and background to concrete colors."""
foreground = resolveColor(fg, bright=bold) or self._themeFg
# Bold brightens the text, never the background.
background = resolveColor(bg) or self._themeBg
if reverse:
foreground, background = background, foreground
return (foreground, background)
def _formatFor(self, attrs: tuple) -> QTextCharFormat:
"""Return the character format for a ``pyte`` attribute tuple.
``attrs`` is a ``Char`` with the data removed, so
``(fg, bg, bold, italics, underscore, strikethrough, reverse, blink)``.
Blink is deliberately ignored.
"""
cached = self._formatCache.get(attrs)
if cached is not None:
return cached
fg, bg, bold, italics, underscore, strikethrough, reverse, _blink = attrs
foreground, background = self._colors(fg, bg, bold, reverse)
fmt = QTextCharFormat()
fmt.setForeground(foreground)
# Only paint a background when it differs from the view, so ordinary
# text is not covered in same-colored rectangles.
if background != self._themeBg:
fmt.setBackground(background)
if bold:
fmt.setFontWeight(QFont.Bold)
if italics:
fmt.setFontItalic(True)
if underscore:
fmt.setFontUnderline(True)
if strikethrough:
fmt.setFontStrikeOut(True)
self._formatCache[attrs] = fmt
return fmt
def _setBlockLimit(self, rows: int) -> None:
"""Bound the document to the scrollback plus the live screen.
Qt drops the oldest blocks once the limit is reached, which is what
keeps a long-lived terminal from growing without bound.
"""
self.document().setMaximumBlockCount(SCROLLBACK_LINES + rows)
def _measureCell(self) -> tuple[float, float]:
"""Measure one character cell, avoiding integer rounding drift.
The row height comes from the document layout rather than the font
metrics. ``QFontMetricsF.lineSpacing()`` can be smaller than the height
Qt actually gives a text block, and dividing the viewport by the smaller
value yields one row more than really fits, which leaves the top row
permanently scrolled out of view.
"""
fm = QFontMetricsF(self.font())
width = max(1.0, fm.horizontalAdvance('M'))
height = 0.0
layout = self.document().documentLayout()
if layout is not None:
height = layout.blockBoundingRect(self.document().firstBlock()).height()
if height <= 0.0:
height = fm.height()
return (width, max(1.0, height))
def _viewportRows(self) -> int:
"""Return how many text rows the viewport can display."""
return max(1, int(self.viewport().height() // self._cellHeight))
[docs]
def showEvent(self, event) -> None:
"""Spawn the shell on first display and take the keyboard.
Clicking a tab in a ``QTabWidget`` leaves the keyboard focus on the tab
bar, so without this the terminal would appear ready but swallow nothing
until it was clicked a second time.
"""
QPlainTextEdit.showEvent(self, event)
if not self._spawned:
self._spawned = True
self._spawn()
self.setFocus(Qt.OtherFocusReason)
def _spawn(self) -> None:
"""Start a shell on a new pseudo-terminal."""
self._sawInput = False
try:
self._proc, self._masterFd = spawnShell(self._screen.lines, self._screen.columns,
argv=self._argv)
except (OSError, ValueError) as exc:
self._notice(f'[cannot start a shell: {exc}]')
return
self._readNotifier = QSocketNotifier(self._masterFd, QSocketNotifier.Read, self)
self._readNotifier.activated.connect(self._onReadable)
[docs]
def restart(self) -> None:
"""Discard the current session and start a fresh shell.
Returns the terminal to the state it had when the GUI was opened: an
empty screen, no scrollback, and a new prompt.
"""
self._closeProcess()
self._releaseNotifiers()
self._writeBuf.clear()
self._finished = False
# A new screen rather than a reset one, so no emulator state can carry
# over from the old session.
self._screen = TerminalScreen(self._screen.columns, self._screen.lines, self.writeBytes)
self._stream = pyte.ByteStream(self._screen)
self._repaintTimer.stop()
self._liveRows = 0
self.clear()
self.setExtraSelections([])
self._spawned = True
self._spawn()
def _releaseNotifiers(self) -> None:
"""Drop the socket notifiers so new ones can be bound to a new pty."""
for name in ('_readNotifier', '_writeNotifier'):
notifier = getattr(self, name)
if notifier is not None:
notifier.setEnabled(False)
notifier.deleteLater()
setattr(self, name, None)
def _onReadable(self, *_args) -> None:
"""Drain the pty master into the screen emulator.
Accepts extra arguments because the ``activated`` signal carries an int
on Qt 5 and a ``QSocketDescriptor`` plus a type on Qt 6.
"""
if self._finished or self._masterFd < 0:
return
# The notifier is level triggered, so it is disabled for the duration of
# the handler to prevent re-entrancy.
self._readNotifier.setEnabled(False)
total = 0
try:
while total < _MAX_BYTES_PER_POLL:
try:
chunk = os.read(self._masterFd, _READ_CHUNK)
except BlockingIOError:
break
except InterruptedError:
continue
except OSError as exc:
# Linux raises EIO on the master once the child is gone
# rather than returning an empty read. macOS returns b''.
if exc.errno in (errno.EIO, errno.EBADF):
self._onChildGone()
return
raise
if not chunk:
self._onChildGone()
return
total += len(chunk)
# ByteStream keeps an incremental UTF-8 decoder, so a multi-byte
# character split across reads is reassembled for us.
self._stream.feed(chunk)
self._armRepaint()
finally:
if not self._finished and self._readNotifier is not None:
self._readNotifier.setEnabled(True)
[docs]
def writeBytes(self, data: bytes) -> None:
"""Queue bytes for the child process.
Parameters
----------
data : bytes
Bytes to send to the shell.
"""
if self._masterFd < 0 or not data:
return
self._writeBuf += data
self._flushWrite()
def _flushWrite(self) -> None:
"""Push as much of the write queue as the pty will take."""
while self._writeBuf:
try:
written = os.write(self._masterFd, bytes(self._writeBuf[:_READ_CHUNK]))
except BlockingIOError:
# The pty buffer is full, which a large paste will do. Finish
# from a write notifier instead of blocking the GUI thread.
self._enableWriteNotifier()
return
except InterruptedError:
continue
except OSError:
self._onChildGone()
return
del self._writeBuf[:written]
self._disableWriteNotifier()
def _enableWriteNotifier(self) -> None:
"""Arm the write notifier so a stalled write can finish later."""
if self._writeNotifier is None:
self._writeNotifier = QSocketNotifier(self._masterFd, QSocketNotifier.Write, self)
self._writeNotifier.activated.connect(self._onWritable)
self._writeNotifier.setEnabled(True)
def _disableWriteNotifier(self) -> None:
"""Disarm the write notifier.
A write notifier left enabled on a writable descriptor fires on every
event loop iteration, which is a busy spin at 100% CPU.
"""
if self._writeNotifier is not None:
self._writeNotifier.setEnabled(False)
def _onWritable(self, *_args) -> None:
"""Continue a write that previously filled the pty buffer."""
if self._finished or self._masterFd < 0:
self._disableWriteNotifier()
return
self._flushWrite()
def _armRepaint(self) -> None:
"""Schedule a coalesced repaint. An idle terminal costs nothing."""
if not self._repaintTimer.isActive():
self._repaintTimer.start(_REPAINT_MS)
def _repaint(self) -> None:
"""Commit scrolled-off lines, repaint the live screen, place the cursor.
Only the tail of the document is rewritten. Replacing the whole document
would be both wasteful and wrong: it resets the scroll position, so any
output would yank a user who had scrolled up back to the bottom.
"""
screen = self._screen
pending = []
while screen.scrolledOff:
pending.append(screen.scrolledOff.popleft())
if not screen.dirty and not pending:
return
# pyte never clears this; the consumer is required to.
screen.dirty.clear()
# The whole emulated grid, blank rows included. A terminal is a fixed
# grid of rows, and the shell decides where in it the cursor sits, so
# trimming blank rows would break anything that positions within the
# screen. It is also what makes `clear` work: the cleared grid has to
# cover the viewport, otherwise the scrollback underneath shows through.
live = screenRuns(screen)
doc = self.document()
scrollBar = self.verticalScrollBar()
# Follow new output only when the view is already at the bottom, so
# scrolling back to read is not undone by the next line of output.
follow = scrollBar.value() >= scrollBar.maximum() - 1
cursor = QTextCursor(doc)
cursor.beginEditBlock()
if self._liveRows == 0:
cursor.select(QTextCursor.Document)
cursor.removeSelectedText()
else:
# Removing to the end leaves the first live block in place but
# empty, so the following insert lands in it with no extra newline.
first = max(0, doc.blockCount() - self._liveRows)
cursor.setPosition(doc.findBlockByNumber(first).position())
cursor.movePosition(QTextCursor.End, QTextCursor.KeepAnchor)
cursor.removeSelectedText()
for index, runs in enumerate(pending + live):
if index:
cursor.insertText('\n')
for text, attrs in runs:
if text:
cursor.insertText(text, self._formatFor(attrs))
cursor.endEditBlock()
self._liveRows = len(live)
if follow:
scrollBar.setValue(scrollBar.maximum())
self._applyCursor()
def _applyCursor(self) -> None:
"""Draw the terminal cursor as an inverted cell."""
cursor = self._screen.cursor
if cursor.hidden:
self.setExtraSelections([])
return
doc = self.document()
# The live screen occupies the last _liveRows blocks, so the cursor row
# is an offset into that region rather than an absolute block number.
liveStart = max(0, doc.blockCount() - self._liveRows)
block = doc.findBlockByNumber(min(liveStart + cursor.y, doc.blockCount() - 1))
if not block.isValid():
return
# A row can be shorter than the screen width when it holds double width
# characters, so clamp rather than trusting the column.
column = min(cursor.x, max(0, block.length() - 1))
selection = QTextEdit.ExtraSelection()
selection.cursor = QTextCursor(block)
selection.cursor.setPosition(block.position() + column)
selection.cursor.movePosition(QTextCursor.Right, QTextCursor.KeepAnchor)
selection.format = self._cursorFormatAt(cursor.y, cursor.x)
self.setExtraSelections([selection])
def _cursorFormatAt(self, row: int, column: int) -> QTextCharFormat:
"""Build the cursor block by inverting the colors of the cell under it.
Inverting fixed theme colors instead would make the cursor disappear
wherever it happens to land on text that is already close to those
colors.
"""
cell = self._screen.buffer[row][column]
foreground, background = self._colors(cell.fg, cell.bg, cell.bold, cell.reverse)
fmt = QTextCharFormat()
fmt.setForeground(background)
fmt.setBackground(foreground)
return fmt
[docs]
def keyPressEvent(self, event) -> None:
"""Forward key presses to the shell instead of editing the view."""
modifiers = event.modifiers()
key = event.key()
# Copy stays available after the shell exits so output can be salvaged.
if (modifiers & Qt.ControlModifier) and (modifiers & Qt.ShiftModifier):
if key == Qt.Key_C:
self.copy()
event.accept()
return
if key == Qt.Key_V:
self._paste()
event.accept()
return
self.sendInput(keyToBytes(key, modifiers, event.text()))
event.accept()
def _paste(self) -> None:
"""Send the clipboard to the shell."""
clipboard = QApplication.clipboard()
if clipboard is None:
return
text = clipboard.text()
if not text:
return
data = text.replace('\r\n', '\r').replace('\n', '\r').encode('utf-8', errors='replace')
# Without the bracketed paste markers a multi-line paste executes every
# line as it arrives, which is a real hazard in a hardware control GUI.
if _BRACKETED_PASTE in self._screen.mode:
data = b'\x1b[200~' + data + b'\x1b[201~'
self.sendInput(data)
[docs]
def focusNextPrevChild(self, forward: bool) -> bool:
"""Keep Tab for the shell rather than moving focus."""
return False
[docs]
def resizeEvent(self, event) -> None:
"""Debounce a geometry change before reflowing the shell."""
QPlainTextEdit.resizeEvent(self, event)
self._resizeTimer.start(_RESIZE_MS)
def _applyGeometry(self) -> None:
"""Reflow the emulated screen and the pty to the current widget size."""
cols, rows = computeGrid(self.viewport().width(), self.viewport().height(),
self._cellWidth, self._cellHeight)
if cols == self._screen.columns and rows == self._screen.lines:
return
# pyte.Screen() takes columns first but Screen.resize() takes lines
# first, and struct winsize takes rows first. Pass by keyword where the
# API allows it so the ordering cannot silently transpose.
self._screen.resize(lines=rows, columns=cols)
self._setBlockLimit(rows)
if self._masterFd >= 0:
try:
setWinSize(self._masterFd, rows, cols)
except OSError:
pass
self._screen.dirty.update(range(rows))
self._armRepaint()
def _notice(self, message: str) -> None:
"""Show an out-of-band status line in the view.
Written through the emulator rather than appended directly so it becomes
part of the screen, and so it cannot desynchronise the live region
accounting in :meth:`_repaint`.
"""
self._stream.feed(f'\r\n{message}\r\n'.encode())
self._repaintTimer.stop()
self._repaint()
def _onChildGone(self) -> None:
"""Handle the shell exiting, normally by starting a fresh one.
Exiting the shell with ``exit`` or Ctrl-D is easy to do by accident, and
leaving a dead terminal behind would mean restarting the whole GUI to get
it back, so a new session is started instead.
"""
if self._finished:
return
self._finished = True
if self._readNotifier is not None:
self._readNotifier.setEnabled(False)
self._disableWriteNotifier()
# Exiting is something the user does, so it always follows a keystroke.
# A session that ends without one never got started, and restarting it
# would spawn processes in a loop.
if self._sawInput:
self._startupFailures = 0
else:
self._startupFailures += 1
if self._startupFailures >= _MAX_STARTUP_FAILURES:
status = self._proc.poll() if self._proc is not None else None
# Two short lines rather than one long one, so the notice does not
# wrap mid word in a narrow terminal.
self._stream.feed(
f'\r\n[shell exited with status {status}]'
f'\r\n[exits immediately, not restarting]\r\n'.encode())
self._screen.cursor.hidden = True
self._repaintTimer.stop()
self._repaint()
# Defer closing the descriptor out of the notifier callback.
QTimer.singleShot(0, self._closeProcess)
return
# Deferred for the same reason: this runs inside the read notifier's own
# callback, and it closes the descriptor that notifier is watching.
QTimer.singleShot(0, self.restart)
def _closeProcess(self) -> None:
"""Close the pty and reap the child. Safe to call more than once."""
proc, self._proc = self._proc, None
self._masterFd = closeShell(proc, self._masterFd)
[docs]
def shutdown(self) -> None:
"""Stop all I/O and terminate the shell. Safe to call more than once."""
self._finished = True
for notifier in (self._readNotifier, self._writeNotifier):
if notifier is not None:
notifier.setEnabled(False)
self._repaintTimer.stop()
self._resizeTimer.stop()
self._closeProcess()
[docs]
def closeEvent(self, event) -> None:
"""Tear down the shell when this widget is closed as a window."""
self.shutdown()
QPlainTextEdit.closeEvent(self, event)
[docs]
class TerminalPanel(QWidget):
"""A :class:`LinuxTerminal` with a button to detach it into its own window.
Detaching is useful because a tab is only as tall as the window it lives in.
A separate window can be sized and placed independently, or moved to another
monitor, which makes a long build log or a full screen program readable.
Reparenting does not disturb the shell. The child process is held by a file
descriptor and a socket notifier, neither of which is tied to a window, so
detaching and reattaching keep the same shell, its working directory, and
its scrollback.
Parameters
----------
parent : QWidget | None, optional
Parent Qt widget.
argv : list[str] | None, optional
Program to run, passed through to :class:`LinuxTerminal`. Defaults to
the user's login shell.
label : str, optional
Tab label to restore when reattaching.
windowTitle : str, optional
Title of the detached window.
noun : str, optional
What the detach button tooltips call the contents.
"""
def __init__(self, parent: QWidget | None = None, *,
argv: list[str] | None = None,
label: str = 'Terminal',
windowTitle: str = 'Rogue Terminal',
noun: str = 'terminal') -> None:
QWidget.__init__(self, parent)
self._tab = None
self._tabIndex = 0
self._tabLabel = label
self._windowTitle = windowTitle
self._attachTip = f'Move the {noun} into its own window'
self._detachTip = f'Put the {noun} back in the main window'
self.terminal = LinuxTerminal(parent=None, argv=argv)
self._button = QPushButton('Detach')
self._button.setToolTip(self._attachTip)
# No focus, so clicking it does not take the keyboard away from the
# shell and Tab completion is never captured by the button.
self._button.setFocusPolicy(Qt.NoFocus)
self._button.clicked.connect(self.toggleDetached)
header = QHBoxLayout()
header.setContentsMargins(0, 0, 0, 0)
header.addWidget(self._button)
header.addStretch(1)
layout = QVBoxLayout()
layout.setContentsMargins(0, 0, 0, 0)
layout.addLayout(header)
layout.addWidget(self.terminal, 1)
self.setLayout(layout)
[docs]
def isDetached(self) -> bool:
"""Return whether the terminal is currently its own window."""
return self._tab is not None
def _findTabWidget(self) -> QTabWidget | None:
"""Return the tab widget this panel is a page of, if any.
Pages of a ``QTabWidget`` are children of an internal stack widget, so
this walks up rather than checking the immediate parent.
"""
widget = self.parentWidget()
while widget is not None:
if isinstance(widget, QTabWidget):
return widget
widget = widget.parentWidget()
return None
[docs]
def toggleDetached(self) -> None:
"""Detach into a window, or put it back in its tab."""
if self.isDetached():
self.reattach()
else:
self.detach()
[docs]
def detach(self) -> None:
"""Move the terminal out of its tab and into its own window."""
if self.isDetached():
return
tab = self._findTabWidget()
if tab is None:
return
self._tab = tab
self._tabIndex = tab.indexOf(self)
self._tabLabel = tab.tabText(self._tabIndex)
owner = tab.window()
tab.removeTab(self._tabIndex)
# Reparented to the main window rather than to nothing, with the window
# flag set. It still behaves as a separate window, but it stays owned by
# the GUI, so closing the GUI takes it down too instead of leaving a
# stray window keeping the process alive.
self.setParent(owner, Qt.Window)
self.setWindowTitle(self._windowTitle)
self.resize(*_DETACHED_SIZE)
self._button.setText('Reattach')
self._button.setToolTip(self._detachTip)
self.show()
self.raise_()
self.activateWindow()
self.terminal.setFocus(Qt.OtherFocusReason)
[docs]
def reattach(self) -> None:
"""Put the terminal back where it came from."""
if not self.isDetached():
return
tab = self._tab
self._tab = None
# The tab count can have changed while detached, so clamp rather than
# trusting the remembered index.
index = min(self._tabIndex, tab.count())
self.setWindowFlags(Qt.Widget)
tab.insertTab(index, self, self._tabLabel)
tab.setCurrentIndex(index)
self._button.setText('Detach')
self._button.setToolTip(self._attachTip)
self.terminal.setFocus(Qt.OtherFocusReason)
[docs]
def shutdown(self) -> None:
"""Terminate the shell. Safe to call more than once."""
self.terminal.shutdown()
[docs]
def closeEvent(self, event) -> None:
"""Reattach instead of closing when detached.
Closing the detached window would otherwise leave the terminal with no
way back into the GUI, so the close is treated as a request to reattach.
"""
if self.isDetached():
event.ignore()
self.reattach()
return
QWidget.closeEvent(self, event)