mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-09-29 06:28:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc/ui.txt

Browse Source
This commit is contained in:
Justin M. Keyes
2017-10-28 23:49:41 +02:00
parent f640ae0d6e
commit 8526902790
3 changed files with 51 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
runtime/doc/ui.txt
View File

@@ -1,12 +1,12 @@
*ui.txt* Nvim *ui.txt* Nvim
NVIM REFERENCE MANUAL by Thiago de Arruda NVIM REFERENCE MANUAL
UI protocol *ui* Nvim UI protocol *ui*
Type <M-]> to see the table of contents. Type |gO| to see the table of contents.
============================================================================== ==============================================================================
Introduction *ui-intro* Introduction *ui-intro*
@@ -16,34 +16,35 @@ 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 monospace font size. Some elements (UI "widgets") can be drawn separately from
the grid ("externalized"). the grid ("externalized").
*ui-options* *ui-options*
After connecting to Nvim (usually a spawned, embedded instance) use the 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_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 Nvim screen grid with a size of width × height cells. `options` must be
a dictionary with these (optional) keys: a dictionary with these (optional) keys:
`rgb` Controls what color format to use. `rgb` Decides the color format.
Set to true (default) to use 24-bit rgb Set true (default) for 24-bit RGB colors.
colors. Set false for terminal colors (max of 256).
Set to false to use terminal color codes (at *ui-ext-options*
most 256 different colors).
`ext_popupmenu` Externalize the popupmenu. |ui-popupmenu| `ext_popupmenu` Externalize the popupmenu. |ui-popupmenu|
`ext_tabline` Externalize the tabline. |ui-tabline| `ext_tabline` Externalize the tabline. |ui-tabline|
`ext_cmdline` Externalize the cmdline. |ui-cmdline| `ext_cmdline` Externalize the cmdline. |ui-cmdline|
Nvim will then send msgpack-rpc notifications, with the method name "redraw" Nvim will then send msgpack-rpc notifications, with the method name "redraw"
and a single argument, an array of screen update events. and a single argument, an array of screen update events.
Update events are tuples whose first element is the string name of the update Update events are tuples whose first element is the event name and remaining
kind. The rest are parameters for each update, described in the sections below. elements the event parameters.
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, Events must be handled in order. The user should only see the updated screen
and suffice to implement a terminal-like interface. Nvim also allows a number state after all events in the same "redraw" batch are processed (not any
of screen elements to be sent as descriptive events for the GUI to draw intermediate state after processing only part of the array).
itself, rather than Nvim drawing itself on the grid. This is controlled by the
`ext_` options. Nvim sends |ui-global| and |ui-grid| events unconditionally; these suffice to
implement a terminal-like interface.
Nvim optionally sends screen elements "semantically" as structured events
instead of raw grid-lines. Then the UI must decide how to present those
elements itself; Nvim will not draw those elements on the grid. This is
controlled by the |ui-ext-options|.
Future versions of Nvim may add new update kinds and may append new parameters 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 existing update kinds. Clients must be prepared to ignore such extensions
@@ -64,7 +65,8 @@ Global Events *ui-global*
current mode is given by the `mode_idx` field of the `mode_change` current mode is given by the `mode_idx` field of the `mode_change`
event. event.
Each mode property map may contain these keys: Each mode property map may contain these keys:
KEY DESCRIPTION ~ KEY DESCRIPTION ~
`cursor_shape`: "block", "horizontal", "vertical" `cursor_shape`: "block", "horizontal", "vertical"
`cell_percentage`: Cell % occupied by the cursor. `cell_percentage`: Cell % occupied by the cursor.
@@ -75,7 +77,7 @@ Each mode property map may contain these keys:
`name`: Mode descriptive name. `name`: Mode descriptive name.
`mouse_shape`: (To be implemented.) `mouse_shape`: (To be implemented.)
Some keys are missing in some modes. Some keys are missing in some modes.
["mode_change", mode, mode_idx] ["mode_change", mode, mode_idx]
The mode changed. The first parameter `mode` is a string representing The mode changed. The first parameter `mode` is a string representing
@@ -86,7 +88,6 @@ Some keys are missing in some modes.
instance more submodes and temporary states might be represented as instance more submodes and temporary states might be represented as
separate modes. separate modes.
["mouse_on"] ["mouse_on"]
["mouse_off"] ["mouse_off"]
Tells the client whether mouse support, as determined by |'mouse'| Tells the client whether mouse support, as determined by |'mouse'|
@@ -97,8 +98,8 @@ Some keys are missing in some modes.
["busy_on"] ["busy_on"]
["busy_off"] ["busy_off"]
Nvim started or stopped being busy, and possibly not responsible to user Nvim started or stopped being busy, and possibly not responsive to
input. This could be indicated to the user by hiding the cursor. user input. This could be indicated to the user by hiding the cursor.
["suspend"] ["suspend"]
|:suspend| command or |Ctrl-Z| mapping is used. A terminal client (or other |:suspend| command or |Ctrl-Z| mapping is used. A terminal client (or other
@@ -137,7 +138,7 @@ Grid Events *ui-grid*
Set the default foreground, background and special colors Set the default foreground, background and special colors
respectively. respectively.
*ui-event-highlight_set* *ui-event-highlight_set*
["highlight_set", attrs] ["highlight_set", attrs]
Set the attributes that the next text put on the grid will have. 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 `attrs` is a dict with the keys below. Any absent key is reset
@@ -235,44 +236,49 @@ Only sent if `ext_cmdline` option is set in |ui-options|
["cmdline_show", content, pos, firstc, prompt, indent, level] ["cmdline_show", content, pos, firstc, prompt, indent, level]
content: List of [attrs, string] content: List of [attrs, string]
[[{}, "t"], [attrs, "est"], ...] [[{}, "t"], [attrs, "est"], ...]
Triggered when the user types in the cmdline.
The `content` is the full content that should be displayed in the 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, and the `pos` is the position of the cursor that in the
cmdline. This event will be triggered when you type in the cmdline. cmdline. The content is divided into chunks with different highlight
The content is divided into chunks with different highlight attributes attributes represented as a dict (see |ui-event-highlight_set|).
represented as a dict, see |ui-event-highlight_set|.
`firstc` and `prompt` are text, that if non-empty should be `firstc` and `prompt` are text, that if non-empty should be
displayed in front of the command line. `firstc` always indicates displayed in front of the command line. `firstc` always indicates
built in command lines such as `:` (ex command) and `/` `?` (search), built-in command lines such as `:` (ex command) and `/` `?` (search),
while `prompt` is an |input()| prompt. `indent` tells how many spaces while `prompt` is an |input()| prompt. `indent` tells how many spaces
the content should be indented the content should be indented.
The command line in nvim can be invoked recursively, for instance by The Nvim command line can be invoked recursively, for instance by
typing `<c-r>=` at the command line prompt. The `level` field is used typing `<c-r>=` at the command line prompt. The `level` field is used
to distinguish different command lines active at the same time. The to distinguish different command lines active at the same time. The
first invoked command line will always have level 1, and the next first invoked command line has level 1, the next recursively-invoked
recursively invoked prompt will have level 2. Also, a command line prompt has level 2. A command line invoked from the |cmd-line-window|
invoked while in command line window will have a higher level than has a higher level than than the edited command line.
than the edited command line.
["cmdline_pos", pos, level] ["cmdline_pos", pos, level]
Change the cursor position in the cmdline. Change the cursor position in the cmdline.
["cmdline_special_char", c, shift, level] ["cmdline_special_char", c, shift, level]
Display a special char in the cmdline at the cursor position. This is 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. typically used to indicate a pending state, e.g. after |c_CTRL-V|. If
if shift is true the text after the cursor should be shifted, `shift` is true the text after the cursor should be shifted, otherwise
otherwise it should overshadow the char at the cursor. it should overwrite the char at the cursor.
Should be hidden at next cmdline_char
Should be hidden at next cmdline_pos.
["cmdline_hide"] ["cmdline_hide"]
Hide the cmdline. Hide the cmdline.
["cmdline_block_show", lines] ["cmdline_block_show", lines]
Show a block of context to the current command line. This occurs for Show a block of context to the current command line. For example if
instance if a function is interactively defined at the command line. the user defines a |:function| interactively: >
`lines` is a list of lines where each line is represented as a list of :function Foo()
highlighted chunks, just like `contents` of |ui-event-cmdline_show|. : echo "foo"
:
<
`lines` is a list of lines of highlighted chunks, in the same form as
the "cmdline_show" `contents` parameter.
["cmdline_block_append", line] ["cmdline_block_append", line]
Append a line at the end of the currently shown block. Append a line at the end of the currently shown block.

2
src/nvim/globals.h
View File

@@ -984,7 +984,7 @@ EXTERN int km_startsel INIT(= FALSE);
EXTERN int cedit_key INIT(= -1); ///< key value of 'cedit' option EXTERN int cedit_key INIT(= -1); ///< key value of 'cedit' option
EXTERN int cmdwin_type INIT(= 0); ///< type of cmdline window or 0 EXTERN int cmdwin_type INIT(= 0); ///< type of cmdline window or 0
EXTERN int cmdwin_result INIT(= 0); ///< result of cmdline window or 0 EXTERN int cmdwin_result INIT(= 0); ///< result of cmdline window or 0
EXTERN int cmdwin_level INIT(= 0); ///< cmdline level of cmdline window or 0 EXTERN int cmdwin_level INIT(= 0); ///< cmdline recursion level
EXTERN char_u no_lines_msg[] INIT(= N_("--No lines in buffer--")); EXTERN char_u no_lines_msg[] INIT(= N_("--No lines in buffer--"));

1
src/nvim/ui.c
View File

@@ -30,7 +30,6 @@
#include "nvim/os/input.h" #include "nvim/os/input.h"
#include "nvim/os/signal.h" #include "nvim/os/signal.h"
#include "nvim/popupmnu.h" #include "nvim/popupmnu.h"
#include "nvim/ex_getln.h"
#include "nvim/screen.h" #include "nvim/screen.h"
#include "nvim/syntax.h" #include "nvim/syntax.h"
#include "nvim/window.h" #include "nvim/window.h"