Home Explore Blog CI



neovim

5th chunk of `runtime/doc/ui.txt`
de2f09ef0cbb2a48bc00672d21c1dfec165233e12091e49f0000000100000fa2
 |ui-multigrid|.

Highlight attribute groups are predefined. UIs should maintain a table to map
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
	being created with this size.

["default_colors_set", rgb_fg, rgb_bg, rgb_sp, cterm_fg, cterm_bg] ~
	The first three arguments set the default foreground, background and
	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
	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 builtin ("ANSI") defaults
	are expected.

	Note: Unlike the corresponding |ui-grid-old| events, the screen is not
	always cleared after sending this event. The UI must repaint the
	screen with changed background color itself.

							*ui-event-hl_attr_define*
["hl_attr_define", id, rgb_attr, cterm_attr, info] ~
	Add a highlight with `id`  to the highlight table, with the
	attributes specified by the `rgb_attr` and `cterm_attr` dicts, with the
	following (all optional) keys.

	`foreground`:		foreground color.
	`background`:		background color.
	`special`:		color to use for various underlines, when
				present.
	`reverse`:		reverse video. Foreground and background colors
				are switched.
	`italic`:		italic text.
	`bold`:			bold text.
	`strikethrough`:	struckthrough text.
	`underline`:		underlined text. The line has `special` color.
	`undercurl`:		undercurled text. The curl has `special` color.
	`underdouble`:		double underlined text. The lines have `special` color.
	`underdotted`:		underdotted text. The dots have `special` color.
	`underdashed`:		underdashed text. The dashes have `special` color.
	`altfont`:		alternative font.
	`blend`:		blend level (0-100). Could be used by UIs to
				support blending floating windows to the
				background or to signal a transparent cursor.
	`url`:			URL associated with this highlight. UIs should
				present the region as a clickable hyperlink.

	For absent color keys the default color should be used. Don't store
	the default value in the table, rather a sentinel value, so that
	a changed default color will take effect.
	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
	terminal 256-color codes, as the `rgb_attr` and `cterm_attr` parameters
	respectively. The |ui-rgb| option has no effect anymore.
	Most external UIs will only need to store and use the `rgb_attr`
	attributes.

	`id` 0 will always be used for the default highlight with colors defined
	by `default_colors_set` and no styles applied.

	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 unless |ui-hlstate| is enabled.

["hl_group_set", name, hl_id] ~
	The built-in highlight group `name` was set to use the attributes `hl_id`
	defined by a previous `hl_attr_define` call. This event is not needed
	to render the grids which use attribute ids directly, but is useful
	for a UI who want to render its own elements with consistent
	highlighting. For instance a UI using |ui-popupmenu| events, might
	use the |hl-Pmenu| family of builtin highlights.

							    *ui-event-grid_line*
["grid_line", grid, row, col_start, cells, wrap] ~
	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

Title: Highlight Attributes and Grid Line Events
Summary
This section describes `hl_attr_define`, which adds a highlight definition to the highlight table. The `rgb_attr` and `cterm_attr` dictionaries specify the foreground, background, special color, and styles like reverse video, italic, bold, underline, etc. It also covers `hl_group_set`, which assigns a highlight ID to a built-in highlight group name. Finally, it explains `grid_line`, which redraws a continuous part of a row on a grid, specifying the text, highlight ID, and repetition factor for each cell.