kakoune

Fork of kakoune, an acceptable text editor
git clone git://git.laack.co/kakoune.git
Log | Files | Refs

json_ui.asciidoc (3719B)


      1 Json-Rpc user interface
      2 =======================
      3 
      4 Kakoune user interfaces can be implemented through the
      5 https://www.jsonrpc.org/specification[json-rpc 2.0 protocol].
      6 
      7 By launching Kakoune in client mode with the `-ui json` option, the launched
      8 client will write newline separated json-rpc requests on stdout and read
      9 json-rpc requests on stdin.  Errors will be reported on stderr (not in
     10 json format).
     11 
     12 Kakoune requests are always using positional parameters, never named, and
     13 Kakoune won't be able to parse named parameters in requests.
     14 
     15 Here are the data structures used:
     16 
     17 * Color: a string, either a named color, or #rrggbb, or 'default'
     18 * Attribute: one of {underline, curly_underline, double_underline, reverse, blink, bold, dim, italic, final_fg, final_bg, final_attr}
     19 * Face { Color fg; Color bg; Array<Attribute> attributes; }
     20 * Atom { Face face; String contents; }
     21 * Line : Array of Atom
     22 * Coord { int line; int column }
     23 
     24 Here are the requests that can be written by the json ui on stdout:
     25 
     26 * draw(Array<Line> lines, Coord cursor_pos, Face default_face, Face padding_face, int widget_columns)
     27   padding_face is the face of the padding characters '~' in the
     28   terminal UI.
     29   cursor_pos is the main cursor coordinates
     30   widget_columns is the number of columns at the start of each line used by flag-lines highlighters.
     31 * draw_status(Line prompt, Line content, int cursor_pos, Line mode_line, Face default_face,
     32               String style)
     33   cursor_pos is the location of the cursor in the content, the UI is expected to trim
     34   content in order to ensure the cursor stays visible, if cursor_pos is negative, no
     35   cursor should be displayed in the prompt. Prompt cursor show have priority to buffer
     36   cursor if only one cursor can be displayed.
     37   style can be:
     38   - "command": command prompt (:)
     39   - "search": search prompt (/, ?)
     40   - "prompt": general prompt (e.g. pipe, object desc)
     41   - "status": normal status (file info, echo messages)
     42 * menu_show(Array<Line> items, Coord anchor, Face selected_item_face, Face menu_face,
     43             String style)
     44   style can be:
     45   - prompt: display the menu as a prompt menu (anchor is ignored)
     46   - inline: display the menu next to (above or below) the anchor coordinate
     47   - search: display the menu as a search menu (anchor is ignored)
     48 * menu_select(int selected)
     49 * menu_hide()
     50 * info_show(Line title, Array<Line> content, Coord anchor, Face face, String style)
     51   style can be:
     52   - prompt: display the info as a prompt info (anchor is ignored)
     53   - inline: display the info next to (above or below) the anchor coordinate
     54   - inlineAbove: display the info next to (above) the anchor coordinate
     55   - inlineBelow: display the info next to (below) the anchor coordinate
     56   - menuDoc: display the info next to the menu, as a documentation for it
     57   - modal: display the info in a way that shows Kakoune is waiting for a
     58     special action related to it.
     59 * info_hide()
     60 * set_ui_options(Map<String, String> options)
     61   called when ui_options changed with a map of options name to option values
     62 * refresh(bool force)
     63 
     64 The requests that the json ui can interpret on stdin are:
     65 
     66 * keys(String key1, String key2...): keystrokes
     67 * paste(String content): paste content at selections
     68 * resize(int rows, int columns): notify ui resize
     69 * scroll(int amount, int line, int colum): scroll by given line amount, line and
     70   column relate to cursor position
     71 * mouse_move(int line, int column): line and column relate to the cursor position.
     72 * mouse_press(String button, int line, int column): line and column relate to
     73   cursor position, button can be 'left', 'middle' or 'right'
     74 * mouse_release(String button, int line, int column): same.
     75 * menu_select(int index): explicit select of given menu entry