diff options
Diffstat (limited to 'include/term')
| -rw-r--r-- | include/term/term.h | 52 | ||||
| -rw-r--r-- | include/term/term_input.h | 6 |
2 files changed, 46 insertions, 12 deletions
diff --git a/include/term/term.h b/include/term/term.h index aa1a3d7..9d5a882 100644 --- a/include/term/term.h +++ b/include/term/term.h @@ -41,6 +41,16 @@ struct term_snapshot; #define TERM_SCROLLBACK_DEFAULT 10000 /* + * The version of this header. A host compares TERM_VERSION_CODE with + * term_version() to check that the library matches the header. + */ +#define TERM_VERSION(major, minor, patch) (((major) << 16) | ((minor) << 8) | (patch)) +#define TERM_VERSION_MAJOR 0 +#define TERM_VERSION_MINOR 1 +#define TERM_VERSION_PATCH 0 +#define TERM_VERSION_CODE TERM_VERSION(TERM_VERSION_MAJOR, TERM_VERSION_MINOR, TERM_VERSION_PATCH) + +/* * Colors. A term_color is either a direct color (alpha 0xFF, then RGB) or a * palette slot: an index 0-255, the default foreground, or the default * background. A slot resolves when a snapshot is painted, so a theme change @@ -139,9 +149,14 @@ struct term_callbacks { void (*trace)(void *ud, const char *line); }; -/* Options for term_new(). An all-zero value is valid. */ +/* + * Options for term_new(). An all-zero value is valid. A size component of 0 + * selects 80 columns or 24 rows. A negative component, or columns above + * TERM_MAX_COLS, makes term_new() fail. A negative scrollback fails too. + * cursor_style must be a value of enum term_cursor_style. + */ struct term_options { - struct term_vector2i size; /* columns and rows; each is at least 1 */ + struct term_vector2i size; /* columns and rows */ int scrollback; /* history lines; 0 selects TERM_SCROLLBACK_DEFAULT */ struct term_theme theme; enum term_cursor_style cursor_style; @@ -154,12 +169,16 @@ struct term_options { */ const char *name; struct term_callbacks callbacks; + /* Must be zero. term_new() returns NULL if any word is nonzero, so a + * later version can give a word a meaning. */ + uint32_t reserved[8]; }; -/* NULL when memory runs out. */ /* The Unicode version of the width tables, such as "18.0.0". A host can * pass it to programs as UNICODE_VERSION. */ TERM_API const char *term_unicode_version(void); +/* The TERM_VERSION_CODE the library was built with. */ +TERM_API unsigned term_version(void); /* The length of the prefix of buf made of bytes in [0x20, hi). With hi * 0x7f, it finds a run of printable ASCII in UTF-8 text, so a host can @@ -172,6 +191,7 @@ TERM_API size_t term_scan_printable_span(const char *buf, size_t len, unsigned c * and comparisons. */ TERM_API const char *term_isa(void); +/* NULL when memory runs out or an option is invalid. */ TERM_API struct term *term_new(const struct term_options *opt); TERM_API void term_free(struct term *t); @@ -182,8 +202,9 @@ TERM_API void term_free(struct term *t); TERM_API void term_lock(struct term *t); TERM_API void term_unlock(struct term *t); -/* Change the size in cells. Returns false when memory runs out; the terminal - * is then unchanged. The screen reflows to the new width. */ +/* Change the size in cells. Returns false, and the terminal is unchanged, + * when a component is below 1, when cols is above TERM_MAX_COLS, or when + * memory runs out. The screen reflows to the new width. */ TERM_API bool term_resize(struct term *t, struct term_vector2i size); /* Replace the theme. A different theme also drops the colors that the @@ -204,7 +225,12 @@ enum term_feed_flags { TERM_FEED_ONLCR = 1u << 0, }; -TERM_API void term_feed(struct term *t, const char *bytes, size_t len, unsigned flags); +/* + * Feed bytes from the program. Returns false, and changes nothing, when t is + * NULL, when bytes is NULL and len is not 0, or when flags has a bit that is + * not in enum term_feed_flags. A len of 0 is a no-op that returns true. + */ +TERM_API bool term_feed(struct term *t, const char *bytes, size_t len, unsigned flags); /* Report a focus change. The terminal replies only in focus-event mode. */ TERM_API void term_focus(struct term *t, bool focused); @@ -415,11 +441,16 @@ struct term_view { const uint32_t *palette; /* TERM_PALETTE_SIZE ARGB entries */ }; +/* The view of s, NULL for a NULL s. The view and view->palette keep their + * address until term_snapshot_free(); their contents change on each update. */ TERM_API const struct term_view *term_snapshot_view(const struct term_snapshot *s); -/* The cells of viewport row y: view->size.x entries. */ +/* The cells of viewport row y: view->size.x entries. NULL when y is outside + * the viewport or s is NULL. An update can move the cells, so the pointer is + * valid only until the next term_snapshot_update() or term_snapshot_free() of s. */ TERM_API const struct term_cell *term_snapshot_row(const struct term_snapshot *s, int y); /* An identity for the content of row y. Two rows with the same key hold the - * same cells, also when the content moved to another row. */ + * same cells, also when the content moved to another row. 0 when y is outside + * the viewport or s is NULL. */ TERM_API uint64_t term_snapshot_row_key(const struct term_snapshot *s, int y); /* Number of rows in history above the screen. 0 if alternate screen or no history. */ @@ -430,10 +461,13 @@ TERM_API int term_history_rows(const struct term *t); * an empty string; NULL means allocation failed or t is NULL. Release the * result with term_text_free(). */ TERM_API char *term_history_text(struct term *t, int max_rows); +/* The selected columns of viewport row y, end exclusive. An empty span when y + * is outside the viewport or s is NULL. */ TERM_API struct term_span term_snapshot_row_selection(const struct term_snapshot *s, int y); /* The code points of a cluster cell. Returns the number of code points and - * writes at most cap of them. */ + * writes at most cap of them. Writes nothing when cps is NULL or cap is 0. + * Returns 0 when s is NULL. */ TERM_API int term_snapshot_cluster(const struct term_snapshot *s, uint32_t text, uint32_t *cps, int cap); /* The ARGB value of a color in a view. */ diff --git a/include/term/term_input.h b/include/term/term_input.h index c317bea..19d9355 100644 --- a/include/term/term_input.h +++ b/include/term/term_input.h @@ -1,5 +1,5 @@ -#ifndef TERM_INPUT_TYPES_H -#define TERM_INPUT_TYPES_H +#ifndef TERM_INPUT_H +#define TERM_INPUT_H #include <stdbool.h> #include <stddef.h> @@ -199,4 +199,4 @@ struct term_input_result { } #endif -#endif /* TERM_INPUT_TYPES_H */ +#endif /* TERM_INPUT_H */ |