kakoune/doc/json_ui.asciidoc
Maxime Coste 1631a7d8d9 Replace the Exclusive face attribute with Final
Final is more granular, it consists of FinalFg (f), FinalBg (g)
and FinalAttr (a) which control if a face's fg, bg, or attributes
fully overwrite the previous face (instead of merging) and if
following faces apply on top of this face or not.

Fixes #2388 if the Whitespace face has the FinalFg flag.
2018-09-23 23:27:14 +10:00

64 lines
2.7 KiB
Plaintext

Json-Rpc user interface
=======================
Kakoune user interfaces can be implemented through the json-rpc 2.0 protocol.
By launching kakoune in client mode with the `-ui json` option, the launched
client will write newline separated json-rpc requests on stdout and read
json-rpc requests on stdin. Errors will be reported on stderr (not in
json format).
Kakoune requests are always using positional parameters, never named, and
Kakoune won't be able to parse named parameters in requests.
Here are the data structures used:
* Color: a string, either a named color, or #rrggbb, or 'default'
* Attribute: one of {underline, reverse, blink, bold, dim, italic, final_fg, final_bg, final_attr}
* Face { Color fg; Color bg; Array<Attribute> attributes; }
* Atom { Face face; String contents; }
* Line : Array of Atom
* Coord { int line; int column }
Here are the requests that can be written by the json ui on stdout:
* draw(Array<Line> lines, Face default_face, Face padding_face)
padding_face is the face of the padding characters '~' in the
terminal UI.
* draw_status(Line status_line, Line mode_line,
Face default_face)
* menu_show(Array<Line> items, Coord anchor, Face selected_item_face, Face menu_face,
String style)
style can be:
- prompt: display the menu as a prompt menu (anchor is ignored)
- inline: display the menu next to (above or below) the anchor coordinate
* menu_select(int selected)
* menu_hide()
* info_show(String title, String content, Coord anchor, Face face, String style)
style can be:
- prompt: display the info as a prompt info (anchor is ignored)
- inline: display the info next to (above or below) the anchor coordinate
- inlineAbove: display the info next to (above) the anchor coordinate
- inlineBelow: display the info next to (below) the anchor coordinate
- menuDoc: display the info next to the menu, as a documentation for it
- modal: display the info in a way that shows Kakoune is waiting for a
special action related to it.
* info_hide()
* set_cursor(String mode, Coord coord)
set the main cursor position
mode can be:
- prompt: the coordinate line should be 0, and the cursor is in the prompt area
- buffer: the cursor is in the buffer display area
* set_ui_options(Map<String, String> options)
called when ui_options changed with a map of options name to option values
* refresh(bool force)
The requests that the json ui can interpret on stdin are:
* keys(String key1, String key2...): keystrokes
* resize(int rows, int columns): notify ui resize
* mouse(String type, int line, int column): mouse event, type
can be: 'move', 'press', 'release', 'wheel_up', 'wheel_down',
line, column is the cursor position.
* menu_select(int index): explicit select of given menu entry