kakoune/doc/json_ui.asciidoc

67 lines
2.9 KiB
Plaintext
Raw Normal View History

2016-03-06 15:43:14 +01:00
Json-Rpc user interface
=======================
Kakoune user interfaces can be implemented through the
https://www.jsonrpc.org/specification[json-rpc 2.0 protocol].
2016-03-06 15:43:14 +01:00
2019-09-24 10:07:23 +02:00
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).
2016-03-06 15:43:14 +01:00
Kakoune requests are always using positional parameters, never named, and
2017-01-06 22:21:14 +01:00
Kakoune won't be able to parse named parameters in requests.
2016-03-06 15:43:14 +01:00
Here are the data structures used:
2017-01-06 22:21:14 +01:00
* 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}
2016-03-06 15:43:14 +01:00
* 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)
2017-01-06 22:21:14 +01:00
padding_face is the face of the padding characters '~' in the
terminal UI.
2016-03-06 15:43:14 +01:00
* draw_status(Line status_line, Line mode_line,
Face default_face)
2017-01-06 22:21:14 +01:00
* menu_show(Array<Line> items, Coord anchor, Face selected_item_face, Face menu_face,
2016-03-06 15:43:14 +01:00
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(Line title, Array<Line> content, Coord anchor, Face face, String style)
2016-03-06 15:43:14 +01:00
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.
2016-03-06 15:43:14 +01:00
* 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)
2016-03-06 15:43:14 +01:00
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
* scroll(int amount): scroll by given line amount
* mouse_move(int line, int column): line and column relate to the cursor position.
* mouse_press(String button, int line, int column): line and column relate to
cursor position, button can be 'left', 'middle' or 'right'
* mouse_release(String button, int line, int column): same.
* menu_select(int index): explicit select of given menu entry