View

Provides a viewport of a text instance and mangages selections.

Lifecycle

View *view_new(Text*)
void view_free(View*)
void view_ui(View*, UiWin*)
Text *view_text(View*)
void view_reload(View*, Text*)

Viewport

The cursor of the primary selection is always visible.

Filerange view_viewport_get(View*)

Get the currently displayed text range.

bool view_coord_get(View*, size_t pos, Line **line, int *row, int *col)

Get window coordinate of text position.

Parameters

  • pos – The position to query.

  • line – Will be updated with screen line on which pos resides.

  • row – Will be updaded with zero based window row on which pos resides.

  • col – Will be updated with zero based window column on which pos resides.

Returns

Whether pos is visible. If not, the pointer arguments are left unmodified.

size_t view_screenline_goto(View*, int n)

Get position at the start of the n-th window line, counting from 1.

Line *view_lines_first(View*)

Get first screen line.

Line *view_lines_last(View*)

Get last non-empty screen line.

size_t view_slide_up(View*, int lines)
size_t view_slide_down(View*, int lines)
size_t view_scroll_up(View*, int lines)
size_t view_scroll_down(View*, int lines)
size_t view_scroll_page_up(View*)
size_t view_scroll_page_down(View*)
size_t view_scroll_halfpage_up(View*)
size_t view_scroll_halfpage_down(View*)
void view_redraw_top(View*)
void view_redraw_center(View*)
void view_redraw_bottom(View*)
void view_scroll_to(View*, size_t pos)

Dimension

bool view_resize(View*, int width, int height)
int view_height_get(View*)
int view_width_get(View*)

Draw

void view_invalidate(View*)
void view_draw(View*)
bool view_update(View*)

Selections

A selection is a non-empty, directed range with two endpoints called cursor and anchor. A selection can be anchored in which case the anchor remains fixed while only the position of the cursor is adjusted. For non-anchored selections both endpoints are updated. A singleton selection covers one character on which both cursor and anchor reside. There always exists a primary selection which remains visible (i.e. changes to its position will adjust the viewport).

Creation and Destruction

Selection *view_selections_new(View*, size_t pos)

Create a new singleton selection at the given position.

Note

New selections are created non-anchored.

Warning

Fails if position is already covered by a selection.

Selection *view_selections_new_force(View*, size_t pos)

Create a new selection even if position is already covered by an existing selection.

Note

This should only be used if the old selection is eventually disposed.

bool view_selections_dispose(Selection*)

Dispose an existing selection.

Warning

Not applicable for the last existing selection.

bool view_selections_dispose_force(Selection*)

Forcefully dispose an existing selection.

If called for the last existing selection, it will be reduced and marked for destruction. As soon as a new selection is created this one will be disposed.

Selection *view_selection_disposed(View*)

Query state of primary selection.

If the primary selection was marked for destruction, return it and clear destruction flag.

void view_selections_dispose_all(View*)

Dispose all but the primary selection.

void view_selections_normalize(View*)

Dispose all invalid and merge all overlapping selections.

void view_selections_set_all(View*, Array*, bool anchored)

Replace currently active selections.

Parameters

  • array – The array of Filerange objects.

  • anchored – Whether all selection should be anchored.

Array view_selections_get_all(View*)

Get array containing a Fileranges for each selection.

Cover

Filerange view_selections_get(Selection*)

Get an inclusive range of the selection cover.

bool view_selections_set(Selection*, const Filerange*)

Set selection cover.

Updates both cursor and anchor.

void view_selection_clear(Selection*)

Reduce selection to character currently covered by the cursor.

Note

Sets selection to non-anchored mode.

void view_selections_clear_all(View*)

Reduce all currently active selections.

void view_selections_flip(Selection*)

Flip selection orientation.

Swap cursor and anchor.

Note

Has no effect on singleton selections.

Anchor

void view_selections_anchor(Selection*, bool anchored)

Anchor selection.

Further updates will only update the cursor, the anchor will remain fixed.

bool view_selections_anchored(Selection*)

Check whether selection is anchored.

Cursor

Selection endpoint to which cursor motions apply.

Properties

size_t view_cursors_pos(Selection*)

Get position of selection cursor.

size_t view_cursors_line(Selection*)

Get 1-based line number of selection cursor.

size_t view_cursors_col(Selection*)

Get 1-based column of selection cursor.

Note

Counts the number of graphemes on the logical line up to the cursor position.

Line *view_cursors_line_get(Selection*)

Get screen line of selection cursor.

int view_cursors_cell_get(Selection*)

Get zero based index of screen cell on which selection cursor currently resides.

Warning

Returns -1 if the selection cursor is currently not visible.

Placement

void view_cursors_to(Selection*, size_t pos)

Place cursor of selection at pos.

Note

If the selection is not anchored, both selection endpoints will be adjusted to form a singleton selection covering one character starting at pos. Otherwise only the selection cursor will be changed while the anchor remains fixed.

void view_cursors_scroll_to(Selection*, size_t pos)

Adjusts window viewport until the requested position becomes visible.

Note

For all but the primary selection this is equivalent to view_selection_to.

Warning

Repeatedly redraws the window content. Should only be used for short distances between current cursor position and destination.

void view_cursors_place(Selection*, size_t line, size_t col)

Place cursor on given (line, column) pair.

Parameters

  • line – the 1-based line number

  • col – the 1 based column

    Note

    Except for the different addressing format this is equivalent to view_selection_to.

int view_cursors_cell_set(Selection*, int cell)

Place selection cursor on zero based window cell index.

Warning

Fails if the selection cursor is currently not visible.

Motions

These functions perform motions based on the current selection cursor position.

size_t view_line_down(Selection*)
size_t view_line_up(Selection*)
size_t view_screenline_down(Selection*)
size_t view_screenline_up(Selection*)
size_t view_screenline_begin(Selection*)
size_t view_screenline_middle(Selection*)
size_t view_screenline_end(Selection*)

Primary Selection

These are convenience function which operate on the primary selection.

void view_cursor_to(View*, size_t pos)

Move primary selection cursor to the given position.

Makes sure that position is visible.

Note

If position was not visible before, we attempt to show surrounding context. The viewport will be adjusted such that the line holding the cursor is shown in the middle of the window.

size_t view_cursor_get(View*)

Get cursor position of primary selection.

Filerange view_selection_get(View*)

Get primary selection.

Note

Is always a non-empty range.

Save and Restore

Filerange view_regions_restore(View*, SelectionRegion*)
bool view_regions_save(View*, Filerange*, SelectionRegion*)

Style

void view_options_set(View*, enum UiOption options)
enum UiOption view_options_get(View*)
void view_colorcolumn_set(View*, int col)
int view_colorcolumn_get(View*)
void view_tabwidth_set(View*, int tabwidth)

Set how many spaces are used to display a tab \t character.

bool view_style_define(View*, enum UiStyle, const char *style)

Define a display style.

void view_style(View*, enum UiStyle, size_t start, size_t end)

Apply a style to a text range.

char *view_symbol_eof_get(View*)