211 lines
9.4 KiB
Plaintext
211 lines
9.4 KiB
Plaintext
*qnamepicker.txt* QuickNamePicker: A quick list selector library
|
|
|
|
Author: Matt Spear <batman900 at gmail DOT com>
|
|
QNamePicker version 0.07
|
|
|
|
==============================================================================
|
|
1. Overview~
|
|
*qnamepicker-overview*
|
|
|
|
After using qnamebuf for a while I realized it would be useful to have a
|
|
generic selector interface and to allow modules to build off this. In this
|
|
manner qnamebuf becomes an extension (and I introduced qnamefile). The big
|
|
driver for this was the Project plugin (vimscript #69) which I felt very much
|
|
needed a lusty picker for the file to open.
|
|
|
|
==============================================================================
|
|
2. Installation ~
|
|
*qnamepicker-installation*
|
|
|
|
Extract the downloaded file in your personal |vimfiles| directory (~/.vim
|
|
under Unix or %HOMEPATH%\vimfiles under Windows). Restart Vim and execute:
|
|
>
|
|
helptags ~/.vim/doc
|
|
<
|
|
==============================================================================
|
|
2. Usage ~
|
|
*qnamepicker-usage*
|
|
|
|
This exposes one function for the user:
|
|
>
|
|
QNamePickerStart(list, dict)
|
|
<
|
|
|a:list| is the |List| of items to have the user choose from.
|
|
|a:dict| has the optional keys:
|
|
|acceptors| The set of additional keys to accept on.
|
|
By default has [<Enter>, <M-1>, ..., <M-0>].
|
|
e.g. "acceptors": ["\<M-D>", "\<C-T>", "\<M-L>"].
|
|
|cancelors| The set of keys to close the qnamepicker.
|
|
By default has <Esc>.
|
|
e.g. "cancelors": ["\<C-G>", "\<C-C>"]
|
|
|modifiers| The set of keys to call the modifier_func when pressed.
|
|
By default is empty.
|
|
e.g. "modifiers": ["\<M-L>"]
|
|
|modifier_func| The callback function to modify the list that is
|
|
displayed. The callback is expected to return the new list to
|
|
display. Called as:
|
|
modifier_func(|index|, |modifier_key|)
|
|
where
|
|
|a:index| is the index in |a:list| that is selected, if there is
|
|
no selected item then it will be -1 (this will happen if there are
|
|
no items in the filtered list).
|
|
|modifier_key| is the key that was pressed.
|
|
|render_func| The function to call to render each item. The callback is
|
|
expected to return a string that represents what to show for each item
|
|
in the filtered |a:list|. Called as:
|
|
render_func(|index|, |rel_index|, |length|, |in_column_mode|)
|
|
where
|
|
|a:index| is the index in |a:list| of the item to render.
|
|
|a:rel_index| is the relative index in the filtered list (so that
|
|
one can show the shortcut counts for the <M-1>... keys).
|
|
|a:length| is the number of items in the filtered list (so that
|
|
one can show more information if there are few enough items).
|
|
|a:in_column_mode| is true if there are more items than the size
|
|
of the window.
|
|
|complete_func| The function to call when an item is selected by one of
|
|
the |acceptors|. Called as:
|
|
complete_func(|index|, |acceptor_key|)
|
|
where
|
|
|a:index| is the index in |a:index| of the selected item.
|
|
|a:acceptor_key| is the acceptor key that was pressed.
|
|
|regexp| If true then treats the user input as a regular expression. If
|
|
false or not present, then will use a lusty-style selector.
|
|
|height| The height of the window. If set to 0 or not present, will
|
|
default to one-half of |&lines|.
|
|
|use_leader| If true then any word characters ([a-zA-Z0-9]) in acceptors
|
|
or cancelors or modifiers will be accessable via <Leader><CHAR>. When
|
|
false then any word characters are treated as user input (including
|
|
<Leader>).
|
|
|
|
The default controls are:
|
|
<BS> Delete last char entered
|
|
<C-U> Delete all entered chars
|
|
<ESC> Close the explorer
|
|
<CR> Choose the currently selected file
|
|
<UP> <DOWN> <LEFT> <RIGHT> Navigate the selection
|
|
<HOME> <END> Move to the first/last item
|
|
<M-1>, ..., <M-0> Open the first, ..., tenth file in the list
|
|
|
|
Note, I wanted these to be <C-...> but <C-1>...<C-0> are not real key sequences.
|
|
|
|
Once a function has been written to use |QNamePickerInit| (say |MyQNameWrapper|), then one should add
|
|
a mapping to call the wrapper via:
|
|
>
|
|
nmap <unique> <KEY> :call MyQNameWrapper()<cr>:~
|
|
<
|
|
|
|
==============================================================================
|
|
3. Customization ~
|
|
*qnamepicker-customization*
|
|
Every other line can be colored by highlighting |QNamePickerAlt|, e.g.
|
|
>
|
|
hi QNamePickerAlt gui=NONE guibg=#222222
|
|
<
|
|
|
|
==============================================================================
|
|
4. Example ~
|
|
*qnamepicker-example*
|
|
Included in this are two fairly comprehensive examples:
|
|
|qnamebuf| which shows how I used this core to interact with the set of
|
|
vim buffers. This is very comprehensive and uses pretty much every
|
|
feature of |qnamepicker|.
|
|
|qnamefile| which shows the recursive set of files from a given path, and
|
|
restricting to a set of extensions. This is a much simpler example,
|
|
only requiring a |complete_func| and custom |acceptors|/|cancelors| list.
|
|
|
|
These (and the hint example below) should be sufficient to make use of the
|
|
plugin.
|
|
|
|
==============================================================================
|
|
5. Hints ~
|
|
*qnamepicker-hints*
|
|
|
|
To plug this into the Project (vimscript #69) plugin one would add something
|
|
like:
|
|
>
|
|
function! LustyProjectFilePicker()
|
|
let s:sid = substitute(maparg('<Return>', 'n'), '.*\(<SNR>.\{-}\)_.*', '\1', '')
|
|
" As there may not have been a file opened in the project, if a CD is
|
|
" specified, then we should cd to it before showing the list so that
|
|
" the :. works as expected...all of this is to get to that
|
|
let cd_cmd = b:proj_cd_cmd
|
|
let infoline = {s:sid}_RecursivelyConstructDirectives(line('.'))
|
|
let home = {s:sid}_GetHome(infoline, '') . '/'
|
|
let c_d = {s:sid}_GetCd(infoline, home)
|
|
let abs = {s:sid}_IsAbsolutePath(home)
|
|
if c_d != '' && abs != 2
|
|
if match(g:proj_flags, '\CL') != -1
|
|
call {s:sid}_SetupAutoCommand(c_d)
|
|
endif
|
|
if !isdirectory(glob(c_d))
|
|
call confirm("From this fold's entry,\nCD=".'"'.c_d.'" is not a valid directory.', "&OK", 1)
|
|
else
|
|
silent exec cd_cmd.' '.c_d
|
|
endif
|
|
endif
|
|
let ofnames=split(Project_GetAllFnames(1, line("."), ",,"), ',,')
|
|
let g:cmd_arr = map(ofnames, "fnamemodify(v:val, ':.')")
|
|
call QNamePickerStart(g:cmd_arr, {
|
|
\ "complete_func": function("LustyProjectFileCompletion"),
|
|
\ "acceptors": ["v", "s", "t", "\<M-V>", "\<M-S>", "\<M-T>"],
|
|
\ "use_leader": 1,
|
|
\})
|
|
endfunction
|
|
|
|
function! LustyProjectFileCompletion(index, key)
|
|
let infoline = {s:sid}_RecursivelyConstructDirectives(line('.'))
|
|
if a:key == "\<M-V>" || a:key == "v"
|
|
call {s:sid}_OpenEntry2(line('.'), infoline, fnamemodify(g:cmd_arr[a:index], ':p'), 'vert sp')
|
|
elseif a:key == "\<M-S>" || a:key == "s"
|
|
call {s:sid}_OpenEntry2(line('.'), infoline, fnamemodify(g:cmd_arr[a:index], ':p'), 'sp')
|
|
elseif a:key == "\<M-T>" || a:key == "t"
|
|
call {s:sid}_OpenEntry2(line('.'), infoline, fnamemodify(g:cmd_arr[a:index], ':p'), 'tabe')
|
|
else
|
|
call {s:sid}_OpenEntry2(line('.'), infoline, fnamemodify(g:cmd_arr[a:index], ':p'), 'e')
|
|
endif
|
|
endfunction
|
|
|
|
nmap <buffer> <unique> <LocalLeader>a :call LustyProjectFilePicker()<cr>:~
|
|
<
|
|
to the .vimproject_mappings file.
|
|
|
|
With this <M-V> will open the selected file in a vert split window, <M-S> will
|
|
open it in a split window, <M-T> will open it in a new tab, and <CR> will open
|
|
it in the last accessed window (this is accomplished by cheating and calling
|
|
the |QNameFileCompletion| which is publically exposed from the |qnamefile|
|
|
plugin).
|
|
|
|
==============================================================================
|
|
7. History~
|
|
*qnamepicker-history*
|
|
Version 0.07
|
|
- Initial release
|
|
|
|
==============================================================================
|
|
8. Thanks~
|
|
*qnamepicker-thanks*
|
|
|
|
- Vim Devs for vim
|
|
- Stefano for finding that <M-X> doesn't work with the menu shown and an
|
|
initial documentation
|
|
- Peter for a patch for fixing |@y| being overwritten and pointing out the cmap
|
|
noisiness
|
|
- pal nart For the amazing qname and qbuf which were the inspiration and basis
|
|
for this
|
|
|
|
==============================================================================
|
|
9. Contact ~
|
|
*qnamepicker-contact*
|
|
|
|
If you have questions, bug reports, suggestions, etc. the author can be
|
|
contacted at batman900 AT gmail DOT com. The latest version is available at
|
|
http://www.vim.org/scripts/script.php?script_id=3217. If you like the script
|
|
please vote for it on www.vim.org.
|
|
|
|
==============================================================================
|
|
License ~
|
|
|
|
This software is licensed under the MIT license.
|
|
|
|
vim:tw=78:fo=tcq2:isk=!-~,^*,^\|,^\":ts=8:ft=help:norl:
|