Graphics.Vty.Widgets.TextClip

This module provides "text clipping" routines. These routines are responsible for ensuring that logical characters are clipped properly when being laid out in a given physical region. This is a bit tricky because some Unicode characters use two terminal columns and others (most) use one. We have to take this into account when truncating text to fit into rendering regions, so we concentrate that logic here under the name of a "clipping rectangle" and functions to apply it.

Clipping functionality is provided in two forms: one- and two-dimensional clipping. The former is useful for clipping a single line of text at a given offset and up to a given width. The latter is useful for clipping a list of lines with respect to a 2-D clipping rectangle.

Documentation

data ClipRect

The type of clipping rectangles for 2-D clipping operations. All values are Phys values to indicate that we are dealing explicitly with physical column measurements rather than logical character positions.

Constructors

ClipRect

Fields

clipLeft :: Phys

The left margin of the clipping rectangle.

clipTop :: Phys

The top row of the clipping rectangle.

clipWidth :: Phys

The width, in columns, of the clipping rectangle.

clipHeight :: Phys

The height, in rows, of the clipping rectangle.

Instances

Eq ClipRect

Show ClipRect

clip1d :: Phys -> Phys -> Text -> (Text, Bool, Bool)

One-dimensional text clipping. Takes the left clipping margin, a clipping width, and a text string. For example, clip1d n w s clips the string s so that the result includes characters in s starting at position n and including characters using no more than w columns in width. Returns the clipped text plus Bools indicating whether wide characters were "sliced" on either side (left and right, respectively) of the clipping region. This function guarantees that the text returned will always fit within the specified clipping region. Since wide characters may be sliced during clipping, this may return a text string smaller than the clipping region.

clip2d :: ClipRect -> [Text] -> [(Text, Bool, Bool)]

Two-dimensional text clipping. Returns clipping data for each line as returned by clip1d, with the added behavior that it returns at most clipHeight lines of text and uses clipTop as the offset when clipping rows.

updateRect :: (Phys, Phys) -> ClipRect -> ClipRect

Given a physical point and a clipping rectangle, adjust the clipping rectangle so that the point falls just inside the rectangle. If the point is already within the rectangle, return the rectangle unmodified. NB: this assumes that the physical position given has passed whatever validation checks are relevant for the user of the ClipRect. This function just performs a rectangle transformation.