Emacs Completion-UI 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 1If you're an Elisp coder! 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 2Currently bundled with the package tarball, though this ought to be fixed someday. 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
Comments
Tony
Hello and thank you for the wonderful packages. Is there any plan to support Emacs 26?
Toby Cubitt
@Tony #1: I use all my Emacs packages myself in Emacs 26, and they seem to work OK. For the predictive and completion-UI packages you might need the version from Git, as I haven't rolled a release tarball in many years. (I've been doing some development recently that should finally let me get these last two packages on ELPA. Stay tuned…)
Poul Poulsen
Hello, i use your predictive package since some days. Now i've got it to work. But there are some open problems you could clear for me:
- Tab and M-Tab interfere with org-mode. Is it possible to rebind them? Which predictive functions are bind to them by default?
- How could i add all words from a buffer or file? I read about learning commands from buffer or add one word, but i can't find the fast commands. Any other way?
Regards Poul
Poul Poulsen
…i forgot to mention: i use Emacs 26.1 on linux mint 19.1. Regards Poul
Toby Cubitt
@Poul Poulson #3: You don't say whether you're using the git version of the predictive package (recommended!) or the last tarball release (very out of date!).
- In the git version, no keys at all are bound by
predictiveorcompletion-UIunless a completion is already in progress. So they shouldn't interfere with anything (I'm a heavyorg-modeuser myself). If you want M-tab to start predictive completion, bind it tocomplete-predictive. The normal and `fast' learning functions got merged in the git version. The only command you need for learning words from a buffer is
predictive-learn-from-buffer. The documentation in git hasn't been updated to match :-( The docstrings are a more reliable source of information than the manual for the git version.Note that
predictive-learn-from-bufferbehaves exactly like accepting each word in the buffer as a completion. This means ifpredictive-auto-add-to-dictis not set (the default), it will only update the weights of existing words in the dictionary, not add new ones. To have all words added, you need to setpredictive-auto-add-to-dictto t (at least temporarily).
Leave a comment
All comments are moderated. Clicking submit will open your email client and let you send your comment by email. By submitting your comment you agree to license the content under a Creative Commons Attribution-ShareAlike 4.0 International License.