n_wrap.h File Reference

Greedy word-wrap over pre-measured, styled items. More...

#include <stddef.h>

Include dependency graph for n_wrap.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	n_wrap_item
	One pre-measured layout item: a glyph, an emoji cell, an inline image, or a whole word, the wrap only ever looks at width and flags. More...

Macros
#define	N_WRAP_NEWLINE   (1u << 1)
	the item is a hard line break; it ends the line and occupies no cell
#define	N_WRAP_SPACE   (1u << 0)
	the item is a legal break point (typically a space); it is DROPPED when a line breaks there, appearing on neither line

Typedefs
typedef void(*	n_wrap_emit) (size_t first, size_t last, size_t line, double width, void *user)
	Called once per laid-out line, in order.
typedef void(*	n_wrap_rect_emit) (size_t line, double x0, double x1, void *user)
	Called once per line that a span covers, by n_wrap_span_rects().

Functions
size_t	n_wrap_index_at (const n_wrap_item *items, size_t count, double max_width, double line_height, double x, double y)
	The item boundary nearest a point: the inverse of n_wrap_layout(), for turning a click or a drag into a caret or a selection end.
size_t	n_wrap_layout (const n_wrap_item *items, size_t count, double max_width, n_wrap_emit emit, void *user)
	Break items into lines no wider than max_width.
size_t	n_wrap_span_rects (const n_wrap_item *items, size_t count, double max_width, size_t lo, size_t hi, n_wrap_rect_emit emit, void *user)
	The rectangles that cover the items [lo, hi): one per line the range touches, in order, for painting a selection highlight.

Detailed Description

Greedy word-wrap over pre-measured, styled items.

The line-breaking half of laying out styled text, with the measuring half left to the caller. A caller turns its text into an array of items that each carry only a width and two flags, and this decides where the lines break. Because an item is just a width, the same wrap serves a glyph, an inline image, an emoji cell or a whole word, in any mix of fonts and styles, the module never sees a font, a glyph or a renderer.

Why it is one function rather than two. A measure pass and a draw pass that walk separately drift, and a height cache built on the measure pass then disagrees with what is drawn. Here the measure pass IS the draw pass with emit set to NULL: the same code decides the breaks either way, so the height a caller caches and the lines it later paints cannot diverge.

Algorithm: greedy, breaking at the last legal break point (an N_WRAP_SPACE item) that fits, or mid-run when there is none. Rules worth knowing before you rely on them:

• The space a line breaks at is dropped: it ends neither line, so a wrapped paragraph never starts a line with a space.
• When the item that overflows is ITSELF a break point, the line breaks there rather than backtracking to the previous one, a trailing space never pushes a word that already fitted onto the next line.
• An item **wider than max_width** is placed alone on its own line rather than looping forever. Nothing is ever discarded to make text fit.
• An N_WRAP_NEWLINE item is a hard break that occupies no cell.
• The line count is always at least 1, so empty text still occupies one line's height.
• A trailing hard break counts a final empty line but does not emit it, count and emission agree with each other, which is what matters, but a caller drawing a caret on that last empty line must place it itself.

Author

Castagnier Mickael

Version

1.0

Definition in file n_wrap.h.

---

Data Structure Documentation

n_wrap_item

struct n_wrap_item

One pre-measured layout item: a glyph, an emoji cell, an inline image, or a whole word, the wrap only ever looks at width and flags.

Examples

ex_wrap.c.

Definition at line 76 of file n_wrap.h.

Collaboration diagram for n_wrap_item:

Data Fields
unsigned int	flags	N_WRAP_SPACE / N_WRAP_NEWLINE, or 0
double	width	advance width in the caller's units (pixels, columns, ...)

Macro Definition Documentation

N_WRAP_NEWLINE

#define N_WRAP_NEWLINE   (1u << 1)

the item is a hard line break; it ends the line and occupies no cell

Examples

ex_wrap.c.

Definition at line 72 of file n_wrap.h.

Referenced by _wrap_words(), _wrap_words_emit(), main(), md_wrap_of(), and n_wrap_layout().

N_WRAP_SPACE

#define N_WRAP_SPACE   (1u << 0)

the item is a legal break point (typically a space); it is DROPPED when a line breaks there, appearing on neither line

Examples

ex_wrap.c.

Definition at line 70 of file n_wrap.h.

Referenced by _wrap_words(), main(), md_wrap_of(), and n_wrap_layout().

Typedef Documentation

n_wrap_emit

typedef void(* n_wrap_emit) (size_t first, size_t last, size_t line, double width, void *user)

Called once per laid-out line, in order.

Parameters

first	index of the line's first item
last	index ONE PAST its last item (so the range is [first, last) and an empty line has first == last)
line	zero-based line number
width	summed width of the items in the range, for centring / right alignment / a selection rectangle
user	the caller's cookie, passed through untouched

Definition at line 92 of file n_wrap.h.

n_wrap_rect_emit

typedef void(* n_wrap_rect_emit) (size_t line, double x0, double x1, void *user)

Called once per line that a span covers, by n_wrap_span_rects().

Parameters

line	zero-based line number (its top is line * line_height)
x0	left edge of the covered part, from the line's start
x1	right edge (x1 > x0)
user	the caller's cookie

Definition at line 102 of file n_wrap.h.

Function Documentation

n_wrap_index_at()

size_t n_wrap_index_at	(	const n_wrap_item *	items,
		size_t	count,
		double	max_width,
		double	line_height,
		double	x,
		double	y )

The item boundary nearest a point: the inverse of n_wrap_layout(), for turning a click or a drag into a caret or a selection end.

The point is in the laid-out text's own coordinates (0,0 = the first line's top-left), with every line line_height tall. The layout is the one n_wrap_layout() produces for the same items and max_width, so a hit can never disagree with what was drawn.

Within a line, a point on the left half of an item resolves to the boundary before it and on the right half to the boundary after it, so an atomic item (an emoji cell, an inline image) is selected whole or not at all. A point past a line's end resolves to that line's end; above the first line to 0; below the last line to count.

Parameters

items	the items given to n_wrap_layout(); may be NULL if count is 0
count	number of items
max_width	the width they were wrapped to
line_height	height of one line; a value <= 0 resolves every point to the first line
x	point, from the left edge
y	point, from the top edge

Returns

a boundary index in [0, count]: "before item i", count = after the last

Definition at line 176 of file n_wrap.c.

References wrap_hit::found, wrap_hit::items, n_wrap_layout(), wrap_hit::result, wrap_hit::want, wrap_hit_line(), and wrap_hit::x.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

n_wrap_layout()

size_t n_wrap_layout	(	const n_wrap_item *	items,
		size_t	count,
		double	max_width,
		n_wrap_emit	emit,
		void *	user )

Break items into lines no wider than max_width.

Greedy: each line takes as much as fits, breaking at the last N_WRAP_SPACE that fits or, when the line holds no space, immediately before the item that overflows. An item that cannot fit even alone is placed alone rather than looping.

Parameters

items	pre-measured items; may be NULL when count is 0
count	number of items
max_width	the width to wrap to; a value <= 0 puts every non-empty line on its own item, since nothing but the first item of a line can ever fit
emit	called once per line, or NULL to only count lines (the measure pass, same breaks, no output)
user	cookie handed back to emit

Returns

the number of lines, always >= 1

Definition at line 50 of file n_wrap.c.

References n_wrap_item::flags, N_WRAP_NEWLINE, N_WRAP_SPACE, n_wrap_item::width, and WRAP_NO_SPACE.

Referenced by _wrap_words(), main(), md_flow(), n_wrap_index_at(), n_wrap_span_rects(), and run().

Here is the caller graph for this function:

n_wrap_span_rects()

size_t n_wrap_span_rects	(	const n_wrap_item *	items,
		size_t	count,
		double	max_width,
		size_t	lo,
		size_t	hi,
		n_wrap_rect_emit	emit,
		void *	user )

The rectangles that cover the items [lo, hi): one per line the range touches, in order, for painting a selection highlight.

Uses the same layout as n_wrap_layout(), so the rectangles sit exactly under the drawn items. A space dropped at a line break belongs to no line and so lies under no rectangle; a line whose covered part has zero width (only a hard break) emits nothing. lo and hi may come in either order.

Parameters

items	the items given to n_wrap_layout()
count	number of items
max_width	the width they were wrapped to
lo	first boundary of the span
hi	other boundary (clamped to count)
emit	called once per covered line; may be NULL to only count
user	cookie handed back to emit

Returns

the number of rectangles

Definition at line 249 of file n_wrap.c.

References wrap_span::emit, wrap_span::hi, wrap_span::items, wrap_span::lo, wrap_span::n, n_wrap_layout(), wrap_span::user, and wrap_span_line().

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function: