docs: breakout ui.txt from msgpack_rpc.txt

1 files changed, 284 insertions, 0 deletions

diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt
new file mode 100644
index 0000000000..b875c1b183
--- /dev/null
+++ b/runtime/doc/ui.txt
@@ -0,0 +1,284 @@
+*ui.txt*	Nvim
+
+
+		 NVIM REFERENCE MANUAL    by Thiago de Arruda
+
+
+UI protocol					     *ui*
+
+				      Type <M-]> to see the table of contents.
+
+==============================================================================
+Introduction							     *ui-intro*
+
+GUIs can be implemented as external processes communicating with Nvim over the
+RPC API. The UI model consists of a terminal-like grid with a single,
+monospace font size. Some elements (UI "widgets") can be drawn separately from
+the grid ("externalized").
+
+								    *ui-options*
+After connecting to Nvim (usually a spawned, embedded instance) use the
+|nvim_ui_attach| API method to tell Nvim that your program wants to draw the
+Nvim screen grid with a size of width × height cells. `options` must be
+a dictionary with these (optional) keys:
+	`rgb`			Controls what color format to use.
+				Set to true (default) to use 24-bit rgb
+				colors.
+				Set to false to use terminal color codes (at
+				most 256 different colors).
+	`ext_popupmenu`		Externalize the popupmenu. |ui-popupmenu|
+	`ext_tabline`		Externalize the tabline. |ui-tabline|
+	`ext_cmdline`		Externalize the cmdline. |ui-cmdline|
+
+Nvim will then send msgpack-rpc notifications, with the method name "redraw"
+and a single argument, an array of screen update events.
+Update events are tuples whose first element is the string name of the update
+kind. The rest are parameters for each update, described in the sections below.
+These should be processed in order. Preferably the user should only be able to
+see the screen state after all update events in the same "redraw" event are
+processed (not any intermediate state after processing only a part of the
+array).
+
+Section 2 and 3 describes grid and mode events that are send unconditionally,
+and suffice to implement a terminal-like interface. Nvim also allows a number
+of screen elements to be sent as descriptive events for the GUI to draw
+itself, rather than Nvim drawing itself on the grid. This is controlled by the
+`ext_` options.
+
+Future versions of Nvim may add new update kinds and may append new parameters
+to existing update kinds. Clients must be prepared to ignore such extensions
+to be forward-compatible. |api-contract|
+
+==============================================================================
+Global Events							    *ui-global*
+
+["set_title", title]
+["set_icon", icon]
+	Set the window title, and icon (minimized) window title, respectively.
+	In windowing systems not distinguishing between the two, "set_icon"
+	can be ignored.
+
+["mode_info_set", cursor_style_enabled, mode_info]
+	`cursor_style_enabled` is a boolean indicating if the UI should set
+	the cursor style. `mode_info` is a list of mode property maps. The
+	current mode is given by the `mode_idx` field of the `mode_change`
+	event.
+
+Each mode property map may contain these keys:
+	KEY		DESCRIPTION ~
+	`cursor_shape`:	"block", "horizontal", "vertical"
+	`cell_percentage`: Cell % occupied by the cursor.
+	`blinkwait`, `blinkon`, `blinkoff`: See |cursor-blinking|.
+	`hl_id`:	Cursor highlight group.
+	`hl_lm`:	Cursor highlight group if 'langmap' is active.
+	`short_name`:	Mode code name, see 'guicursor'.
+	`name`:		Mode descriptive name.
+	`mouse_shape`:	(To be implemented.)
+
+Some keys are missing in some modes.
+
+["mode_change", mode, mode_idx]
+	The mode changed.  The first parameter `mode` is a string representing
+	the current mode. `mode_idx` is an index into the array received in
+	the `mode_info_set` event. UIs should change the cursor style
+	according to the properties specified in the corresponding item. The
+	set of modes reported will change in new versions of Nvim, for
+	instance more submodes and temporary states might be represented as
+	separate modes.
+
+
+["mouse_on"]
+["mouse_off"]
+	Tells the client whether mouse support, as determined by |'mouse'|
+	option, is considered to be active in the current mode. This is mostly
+	useful for a terminal frontend, or other situations where nvim mouse
+	would conflict with other usages of the mouse. It is safe for a client
+	to ignore this and always send mouse events.
+
+["busy_on"]
+["busy_off"]
+	Nvim started or stopped being busy, and possibly not responsible to user
+	input. This could be indicated to the user by hiding the cursor.
+
+["suspend"]
+	|:suspend| command or |Ctrl-Z| mapping is used. A terminal client (or other
+	client where it makes sense) could suspend itself.  Other clients can
+	safely ignore it.
+
+["update_menu"]
+	The menu mappings changed.
+
+["bell"]
+["visual_bell"]
+	Notify the user with an audible or visual bell, respectively.
+
+==============================================================================
+Grid Events							      *ui-grid*
+
+["resize", width, height]
+	The grid is resized to `width` and `height` cells.
+
+["clear"]
+	Clear the grid.
+
+["eol_clear"]
+	Clear from the cursor position to the end of the current line.
+
+["cursor_goto", row, col]
+	Move the cursor to position (row, col). Currently, the same cursor is
+	used to define the position for text insertion and the visible cursor.
+	However, only the last cursor position, after processing the entire
+	array in the "redraw" event, is intended to be a visible cursor
+	position.
+
+["update_fg", color]
+["update_bg", color]
+["update_sp", color]
+	Set the default foreground, background and special colors
+	respectively.
+
+							*ui-event-highlight_set*
+["highlight_set", attrs]
+	Set the attributes that the next text put on the grid will have.
+	`attrs` is a dict with the keys below. Any absent key is reset
+	to its default value. Color defaults are set by the `update_fg` etc
+	updates. All boolean keys default to false.
+
+	`foreground`:	foreground color.
+	`background`:	backround color.
+	`special`:	color to use for underline and undercurl, when present.
+	`reverse`:	reverse video. Foreground and background colors are
+			switched.
+	`italic`:	italic text.
+	`bold`:		bold text.
+	`underline`:	underlined text. The line has `special` color.
+	`undercurl`:	undercurled text. The curl has `special` color.
+
+["put", text]
+	The (utf-8 encoded) string `text` is put at the cursor position
+	(and the cursor is advanced), with the highlights as set by the
+	last `highlight_set` update.
+
+["set_scroll_region", top, bot, left, right]
+	Define the scroll region used by `scroll` below.
+
+["scroll", count]
+	Scroll the text in the scroll region. The diagrams below illustrate
+	what will happen, depending on the scroll direction. "=" is used to
+	represent the SR(scroll region) boundaries and "-" the moved rectangles.
+	Note that dst and src share a common region.
+
+	If count is bigger than 0, move a rectangle in the SR up, this can
+	happen while scrolling down.
+>
+		+-------------------------+
+		| (clipped above SR)      |            ^
+		|=========================| dst_top    |
+		| dst (still in SR)       |            |
+		+-------------------------+ src_top    |
+		| src (moved up) and dst  |            |
+		|-------------------------| dst_bot    |
+		| src (cleared)           |            |
+		+=========================+ src_bot
+<
+	If count is less than zero, move a rectangle in the SR down, this can
+	happen while scrolling up.
+>
+		+=========================+ src_top
+		| src (cleared)           |            |
+		|------------------------ | dst_top    |
+		| src (moved down) and dst|            |
+		+-------------------------+ src_bot    |
+		| dst (still in SR)       |            |
+		|=========================| dst_bot    |
+		| (clipped below SR)      |            v
+		+-------------------------+
+<
+==============================================================================
+Popupmenu Events						 *ui-popupmenu*
+
+Only sent if `ext_popupmenu` option is set in |ui-options|
+
+["popupmenu_show", items, selected, row, col]
+	`items` is an array of the items to show, the
+	items are themselves arrays of the form [word, kind, menu, info]
+	as defined at |complete-items|, except that `word` is replaced by
+	`abbr` if present.  `selected` is the initially selected item, either a
+	zero-based index into the array of items, or -1 if no item is
+	selected. `row` and `col` is the anchor position, where the first
+	character of the completed word will be.
+
+["popupmenu_select", selected]
+	An item in the currently displayed popupmenu is selected. `selected`
+	is either a zero-based index into the array of items from the last
+	`popupmenu_show` event, or -1 if no item is selected.
+
+["popupmenu_hide"]
+	The popupmenu is hidden.
+
+==============================================================================
+Tabline Events							   *ui-tabline*
+
+Only sent if `ext_tabline` option is set in |ui-options|
+
+["tabline_update", curtab, tabs]
+	Tabline was updated. UIs should present this data in a custom tabline
+	widget.
+	curtab:	  Current Tabpage
+	tabs:	  List of Dicts [{ "tab": Tabpage, "name": String }, ...]
+
+==============================================================================
+Cmdline Events							   *ui-cmdline*
+
+Only sent if `ext_cmdline` option is set in |ui-options|
+
+["cmdline_show", content, pos, firstc, prompt, indent, level]
+        content: List of [attrs, string]
+	         [[{}, "t"], [attrs, "est"], ...]
+	The `content` is the full content that should be displayed in the
+	cmdline, and the `pos` is the position of the cursor that in the
+	cmdline. This event will be triggered when you type in the cmdline.
+	The content is divided into chunks with different highlight attributes
+	represented as a dict, see |ui-event-highlight_set|.
+
+	`firstc` and `prompt` are text, that if non-empty should be
+	displayed in front of the command line. `firstc` always indicates
+	built in command lines such as `:` (ex command) and `/` `?` (search),
+	while `prompt` is an |input()| prompt. `indent` tells how many spaces
+	the content should be indented
+
+	The command line in nvim can be invoked recursively, for instance by
+	typing `<c-r>=` at the command line prompt. The `level` field is used
+	to distinguish different command lines active at the same time. The
+	first invoked command line will always have level 1, and the next
+	recursively invoked prompt will have level 2. Also, a command line
+	invoked while in command line window will have a higher level than
+	than the edited command line.
+
+["cmdline_pos", pos, level]
+	Change the cursor position in the cmdline.
+
+["cmdline_special_char", c, shift, level]
+	Display a special char in the cmdline at the cursor position. This is
+	typically used to indicate a pending state, like right after Ctrl-V.
+	if shift is true the text after the cursor should be shifted,
+	otherwise it should overshadow the char at the cursor.
+	Should be hidden at next cmdline_char
+
+["cmdline_hide"]
+	Hide the cmdline.
+
+["cmdline_block_show", lines]
+	Show a block of context to the current command line. This occurs for
+	instance if a function is interactively defined at the command line.
+	`lines` is a list of lines where each line is represented as a list of
+	highlighted chunks, just like `contents` of |ui-event-cmdline_show|.
+
+["cmdline_block_append", line]
+	Append a line at the end of the currently shown block.
+
+["cmdline_block_hide"]
+	Hide the block.
+
+==============================================================================
+ vim:tw=78:ts=8:noet:ft=help:norl: