Add key mappings to close completion menu

README.md

@@ -2313,6 +2313,19 @@ Default: `['<S-TAB>', '<Up>']`
 let g:ycm_key_list_previous_completion = ['<S-TAB>', '<Up>']
 ```
 
+### The `g:ycm_key_list_stop_completion` option
+
+This option controls the key mappings used to close the completion menu. This is
+useful when the menu is blocking the view, when you need to insert the `<TAB>`
+character, or when you want to expand a snippet from [UltiSnips][] and navigate
+through it.
+
+Default: `['<C-y>']`
+
+```viml
+let g:ycm_key_list_stop_completion = ['<C-y>']
+```
+
 ### The `g:ycm_key_invoke_completion` option
 
 This option controls the key mapping used to invoke the completion menu for

autoload/youcompleteme.vim

@@ -22,6 +22,7 @@ set cpo&vim
 " This needs to be called outside of a function
 let s:script_folder_path = escape( expand( '<sfile>:p:h' ), '\' )
 let s:force_semantic = 0
+let s:completion_stopped = 0
 let s:default_completion = {
       \   'start_column': -1,
       \   'candidates': []
@@ -215,13 +216,19 @@ function! s:SetUpKeyMappings()
           \ ' pumvisible() ? "\<C-n>" : "\' . key .'"'
   endfor
 
-
   for key in g:ycm_key_list_previous_completion
     " This selects the previous candidate for shift-tab (default)
     exe 'inoremap <expr>' . key .
           \ ' pumvisible() ? "\<C-p>" : "\' . key .'"'
   endfor
 
+  for key in g:ycm_key_list_stop_completion
+    " When selecting a candidate and closing the completion menu with the <C-y>
+    " key, the menu will automatically be reopened because of the TextChangedI
+    " event. We define a command to prevent that.
+    exe 'inoremap <expr>' . key . ' <SID>StopCompletion( "\' . key . '" )'
+  endfor
+
   if !empty( g:ycm_key_invoke_completion )
     let invoke_key = g:ycm_key_invoke_completion
 
@@ -538,6 +545,16 @@ function! s:OnDeleteChar( key )
 endfunction
 
 
+function! s:StopCompletion( key )
+  call timer_stop( s:pollers.completion.id )
+  if pumvisible()
+    let s:completion_stopped = 1
+    return "\<C-y>"
+  endif
+  return a:key
+endfunction
+
+
 function! s:OnCursorMovedNormalMode()
   if !s:AllowedToCompleteInCurrentBuffer()
     return
@@ -561,6 +578,12 @@ function! s:OnTextChangedInsertMode()
     return
   endif
 
+  if s:completion_stopped
+    let s:completion_stopped = 0
+    let s:completion = s:default_completion
+    return
+  endif
+
   call s:IdentifierFinishedOperations()
 
   " We have to make sure we correctly leave semantic mode even when the user

doc/youcompleteme.txt

@@ -115,18 +115,19 @@ Contents ~
   32. The |g:ycm_max_diagnostics_to_display| option
   33. The |g:ycm_key_list_select_completion| option
   34. The |g:ycm_key_list_previous_completion| option
-  35. The |g:ycm_key_invoke_completion| option
-  36. The |g:ycm_key_detailed_diagnostics| option
-  37. The |g:ycm_global_ycm_extra_conf| option
-  38. The |g:ycm_confirm_extra_conf| option
-  39. The |g:ycm_extra_conf_globlist| option
-  40. The |g:ycm_filepath_completion_use_working_dir| option
-  41. The |g:ycm_semantic_triggers| option
-  42. The |g:ycm_cache_omnifunc| option
-  43. The |g:ycm_use_ultisnips_completer| option
-  44. The |g:ycm_goto_buffer_command| option
-  45. The |g:ycm_disable_for_files_larger_than_kb| option
-  46. The |g:ycm_python_binary_path| option
+  35. The |g:ycm_key_list_stop_completion| option
+  36. The |g:ycm_key_invoke_completion| option
+  37. The |g:ycm_key_detailed_diagnostics| option
+  38. The |g:ycm_global_ycm_extra_conf| option
+  39. The |g:ycm_confirm_extra_conf| option
+  40. The |g:ycm_extra_conf_globlist| option
+  41. The |g:ycm_filepath_completion_use_working_dir| option
+  42. The |g:ycm_semantic_triggers| option
+  43. The |g:ycm_cache_omnifunc| option
+  44. The |g:ycm_use_ultisnips_completer| option
+  45. The |g:ycm_goto_buffer_command| option
+  46. The |g:ycm_disable_for_files_larger_than_kb| option
+  47. The |g:ycm_python_binary_path| option
  11. FAQ                                                    |youcompleteme-faq|
   1. I used to be able to 'import vim' in '.ycm_extra_conf.py', but now can't |youcompleteme-i-used-to-be-able-to-import-vim-in-.ycm_extra_conf.py-but-now-cant|
   2. I get 'ImportError' exceptions that mention 'PyInit_ycm_core' or 'initycm_core' |youcompleteme-i-get-importerror-exceptions-that-mention-pyinit_ycm_core-or-initycm_core|
@@ -2565,6 +2566,18 @@ Default: "['<S-TAB>', '<Up>']"
   let g:ycm_key_list_previous_completion = ['<S-TAB>', '<Up>']
 <
 -------------------------------------------------------------------------------
+The *g:ycm_key_list_stop_completion* option
+
+This option controls the key mappings used to close the completion menu. This
+is useful when the menu is blocking the view, when you need to insert the
+'<TAB>' character, or when you want to expand a snippet from UltiSnips [21] and
+navigate through it.
+
+Default: "['<C-y>']"
+>
+  let g:ycm_key_list_stop_completion = ['<C-y>']
+<
+-------------------------------------------------------------------------------
 The *g:ycm_key_invoke_completion* option
 
 This option controls the key mapping used to invoke the completion menu for

plugin/youcompleteme.vim

@@ -82,6 +82,9 @@ let g:ycm_key_list_select_completion =
 let g:ycm_key_list_previous_completion =
       \ get( g:, 'ycm_key_list_previous_completion', ['<S-TAB>', '<Up>'] )
 
+let g:ycm_key_list_stop_completion =
+      \ get( g:, 'ycm_key_list_stop_completion', ['<C-y>'] )
+
 let g:ycm_key_invoke_completion =
       \ get( g:, 'ycm_key_invoke_completion', '<C-Space>' )