UIAttach, UIDetach

doc: ginit.vim, gvimrc
fix #3656

5 files changed, 19 insertions, 63 deletions

diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index 0fab2bd24f..4e55122916 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -280,7 +280,7 @@ Name			triggered by ~
 
 	Startup and exit
 |VimEnter|		after doing all the startup stuff
-|UIAttach|		after a new UI attaches
+|UIAttach|		after a UI attaches
 |UIDetach|		after a UI detaches
 |TermResponse|		after the terminal response to t_RV is received
 |QuitPre|		when using `:quit`, before deciding whether to exit
@@ -805,13 +805,16 @@ FuncUndefined			When a user function is used but it isn't
 				NOTE: When writing Vim scripts a better
 				alternative is to use an autoloaded function.
 				See |autoload-functions|.
-							{Nvim} *UIAttach*
-UIAttach			After a new UI connects to nvim and successfully
-				calls |nvim_ui_attach|. Sets chan in |v:event| with
-				the channel id or 0 if using the internal UI.
-							{Nvim} *UIDetach*
-UIDetach			After a UI detaches from nvim. Sets chan in |v:event|
-				with the channel id or 0 if using the internal UI.
+							*UIAttach*
+UIAttach			After a UI connects via |nvim_ui_attach()|,
+				after VimEnter.  Can be used for GUI-specific
+				configuration.
+				Sets these |v:event| keys:
+				    chan
+							*UIDetach*
+UIDetach			After a UI detaches from Nvim.
+				Sets these |v:event| keys:
+				    chan
 							*InsertChange*
 InsertChange			When typing <Insert> while in Insert or
 				Replace mode.  The |v:insertmode| variable
diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index c26ddf8fe8..77d687cf0f 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -28,7 +28,7 @@ Environment Variables ~
 Events ~
 *EncodingChanged*	Never fired; 'encoding' is always "utf-8".
 *FileEncoding*		Never fired; equivalent to |EncodingChanged|.
-*GUIEnter*		Never fired; Use |UIAttach| instead.
+*GUIEnter*		Never fired; use |UIAttach| instead.
 *GUIFailed*		Never fired.
 
 Keycodes ~
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index ec0a28abe8..c38edb5f92 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1567,6 +1567,7 @@ v:event		Dictionary of event data for the current |autocommand|.  Valid
 			abort		Whether the event triggered during
 					an aborting condition (e.g. |c_Esc| or
 					|c_CTRL-C| for |CmdlineLeave|).
+			chan		|channel-id| or 0 for "internal".
 			cmdlevel	Level of cmdline.
 			cmdtype		Type of cmdline, |cmdline-char|.
 			cwd		Current working directory.
diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt
index f8c7693d45..bba38b7607 100644
--- a/runtime/doc/gui.txt
+++ b/runtime/doc/gui.txt
@@ -4,7 +4,7 @@
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
 
 
-Vim's Graphical User Interface				*gui* *GUI*
+Nvim Graphical User Interface				*gui* *GUI*
 
                                       Type |gO| to see the table of contents.
 
@@ -12,30 +12,11 @@ Vim's Graphical User Interface				*gui* *GUI*
 Starting the GUI				*gui-start* *E229* *E233*
 
 				*ginit.vim* *gui-init* *gvimrc* *$MYGVIMRC*
-The gvimrc file is where GUI-specific startup commands should be placed.  It
-is always sourced after the |init.vim| file.  If you have one then the 
-$MYGVIMRC environment variable has its name.
-
-When the GUI starts up initializations are carried out, in this order:
-- If the system menu file exists, it is sourced.  The name of this file is
-  normally "$VIMRUNTIME/menu.vim".  You can check this with ":version".  Also
-  see |$VIMRUNTIME|.  To skip loading the system menu include 'M' in
-  'guioptions'.				*buffers-menu* *no_buffers_menu*
-  The system menu file includes a "Buffers" menu.  If you don't want this, set
-  the "no_buffers_menu" variable in your init.vim (not ginit.vim!): >
-	:let no_buffers_menu = 1
-< NOTE: Switching on syntax highlighting also loads the menu file, thus
-  disabling the Buffers menu must be done before ":syntax on".
-  The path names are truncated to 35 characters.  You can truncate them at a
-  different length, for example 50, like this: >
-	:let bmenu_max_pathlen = 50
-
-All this happens AFTER the normal Vim initializations, like reading your
-vimrc file.  See |initialization|.
-But the GUI window is only opened after all the initializations have been
-carried out.  If you want some commands to be executed just after opening the
-GUI window, use the |GUIEnter| autocommand event.  Example: >
-	:autocmd GUIEnter * winpos 100 50
+For GUI-specific configuration Nvim provides the |UIAttach| event.  This
+happens after other |initialization|s, like reading your vimrc file.
+
+Example: this sets "g:gui" to the value of the UI's "rgb" field:    >
+	:autocmd UIAttach * let g:gui = filter(nvim_list_uis(),{k,v-> v.chan==v:event.chan})[0].rgb
 <
 
 						*:winp* *:winpos* *E188*
diff --git a/runtime/doc/usr_31.txt b/runtime/doc/usr_31.txt
index fb9a4fd223..74de3f1042 100644
--- a/runtime/doc/usr_31.txt
+++ b/runtime/doc/usr_31.txt
@@ -236,35 +236,6 @@ using the terminal for something else.  The "-f" argument is used here to run
 the GUI in the foreground.  You can also use ":gui -f".
 
 
-THE GVIM STARTUP FILE
-
-When gvim starts, it reads the gvimrc file.  That's similar to the vimrc file
-used when starting Vim.  The gvimrc file can be used for settings and commands
-that are only to be used when the GUI is going to be started.  For example,
-you can set the 'lines' option to set a different window size: >
-
-	:set lines=55
-
-You don't want to do this in a terminal, since its size is fixed (except for
-an xterm that supports resizing).
-   The gvimrc file is searched for in the same locations as the vimrc file.
-Normally its name is "~/.config/nvim/ginit.vim".
-The $MYGVIMRC environment variable is set to it, thus you can use this command
-to edit the file, if you have one: >
-
-	:edit $MYGVIMRC
-<
-   If for some reason you don't want to use the normal gvimrc file, you can
-specify another one with the "-U" argument: >
-
-	gvim -U thisrc ...
-
-That allows starting gvim for different kinds of editing.  You could set
-another font size, for example.
-   To completely skip reading a gvimrc file: >
-
-	gvim -U NONE ...
-
 ==============================================================================
 
 Next chapter: |usr_32.txt|  The undo tree