Find file
Fetching contributors…
Cannot retrieve contributors at this time
130 lines (110 sloc) 7.3 KB
This is a mirror of
Forms is a Vim TUI (Text User Interface) library. It allows for the creation
and display of text-based forms in both console Vim and GVim. Many of the
standard GUI widget types are supported by Forms such as labels, buttons,
menus and layout constructs. It supports navigation, selection and input with
a keyboard, as well as, navigation and selection with a mouse.
Screen-shot (background: dark/light) of clone of GVim menu/popup:
Some example (background: dark/light) forms from the "Examples" form:
Code for the above examples can be found at:
Forms tutorial:
A user can always stop a form with no side effects by entering <Esc>.
This is basically a "panic button"; the user wants out.
If the user is a couple of sub-forms deep in a presentation, each <Esc>
entered pops the user out of the current form only.
Developers should be aware that a user might not take any of the actions
offered by a form and simply enter <Esc>. Such user action, <Esc>
to exit Forms, should NOT be prevented by a forms developer.
The behavior of a form created with the Forms library differs from that of a
GUI form. Generally, a GUI form can be displayed and moved about anywhere on
the screen. On the other hand, a TUI form has to reside within the Vim/GVim
window; it can not be moved outside of the text area. In addition, when a form
is being displayed, it captures all user input, keyboard and mouse in that
window, so that there is no access to the underlying text until the form is
closed. In that sense, all Forms forms are like modal GUI forms.
Because a form must fit within a text window, it is sometimes the case that
the form's height and/or width is greater than that of the hosting window.
Form developer should be aware of this and strive to make their forms
smaller than expected window sizes. One approach is to break a large form
into a number of sub-forms.
In case a form is too big, an information form is displayed to the user
stating that fact along with a suggested size to enlarge the window to
so that the form will fit. If the window is too small even to display
the information form, an error message is output (via a thrown exception).
A form can be displayed over the current text or the form can create a new tab
and displayed there.
Strictly speaking, the Forms library is a library and, so, there ought not
be any mappings. But, while developing Forms a number of examples were
created which, it turns out, were critical for uncovering bugs, missing
features in the implementation and usage issues. Two of the examples
might have general appeal, the menu and popup forms that mirror the
capability (and copy some of the support code of) the GVim menu and popup.
While power users will disdain the Forms menu and popup examples
as superfluous, covering Vim commands that are know by heart, so to
power users disdain the GVim menu/popup - so, the power user is not
the target user. Rather, the same users that find the GVim menu/popup
useful will find the Forms menu/popup equally useful.
Here are the mappings for the menu and popup:
nmap <Leader>m :call forms#menu#MakeMenu('n')<CR>
vmap <Leader>m :call forms#menu#MakeMenu('v')<CR>
nmap <Leader>p :call forms#menu#MakePopUp('n')<CR>
vmap <Leader>p :call forms#menu#MakePopUp('v')<CR>
It should be noted that there are normal and visual mode mappings.
That is because some capabilities of the menu/popup are enabled/disabled
depending upon mode, as well as, which command to ultimately execute
may depend upon mode.
There is also a mapping which launches a form that links to some 40 Forms
demonstration forms. The demonstration forms range from a simple box
drawing example to a file browser and color chooser:
nmap <Leader>d :call forms#example#demo#Make()<CR>
If any of the demonstration forms do not display or function as one might
expect on your platform, then drop me a line - thanks.
One will observe that these mappings use the characters: 'm' 'p' and 'd'.
While the demo mapping can/should ultimately be commented out by
all but Forms developers, at least for the non-power user, having
a short, easy to remember, mnemonic mapping for menu and popup is certainly
Source can be found at:
The Forms library is currently being used in the following scripts:
Colorschemer utility
Vimside, Vim Scala IDE