vimuiex.txt User Interface Extensions Last Change: August 2010
User Interface Extensions (Experiment)
Version 0.7
vimuiex
Description vimuiex-description
Default popup list operation vimuiex-operation
Plugins vimuiex-plugins
Python library usage vimuiex-pythonlib
Installation vimuiex-installation
Example configuration vimuiex-keymap
For Vim version 7.2 and above.
Requires python interface. A patch is required for GVim.
==============================================================================
DESCRIPTION vimuiex-description
Vimuiex is a library and a set of plugins for the Vim text editor. It adds a
popup listbox that is displayed in an overlapping window. The list can be
navigated with the usual Vim keys. When an item is selected from the list an
arbitrary action can be taken.
The core of the library is written in Python so it will only work if "+python"
feature is present in Vim at runtime.
==============================================================================
DEFAULT POPUP LIST OPERATION vimuiex-operation
A popup list has 4 basic modes of operation:
normal navigation vimuiex-navigation
item filtering vimuiex-filtering
quick-char selection vimuiex-quickchar
numeric selection vimuiex-numeric
vimuiex-navigation
The following commands are available when in normal operation:
j, <down>, <tab> next
k, <up>, <s-tab> previous
h, <left> shift left
l, <right> shift right
n, <space>, <pgdown> page down
b, <pgup> page up
0, gg, <home> top of list
$, G, <end> bottom of list
f, / enter filtering mode vimuiex-filtering
i, # enter numeric mode vimuiex-numeric
& enter quickchar mode vimuiex-quickchar
q, <Esc> close the list without selection
<CR> select the current item and execute a command
wh, wj, wk, wl move window to border
wc, wv, wC center window
m toggle item's marked state
F1 help - shows the currently mapped keys for all modes
vimuiex-filtering
In filtering mode new ASCII characters are added to the filter and only the
items that match the filter are displayed. First the items that start with the
filter string are displayed followed by the items that contain the filter
string elsewhere. In filtering mode the following keys can be used:
<Esc> clear the filter and exit filtering mode
<CR> exit filtering mode and keep the filter string
<BS> remove the last character from the filter string
<tab> exit filtering mode and move to next item
<s-tab> exit filtering mode and move to previous item
Multiple search terms can be entered in the filter, separated by ','. A term
that begins with '-' will succeed on items that don't contain the term. The
filter selects an item if all terms succeed for that item.
(TODO: new keys can be added to the popup list keymap)
vimuiex-numeric
When the listbox enters numeric-selection mode, numbers are displayed in front
of every item. When numbers are entered the currently selected item changes
according to the entered numbers. The keys "mjkluio" are "mapped" to numbers
"0123456" which is the position of the numeric keyboard on a notebook with an
english keyboard layuot.
vimuiex-quickchar
This mode is functional only when a quick-char (shortcut letter) is assiged to
every item in the list.
Items are selected with letters from the keyboard. Each item has a quick-char
that leads to it marked. If an item has a unique quick-char the item will be
selected when the appropriate key is pressed. Otherwise pressing the key will
cycle between the items and <CR> must be pressed to select the item.
==============================================================================
POPUP LIST CONFIGURATION vimuiex-config
Position of the listbox for each plugin:
>
<
where <plugin-id> is usually the command associated with the plugin.
The available options are:
size=x,y size of the popuplist; absolute or relative
x,y integer => absolute size
x,y float => relative size
minsize=x,y minimal size of the popuplist; absolute or relative
x,y same as above
position=F position of the popuplist
F=[ltrbvhc]* align to border (l/t/r/b) or center (v/h/c)
F=Nxy divide the screen in NxN cells and align to cell xy
where 1<=x,y<=N
autosize=F F=[vh]* autosize the box in direction (v/h) according to the
size of the list content
firstcolumn=b b=[01]; not yet
startupmode=F F=[/%#]; not yet
Example:
1. By default align all popup listboxes to bottom-left, let the size of each
popup box be 1/2 of the screen:
>
<
2. When using VxBufListSelect show the box in the upper middle position of
the screen, let min size be 8 lines and 1/2 of available width:
>
<
==============================================================================
PYTHON LIBRARY USAGE vimuiex-pythonlib
NOTE: From version 0.7 the function vimuiex#vxlist#VxPopup() is available
which allows the use of the popup listbox with pure vimscript. Some
documentation is in the code (vxlist.vim, example in vxcapture.vim).
Example: Display a list of buffers vimuiex-list-example
1. Prepare python so that it will load modules from ~/.vim/modpython:
>
<
It is best to add this call to every function that is exported from the script
and uses python modules installed in modpython. This way python won't be used
when it is not needed.
2. Prepare a list of buffers and store them to a global vim list variable:
>
<
3. Use python to load and display the list:
>
<
Create a CList object and load the items from the global variable into the
list. The strings from the list will be converted to unicode using the
encoding setting. The tabs in list items are used to separate the columns
of the list. To set the initial position of the window see
vimuiex-python-position.
>
<
Set the callback function that will be used when an item is selected
(cmdAccept). The function must be global. The placeholder "{{i}}" will be
converted to the index of the selected item. Another callback function can
be defined in case some action should be taken when selection from the list
is aborted (cmdCancel).
>
<
Process the list. The initially selected item can be set. This can be useful
if the buffer list is in MRU order. Setting curindex to 1 will select the
alternate buffer.
In the curses implementation process() will exit after the list processing
has finished. In the wx implementation it will exit immediately.
>
<
Remove the refeence to the List variable. This may free some memory used by
python. The List variable is defined globally and remains in memory between
calls to python. In wx implementation the memory will be freed only after
the window with the list is closed.
>
<
4. Define the callback function
>
<
See also code in: vxbuflist.vim, vxtextmenu.vim, vxrecentfile.vim
Initial position of the window vimuiex-python-position
------------------------------
TODO: Changed in version 0.6.
Example (.vimrc): >
<
Interpretation:
position=534 grid=5x5 cells, align to cell (col=3,row=4)
cell numbers start with 1
minsize=0.5,8 50% of width, 8 lines
Version 0.5:
When creating a CList or CTextMenu the size and position of the popup listbox
can be specified as construction parameters:
position: (x, y); if None, center the listbox
align: alignment string (eg. "TL", "BR", "T", ...); overrides position
size: (width, height); if None, half of screen size in each direction
autosize: autosize string (eg. "V", "H", "VH")
For example a menu constructed with:
>
<
will place the menu at the top-left corner of the vim screen and autosize the
menu in the vertical and horizontal direction.
==============================================================================
INSTALLATION vimuiex-installation
To install:
- Download the vimuiex.zip.
- Extract the zip archive into your runtime directory (eg. ~/.vim).
- Start Vim or goto an existing instance of Vim.
- Execute the following command:
>
<
This will generate all the help tags for any file located in the doc
directory.
To use the library in GVim a patch must be applied to Vim source. The patch is
available at:
http://sourceforge.net/projects/vimuiex/files/
Windows: Python must be installed (http://www.python.org). A patch must be
applied to Vim source. The patch and prebuilt binaries are available at:
http://sourceforge.net/projects/vimuiex/files/
Note: In versions 0.1 - 0.4 a wxpython implementation was also available. The
implementation was not updated and tested in versions 0.5-0.7.
==============================================================================
EXAMPLE CONFIGURATION vimuiex-keymap
Here is an example configuration that maps most of the commands from the
vimuiex package. The code can be copied to .vimrc.
call vxlib#plugin#Init()
" configure the positions of various popup windows
VxLet VxPopupListPos default "position=525"
VxLet VxPopupListPos VxBufListSelect "position=534 minsize=0.5,8"
VxLet VxPopupListPos VxOpenRecentFile "position=534 minsize=0.5,8"
VxLet VxPopupListPos VxTextMenu "position=524"
" VxOccur: use grep+xargs+find
let g:vxoccur_grep_mode = 2
nmap <silent> <F2> <Plug>VxFileBrowser
imap <silent> <F2> <Plug>VxFileBrowser
vmap <silent> <F2> <Plug>VxFileBrowser
nmap <silent> <s-F2> <Plug>VxFileFilter
imap <silent> <s-F2> <Plug>VxFileFilter
vmap <silent> <s-F2> <Plug>VxFileFilter
nmap <silent> <F3> <Plug>VxBufListSelect
imap <silent> <F3> <Plug>VxBufListSelect
vmap <silent> <F3> <Plug>VxBufListSelect
nmap <silent> <s-F3> <Plug>VxOpenRecentFile
imap <silent> <s-F3> <Plug>VxOpenRecentFile
vmap <silent> <s-F3> <Plug>VxOpenRecentFile
nmap <silent> <c-F5> <Plug>VxMapDefaultKeys
imap <silent> <c-F5> <Plug>VxMapDefaultKeys
vmap <silent> <c-F5> <Plug>VxMapDefaultKeys
nmap <silent> <F9> <Plug>VxTextMenu
imap <silent> <F9> <Plug>VxTextMenu
vmap <silent> <F9> <Plug>VxTextMenu
nmap <silent> gl <Plug>VxLineJump
vmap <silent> gl <Plug>VxLineJump
nmap <silent> gt <Plug>VxWindowJump
vmap <silent> gt <Plug>VxWindowJump
nmap <silent> [I <Plug>VxOccurCurrent
vmap <silent> [I <Plug>VxOccurCurrent
" The following keymaps conflict with netrw-gx, so we disable it
let g:netrw_nogx=1
nmap <silent> gxr <Plug>VxOccurRoutines
nmap <silent> gxt <Plug>VxOccurTags
nmap <silent> gxx <Plug>VxOccurRegex
nmap <silent> g/ <Plug>VxOccurRegex
nmap <silent> gxh <Plug>VxOccurSelectHist
nmap <silent> gxv <Plug>VxOccurHist
nmap <silent> gxn <Plug>VxCNext
nmap <silent> gxp <Plug>VxCPrev
## vim:tw=78:noet:wrap:ts=8:ft=help:norl:
