Emacs: Completion User Interface package

The Completion User Interface package is a library that implements user-interfaces for in-buffer completion.

Typically, in packages providing some kind of text completion, a large amount of code deals with providing the user interface rather than finding good completions. The goal of Completion-UI is to be the swiss-army knife of in-buffer completion user-interfaces; a library which any completion package can use to provide an in-buffer completion user-interface, thereby freeing completion package writers to concentrate on the task of finding the completions in the first place.

In fact, Completion-UI is even better than a swiss-army knife, because it's also extensible: it's easy1 to add new completion user-interfaces and hook them into Completion-UI. The new interface will then be available to any completion package that uses the Completion-UI library, without needing to make any changes to that package.

Various standard completion user-interfaces and commands are provided "out of the box". These can be separately enabled, disabled and tweaked by the Emacs user via the usual bewildering array of customization variables. The UIs provided with the package are:

Dynamic completion
Provisionally inserts the best completion candidate in the buffer, highlighting the completed portion.
Completion hotkeys
Single-key selection of a completion.
Cycling
Cycle through completion candidates.
Tab-completion
"Traditional" expansion to longest common substring.
Echo area
Display a list of completion candidates in the echo-area.
Tooltip
Display a list of completion candidates in a tool-tip located below the point.
Pop-up tip
Display a list of completion candidates in a pseudo tool-tip located below the point, using the <code>popup.el</code> library.2 Displays faster and looks better than real tooltips.
Pop-up frame
Allow completion candidates to be selected from a pop-up frame displayed below the point.
Completion menu
Allow completion candidates to be selected from a drop-down menu located below the point.
Completion browser
Allow completion candidates to be selected from a hierarchically organised stack-of-cards menu structure.
auto-completion-mode
Automatically complete words as you type. Behaviour can be customized very extensively through Customization variables and Lisp code.

The philosophy of Completion-UI is that customization of the user-interface should be left up to users. They know what they want better than you (the package author) do! And by providing a universal user-interface that can be used by all completion packages, Completion-UI lets users customize their in-buffer completion user interface once-and-for-all to suit their tastes, rather than having to learn how to customize the UI for each completion package separately.

The default Completion-UI key bindings that are enabled when you're completing a word are:

M-<tab> M-/
Cycle through completions.
M-S-<tab> =M-?
Cycle backwards through completions.
C-<ret>
Accept the current completion.
C-<del>
Reject the current completion.
<tab>
Traditional tab-completion, i.e. insert longest common substring.
C-<tab>
Accept current completion and re-complete the resulting word.
S-<down>
Display the completion tooltip (then use <up> and <down> to cycle).
M-<down>
Display the completion menu.
C-<down>
Display the completion pop-up frame.
S-<up> C-<up> M-<up> (in pop-up frame)
Dismiss the completion pop-up frame.
M-/ (in pop-up frame)
Toggle displaying all completions.

Download and Installation

The current release of the Completion-UI package is version 0.12 (released February 2013). However, it's still under active development at the moment, so don't forget to check back here for updates every so often. If you want to live on the bleeding edge, the latest "development" version of the Completion-UI package is hosted in the same git repository as the Predictive Completion package.

  • Git repository: http://www.dr-qubit.org/git/predictive.git
  • Current version (0.12)

Note that the git repository URL is a git repository, not a web-site. You cannot view it in a web browser. To grab the latest development version, clone the repository using something like:

git clone http://www.dr-qubit.org/git/predictive.git

To install, simply extract the files to a directory in your Emacs load-path, and add the line:

(require 'completion-ui)

to your .emacs file.

Documentation

If you're an Emacs user interested in using Completion-UI (as opposed to an Elisp programmer interesting in extending Completion-UI or making use of it in your own package), then the first section of the Completion-UI manual would contain all the information you could possibly need…were it to exist. In the meantime, the description given above should get you started, and all the commands and customization options are reasonably well documented via the standard, built-in, Emacs documentation features. All the relevant customization options can be found in the completion-ui customization group (and subgroups thereof).

If you're interested in extending Completion-UI with a new user-interface or new completion source, or want to make use of Completion-UI in your own package, then full documentation will…ahem…shortly be available in a variety of formats, for download and viewing online. In the meantime, the docstrings for completion-ui-register-interface and completion-ui-register-source should get you started.

Completion-UI Manual

men_at_work.png

1
If you're an Elisp coder!
2
Currently bundled with the package tarball, though this ought to be fixed someday.

Leave a comment

All comments are moderated. By submitting your comment you agree to license the content under a Creative Commons Attribution-ShareAlike 4.0 International License.




Creative Commons License