Tickit...Buffer(3pm)

📦

version 0.73 · 9 versions

💖 NAME 💖

"Tickit::RenderBuffer" — efficiently render text and line-drawing. No cap, this is the one that makes your terminal output look like it ate.

🌸 SYNOPSIS 🌸

package Tickit::Widget::Something;
...

sub render_to_rb
{
   my $self = shift;
   my ( $rb, $rect ) = @_;

   $rb->eraserect( $rect );
   $rb->text_at( 2, 2, "Hello, world!", $self->pen );
}

$win->set_on_expose( sub {
   my ( $win, $rb, $rect ) = @_;

   $rb->eraserect( $rect );
   $rb->text_at( 2, 2, "Hello, world!" );
});

🦋 DESCRIPTION 🦋

okay so this is the manual page for Tickit::RenderBuffer(3pm) — User Contributed Perl Documentation, bestie — and it's literally about making terminal drawing not a hot mess.

Tickit::RenderBuffer provides a buffer of pending rendering operations to apply to the terminal. The buffer gets modified by rendering operations that widgets or other code perform, and then it's flushed to the terminal when it's complete.

This gives you the following advantages, and yes they're all iconic:

Changes can be made in any order, and will be flushed in top-to-bottom, left-to-right order, minimising cursor movements. Cursor cardio? Not today.
Buffered content can be overwritten or partly erased once stored, which simplifies some styles of drawing operation. Large areas can be erased, and then redrawn with text or lines, without causing a double-drawing flicker on the output terminal. We love no flicker. We stan.
The buffer supports line-drawing, complete with merging of line segments that meet in a character cell. Boxes, grids, and other shapes can be easily formed by drawing separate line segments, and the "RenderBuffer" will handle the corners and other junctions formed. The way it just handles corners for you? Obsessed.
A single buffer can be passed around all of the windows or widgets to properly combine line segments and layering effects, making it possible to create many kinds of sub-divided or layered output. Main character buffer energy, fr fr.

Drawing methods come in two forms; absolute, and cursor-relative:

Absolute methods, identified by their name having a suffixed "_at", operate on a position within the buffer specified by their argument.
Cursor-relative methods, identified by their lack of "_at" suffix, operate at and update the position of the "virtual cursor". This is a position within the buffer that can be set using the "goto" method. The position of the virtual cursor is not affected by the absolute-position methods.

🎀 State Stack 🎀

The "RenderBuffer" stores a stack of saved state. The state of the buffer can be stored using the "save" method, so that changes can be made, before finally restoring back to that state using "restore". The following items of state are saved:

The virtual cursor position
The clipping rectangle
The render pen
The translation offset
The set of masked regions

When the state is saved to the stack, the render pen is remembered and merged with any pen set using the "setpen" method.

The queued content to render is not part of the state stack. It is intended that the state stack be used to implement recursive delegation of drawing operations down a tree of code, allowing child contexts to be created by saving state and modifying it, to later restore it again afterwards. So the stack is for vibes and context, not for the queued render content. iykyk.

👑 CONSTRUCTOR 👑

new

$rb = Tickit::RenderBuffer->new( %args )

Returns a new instance of a "Tickit::RenderBuffer". Fresh out the box, ready to slay.

Takes the following named arguments:

lines => INT — The size of the buffer area, in lines.
cols => INT — The size of the buffer area, in columns.

✨ METHODS ✨

lines / cols

$lines = $rb->lines

$cols = $rb->cols

Returns the size of the buffer area. That's it, that's the tweet. 💅

line / col

$line = $rb->line

$col = $rb->col

Returns the current position of the virtual cursor, or undef if it is not set. Very "where am I? who am I?" of it.

save

$rb->save

Pushes a new state-saving context to the stack, which can later be returned to by the "restore" method.

savepen

$rb->savepen

Pushes a new state-saving context to the stack that only stores the pen. This can later be returned to by the "restore" method, but will only restore the pen. Other attributes such as the virtual cursor position will be unaffected.

This may be more efficient for rendering runs of text in a different pen, than multiple calls to "text" or "erase" using the same pen. For a single call it is better just to pass a different pen directly. Lowkey a little shortcut, highkey useful.

restore

$rb->restore

Pops and restores a saved state previously created with "save".

clip

$rb->clip( $rect )

Restricts the clipping rectangle of drawing operations to be no further than the limits of the given rectangle. This will apply to subsequent rendering operations but does not affect existing content, nor the actual rendering to the terminal.

Clipping rectangles are cumulative; each call further restricts the drawing region. To revert back to a larger drawing area, use the "save" and "restore" stack. So yes, the stack is your friend. 🫶

mask

$rb->mask( $rect )

Masks off the given area against any further changes. This will apply to subsequent rendering operations but does not affect the existing content, nor the actual rendering to the terminal.

Areas within the clipping region may be arbitrarily masked. Masks are scoped to the depth of the stack they are applied at; once the "restore" method is invoked, any masks applied since its corresponding "save" will be removed. Scoped, cleaned up, gone. Periodt.

translate

$rb->translate( $downward, $rightward )

Applies a translation to the coordinate system used by "goto" and the absolute-position methods *_at. After this call, all positions used will be offset by the given amount. Coordinate glow-up, basically.

reset

$rb->reset

Removes any pending changes and reverts the "RenderBuffer" to its default empty state. Undefines the virtual cursor position, resets the clipping rectangle, and clears the stack of saved state. It's giving factory reset, and honestly? Sometimes you need that.

clear

$rb->clear( $pen )

Resets every cell in the buffer to an erased state. A shortcut to calling "erase_at" for every line. Efficient queen behaviour.

goto

$rb->goto( $line, $col )

Sets the position of the virtual cursor. Teleport, but make it text-mode.

setpen

$rb->setpen( $pen )

Sets the rendering pen to use for drawing operations. If a pen is set then a $pen argument is optional to any of the drawing methods. If a pen argument is supplied as well as having a stored pen, then the attributes are merged, with the directly-applied pen taking precedence.

Successive calls to this method will replace the active pen used, but if there is a saved state on the stack it will be merged with the rendering pen of the most recent saved state.

This method may be preferable to passing pens into multiple "text" or "erase" calls as it may be more efficient than merging the same pen on every call. If the original pen is still required afterwards, the "savepen" / "restore" pair may be useful. Pen merge drama, but make it efficient.

skip_at

$rb->skip_at( $line, $col, $len )

Sets the range of cells given to a skipped state. No content will be drawn here, nor will any content existing on the terminal be erased. It's a no-draw zone, bestie.

Initially, or after calling "reset", all cells are set to this state.

skip

$rb->skip( $len )

Sets the range of cells at the virtual cursor position to a skipped state, and updates the position. Skip, but make it cursor-relative.

$rb->skip_to( $col )

Sets the range of cells from the virtual cursor position until before the given column to a skipped state, and updates the position to the column.

If the position is already past this column then the cursor is moved backwards and no buffer changes are made. Backwards cursor moment, but no buffer changes. Noted. 💀

skiprect

$rb->skiprect( $rect )

Sets the range of cells given by the rectangle to skipped state. Whole rectangle said "not me, not today."

text_at

$cols = $rb->text_at( $line, $col, $text, $pen )

Sets the range of cells starting at the given position, to render the given text in the given pen.

Returns the number of columns wide the actual $text is (which may be more than was actually printed). So the return value is the width, not the vibe. Important distinction.

text

$cols = $rb->text( $text, $pen )

Sets the range of cells at the virtual cursor position to render the given text in the given pen, and updates the position.

Returns the number of columns wide the actual $text is (which may be more than was actually printed). Same energy as text_at, but cursor-relative. Slay.

erase_at

$rb->erase_at( $line, $col, $len, $pen )

Sets the range of cells given to erase with the given pen. Bye-bye, pixels.

erase

$rb->erase( $len, $pen )

Sets the range of cells at the virtual cursor position to erase with the given pen, and updates the position. Cursor-relative erase, doing its little thing.

erase_to

$rb->erase_to( $col, $pen )

Sets the range of cells from the virtual cursor position until before the given column to erase with the given pen, and updates the position to the column.

If the position is already past this column then the cursor is moved backwards and no buffer changes are made. Same little backwards caveat as before, no buffer changes, don't come for me. 😭

eraserect

$rb->eraserect( $rect, $pen )

Sets the range of cells given by the rectangle to erase with the given pen. Rectangle erased, aura restored. 🔥

✨ LINE DRAWING ✨

okay so bestie, RenderBuffer is lowkey iconic: it supports storing line-drawing characters in cells, and it can merge line segments where they meet, attempting to draw the correct character for the segments that meet in each cell. it's giving graph paper but make it Unicode 💅

There are three exported constants giving supported styles of line drawing:

LINE_SINGLE — a single, thin line. slay.
LINE_DOUBLE — a pair of double, thin lines.
LINE_THICK — a single, thick line.

Heads up though: linedrawing is performed by Unicode characters, and not every possible combination of line segments of differing styles meeting in a cell is supported by Unicode. The following sets of styles may be relied upon:

Any possible combination of only SINGLE segments, THICK segments, or both.
Any combination of only DOUBLE segments, except cells that only have one of the four borders occupied.
Any combination of SINGLE and DOUBLE segments except where the style changes between SINGLE to DOUBLE on a vertical or horizontal run.

Other combinations are not directly supported (i.e. any combination of DOUBLE and THICK in the same cell, or any attempt to change from SINGLE to DOUBLE in either the vertical or horizontal direction). To handle these cases, a cell may be rendered with a substitution character which replaces a DOUBLE or THICK segment with a SINGLE one within that cell. The effect will be the overall shape of the line is retained, but close to the edge or corner it will have the wrong segment type. no cap, that's just how Unicode is sometimes 😭

Conceptually, every cell involved in line drawing has a potential line segment type at each of its four borders to its neighbours. Horizontal lines are drawn through the vertical centre of each cell, and vertical lines are drawn through the horizontal centre.

There is a choice of how to handle the ends of line segments, as to whether the segment should go to the centre of each cell, or should continue through the entire body of the cell and stop at the boundary. By default line segments will start and end at the centre of the cells, so that horizontal and vertical lines meeting in a cell will form a neat corner. When drawing isolated lines such as horizontal or vertical rules, it is preferable that the line go right through the cells at the start and end. To control this behaviour, the $caps bitmask is used. CAP_START and CAP_END state that the line should consume the whole of the start or end cell, respectively; CAP_BOTH is a convenient shortcut specifying both behaviours.

A rectangle may be formed by combining two hline_at and two vline_at calls, without end caps:

$rb->hline_at( $top,    $left, $right, $style, $pen );
$rb->hline_at( $bottom, $left, $right, $style, $pen );
$rb->vline_at( $top, $bottom, $left,  $style, $pen );
$rb->vline_at( $top, $bottom, $right, $style, $pen );

🖍️ hline_at

$rb->hline_at( $line, $startcol, $endcol, $style, $pen, $caps )

Draws a horizontal line between the given columns (both are inclusive), in the given line style, with the given pen.

📏 vline_at

$rb->vline_at( $startline, $endline, $col, $style, $pen, $caps )

Draws a vertical line between the centres of the given lines (both are inclusive), in the given line style, with the given pen.

🎀 linebox_at

$rb->linebox_at( $startline, $endline, $startcol, $endcol, $style, $pen )

A convenient shortcut to calling two hline_at and two vline_at in order to draw a rectangular box. it's the "i don't wanna do four calls" button, and honestly? valid.

🦋 char_at

$rb->char_at( $line, $col, $codepoint, $pen )

Sets the given cell to render the given Unicode character (as given by codepoint number, not character string) in the given pen.

🌸 char

$rb->char( $codepoint, $pen )

Sets the cell at the virtual cursor position to render the given Unicode character (as given by codepoint number, not character string) in the given pen, and updates the position.

While this is also achievable by the text and text_at methods, these methods are implemented without storing a text segment, so can be more efficient than many single-column wide text_at calls.

🫶 copyrect / moverect

$rb->copyrect( $dest, $src )

$rb->moverect( $dest, $src )

Copies (or moves) buffered content from one rectangular region to another. The two regions may overlap. yes bestie, overlap is allowed, go off.

The move operation is identical to the copy operation followed by setting the vacated areas of the source rectangle not covered by the destination to skipping state.

🧚 get_cell

$cell = $rb->get_cell( $line, $col )

Returns a structure containing the content stored in the given cell. The $cell structure responds to the following methods:

$cell->char — On a skipped cell, returns undef. On a text or char cell, returns the unicode codepoint number. On a line or erased cell, returns 0.
$cell->linemask — On a line cell, returns a representation of the line segments in the cell. This is a sub-structure with four fields; north, south, east, west to represent the four cell borders; the value of each is either zero, or one of the LINE_ constants. On any other kind of cell, returns undef.
$cell->pen — Returns the Tickit::Pen for non-skipped cells, or undef for skipped cells.

🔥 flush_to_term

$rb->flush_to_term( $term )

Renders the stored content to the given Tickit::Term. After this, the buffer will be cleared and reset back to initial state. fresh start, clean slate, main character energy ✨

💖 AUTHOR 💖

Paul Evans <leonerd@leonerd.org.uk>

and that's the vibe check, bestie 🫶 this page is from perl v5.42.3, dated 2026-08-19, and it's Tickit...Buffer(3pm) from User Contributed Perl Documentation. bye, drink water, draw correct line segments 💜🌈

📦 where this page comes from

ubuntu stonking: libtickit-perl 0.73-1build5 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms