opensourcemirror
/
neovim
mirror of https://github.com/neovim/neovim.git
1
0
Fork 0
Code Issues Releases Wiki Activity

doc: UI

This commit is contained in:
Justin M. Keyes 2019-04-09 03:14:27 +02:00
parent 4d97abe805
commit eabe7d95f8
5 changed files with 103 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
runtime/doc/api.txt
View File

@ -1159,7 +1159,7 @@ nvim_buf_line_count({buffer}) *nvim_buf_line_count()*
Line count, or 0 for unloaded buffer. |api-buffer|
nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()*
Activate updates from this buffer to the current channel.
Activates buffer-update events on the channel.
Parameters: ~
{buffer} Buffer handle, or 0 for current buffer
@ -1178,7 +1178,7 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()*
True.
nvim_buf_detach({buffer}) *nvim_buf_detach()*
Deactivate updates from this buffer to the current channel.
Deactivates buffer-update events on the channel.
Parameters: ~
{buffer} Buffer handle, or 0 for current buffer
@ -1736,10 +1736,29 @@ nvim_tabpage_is_valid({tabpage}) *nvim_tabpage_is_valid()*
UI Functions *api-ui*
nvim_ui_attach({width}, {height}, {options}) *nvim_ui_attach()*
TODO: Documentation
Activates UI events on the channel.
Entry point of all UI clients. Allows |--embed| to continue
startup. Implies that the client is ready to show the UI. Adds
the client to the list of UIs. |nvim_list_uis()|
Note:
If multiple UI clients are attached, the global screen
dimensions degrade to the smallest client. E.g. if client
A requests 80x40 but client B requests 200x100, the global
screen has size 80x40.
Parameters: ~
{width} Requested screen columns
{height} Requested screen rows
{options} |ui-options| map
nvim_ui_detach() *nvim_ui_detach()*
TODO: Documentation
Deactivates UI events on the channel.
Removes the client from the list of UIs. |nvim_list_uis()|
Parameters: ~
nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()*
TODO: Documentation

38
runtime/doc/starting.txt
View File

@ -355,35 +355,33 @@ argument.
--embed Use stdin/stdout as a msgpack-RPC channel, so applications can
embed and control Nvim via the |rpc-api|.
By default nvim will wait for the embedding process to call
`nvim_ui_attach` before sourcing startup files and reading
buffers. This is so that UI can show startup messages and
possible swap file dialog for the first loaded file. The
process can do requests before the `nvim_ui_attach`, for
instance a `nvim_get_api_info` call so that UI features can be
safely detected by the UI before attaching.
Waits for the client ("embedder") to call |nvim_ui_attach()|
before sourcing startup files and reading buffers, so that UIs
can deterministically handle (display) early messages,
dialogs, etc. The client can do other requests before
`nvim_ui_attach` (e.g. `nvim_get_api_info` for feature-detection).
During this pre-startup phase the user config is of course not
available (similar to `--cmd`).
See |ui-startup| for more information about UI startup.
Embedders _not_ using the UI protocol must pass |--headless|: >
nvim --embed --headless
To embed nvim without using the UI protocol, `--headless` should
be supplied together with `--embed`. Then initialization is
performed without waiting for an UI. This is also equivalent
to the following alternative: >
nvim --headless --cmd "call stdioopen({'rpc': v:true})"
<
See also |channel-stdio|.
< Then startup will continue without waiting for `nvim_ui_attach`.
This is equivalent to: >
nvim --headless --cmd "call stdioopen({'rpc': v:true})"
< See also: |ui-startup| |channel-stdio|
*--headless*
--headless Start nvim without an UI. The TUI is not used, so stdio
can be used as an arbitrary communication channel.
|channel-stdio| When used together with `--embed`, do not wait
for the embedder to attach an UI.
--headless Start without UI, and do not wait for `nvim_ui_attach`. The
builtin TUI is not used, so stdio works as an arbitrary
communication channel. |channel-stdio|
Also useful for scripting (tests) to see messages that would
not be printed by |-es|.
To detect if a UI is available, check if |nvim_list_uis()| is
empty in or after |VimEnter|.
empty during or after |VimEnter|.
To read stdin as text, "-" must be given explicitly:
--headless cannot assume that stdin is just text. >

76
runtime/doc/ui.txt
View File

@ -64,7 +64,7 @@ the batch array, nor after a batch not ending with "flush".
By default, Nvim sends |ui-global| and |ui-grid-old| events; these suffice to
implement a terminal-like interface. However there are two revisions of the
grid part of the protocol. The newer revision |ui-linegrid|, enabled by
`ext_linegrid` option, has a more effecient representation of text (especially
`ext_linegrid` option, has a more efficient representation of text (especially
highlighted text), and allows extensions that use multiple grids.
The older revision is available and used by default only for backwards
@ -83,35 +83,31 @@ for forward-compatibility. |api-contract|
==============================================================================
UI startup *ui-startup*
Nvim defines a standard procedure for how an embedding UI should interact with
the startup phase of Nvim. When spawning the nvim process, use the |--embed| flag
but not the |--headless| flag. The started Nvim process will pause before loading
startup files and reading buffers, and give the UI a chance to invoke requests
to do early initialization. As soon as the UI invokes |nvim_ui_attach()|, the
startup will continue.
UI embedders (clients that start Nvim with |--embed| and later call
|nvim_ui_attach()|) must start Nvim without |--headless|: >
nvim --embed
Nvim will pause before loading startup files and reading buffers, so the UI
has a chance to invoke requests and do early initialization. Startup will
continue as soon as the UI invokes |nvim_ui_attach()|.
A simple UI only need to do a single |nvim_ui_attach()| request and then
be prepared to handle any UI event. A more featureful UI, which might need
A simple UI only needs to do a single |nvim_ui_attach()| request and then
prepare to handle any UI event. A more featureful UI, which might need
additional configuration of the nvim process, should use the following startup
procedure:
1. Invoke |nvim_get_api_info()|, if this is needed to setup the client library
and/or to get the list of supported UI extensions.
2. At this time, any configuration that should be happen before init.vim
loading should be done. Buffers and windows are not available at this
point, but this could be used to set |g:| variables visible to init.vim
3. If the UI wants to do additional setup after the init.vim file was loaded
register an autocmd for VimEnter at this point: >
nvim_command("autocmd VimEnter * call rpcrequest(1, 'vimenter')")
<4. Now invoke |nvim_ui_attach()|. The UI will need to handle keyboard input
at this point, as sourcing init.vim and loading buffers might lead to
blocking prompts.
5. If step 3 was used, nvim will send a blocking "vimenter" request to the
UI. Inside this request handler, the UI can safely do any initialization
before entering normal mode, for instance reading variables set by
init.vim.
1. Invoke |nvim_get_api_info()|, if needed to setup the client library and/or
to get the list of supported UI extensions.
2. Do any configuration that should be happen before user config is loaded.
Buffers and windows are not available at this point, but this could be used
to set |g:| variables visible to init.vim
3. If the UI wants to do additional setup after user config is loaded,
register a VimEnter autocmd: >
nvim_command("autocmd VimEnter * call rpcrequest(1, 'vimenter')")
<4. Now invoke |nvim_ui_attach()|. The UI must handle user input by now:
sourcing init.vim and loading buffers might lead to blocking prompts.
5. If step 3 was used, Nvim will send a blocking "vimenter" request to the UI.
Inside this request handler, the UI can safely do any initialization before
entering normal mode, for example reading variables set by init.vim.
==============================================================================
Global Events *ui-global*
@ -231,7 +227,7 @@ created. To enable per-window grids, `ext_multigrid` option should be set (see
|ui-multigrid|).
Highlight attribute groups are predefined. UIs should maintain a table to map
numerical highlight `id`:s to the actual attributes.
numerical highlight ids to the actual attributes.
["grid_resize", grid, width, height]
Resize a `grid`. If `grid` wasn't seen by the client before, a new grid is
@ -242,12 +238,12 @@ numerical highlight `id`:s to the actual attributes.
special colors respectively. `cterm_fg` and `cterm_bg` specifies the
default color codes to use in a 256-color terminal.
The rgb values will always be valid colors, by default. If no
The RGB values will always be valid colors, by default. If no
colors have been set, they will default to black and white, depending
on 'background'. By setting the `ext_termcolors` option, instead
-1 will be used for unset colors. This is mostly useful for a
TUI implementation, where using the terminal emulators builitn
defaults are expected.
-1 will be used for unset colors. This is mostly useful for a TUI
implementation, where using the terminal builtin ("ANSI") defaults
are expected.
Note: unlike the corresponding events in the first revision, the
screen is not always cleared after sending this event. The GUI has to
@ -275,7 +271,7 @@ numerical highlight `id`:s to the actual attributes.
All boolean keys default to false, and will only be sent when they
are true.
Highlights are always transmitted both for both the rgb format and as
Highlights are always transmitted both for both the RGB format and as
terminal 256-color codes, as the `rgb_attr` and `cterm_attr` parameters
respectively. The |ui-rgb| option has no effect effect anymore.
Most external UIs will only need to store and use the `rgb_attr`
@ -284,17 +280,17 @@ numerical highlight `id`:s to the actual attributes.
`id` 0 will always be used for the default highlight with colors defined
by `default_colors_set` and no styles applied.
Note: `id`:s can be reused if Nvim's internal highlight table is full.
In this case, Nvim will always issue redraws of screen cells that are
affected by redefined `id`:s, so UIs do not need to keep track of this
Note: Nvim may reuse `id` values if its internal highlight table is full.
In that case Nvim will always issue redraws of screen cells that are
affected by redefined ids, so UIs do not need to keep track of this
themselves.
`info` is an empty array per default, and will be used by the
|ui-hlstate| extension explaned below.
`info` is an empty array by default, and will be used by the
|ui-hlstate| extension explained below.
*ui-event-grid_line*
["grid_line", grid, row, col_start, cells]
Redraw a continous part of a `row` on a `grid`, starting at the column
Redraw a continuous part of a `row` on a `grid`, starting at the column
`col_start`. `cells` is an array of arrays each with 1 to 3 items:
`[text(, hl_id, repeat)]` . `text` is the UTF-8 text that should be put in
a cell, with the highlight `hl_id` defined by a previous `hl_attr_define`
@ -407,7 +403,7 @@ option is not set. New UIs should use |ui-linegrid|.
updates. All boolean keys default to false.
`foreground`: foreground color.
`background`: backround color.
`background`: background color.
`special`: color to use for underline and undercurl, when present.
`reverse`: reverse video. Foreground and background colors are
switched.
@ -531,7 +527,7 @@ tabs.
["win_external_pos", grid, win]
Display or reconfigure external window `win`. The window should be
displayed as a separate top-level window in the desktop envirionment,
displayed as a separate top-level window in the desktop environment,
or something similar.
["win_hide", grid]

10
src/nvim/api/buffer.c
View File

@ -97,7 +97,7 @@ String buffer_get_line(Buffer buffer, Integer index, Error *err)
return rv;
}
/// Activate updates from this buffer to the current channel.
/// Activates buffer-update events on the channel.
///
/// @param channel_id
/// @param buffer Buffer handle, or 0 for current buffer
@ -106,7 +106,7 @@ String buffer_get_line(Buffer buffer, Integer index, Error *err)
/// `nvim_buf_lines_event`. Otherwise, the first notification will be
/// a `nvim_buf_changedtick_event`
/// @param opts Optional parameters. Reserved for future use.
/// @param[out] err Details of an error that may have occurred
/// @param[out] err Error details, if any
/// @return False when updates couldn't be enabled because the buffer isn't
/// loaded or `opts` contained an invalid key; otherwise True.
Boolean nvim_buf_attach(uint64_t channel_id,
@ -129,12 +129,12 @@ Boolean nvim_buf_attach(uint64_t channel_id,
return buf_updates_register(buf, channel_id, send_buffer);
}
//
/// Deactivate updates from this buffer to the current channel.
/// Deactivates buffer-update events on the channel.
///
/// @param channel_id
/// @param buffer Buffer handle, or 0 for current buffer
/// @param[out] err Details of an error that may have occurred
/// @param[out] err Error details, if any
/// @return False when updates couldn't be disabled because the buffer
/// isn't loaded; otherwise True.
Boolean nvim_buf_detach(uint64_t channel_id,

21
src/nvim/api/ui.c
View File

@ -76,6 +76,21 @@ void remote_ui_wait_for_attach(void)
pmap_has(uint64_t)(connected_uis, CHAN_STDIO));
}
/// Activates UI events on the channel.
///
/// Entry point of all UI clients. Allows |\-\-embed| to continue startup.
/// Implies that the client is ready to show the UI. Adds the client to the
/// list of UIs. |nvim_list_uis()|
///
/// @note If multiple UI clients are attached, the global screen dimensions
/// degrade to the smallest client. E.g. if client A requests 80x40 but
/// client B requests 200x100, the global screen has size 80x40.
///
/// @param channel_id
/// @param width Requested screen columns
/// @param height Requested screen rows
/// @param options |ui-options| map
/// @param[out] err Error details, if any
void nvim_ui_attach(uint64_t channel_id, Integer width, Integer height,
Dictionary options, Error *err)
FUNC_API_SINCE(1) FUNC_API_REMOTE_ONLY
@ -164,6 +179,12 @@ void ui_attach(uint64_t channel_id, Integer width, Integer height,
api_free_dictionary(opts);
}
/// Deactivates UI events on the channel.
///
/// Removes the client from the list of UIs. |nvim_list_uis()|
///
/// @param channel_id
/// @param[out] err Error details, if any
void nvim_ui_detach(uint64_t channel_id, Error *err)
FUNC_API_SINCE(1) FUNC_API_REMOTE_ONLY
{