hsh :: content :: text_formatter :: TextFormatter :: Class TextFormatter
[hide private]
[frames] | no frames]

Class TextFormatter

object --+
         |
        TextFormatter
Known Subclasses:

Formats a given Text object to make it appropriate for presentation to the user, most importantly supporting line-folding for fixed width displays. Details of formatting are configurable through assigning of format options.

Formatting includes assigning faces, such as colours for curses displays, to regions within the formatted output. In addition to faces used by the formatter itself (eg. wrap markers and search highlighting) input text can be tagged with a source, which is used to determine a face. The formatter uses its association with a specific view to choose specific faces.

Coordinates as defined in Text are heavily utilized, including functions for manipulating them from the perspective of the visible formatting.

Instance Methods [hide private]
 
__init__(self, text)
Create a formatter for the given text with default formatting.
 
get_format(self, key)
Return the format option for the given key.
 
set_format(self, **kwargs)
Set formatting options.
Text
get_text(self)
Returns: Text being formatted.
 
set_text(self, text)
 
_clear_cache(self)
Forget any cached formatting work because something has changed.
 
_get_face(self, formatname=None, facename=None)
Return a face for this specific view, specified either by its format name or face name.
 
_set_face(self, region)
Set a face for a region, either using the region's source (eg.
 
char_at(self, coord)
Return the character at the given raw coordinates, or None.
 
text_width(self)
The actual width for drawing text, accounting for wrap columns at either end and a prefix.
 
coord_line_start(self, coord_src)
Modify the given raw coordinates to the beginning of the line.
Coordinates
coord_diff(self, coord_src, coord_origin)
Given two sets of coordinates in raw text, determine the difference between them in formatted coordinates.
 
coord_visi(self, coord_src, coord_origin)
Given source and origin coordinates in raw text, with origin representing the top left displayed position, return the coordinates of source in the visible area, adjusted for formatting, wrap columns and line prefix.
int
coord_up_fline(self, coord, clamp, count=1, beyond=0)
Given raw coordinates, modify them so that they refer to a cursor position in a formatted line above.
int
coord_down_fline(self, coord, clamp, count=1, beyond=0)
Given raw coordinates, modify them so that they refer to the cursor position in the formatted line directly below.
MutableText
get_lines(self, height, display_pos=[0, 0], search=None, text=None, more=None)
Get formatted lines suitable for drawing to a fix-width UI window.
 
_clean_control_characters(self, line)
Handle ASCII control characters to prevent drawing corruption.
 
_format_line(self, line, trim, prewrap, lnum)
 
_format_line_wrap(self, line_fmt, wrapface, lc)
Internal function for _format_line()
 
_format_line_clip(self, line_fmt, wrapface)
Internal function for _format_line()
 
_format_line_start(self, line_fmt, wrapface, lc, trim, prewrap)
Internal function for _format_line()
 
_format_line_end(self, line_fmt)
Internal function for _format_line()
(coordinates,coordinates) or None
search(self, pattern, from_pos=[0, 0], forward=True)
Search for a pattern within the raw text.

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, text)
(Constructor)

 

Create a formatter for the given text with default formatting.

Parameters:
  • text (Text) - The text to be formatted.
Overrides: object.__init__

set_format(self, **kwargs)

 

Set formatting options. All parameters are optional, and only specified parameters are modified.

Parameters:
  • face_default (string) - Name of the default face.
  • face_prefix (string) - Name of the face to use on the line prefix.
  • face_search (string) - Name of the face to show search matches.
  • face_view_name (string) - Name of the view showing this text, to assist with locating the named faces.
  • face_wrap (string) - Name of the face to use on wrap markers
  • prefix (string) - Text to be prepended to each line before formatting.
  • reverse (Boolean) - If True, formatting goes backwards from display_pos.
  • trim (integer >= 0) - Number of characters to trim from the beginning of each line before formatting.
  • truncate (integer or None) - Return at most this number of lines, and include a truncation marker if some lines were skipped.
  • width (integer > 0) - The number of columns available for formatting text.
  • wrap (Boolean) - True to wrap text onto subsequent lines if it exceeds width, False to clip it at width.

get_text(self)

 
Returns: Text
Text being formatted.

set_text(self, text)

 
Parameters:
  • text (Text) - New text to be formatted.

_get_face(self, formatname=None, facename=None)

 

Return a face for this specific view, specified either by its format name or face name.

Parameters:
  • formatname - key into format options which identifies a facename
  • facename - a face name as specified in display configuration

_set_face(self, region)

 

Set a face for a region, either using the region's source (eg. stderr) if specified, any face already assigned, or a default.

coord_diff(self, coord_src, coord_origin)

 

Given two sets of coordinates in raw text, determine the difference between them in formatted coordinates.

Typically this is used to find the location of the cursor relative to the top left corner of the display, in which case the cursor coordinates would be passed as the first parameter, and the display position as the second.

Parameters:
  • coord_src (Coordinates) - The raw coordinates to locate
  • coord_origin (Coordinates) - The position relative to which the result is given
Returns: Coordinates
difference between positions in formatted coordinates

coord_up_fline(self, coord, clamp, count=1, beyond=0)

 

Given raw coordinates, modify them so that they refer to a cursor position in a formatted line above.

Parameters:
  • coord - Raw coordinates
  • clamp - If True, adjust coord[1] so that the coords refer to a place that exists, possibly outside the visible area.
  • count - how many lines up to go
  • beyond - If 1, allow coord to go one line beyond the top
Returns: int
The number of rows moved up

coord_down_fline(self, coord, clamp, count=1, beyond=0)

 

Given raw coordinates, modify them so that they refer to the cursor position in the formatted line directly below.

Parameters:
  • coord - Coordinates
  • clamp - If True, adjust coord[1] so that the coords refer to a place that exists, possibly outside the visible area.
  • count - how many lines down to go
  • beyond - If 1, allow coord to go one line beyond the bottom
Returns: int
The number of rows moved down

get_lines(self, height, display_pos=[0, 0], search=None, text=None, more=None)

 

Get formatted lines suitable for drawing to a fix-width UI window.

Return the requested number of lines, or fewer if that's not possible.

Parameters:
  • height (positive integer) - The number of lines to return
  • display_pos (Coordinates) - Where to start drawing from. If reverse formatting is set, drawing goes upwards.
  • search (regular expression or None) - Optional regexp to be highlighted in results.
  • text (Text) - Optional text to be formatted, replacing current text.
  • more (list or None) - Optional list which will have a boolean placed in it indicating if formatting stopped before the end.
Returns: MutableText
Appropriately formatted text, preserving any formatting regions of the original source. Columns containing line continuation and clipping markers are added to either side of the output. Each contained TextLine its line_number variable set to the number of the line from which it originated, and regions are updated to include face information based on input channel.

_clean_control_characters(self, line)

 

Handle ASCII control characters to prevent drawing corruption.

This support is still very limited: tabs are replaced with spaces, and carriage returns are removed.

Parameters:
  • line (TextLine) - the input to clean - will be modified

search(self, pattern, from_pos=[0, 0], forward=True)

 

Search for a pattern within the raw text.

Searching stops at the beginning or end of the text. As a special case if forward is False and search is from the beginning, it will start searching at the end.

Parameters:
  • pattern (compiled regexp) - Pattern to search for
  • from_pos (coordinates) - Position to start search from
  • forward - True to search forward, False for backwards
Returns: (coordinates,coordinates) or None
Pair of raw coordinates, the beginning and end of the match. None if there was no match.