diff options
Diffstat (limited to 'include/term')
| -rw-r--r-- | include/term/term.h | 23 |
1 files changed, 17 insertions, 6 deletions
diff --git a/include/term/term.h b/include/term/term.h index dc41114..05afbd9 100644 --- a/include/term/term.h +++ b/include/term/term.h @@ -139,9 +139,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; @@ -149,7 +154,6 @@ struct term_options { struct term_callbacks callbacks; }; -/* 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); @@ -165,6 +169,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); @@ -175,8 +180,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 @@ -197,7 +203,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); |