The default Window¶

We can make a simple window to show the contents of some iterable data input.

class ShowMyData( Window ):
      def contents( self, **kwargs ):

         # write our header
         self.write( self.to_first_line, 0, "This is my data" )
         self.write( self.to_next_line, 0, "-" * 50 )

         # get the data we want from the kwargs
         data = kwargs.pop( "data", None )
         if data is None:
            self.write( self.to_next_line, 0, "No data was passed to the window" )
         else:
            for line in data:
               self.write( self.to_next_line, 0, line )

         # make sure that the window can be exited again
         self.quit_on( keystring = "q" )

         # and refresh the window contents
         self.refresh()

Now we can call this window within our code like this:

w = ShowMyData( height = 20, width = 50 ) # we give the window large enough dimensions
mydata = [ f"This is my data ({i+1})" for i in range(10) ]
w.run( data = mydata )

And the resulting window will look like this:

This is my data
--------------------------------------------------
This is my data (1)
This is my data (2)
This is my data (3)
This is my data (4)
This is my data (5)
This is my data (6)
This is my data (7)
This is my data (8)
This is my data (9)
This is my data (10)

pytermwindows.Window class¶

class pytermwindows.Window.Window(name: Optional[str] = None, width: Optional[int] = None, height: Optional[int] = None, start_line: int = 0, refresh: int = 100, waitkey: int = 50, use_color: bool = False)¶

Bases: object

A window to handle writing python data to the terminal using the curses library. It offers a number of features to make it easier to write to the terminal in specific settings.

window¶

The main curses window object.

Type: curses.window

width¶

The width of the window in characters per line.

Type: int

height¶

The height of the window as maximal number of lines.

Type: int

children¶

A dictionary of sub-windows and panes that may be stored inside the main window. These can be added to using add_child, and accessed directly or via get_child.

Type: dict

name¶

The name of this window.

Type: str

parent¶

The parent window of this window. This will be automatically set in case a window is added via add_child.

Type: Window

Setting Updates

set_update_interval: Set the update interval. The Window supports a second time interval (measured in seconds rather than milliseconds) in which periodic updates may be performed such as reading external data files to update the window content, while allowing the window itself to render at a much faster rate.
can_update: Check if the window can update. If the update interval has been reached, this will return True and reset the internal update counter.
update_counter: Increment the update counter. This should be called each time the window is refreshed.

Parameters

width (int) – Width of the window in characters per line.
height (int) – Height of the window as maximal number of lines.
start_line (int) – Start line of the window.
refresh (int) – Refresh rate of the window in milliseconds.
waitkey (int) – Wait time between each refresh in milliseconds.
use_color (bool) – Use colors if available. This will slow down the rendering a bit…

add_child(child)¶

Add a child window or pane to the main window.

Parameters: child – The child window or pane to add.

adjust_size()¶: Resizes the window to terminal size.

auto_adjust_size()¶: Automatically adjust the size of the window in case of terminal resize.

property bottom_line: int¶: Get the bottom line of the window.

can_update()¶: Check if the window can be updated and reset the counter if so.

clear_line(line: int)¶

Clear a line.

Note

This will not refresh the window. And not affect the positioning of the current_line.

Parameters: line (int or Iterable) – The line(s) to clear.

colored(text: str, color: str)¶

Turn a string to a tuple with a color.

Parameters

text (str) – The string to turn to a colored tuple.
color (str) – The color to use.

contents(**kwargs)¶: The actual content of the window. This will be the method called by run.

property current_line: int¶: Get the current line (by default the bottom-most line)

erase()¶: Erase the window contents and refresh.

exit()¶: Exit the window via keyboard interrupt.

property first_line: int¶: Get the first line of the window.

get_child(name)¶

Get a child window or pane from the main window.

Parameters: name (str) – The name of the child window or pane to get.

static int_to_key(key) → str¶: Convert an integer to a keypress.

is_columwise_iterable(pos, string) → bool¶

Check if a string is columnwise iterable.

Note

Column-wise iterable means the data is interpreted as a row!

Parameters

pos (int or list or tuple) – The position(s) to write to.
string (str or list or tuple) – The string(s) to write.

Return type

bool

is_linewise_iterable(line, string) → bool¶

Check if a string is linewise iterable.

Note

Line-wise iterable means the data is interpreted as a column!

Parameters

line (int or list or tuple) – The line(s) to write to.
string (str or list or tuple) – The string(s) to write.

Return type

bool

static key_to_int(key) → int¶: Convert a keypress to an integer.

property keycode: int¶: Get the last keypress event from the window as an integer code or None (if no keys were pressed).

property keystring: str¶: Get the last keypress event from the window as a string or None (if no keys were pressed).

property last_line: int¶: Get the down-most line that was written to.

line_diff(line)¶

Get the difference between the current line and the given line.

Parameters: line (int) – The line to get the difference to.

property next_line: int¶: Get the one-next line.

property previous_line: int¶: Get the one-previous line.

quit_on(keycode: Optional[int] = None, keystring: Optional[str] = None)¶

Quit the window when the given keycode or keystring is pressed.

Parameters

keycode (int) – The keycode of the key that will quit the window.
keystring (str) – The keystring of the key that will quit the window.

refresh()¶: Refresh the window.

reload()¶: Reload the window. This will erase, refresh, and reset the line counter.

reset_lines()¶: Reset the line counter to the first line.

resize(height: int, width: int)¶

Resize the window.

Parameters

height (int) – The new height of the window (in numbers of lines).
width (int) – The new width of the window (in numbers of characters per line).

run(**kwargs)¶: Run the main window.

set_line(line)¶: Set the current line.

set_update_interval(value: int)¶

Set the interval after which the window should be “updatable”. In this case the method can_update will return True if a number of refreshes have been performed that corresponded approximately to the provided time interval.

Parameters: value (int) – The new update interval in seconds.

setup(width: Optional[int] = None, height: Optional[int] = None, start_line: int = 0, refresh: int = 100, waitkey: int = 50, use_color: bool = False)¶

Settings for the window.

Parameters

width (int) – Width of the window in characters per line.
height (int) – Height of the window as maximal number of lines.
start_line (int) – Start line of the window.
refresh (int) – Refresh rate of the window in milliseconds.
waitkey (int) – Wait time between each refresh in milliseconds.
use_color (bool) – Use colors if available. This will slow down the rendering a bit…

property size: tuple¶: Get the size of the window in as (height, width). Height is given in number of lines in the window, and width in number of characters per line.

property to_bottom_line: int¶: Go to the bottom line of the window.

property to_first_line: int¶: Go to the top line of the window.

property to_last_line: int¶: Go to the down-most line that was written to.

property to_next_line: int¶: Go to the one-next line and update the current line.

property to_previous_line: int¶: Go to the one-previous line and update the current line.

update_counter()¶: Increment the counter value.

write(line: int, pos: int, string: str, refresh: bool = False, clear: bool = False)¶

Write a string to the window.

Parameters

line (int) – The line to write to.
pos (int) – The position within the line to start writing at.
string (str) – The string to write.
refresh (bool) – Whether to refresh the window after writing.
clear (bool) – Whether to clear the line before writing.

write_to(window_or_pane, line: int, pos: int, string: str, refresh: bool = False, clear: bool = False)¶

Write a string to a specific (sub)window or pane.

Parameters

window_or_pane – The window or pane to write to.
line (int) – The line to write to.
pos (int) – The position within the line to start writing at.
string (str) – The string to write.
refresh (bool) – Whether to refresh the window after writing.
clear (bool) – Whether to clear the line before writing.