Get a single character from the user or input stream. If [expr] is omitted, wait until a character is available. If [expr] is 0, only get a character when one is available. Return zero otherwise. If [expr] is 1, only check if a character is available, it is not consumed. Return zero if no character available. If you prefer always getting a string use getcharstr().

Without [expr] and when [expr] is 0 a whole character or special key is returned. If it is a single character, the result is a Number. Use nr2char() to convert it to a String. Otherwise a String is returned with the encoded character. For a special key it's a String with a sequence of bytes starting with 0x80 (decimal: 128). This is the same value as the String "\<Key>", e.g., "\<Left>". The returned value is also a String when a modifier (shift, control, alt) was used that is not included in the character.

When [expr] is 0 and Esc is typed, there will be a short delay while Vim waits to see if this is the start of an escape sequence.

When [expr] is 1 only the first byte is returned. For a one-byte character it is the character itself as a number. Use nr2char() to convert it to a String.

Use getcharmod() to obtain any additional modifiers.

When the user clicks a mouse button, the mouse event will be returned. The position can then be found in v:mouse_col, v:mouse_lnum, v:mouse_winid and v:mouse_win. getmousepos() can also be used. Mouse move events will be ignored. This example positions the mouse as it would normally happen:

let c = getchar()
if c == "\<LeftMouse>" && v:mouse_win > 0
  exe v:mouse_win .. "wincmd w"
  exe v:mouse_lnum
  exe "normal " .. v:mouse_col .. "|"
endif

When using bracketed paste only the first character is returned, the rest of the pasted text is dropped. xterm-bracketed-paste.

There is no prompt, you will somehow have to make clear to the user that a character has to be typed. The screen is not redrawn, e.g. when resizing the window. When using a popup window it should work better with a popup-filter.

There is no mapping for the character. Key codes are replaced, thus when the user presses the <Del> key you get the code for the <Del> key, not the raw character sequence. Examples:

getchar() == "\<Del>"
getchar() == "\<S-Left>"

This example redefines "f" to ignore case:

:nmap f :call FindChar()<CR>
:function FindChar()
:  let c = nr2char(getchar())
:  while col('.') < col('$') - 1
:    normal l
:    if getline('.')[col('.') - 1] ==? c
:      break
:    endif
:  endwhile
:endfunction

You may also receive synthetic characters, such as <CursorHold>. Often you will want to ignore this and get another character:

:function GetKey()
:  let c = getchar()
:  while c == "\<CursorHold>"
:    let c = getchar()
:  endwhile
:  return c
:endfunction