LinuxTerminal

For conceptual usage, see:

class pyrogue.pydm.widgets.TerminalPanel(parent=None, *, argv=None, label='Terminal', windowTitle='Rogue Terminal', noun='terminal')[source]

A 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, default: None) – Parent Qt widget.

  • argv (list[str] | None, default: None) – Program to run, passed through to LinuxTerminal. Defaults to the user’s login shell.

  • label (str, default: 'Terminal') – Tab label to restore when reattaching.

  • windowTitle (str, default: 'Rogue Terminal') – Title of the detached window.

  • noun (str, default: 'terminal') – What the detach button tooltips call the contents.

closeEvent(event)[source]

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.

Return type:

None

detach()[source]

Move the terminal out of its tab and into its own window.

Return type:

None

isDetached()[source]

Return whether the terminal is currently its own window.

Return type:

bool

reattach()[source]

Put the terminal back where it came from.

Return type:

None

shutdown()[source]

Terminate the shell. Safe to call more than once.

Return type:

None

toggleDetached()[source]

Detach into a window, or put it back in its tab.

Return type:

None

class pyrogue.pydm.widgets.LinuxTerminal(parent=None, *, argv=None)[source]

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, default: None) – Parent Qt widget.

  • argv (list[str] | None, default: None) – 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.

closeEvent(event)[source]

Tear down the shell when this widget is closed as a window.

Return type:

None

focusNextPrevChild(forward)[source]

Keep Tab for the shell rather than moving focus.

Return type:

bool

Parameters:

forward (bool)

inputMethodEvent(event)[source]

Swallow input method events; composition is not supported.

Return type:

None

keyPressEvent(event)[source]

Forward key presses to the shell instead of editing the view.

Return type:

None

resizeEvent(event)[source]

Debounce a geometry change before reflowing the shell.

Return type:

None

restart()[source]

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.

Return type:

None

sendInput(data)[source]

Send user input to the shell.

Separate from writeBytes() because the emulator also writes to the pty on its own to answer terminal queries. Only real input shows that the session reached a usable state, which is what distinguishes a user exiting a shell from a shell that never started.

Parameters:

data (bytes) – Bytes produced by a key press or a paste.

Return type:

None

showEvent(event)[source]

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.

Return type:

None

shutdown()[source]

Stop all I/O and terminate the shell. Safe to call more than once.

Return type:

None

writeBytes(data)[source]

Queue bytes for the child process.

Parameters:

data (bytes) – Bytes to send to the shell.

Return type:

None

pyrogue.pydm.widgets.terminal.keyToBytes(key, modifiers, text)[source]

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 to write to the pty, or b'' when the key produces no input.

Return type:

bytes

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.

pyrogue.pydm.widgets.terminal.resolveColor(value, bright=False)[source]

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, default: False) – 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:

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.

Return type:

QColor | None