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
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*
@@ -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
the grid ("externalized").
*ui-options*
*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).
`rgb` Decides the color format.
Set true (default) for 24-bit RGB colors.
Set false for terminal colors (max of 256).
*ui-ext-options*
`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).
Update events are tuples whose first element is the event name and remaining
elements the event parameters.
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.
Events must be handled in order. The user should only see the updated screen
state after all events in the same "redraw" batch are processed (not any
intermediate state after processing only part of the array).
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
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`
event.
Each mode property map may contain these keys:
Each mode property map may contain these keys:
KEY DESCRIPTION ~
`cursor_shape`: "block", "horizontal", "vertical"
`cell_percentage`: Cell % occupied by the cursor.
@@ -75,7 +77,7 @@ Each mode property map may contain these keys:
`name`: Mode descriptive name.
`mouse_shape`: (To be implemented.)
Some keys are missing in some modes.
Some keys are missing in some modes.
["mode_change", mode, mode_idx]
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
separate modes.
["mouse_on"]
["mouse_off"]
Tells the client whether mouse support, as determined by |'mouse'|
@@ -97,8 +98,8 @@ Some keys are missing in some modes.
["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.
Nvim started or stopped being busy, and possibly not responsive 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
@@ -137,7 +138,7 @@ Grid Events *ui-grid*
Set the default foreground, background and special colors
respectively.
*ui-event-highlight_set*
*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
@@ -235,44 +236,49 @@ 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"], ...]
Triggered when the user types in the cmdline.
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|.
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),
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 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
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.
first invoked command line has level 1, the next recursively-invoked
prompt has level 2. A command line invoked from the |cmd-line-window|
has 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
typically used to indicate a pending state, e.g. after |c_CTRL-V|. If
`shift` is true the text after the cursor should be shifted, otherwise
it should overwrite the char at the cursor.
Should be hidden at next cmdline_pos.
["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|.
Show a block of context to the current command line. For example if
the user defines a |:function| interactively: >
:function Foo()
: 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]
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 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_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--"));

1
src/nvim/ui.c
View File

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