*nvim_gui_shim.txt* A helper plugin for Neovim GUIs
*nvim-gui-shim*

In Neovim the GUI is an external process that communicates with the `nvim`
process using the |msgpack-rpc-api|. This separation means the GUI is just a
particular type of plugin, as a consequence some functionality that was
available in Vim is a NOOP in Neovim, or is still in the process of being
specified.

This plugin provides replacements for some missing GUI bits in Neovim. These
can be used in |ginit.vim| provided that

1. The user's GUI loaded the |ginit.vim| file
2. The user's GUI supports the rpc events used by this plugin


==============================================================================
1. Commands

								*GuiAdaptiveColor*
GuiAdaptiveColor    Use the neovim `colorscheme` to style the GUI.
>
		    :GuiAdaptiveColor 1
<
								*GuiAdaptiveFont*
GuiAdaptiveFont     Use the current `GuiFont`` to decorate the GUI.
>
		    :GuiAdaptiveFont 1
<
								*GuiAdaptiveStyle*
GuiAdaptiveStyle    Override the default Qt Style/Theme. See
>
		    :GuiAdaptiveStyle Fusion
<
								*GuiAdaptiveStyleList*
GuiAdaptiveStyleList    Shows the list of available Qt Styles.

								*GuiFont*
GuiFont		When called with no arguments this command display the
		current font used by the GUI.

		If an argument is provided it is treated as the font
		description. The format for the font is a subset of the font
		name used by Vim's 'guifont' in OS X. For example to set the
		GUI font family to Monaco with height 13: >

		    :GuiFont Monaco:h13
<
		You can also use floating-point sizes:
>
		    :GuiFont Monaco:h13.5
<
		The following attributes are available

			hXX - height is XX in points (can be floating-point)
			wXX - weight is XX
			b   - bold weight
			sb  - semibold weight
			l   - light weight
			i   - italic

		It warns and fails when an invalid font has specified.
		Use a |bang| (!) to forcedly assign an invalid font like:
>
		    :GuiFont! <An invalid font>
<
								*GuiLinespace*
GuiLinespace	When called with no arguments this command displays the
		linespace, the number of extra pixels each line will have.
                A single argument is accepted as the new linespace height.

								*GuiRenderFontAttr*
GuiRenderFontAttr	Enable or disable Rendering of GUI font attributes. Turning
			this off disables rendering of italic or bold text.

								*GuiScrollBar*
GuiScrollBar	Enable or disable the external GUI scrollbar

								*GuiTabline*
GuiTabline	Enable or disable the external GUI tabline

								*GuiPopupmenu*
GuiPopupmenu	Enable or disable the external GUI popup menu

								*GuiRenderLigatures*
GuiRenderLigatures	Enable or disable rendering ligatures

								*GuiWindowOpacity*
GuiWindowOpacity	Set window opacity. Takes a single argument,
				a double in the range 0.0 to 1.0 (fully opaque).
				This capability might not be supported in some platforms.

==============================================================================
2. GUI variables

							*g:GuiLoaded*
g:GuiLoaded is set when this plugin loads. Use it in |ginit.vim| to make sure
the shim has loaded. For example to set the GUI font on startup >

    if exists('g:GuiLoaded')
	Guifont DejaVu Sans Mono:h15
    endif

The GUI is expected to set certain variables about its current state, however
you are encouraged to be defensive about using the following variables.
Setting the values of these variables has no effect on the GUI (i.e. only the
GUI should set them).

							*g:GuiWindowMaximized*
g:GuiWindowMaximized indicates whether the GUI window is maximized. In some
system (X11) this not a reliable indicator, since the window manager can
override the window behaviour.

							*g:GuiWindowFullScreen*
g:GuiWindowFullScreen indicates whether the GUI window is maximized. In some
system (X11) this not a reliable indicator, since the window manager can
override the window behaviour.

							*g:GuiWindowFrameless*
g:GuiWindowFrameless indicates whether the GUI window is frameless. In some
system (X11) this not a reliable indicator, since the window manager can
override the window behaviour.

							*g:GuiWindowId*
g:GuiWindowId holds the window id (X11) or the window handle (Windows).
This was an alternative to v:windowid, but since nvim 0.1.4, v:windowid can
also be used by external UIs to hold this information.

							*g:GuiFont*
g:GuiFont holds the current GUI font name, the same value used by
|GuiFont|.

							*g:GuiLinespace*
g:GuiLinespace holds the extra vertical space (in pixels) added to
each line.

							*g:GuiMousehide*
g:GuiMousehide is 1 if mouse hiding is in effect, 0 otherwise.

==============================================================================
3. Functions

							*GuiForeground()*
GuiForeground()	moves the GUI window to the foreground. In some systems this
might not work due to window manager policy (X11) or focus stealing prevention
(Windows). Replaces |foreground()|.

							*GuiWindowMaximized()*
GuiWindowMaximized(enabled) sets the window maximized state, 1 means
enabled and 0 disabled. In some systems (X11) this function is not guaranteed
to work.

							*GuiWindowFullScreen()*
GuiWindowFullScreen(enabled) sets the window fullscreen state, 1 means
enabled and 0 disabled.

							*GuiWindowFrameless()*
GuiWindowFrameless(enabled) sets the window frameless state, 1 means
enabled and 0 disabled.

							*GuiFont()*
GuiFont(fname) Sets the GUI font, see |GuiFont| for details on the font name
format. Replaces |'guifont'|.

							*GuiLinespace()*
GuiLinespace(height) sets the number of vertical pixels added to each line.
Replaces |'linespace'|.

							*GuiDrop()*
GuiDrop(...) is a wrapper around |:drop| it escapes all given arguments
using |fnameescape()| and then passes them to :drop. This is useful if
the GUI is requesting Neovim to open additional files. A custom implementation
may be provided to override the default behavior, GuiDropCustom.
GuiDropCustomHandler should accept an arbitrary number of file paths as arguments.
Each argument should be processed, escaped, and passed to :drop.

							*GuiMousehide()*
GuiMousehide(enabled) enables mouse hiding while typing. If enabled is
1, as soon as the user types the mouse cursor is concealed. When the
user moves the mouse, the cursor becomes visible. Replaces |'mousehide'|.

							*GuiClose()*
GuiClose() notifies the GUI that it should close. The GUI may or may not
respect this request. The shim setups an autocommand to call this function
when the |'VimLeave'| event occurs.

							*GuiNewWindow(opts)*
|GuiNewWindow()| creates a new window with the given map of arguments.
Supported arguments are:

The following parameters desceibe the fields in {opts}.

Parameters: ~
	{server} (optional, string): Server to connect to for the new window.
	{nvim} (optional, string): Path to nvim instance.

							*GuiName()*
Returns the name of the GUI client. If multiple GUIs are connected the last
one is used. If no name is available an empty string is returned.
This can be used to check for a specific GUI in ginit.vim, e.g.
>
	if GuiName() == 'nvim-qt'
	  " ...
	endif

This is a wrapper around |nvim_get_chan_info()|.

							*GuiShowContextMenu()*
Displays a Cut-Copy-Paste context menu at the current cursor position. This
menu can be mapped to right click events in ginit.vim, e.g.
>
	nnoremap <silent><RightMouse> :call GuiShowContextMenu()<CR>
	inoremap <silent><RightMouse> <Esc>:call GuiShowContextMenu()<CR>
	vnoremap <silent><RightMouse> :call GuiShowContextMenu()<CR>gv

==============================================================================
4. Internals

This section is not very interesting unless you are implementing a GUI and
want to reuse this. Internally the plugin uses the |msgpack-rpc-api| to
broadcast notifications to attached GUIs, for example: >

	call rpcnotify(0, 'Gui', 'Foreground')

All notifications use the 'Gui' event name followed by a name and optionally
more parameters. Use the Neovim API (vim_subscribe) to subscribe to these
events. By convention all the functions listed in the previous section are
named as GuiEventName, and mapped as
 >
	call rpcnotify(0, 'Gui', 'EventName', ...)

The GUI is expected to load the user's |ginit.vim|, it should also make sure
this plugin is loaded before loading |ginit.vim|, for example setting
the runtimepath.


==============================================================================
 vim:tw=78:ts=8:ft=help:norl: