Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Getting and Setting Values

libghostty-vt has hundreds of values you may want to read or change. Unlike the C API, however, the Rust API provides separate methods for getting or setting each value, since there are no concerns about ABI compatibility, and type safety is much more significant instead.

Newer Headers, Older Libraries

We add new configurable values over time. A program built with a newer header can end up running against an older copy of the library, for example when the library is installed separately as a shared library.

If you pass a key that the loaded library doesn’t know, the call returns Error::Unsupported and doesn’t touch your output. This works the same way in debug and release builds of the library.

That lets you use a newer key when it’s there and fall back when it isn’t. In this example, imagine that render::Snapshot::cursor_blinking was added in a later release than the library your program loads:

let blinking = match snapshot.cursor_blinking() {
  Ok(v) => v,
  // This library predates the key. Use a sensible default instead.
  Err(Error::Unsupported) => true,
  // A real error. Handle it as usual.
  Err(err) => return err,
};

Note that for functions that return Result<Option<T>>, the Ok(None) case and the Err(Error::Unsupported) case mean different things. Error::Unsupported means the library doesn’t know the value at all. None means the library knows the value, but something you passed with it is wrong.

The same check applies to enum values you pass as plain arguments or inside option values, such as a key::Action or the variant of a Point. A value the library doesn’t recognize returns Error::InvalidValue and leaves the object unchanged.