package matrix
Build not yet checkedInstall
dune-project
Dependency
Authors
Maintainers
Sources
sha256=a92cbbcbe016fb19fb0a749222da0e459a9567aef3f4c7340d9bd6b71c53ed6f
sha512=6a7ab054605538bb31a2b73a1a6d093981a2704c9f0af5852221c05735290d74aca7c7282298c4d0f91e86a800e2ccd94b4918af883cd963449c758eb6b272b3
doc/matrix.text/Matrix_text/Layout/index.html
Module Matrix_text.LayoutSource
Texts cut into rows of a given width, as a text view or an editor shows them.
A source (Source) is a text indexed by grapheme cluster. Its clusters are numbered from 0, and boundary g is the boundary before cluster g, from 0 to the number of clusters. Every position in a layout is a boundary. A logical line is a run of clusters ended by a line terminator (LF, CR or CR LF) or by the end of the text.
A layout cuts each logical line of a source into rows of a given width, by one of the wrap modes. A row after the first of its line is a continuation. A cluster wider than the width has a row of its own. The blanks (spaces and TABs) at the end of a row that wraps hang there. They belong to the row and are shown in no cell, and they take none of its width when the row is filled, so a blank never starts a continuation and never makes a row wrap early. At the end of a line the blanks hang only where they do not fit. CSS Text 3 hangs the white space at the end of a pre-wrap line in the same way, "unless the sequence is followed by a forced line break, in which case it must conditionally hang the sequence instead" (§4.1.2). Without wrapping, a layout may truncate a line wider than the width, which then shows the prefix that fits in one cell less, and an ellipsis, a cell that stands for the clusters left out, its omitted suffix. The program draws the ellipsis. At a width of 0 or less the ellipsis does not fit either, and a truncated line shows only the clusters of width 0 that begin it.
A caret is a boundary with an affinity. A boundary where a line wraps is both the end of a row and the start of the next, and one inside an omitted suffix is on both sides of its ellipsis. Upstream places the caret on the earlier side and Downstream on the later.
Unless a function's doc says otherwise, a row, line or boundary out of range is clamped to the nearest one, the width method defaults to `Unicode, and the tab width to 2. The functions that map a cell to boundaries (hit and coverage) take a row before the first as the start of the source and a row after the last as its end, so that a pointer dragged above or below the text reaches its first or last boundary. A TAB is as wide as the tab width wherever it is. Each cluster is as wide as measure makes it, whatever the width method, so a layout follows grapheme clusters even under `Wcwidth.
The life cycle of a layout:
Source.of_stringindexes a text once, andSource.editindexes again only the lines an edit touches.createlays it out at a width, and again when the width changes.iter_rowsanditer_cellsdraw the rows that show, andlocate,hitandcoveragemap carets and cells to each other.
The type for affinities.
The type for carets. grapheme is a boundary.
The type for wrap modes. `None keeps one row per logical line. `Char wraps between clusters. `Word wraps at the last break opportunity (iter_wrap_breaks) that fits, and between clusters in a row that has none.
The type for layouts. A layout is immutable and holds its source. Its rows count from 0, and a row's columns from 0, before any scrolling or clipping.
val create :
?width_method:width_method ->
?tab_width:int ->
?truncate:bool ->
Source.t ->
width:int ->
wrap:wrap ->
tcreate source ~width ~wrap is the layout of source in rows of width cells, wrapped by wrap. A width of 0 or less keeps one row per logical line. With ~truncate:true and `None a line wider than width is truncated. truncate defaults to false.
source keeps the layouts of its last four calls that lay it out differently, and create returns the one it keeps when its arguments lay it out the same way. A layout makes the rows of a line when they are first asked, and the layouts a source keeps share 32 MiB of rows: the one create returns is kept whatever its rows, and the others while their rows fit what it leaves. When source was made by Source.edit from a source that keeps a layout for the same arguments, create lays out only the lines the edit touched.
val measure :
?width_method:width_method ->
?tab_width:int ->
?truncate:bool ->
Source.t ->
width:int ->
wrap:wrap ->
int * intmeasure source ~width ~wrap is (row_count l, max_width l) for the layout l that create returns, which makes no rows.
row_end t row is the boundary that ends row, before its line terminator and after its omitted suffix or the blanks it hangs.
continuation t row is 0 for the first row of a logical line and n for its nth continuation.
val iter_rows :
t ->
first:int ->
count:int ->
(row:int -> logical_line:int -> continuation:int -> unit) ->
unititer_rows t ~first ~count f calls f ~row ~logical_line ~continuation on the rows from first to first + count - 1 that t has, in order, and on none if count is negative.
locate t c is the row and column of the caret c. At a wrap, Upstream is the end of the earlier row and Downstream the start of the later. A boundary inside an omitted suffix is before the ellipsis if Upstream and after it if Downstream, and the end of the suffix is after it.
hit t ~row ~column is the caret nearest to column in row, the later of two equally near. Where boundaries share a column, as around a cluster of width 0, it is the first if affinity is Upstream and the last if Downstream, which is the default. A caret at the end of a row that wraps is Upstream and one at the start of a row Downstream, so that it locates on row. In a truncated row, the ellipsis gives the boundary before it, and a column after the row its end. A row out of range gives the start or the end of the source (Layout). Several cells hit one caret, so locate of a hit may be another cell.
coverage t ~row ~column is (first, last), the boundaries around the clusters the cell at row and column shows. These are the cluster for each cell of a wide cluster, and the omitted suffix for the ellipsis. The range is empty for a cell that shows nothing, and for a row out of range, at the start or the end of the source (Layout). The program decides whether a gesture on the cell selects it.
val iter_cells :
t ->
row:int ->
first_column:int ->
last_column:int ->
(first:int -> last:int -> column:int -> width:int -> ellipsis:bool -> unit) ->
unititer_cells t ~row ~first_column ~last_column f calls f ~first ~last ~column ~width ~ellipsis on each cluster of positive width of row with a cell in columns first_column to last_column - 1, in order. first and last are the boundaries around the cluster, and column and width its first column and width. The ellipsis comes last, as its omitted suffix with ~width:1 and ~ellipsis:true. A row out of range visits nothing.