Skip to content

vtf txb display displays

Jump to bottom
srccircumflex edited this page Apr 24, 2023 · 5 revisions

↑ vtf-txb-display

displays

The module contains the display types for creating representations of the TextBuffer data.

Module contents

Objects

Final Display Types

class displays.DisplayBrowsable(_DisplayBase)

The completed display type for browsable display of TextBuffer data.

┌- - - - - - - -  displayed area   - - - - - - - - - - - - - - - - - - - - - - - - - - - - -┐
│                                                                                           │
│his is the content of a row  and is scrolled by the size of a defined area when passing█the│edge of the displayed area, the lapping indicates how many characters from the previous area are visible at the left edge.

                                                                                        ┌- - - - - - - -  displayed area   - - - - - - - - - - - - - - - - - - - - - - - - - - - - -┐
                                                                                        │                                                                                           │
This is the content of a row  and is scrolled by the size of a defined area when passing│the█edge of the displayed area, the lapping indicates how many characters from the previous│area are visible at the left edge.

Parameters and settings in addition to the basic ones of the _DisplayBase:

  • width

    The total width of the display. The space reserved for prompts is subtracted for the display of the row data.

  • prompt_factory

    A factory to create the right and left prompt at the edge of the displayed area. Receives the _Row object and the type of the displayed area when queried, and must return the prompts as EscSegment or EscContainer type.

    Types of a displayed area:
    • 0 ( Basic area )
      The characters of the row do not span the size of the displayed area.
    • 1 ( First area )
      The number of characters in the row is larger than the space in the display and the area at the left end is displayed.
    • 2 ( Middle area )
      ... and neither the area at the left end nor the area at the right end is displayed.
    • 3 ( Last area )
      ... and the area at the right end is displayed.
    • 4 ( Out of range )
      Occurs only when the visual representation of remaining rows follows the cursor in parallel even beyond the data limits of a row (see parameter stdcurpos).
    >>> prompt_factory=lambda row, dispt: (EscSegment("%-4s║" % row.__row_num__), EscSegment("║%-4s" % (row.cursors.content if row.inrow() else "")))
  • promptl_len

    The reserved area for the prompt on the left side of the display, the prompt from the query through prompt_factory must have this length.

  • promptr_len

    The reserved area for the prompt on the right side of the display, the prompt from the query through prompt_factory must have this length.

  • lapping

    This number of characters of the previous area will be displayed in the next part after passing the displayed area of a row.

  • vis_overflow

    Characters to represent the overspan of the displayed area by row data.

    ( <overspan on the left side>, <overspan on the right side>, <wide overspan on the left side -- only relevant if the rows follows the cursor in parallel even beyond the data limits of a row (see parameter stdcurpos)> )

    >>> vis_overflow=("<", ">", "<<")
  • width_min_char

    This character is displayed multiplied by the remaining width if the minimum width is not reached. The minimum width consists of the prompt lengths, the lapping and the characters for the displayed overflow.

_¶

x_minimum_size_undercut: bool

The attribute is set to True if the minimum width is not reached.

make_row_frame(row, vis_cursor) -> RowFrameItem

The characteristic row-framing method for completing _DisplayBase.

scroll_x(z, mark) -> bool

Move the cursor in the TextBuffer by display part(s) on the x-axis.

overload settings(*, width=..., height=..., y_auto_scroll_distance=..., lapping=..., prompt_factory=..., promptl_len=..., promptr_len=..., vis_overflow=..., width_min_char=..., vis_marked=..., vis_end=..., vis_nb_end=..., visendpos=..., vis_cursor=..., vis_anchor=..., vis_cursor_row=..., highlighter=..., highlighted_rows_cache_max=..., highlighted_row_segments_max=..., vis_tab=..., stdcurpos=..., i_rowitem_generator=..., i_display_generator=..., i_before_framing=...) -> None

settings(**kwargs) -> None

Change the _DisplayBase | DisplayBrowsable settings.

class displays.DisplayScrollable(DisplayBrowsable)

A derivative of the DisplayBrowsable to represent the display as scrolling text.

┌- - - - - - - -  displayed area   - - - - - - - - - - - - - - - - - - - - - - - - - - - - -┐
│                                                                                           │
│his is the content of a row, which█is successively scrolled when the lapping is passed. The│cursor then remains at the visual position of the lapping (scrolling text).

 ┌- - - - - - - -  displayed area   - - - - - - - - - - - - - - - - - - - - - - - - - - - - -┐
 │                                                                                           │
T│is is the content of a row, which █s successively scrolled when the lapping is passed. The │ursor then remains at the visual position of the lapping (scrolling text).

  ┌- - - - - - - -  displayed area   - - - - - - - - - - - - - - - - - - - - - - - - - - - - -┐
  │                                                                                           │
Th│s is the content of a row, which i█ successively scrolled when the lapping is passed. The c│rsor then remains at the visual position of the lapping (scrolling text).

The parameter lapping specifies in this type from which character, counted from the left side of the display, the visual text scrolling is triggered.

make_row_frame(row, vis_cursor) -> RowFrameItem

The characteristic row-framing method for completing _DisplayBase.

overload settings(*, width=..., height=..., y_auto_scroll_distance=..., lapping=..., prompt_factory=..., promptl_len=..., promptr_len=..., vis_overflow=..., width_min_char=..., vis_marked=..., vis_end=..., vis_nb_end=..., visendpos=..., vis_cursor=..., vis_anchor=..., vis_cursor_row=..., highlighter=..., highlighted_rows_cache_max=..., highlighted_row_segments_max=..., vis_tab=..., stdcurpos=..., i_rowitem_generator=..., i_display_generator=..., i_before_framing=...) -> None

settings(**kwargs) -> None

Change the _DisplayBase | DisplayScrollable settings.

class displays.DisplayStatic(_DisplayBase)

The completed display type for the restricted bounding display of TextBuffer data. This display does not allow to limit the width of the visual representation of the data over this component.

Apart from the parameters and settings of the _DisplayBase, this display type has only one other feature:

  • prompt_factory

    A factory to create the right and left prompt at the edge of the displayed area. Receives the _Row object when queried, and must return the prompts as EscSegment or EscContainer type.

    >>> prompt_factory=lambda row: (EscSegment("%-4s║" % row.__row_num__), EscSegment("║%-4s" % (row.cursors.content if row.inrow() else "")))

make_row_frame(row, vis_cursor) -> RowFrameItem

The characteristic row-framing method for completing _DisplayBase.

scroll_x(z, mark) -> bool

Raises TypeError.

overload settings(*, height=..., y_auto_scroll_distance=..., prompt_factory=..., vis_marked=..., vis_end=..., vis_nb_end=..., visendpos=..., vis_cursor=..., vis_anchor=..., vis_cursor_row=..., highlighter=..., highlighted_rows_cache_max=..., highlighted_row_segments_max=..., vis_tab=..., i_rowitem_generator=..., i_display_generator=..., i_before_framing=...) -> None

settings(**kwargs) -> None

Change the _DisplayBase | DisplayStatic settings.
Display Base

class displays._DisplayBase

The basic object of the display types for a TextBuffer.

From the TextBuffer data to the display:

  • Determination of the rows to be displayed -> list[ _Row ].

  • Calibration of coordinates of tabs, markers, and cursor anchors per row -> VisRowItem.
    • Calculation of the framing parameters of the row (this method determines the behavior of the display and is implemented in the final display types) -> RowFrameItem.

  • Highlight row by HighlightRegex or HighlightAdvanced or HighlighterBase -> EscContainer.

  • Visual marked areas -> EscContainer.

  • Visual finishing -> EscContainer.

    i

    function

    ~

    Row end visualization

    #

    Cursor anchor visualization

    █

    Cursor visualization

    +

    Row framing
    Orders:
    visendpos == "data":

    ~ # █ +

    visendpos == "data f":

    # █ ~ +

    visendpos == "visN1":

    # █ + ~

  • Creation of the final display row -> DisplayRowItem.
    • Append left/right prompts to the framed and visualized row.

  • Summarizing the display rows and setting the cursor x/y-position relative to the displayed area -> DisplayItem.

Basic parameters and settings:

  • __buffer__

    The TextBuffer object for which the display is created.

  • height

    The number of rows in the area to be displayed.

  • y_auto_scroll_distance

    The number of rows that may remain between the current cursor position and the boundary of the currently displayed area until the automatic scrolling is triggered.

  • highlighter

    Which highlighter is to be assigned to attribute __highlighter__ (required component of the display).

  • highlighted_rows_cache_max

    Has meaning when the highlighter is HighlightRegex or HighlightAdvanced.

  • highlighted_row_segments_max

    Has meaning when the highlighter is HighlightRegex or HighlightAdvanced.

  • vis_tab [OPTIONAL -- can be None]

    Assigns a function to the visualization of relative tab ranges that receives the size of the range and must return a correspondingly long string.

  • vis_marked [OPTIONAL -- can be None]

    Two executable objects for displaying marked areas. The first function is applied only to the first character of the range, remaining strings are passed to the second. The functions receive the applicable row string, the VisRowItem and the marker coordinate calibrated to the row; the return value should be the visualized row string.

    >>> from vtframework.iodata.sgr import SGRWrap, Ground, Fore
>>> vis_marked=(lambda c, itm, coord: SGRWrap(c, Ground.hex('11ACAE') + Fore.black, cellular=True),
>>>             lambda c, itm, coord: SGRWrap(c, Ground.hex('66B8B1') + Fore.black, cellular=True))
  • vis_end [OPTIONAL -- fields or total can be None]

    Defines the visual representation of breaking line breaks in ( normal form, when a marking starts on it, and within a marked area )

  • vis_nb_end [OPTIONAL -- fields or total can be None]

    Defines the visual representation of non-breaking line breaks in ( normal form, when a marking starts on it, and within a marked area )

  • visendpos

    Define the position of the visual end character.

    • "data" : Equal to the data position (directly following).
    • "data f" : Equal to the data position (directly following) also overwrites the visualization of a cursor position.
    • "visN1" : At the last visual place of the display.
  • vis_cursor [OPTIONAL -- can be None]

    Visualize the character at the cursor position. Receives the character and the VisRowItem when executed and should return the visualized version.

    >>> vis_cursor=lambda c, itm: (SGRWrap(c, Ground.name('red1'), inner=True, cellular=True)
>>>                            if insert_mode
>>>                            else c)
  • vis_anchor [OPTIONAL -- can be None]

    Visualize the character of a cursor anchor. Receives the character, the VisRowItem and the anchor item when executed and should return the visualized version.

    >>> vis_anchor=lambda c, itm, itm: SGRWrap(c, Ground.hex('FFF800'), inner=True)
  • vis_cursor_row [OPTIONAL -- can be None]

    Visualize the row of the current cursor position. Receives the characters of the row and the VisRowItem when executed and should return the visualized version.

  • stdcurpos

    Specify the standard cursor position for rows.

    • <as natural number>
    • "follow" : follows as far as possible.
    • "parallel" : follows across row endings as well.
    • "end" : as the right end of a row.
  • i_rowitem_generator [OPTIONAL -- can be None]

    An interface within the reverse iteration to determine the VisRowItem. Receives the VisRowItem.

  • i_display_generator [OPTIONAL -- can be None]

    An interface within the iteration to create the DisplayRowItem. Receives the DisplayRowItem.

  • i_before_framing [OPTIONAL -- can be None]

    An interface that receives the row before framing and the VisRowItem, must return the row.

_¶

__highlighter__: HighlighterBase | HighlightRegex | HighlightAdvanced

current_cursor_row_area: tuple[int, int]

The range that can be reached by the cursor without screen scrolling, indicated as row numbers.

current_display: DisplayItem

current_display_row: DisplayRowItem

current_row_num: int

current_slice: tuple[int, int]

The current slice of the row list in the buffer for the displayed range.

current_x_pointer: int

current_y_pointer: int

height: int

height_central: int

y_auto_scroll_distance: int

y_minimum_size_undercut: bool

The attribute is set to True if the height is set to <= 0.

overload display_coord_target(vis_coord, quarter="", quarter_focus=False, quarter_border_focus=False, column_rel_to_="display", as_far=True) -> DisplayCoordTarget

overload display_coord_target(vis_coord, *, column_rel_to_="display", as_far=True) -> DisplayCoordTarget

display_coord_target(vis_coord, quarter="", quarter_focus=False, quarter_border_focus=False, column_rel_to_="display", as_far=True) -> DisplayCoordTarget

Create a DisplayCoordTarget that points to the visual coordinate (vis_coord) in the display.

If quarter contains a cardinal direction, the coordinate in vis_coord of the associated axis is understood as the distance to the shown buffer. vis_coord is formulated as (<x>, <y>).

Example: If area is "E", the x coordinate is understood as the distance to the left edge of the shown area; the y coordinate then describes an actual row number of the displayed area. If area is "NO", both the x and the y coordinate are understood as a distance specification.

If a cardinal direction is set (quarter), the parameters quarter_focus and quarter_border_focus are evaluated: If quarter_focus is True, only the axis(es) of vis_coord that belongs to the cardinal direction is evaluated and the current position of the remaining axis is kept. If quarter_border_focus is True, before the evaluation of quarter_focus the DisplayCoordTarget is calculated starting from the edge on the side of the cardinal direction of the display.

Example:

>>>        ┌─<Widget>──────┐
... <row0> │               │
... <row1> │            █  │   # Cursor (x = 12, y = 1)
... <row2> │               │
... <row3> │               │
...        └───────────────┘
>>> display_coord_target(vis_coord=(2, 1), quarter="S", quarter_focus=True, quarter_border_focus=True)
...        ┌─<Widget>──────┐
... <row1> │               │
... <row2> │               │
... <row3> │               │
... <row4> │            █  │   # Cursor (x = 12, y = 4)
...        └───────────────┘

By default, DisplayCoordTarget is calculated in conjunction with the visual coordinate (vis_coord) starting from the visual display (column_rel_to_="display"). If this parameter is set to origin, the coordinates are calculated from the original position.

Example:

>>>        ┌─<Widget>──────┐
... <row0> │0123456789ABCD>│
... <row1> │<CDEFGHIJKL█NO>│   # Cursor (x = 22, y = 1)
... <row2> │0123456789ABCD>│
... <row3> │0123456789ABCD>│
...        └───────────────┘
>>> display_coord_target(vis_coord=(2, 2), column_rel_to_="origin")
...        ┌─<Widget>──────┐
... <row0> │0123456789ABCD>│
... <row1> │0123456789ABCD>│
... <row2> │<CDEFGHIJKLMN█>│   # Cursor (x = 24, y = 2)
... <row3> │0123456789ABCD>│
...        └───────────────┘
>>> display_coord_target(vis_coord=(2, 1), column_rel_to_="display")
...        ┌─<Widget>──────┐
... <row0> │0123456789ABCD>│
... <row1> │01█3456789ABCD>│   # Cursor (x = 2, y = 1)
... <row2> │0123456789ABCD>│
... <row3> │0123456789ABCD>│
...        └───────────────┘

If a visual coordinate cannot be reached due to the data in the buffer, the closest possible point in the data is selected by default. If the parameter as_far is set to False, an error is raised instead.

display_coord_target_border(quarter) -> DisplayCoordTarget

Create a DisplayCoordTarget that points to the edge of a display.

display_coord_target_by_vrt(vrt, quarter_focus=False, quarter_border_focus=False, column_rel_to_="display", as_far=True) -> DisplayCoordTarget

Shortcut method to method display_coord_target for processing VisualRealTarget.

get_next_y_by_hint(hint) -> None

Determine the next rows to be displayed with a hint. Move the range of displayed rows until the current cursor position is located "central" in the display or is at the nearest "border" of the display. Remove the hint when None is passed.

get_y_rows() -> list[_Row]

Determine the _Row's to be displayed.

make_display() -> DisplayItem

Summarize the display rows and set the cursor x/y-position relative to the displayed area.

make_display_by_cursors(inrow_cursor, other_cursors) -> DisplayItem

Summarize, using the cursor position in the current row and an executable object that returns the cursor position for the remaining rows, the display rows and set the x/y position of the cursor relative to the displayed area.
@abstractmethod
make_row_frame(__row, vis_cursor) -> RowFrameItem
The characteristic framing for the display type.

make_visual_row_frame(row, inrow_cursor, other_cursors, default_item, markings, anchors, new_markings=True, new_anchors=True, new_tabs=True) -> VisRowItem

Calibrate the coordinates of tabs, markers and cursor anchors for a row. The method can be used to overwrite an existing VisRowItem, this is passed as default_item; the arguments new_markings, new_anchors and new_tabs specify which attributes are to be overwritten.

scroll(*, z_y=None, z_x=None, mark=False) -> ChunkLoad | bool

Scroll the displayed rows along the y-axis or x-axis and move the cursor in the TextBuffer when it is at the border of the automatic scroll area.
@abstractmethod
scroll_x(z, mark) -> bool

scroll_y(z, mark) -> ChunkLoad | bool

Scroll the displayed rows along the y-axis and move the cursor in the TextBuffer when it is at the border of the automatic scroll area.

overload settings(*, height=..., y_auto_scroll_distance=..., highlighter=..., highlighted_rows_cache_max, highlighted_row_segments_max, vis_tab=..., vis_marked=..., vis_end=..., vis_nb_end=..., visendpos=..., vis_cursor=..., vis_anchor=..., vis_cursor_row=..., stdcurpos=..., i_rowitem_generator=..., i_display_generator=..., i_before_framing=...) -> None

settings(**kwargs) -> None

Change the _DisplayBase settings.
Date: 20 Dec 2022
Version: 0.1
Author: Adrian Hoefflin [srccircumflex]
Doc-Generator: "pyiStructure-RSTGenerator" <prototype>
↑ Up
VT-Python-Logo.png
Clone this wiki locally