caret.hpp File Reference

Text-caret appearance and blink policy, shared by every editable widget. More...

#include <pulp/canvas/canvas.hpp>
#include <pulp/view/geometry.hpp>
#include <string>
#include <string_view>

Go to the source code of this file.

Classes
struct	pulp::view::CaretBlinkConfig
	Blink timing. The defaults are the values Pulp has always used. More...
class	pulp::view::CaretBlink
	The "solid while moving, blinking while still" state machine. More...
struct	pulp::view::CaretMetrics
	Where a caret goes, in the coordinate space the widget paints text in. More...

Namespaces
namespace	pulp
namespace	pulp::view
	Hover-cursor tracking for platform window hosts.

Enumerations
enum class	pulp::view::CaretStyle { pulp::view::ibeam , pulp::view::underline , pulp::view::block }
	Caret shape. All three anchor at the same caret x. More...

Functions
const char *	pulp::view::caret_style_to_string (CaretStyle style) noexcept
	Stable lowercase names, for serialization and the JS bridge.
CaretStyle	pulp::view::caret_style_from_string (std::string_view name) noexcept
	Parse a name produced by caret_style_to_string.
CaretStyle	pulp::view::default_caret_style () noexcept
	Process-wide caret defaults.
void	pulp::view::set_default_caret_style (CaretStyle style) noexcept
const CaretBlinkConfig &	pulp::view::default_caret_blink () noexcept
void	pulp::view::set_default_caret_blink (const CaretBlinkConfig &config) noexcept
float	pulp::view::caret_advance (const CaretMetrics &metrics) noexcept
	The width the underline and block shapes cover: advance when there is a glyph at the caret, else nominal_advance.
Rect	pulp::view::caret_rect_for_style (CaretStyle style, const CaretMetrics &metrics) noexcept
	The rect a caret of style occupies.
void	pulp::view::paint_caret (canvas::Canvas &canvas, CaretStyle style, const CaretMetrics &metrics, canvas::Color color)
	Fill the caret rect.
void	pulp::view::paint_caret_over_text (canvas::Canvas &canvas, CaretStyle style, const CaretMetrics &metrics, canvas::Color color, canvas::Color text_bg, const std::string &text, float text_x)
	Paint the caret, and for block redraw the covered glyph in text_bg so it stays legible against the fill.

Detailed Description

Text-caret appearance and blink policy, shared by every editable widget.

A caret has two independent concerns, and this header owns both:

1. Shape — CaretStyle. Three shapes, all anchored at the same x (the boundary between the glyph before the caret and the glyph after it). They differ only in what they cover:

   ibeam be│ a thin vertical rule spanning the glyph cell underline be_ a rule at the underline position, on the baseline block be█ the filled glyph cell, glyph drawn in the bg color

   ibeam is the default. underline is the terminal convention's name for this shape and is unrelated to text-decoration underline; it occupies the cell of the glyph at the caret rather than the text behind it, so it never displaces the text. block is the terminal block cursor.

2. Blink — CaretBlinkConfig + CaretBlink. The caret holds solid for solid_hold_seconds after any caret movement or edit, then resumes blinking with period_seconds at duty on-fraction. That hold is what makes an arrow-key sweep read as a continuous caret instead of a strobe: every arrow, word jump, home/end, keystroke, delete, and mouse drag calls keep_solid(), and blinking only restarts once the caret has been still for the hold duration.

A blinking caret is animated content, so CaretBlink honors MotionPreferences: under MotionPolicy::Off the caret is always visible and never blinks. Setting CaretBlinkConfig::enabled = false does the same thing unconditionally.

Widgets drive the blink from a FrameClock subscription taken while focused, so the phase advances in real time and not once per painted frame — a caret must blink at the same rate on a 60 Hz and a 120 Hz display.

Defaults are process-wide and overridable per widget:

// Everything in this app gets an underline caret that blinks slowly.
pulp::view::set_default_caret_style(pulp::view::CaretStyle::underline);
pulp::view::CaretBlinkConfig slow;
slow.period_seconds = 1.6f;
pulp::view::set_default_caret_blink(slow);
 
// ...but this one field keeps the stock I-beam.
field.set_caret_style(pulp::view::CaretStyle::ibeam);
field.set_caret_blink({});