Window Objects

Windows successively render 2D grids of text (usually instances of FSArray) to the terminal.

A window owns its output stream - it is assumed (but not enforced) that no additional data is written to this stream between renders, an assumption which allowing for example portions of the screen which do not change between renderings not to be redrawn during a rendering.

There are two useful window classes, both subclasses of BaseWindow. FullscreenWindow renders to the terminal’s alternate screen buffer (no history preserved, like command line tools Vim and top) while CursorAwareWindow renders to the normal screen. It is also is capable of querying the terminal for the cursor location, and uses this functionality to detect how a terminal moves its contents around during a window size change. This information can be used to compensate for this movement and prevent the overwriting of history on the terminal screen.

Window Objects - Example

>>> from curtsies import FullscreenWindow, fsarray
>>> import time
>>> with FullscreenWindow() as win:
...     win.render_to_terminal(fsarray([u'asdf', u'asdf']))
...     time.sleep(1)
...     win.render_to_terminal(fsarray([u'asdf', u'qwer']))
...     time.sleep(1)

Window Objects - Context

render_to_terminal() should only be called within the context of a window. Within the context of an instance of BaseWindow it’s important not to write to the stream the window is using (usually sys.stdout). Terminal window contents and even cursor position are assumed not to change between renders. Any change that does occur in cursor position is attributed to movement of content in response to a window size change and is used to calculate how this content has moved, necessary because this behavior differs between terminal emulators.

Entering the context of a FullscreenWindow object hides the cursor and switches to the alternate terminal screen. Entering the context of a CursorAwareWindow hides the cursor, turns on cbreak mode, and records the cursor position. Leaving the context does more or less the inverse.

Window Objects - API Docs

class curtsies.window.BaseWindow(out_stream=None, hide_cursor=True)
array_from_text(msg)

Returns a FSArray of the size of the window containing msg

get_term_hw()

Returns current terminal height and width

height

The current height of the terminal window

width

The current width of the terminal window

class curtsies.FullscreenWindow(out_stream=None, hide_cursor=True)

2D-text rendering window that dissappears when its context is left

FullscreenWindow will only render arrays the size of the terminal or smaller, and leaves no trace on exit (like top or vim). It never scrolls the terminal. Changing the terminal size doesn’t do anything, but rendered arrays need to fit on the screen.

Note

The context of the FullscreenWindow object must be entered before calling any of its methods.

Within the context of CursorAwareWindow, refrain from writing to its out_stream; cached writes will be inaccurate.

Constructs a FullscreenWindow

Parameters:
  • out_stream (file) – Defaults to sys.__stdout__
  • hide_cursor (bool) – Hides cursor while in context
render_to_terminal(array, cursor_pos=(0, 0))

Renders array to terminal and places (0-indexed) cursor

Parameters:array (FSArray) – Grid of styled characters to be rendered.
  • If array received is of width too small, render it anyway
  • If array received is of width too large,
  • render the renderable portion
  • If array received is of height too small, render it anyway
  • If array received is of height too large,
  • render the renderable portion (no scroll)
class curtsies.CursorAwareWindow(out_stream=None, in_stream=None, keep_last_line=False, hide_cursor=True, extra_bytes_callback=None)

Renders to the normal terminal screen and can find the location of the cursor.

Note

The context of the CursorAwareWindow object must be entered before calling any of its methods.

Within the context of CursorAwareWindow, refrain from writing to its out_stream; cached writes will be inaccurate and calculating cursor depends on cursor not having moved since the last render. Only use the render_to_terminal interface for moving the cursor.

Constructs a CursorAwareWindow

Parameters:
  • out_stream (file) – Defaults to sys.__stdout__
  • in_stream (file) – Defaults to sys.__stdin__
  • keep_last_line (bool) – Causes the cursor to be moved down one line on leaving context
  • hide_cursor (bool) – Hides cursor while in context
  • extra_bytes_callback (f(bytes) -> None) – Will be called with extra bytes inadvertantly read in get_cursor_position(). If not provided, a ValueError will be raised when this occurs.
get_cursor_position()

Returns the terminal (row, column) of the cursor

0-indexed, like blessings cursor positions

get_cursor_vertical_diff()

Returns the how far down the cursor moved since last render.

Note

If another get_cursor_vertical_diff call is already in progress, immediately returns zero. (This situation is likely if get_cursor_vertical_diff is called from a SIGWINCH signal handler, since sigwinches can happen in rapid succession and terminal emulators seem not to respond to cursor position queries before the next sigwinch occurs.)

render_to_terminal(array, cursor_pos=(0, 0))

Renders array to terminal, returns the number of lines scrolled offscreen

Returns:Number of times scrolled
Parameters:array (FSArray) –

Grid of styled characters to be rendered.

If array received is of width too small, render it anyway

if array received is of width too large, render it anyway

if array received is of height too small, render it anyway

if array received is of height too large, render it, scroll down, and render the rest of it, then return how much we scrolled down