vim-popped

---

This plugin provides four commands that use Vim’s builtin popup window functionality. Vim’s popup-intro provides examples of when you may want to use popup windows, so that is not explained here. The Screenshots and Mappings illustrate how to use the commands, and ways they may be useful.

Compatibility: vim-popped is built primarily for Vim 9.^[1] It will not work with Neovim because Neovim has none of Vim’s popup functions — refer Neovim’s help (builtin.txt).

---

• 1. Screenshots
• 2. Mappings
• 3. Borderchars
• 4. Installation
• 5. Licence

1. Screenshots

Four commands are enabled, which are associated with user-defined functions. Command line abbreviations are also provided, which, like the functions, are structured as initialisms of the command names.

Command	Function	Abbreviation
CpDialogCommand	Fpdc()	Cpdc
CpDialogCommandTimer	Fpdct()	Cpdct
CpDialogTitleCommand	Fpdtc()	Cpdtc
CpMenuBuffers	Fpmb()	Cpmb

The commands are illustrated and annotated in the following screenshots.

 

 

 

2. Mappings

<Leader>b and <Leader><S-b>

Unless the user already has it mapped, <Leader><S-b> is mapped, in Normal mode only, to :CpMenuBuffers buffers!, demonstrated immediately above.

Similarly, <Leader>b, unless the user already has it mapped, is mapped, in Normal mode only, to :CpMenuBuffers buffers. (The only difference is <Leader>b will not show unlisted buffers, which in some instances is preferable.)

gA

The second mapping is gA. This provides an extension to the builtin command, ga (aka :ascii). By default, that command provides information about the character (and combining character(s), when applicable) under the cursor, i.e., the Unicode code point(s) in decimal, hexadecimal, and octal. The gA mapping expands on that to provide lots of additional information in a popup dialog window:

UTF8	The UTF8 hex values of the bytes used in the character(s) (Equivalent to the g8 command)
hi	Highlight group (only when applicable, otherwise blank)
word	The word under the cursor
WORD	The WORD under the cursor
file	The current filename. (This is blank if there’s no file and is equivalent to :echo expand('%:t'))
cwd	The current working directory. (Equivalent to :echo getcwd())

Illustrating this in action:

💡

If you use Tim Pope’s vim-characterize plugin, ga will display the HTML5 named character references, emoji, Unicode name, and all digraphs, when applicable. For example, ga on the character 😀, U+1F600, will display, in the cmdline statusmsg area: <😀> 128512, U+1F600 GRINNING FACE, :grinning: Another example: a̅ (an 'a' with a combining macron, U+0061,U+0305) will display: <a> 97, \141, U+0061 LATIN SMALL LETTER A + < ̅> 773, U+0305 COMBINING OVERLINE

3. Borderchars

Popups may have several options set (refer popup_setoptions()). One of those options is borderchars, which is a list with characters that are used for displaying the border around a popup. The example in Vim’s help is:

['-', '|', '-', '|', '┌', '┐', '┘', '└']

Those characters have the benefit of being ones that display satisfactorily with most fonts: hyphen (U+002D), vertical line (U+007C), and box drawing characters (U+250C, U+2510, U+2518, and U+2514).

A downside to using those default characters is that they do not join together well. They may end up looking like this, depending on factors such as your operating system, font, etc.:

  ┌---------------------┐
  | Default borderchars |
  └---------------------┘

To address this, and to provide optionality, this plugin uses the variable g:borderchars. It enables the user to determine, in their ~/.vimrc, their own border characters for the popups created by this plugin. If g:borderchars has not been set, the following default list is used (chosen because it is unobtrusive and should work with any font). It uses an em dash (i.e., U+2014) for the bottom border and bottom corners, and a space for everything else:

[' ', ' ', '—', ' ', ' ', ' ', '—', '—']

If you want no borders on the popup windows, add this to your ~/.vimrc:

let g:borderchars = [' ']

4. Installation

❗

Vim before 8.2.3434 / Neovim: vim-popped neither works with Vim versions before 8.2 patch 3434 nor any version of Neovim. That is because: Vim versions before 8.2 patch 3434 lack patches that are required to render popup windows produced by vim-popped. Neovim does not have any of Vim’s builtin popup window commands.

There are three installation methods outlined here. Linux is presumed, so .vimrc (not _vimrc), etc.^[2]

Method 1. Using packadd! in your .vimrc

This is a contemporary way to install plugins. It uses Vim’s native packadd! functionality.

Either
git clone https://github.com/kennypete/vim-popped ~/.vim/pack/plugins/opt/vim-popped
Or
Download the .zip from https://github.com/kennypete/vim-popped and unzip the contents within the folder vim-popped-main to ~/.vim/pack/plugins/opt/vim-popped

In your ~/.vimrc, add the line, packadd! vim-popped. (If you want to turn vim-popped off, delete or comment out that line.)

Method 2. Vim’s packages method, automatically

Similar to the steps above, except substitute start for opt. This is a less versatile method because to turn the plugin off you need to move it out of the start directory. So, it is easier in a way, though neither as transparent nor as flexible.

Method 3. Using a plugin manager

For example, vim-plug (NB: using “shorthand notation”).

In the vim-plug section of your .vimrc, add Plug 'kennypete/vim-popped' between call plug#begin() and call plug#end(). Reload your .vimrc and then :PlugInstall.

5. Licence

BSD 3-Clause License. Copyright © 2023 Peter Kenny

---

 

---

1. This plugin has been built with both vim9script and vimscript functions. The main script, in vim-popped/plugins/vim-popped.vim, uses vim9-mix capability, determining the script version based on v:version and has(), testing for 8.2 and patch >=4057. If 8.2 and patch <4057, but >=3434, vimscript functions/commands are used.

2. If your operating system is Windows, instead of ~/.vim/ use $HOME\vimfiles\ or ~/vimfiles/ (PowerShell), or %USERPROFILE%\vimfiles\ (cmd.exe).