Next: , Up: Completing Words


4.1 Overview

Predictive mode is extremely flexible, and how you interact with it depends heavily on how you customize it. Broadly, there are two and a half ways to use predictive mode: it can either do nothing until you ask it to complete a word, or it can automatically search for the most likely completions as you type. (You may have seen something similar to the latter on certain models of mobile phone, though predictive mode is far more powerful.) This behaviour is controlled by enabling or disabling auto-completion-mode (see Auto-Completion Mode). It is enabled for you automatically if the predictive-auto-complete customization option is enabled (the default).

The half-a-way to use predictive mode is to set predictive-auto-correction-no-completion. In that case, predictive mode doesn't complete words at all, it only auto-corrects words you typed. For this to be useful, you also have to customize a number of options appropriately. See Miscellaneous Options.

Even if you are using auto-completion-mode, you can (by default) continue to type normally. Possible completion candidates will be displayed, ranked in order of likelihood, but will not be accepted unless you do so explicitly using completion-accept, bound to C-RET. (All the key bindings described here are the defaults, and can of course be customized to anything you desire, see Keymaps and Key Bindings) However, since it learns as you type, predictive mode can become very good at predicting the word you want, and it can become tedious to have to hit C-RET all the time. In that case, you can customize auto-completion-syntax-alist so that typing a punctuation or white-space character automatically accepts the current completion, before inserting the character. This lets you skip typing the rest of the characters in a word as soon as predictive mode has found the completion you want. However, the down side is that you have to slightly change the way you type, and it can take a little while until your fingers “get used to it”. If you need to reject a completion candidate, you can do so using C-DEL or C-SPC (DEL is usually the backspace key). If you aren't using auto-completion-mode, you will need to call the complete-predictive command whenever you want to complete the word at or next to the point. This is bound to M-TAB, M-SHIFT-TAB, M-/ and M-?. There are then two “styles” of behaviour: completions can either be ephemeral, acting purely as a visual indicator, and disappearing unless you explicitly accept them using completion-accept, bound to C-RET. (You may be used to this style of behaviour from word processing software such as OpenOffice Writer). Alternatively, completions can be permanent, so that completing a word really does insert those characters into the buffer unless you explicitly reject it using completion-reject, bound to C-DEL. (This is the more traditional Emacs-style behaviour, that you may be used to from using dabbrevs, for example.) The choice is yours, and is controlled by the completion-accept-or-reject-by-default customization option (see Miscellaneous Options). (Note that these two different “styles” of behaviour are mainly relevant when Dynamic Completion is enabled, as it is by default. This is described below.) Whether you are using auto-completion-mode or not, there are various ways to display and select completions. All of them can be enabled or disabled indepentently, and many of them can be extensively customized.

Perhaps the simplest is to display the most likely completion in the buffer (see Dynamic Completion). You can then cycle through the other completion candidates using the completion-cycle command. M-TAB and M-/ cycle forwards, whereas M-SHIFT-TAB and M-? cycle backwards. (These are the same key bindings used to manually complete the word at the point. Hitting them for the first time will bring up the possible completions, hitting them again will cycle.)

You can also insert a completion candidate directly, without having to cycle through them until you get to the one you want, by using a completion hot-key (see Completion Hotkeys). By default, the hot-keys are the number keys 09, which insert the first through to the tenth candidate, respectively.

Of course, you won't know which completion candidate you want unless you can see which candidates are available! The completion candidates can be displayed in the echo area, and/or in a tooltip below the point (see Displaying Completions in the Echo Area, and see Completion Tooltip). When completion hot-keys are enabled, both of these also indicate which completion candidate corresponds to which hot-key. If you only want the hotkeys to be enabled when the tooltip or pop-up frame (see below) are displayed, then set completion-use-hotkeys to pop-up.

The completion tooltip is more than just a visual reminder of which completions are available. When it is displayed, you can select a completion from the list using the up and down arrow keys. When completing a word, you can display the tooltip at any time using completion-show-tooltip, bound to S-down. See Completion Tooltip.

A slightly more powerful alternative to the completion tooltip is a pop-up frame, displayed using completion-popup-frame, bound to C-down (see Pop-Up Frame). This lists the completion candidates in a separate Emacs frame positioned below the point, and you can use the usual Emacs motion keys to move through the list and select a candidate. However, you can also toggle between displaying just the most likely completion candidates and displaying all possible completions, using completion-popup-frame-toggle-all, bound to M-Tab and M-/. You can still type and delete characters when the pop-up frame is displayed; it will be updated to reflect the new set of completion candidates. To get rid of a pop-up frame, use completion-popup-frame-dismiss, bound to C-up and M-up. (Note that the pop-up frame key bindings are only active when the pop-up frame has the focus. If you manually switch the focus back to the original frame, you can still type normally and the pop-up frame will be updated appropriately, but the completion-popup-frame-toggle-all and completion-popup-frame-dismiss bindings will not work.)

The completion menu is the most flexible way of selecting completions, and can be displayed using completion-show-menu, bound to M-down. Again, it displays the completion candidates and lets you select them, and, like the pop-up frame, it also allows you to see all possible completions, rather than just displaying the most likely ones, by selecting the ‘Browser’ item from the menu. The completion browser doesn't just display all possible completions in a big list. Instead, it organises them hierarchically, making it easier to browse through them until you find the one you want.

The completion tooltip, pop-up frame, and menu all display a list of completion candidates, but each has its own advantages and disadvantages. The tooltip is visually and functionally least intrusive, but also gives you fewer ways to find the completion you want. The pop-up frame is encumbered by your window manager's frame decoration and positioning policy (though some window managers allow you to disable this for specific windows – called frames in Emacs). But it can display large numbers of completion candidates far more effectively than a tooltip. The completion menu and completion browser make finding the desired completion much easier, especially when you're not sure precisely what it is you're looking for. But menus steal the keyboard focus in Emacs, so you can no longer type in the buffer until you dismiss the menu.

You can select one of these three (tooltip, pop-up frame or menu) to be displayed automatically when you complete a word, by setting the completion-auto-show customization option. You can optionally leave a short delay before it is displayed, by setting completion-auto-show-delay1.


Footnotes

[1] Although you can choose to display the completion menu automatically, because it steals the keyboard focus this probably isn't all that useful, at least not without a long delay.