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