The ScrollWindow¶

The ScrollWindow class is a daugther of the Window class. It is used to create a window that can be scrolled up and down. To re-use our ShowMyData class from before, we could use the ScrollWindow class to display only parts of our lines. For instance, we could decide only to write 10 lines of our data at a time:

class MyScrollData( ScrollWindow ):
      def contents( self, **kwargs ):

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

         data = kwargs.get( "data", None )

         if data is None:
            self.write( self.to_first_line, 0, "No data was passed to the window" )

         else:

            # we subset to the lines within our scrolling range
            subset = data[ self.scroll_range( as_slice = True ) ]
            # there is also a pre-defined method to do this:
            # subset = self.crop_data_to_scroll_range( data )

            # then we write our data
            self.to_first_line
            for line in subset:
               self.write( self.to_next_line, 0, line )


            self.write( self.to_next_line, 0, f"{'-' * 10} end of scroll-range {'-' * 10}" )

         # now we enable the scrolling, and restrict the scrolling to make sure that the window dimensios do not interfer with our scrolling.
         # This is useful when our window is much larger or smaller than our data. In this case we might either scroll past our data
         # or not be able to scroll all our data, because by default the window height is used as scrolling reference.
         self.auto_scroll( restrict = len(data) )

         self.quit_on( keystring = "q" )
         self.refresh()

We can now call this and get a scrollable window

w = MyScrollData( start_line = 1, height = 50, width = 50 )

# now we set the scroll range to 10 entries
w.set_scroll_range( 10 )

w.run( data = [ f"This is line {i+1}" for i in range(100) ] )

And our final window looks like this (scrolled a little bit):

This is my data
--------------------------------------------------
This is line 5
This is line 6
This is line 7
This is line 8
This is line 9
This is line 10
This is line 11
This is line 12
This is line 13
This is line 14
---------- end of scroll-range ----------

pytermwindows.ScrollWindow class¶

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

Bases: Window

A window to handle writing data to the terminal using the curses library. This window is specifically designed to write content that is too long to be shown in full and instead should be presented scrollably.

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…

auto_scroll(restrict: Optional[int] = None)¶

Automatically checks for the key input as either up or down arrow keys and scrolls accordingly.

Parameters: restrict (int) – The maximum number of entries to scroll. This can be for instance the length of the data to ensure it does not scroll out of the window. By default the window height is used.
Returns: True if the current top index has been changed, False otherwise.
Return type: bool

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

crop_data_to_scroll_range(data)¶: Return a subset of the data to display in the scroll window.

down = 1¶

scroll(direction)¶

Scroll the dataa by n entries either up or down.

Parameters: direction (int) – The direction to scroll in numbers of entries. If this is negative then the direction is upward. If this is positive then the direction is downward.

scroll_down(n: int = 1, restrict: Optional[int] = None)¶

Scroll down n data entries.

Parameters

n (int) – The number of entries to scroll down.
restrict (int) – The maximum number of entries to scroll. By default this will be the number of lines in the window, but this can be set to a different value such as the length of the currently displayed data.

scroll_range(as_slice: bool = False)¶

Get the top and bottom index of the data to display in the scroll window.

Parameters: as_slice (bool) – If True then return a slice object instead of a tuple of the top and bottom indices.

scroll_up(n: int = 1)¶

Scroll up n data entries.

Parameters: n (int) – The number of entries to scroll up.

set_scroll_keys(up_key: int, down_key: int)¶

Set the keys to scroll the window.

Parameters

up_key (int) – The key to scroll up at.
down_key (int) – The key to scroll down at.

set_scroll_range(bottom: int)¶

Set the number of lines to print after the top line within the scroll window. This will be used to subset any iterable data to write to the scroll window.

Parameters: bottom (int) – The number of lines to print after the top line.

up = -1¶