'In-place completion' allows the user to select from a list of possible completions displayed in a special non-modal window which appears in front of an input pane (such as an editor-pane or a text-input-pane) but does not grab the input focus.
To raise this special window and select a completion from it, the user invokes certain keyboard gestures including Up, Down and Return. The full set of keys for operations on an in-place completion window are described In-place completion user interface. The user can also continue typing her input in which case the list of possible completions is updated to reflect the text in the input pane.
This section describes the user interface of in-place completion.
In-place completion is available in the LispWorks IDE, in the Editor tool and also in tools that ask for a named object such as the Class Browser and the Generic Function Browser. Set the Preferences... Environment > General > Use in-place completion option to use in-place completion in the LispWorks IDE, and see LispWorks IDE User Guide for further details.
In-place completion is also available to you to use in your CAPI applications. You may wish to adapt the remainder of this section for your end-user documentation. See Programmatic control of in-place completion for information on how to implement it.
In a text-input-pane that supports in-place completion, any of the gestures Up, Down, PageUp, and PageDown invokes the in-place completion unless it is already displayed.
In an editor-pane, completion commands invoke in-place completion by default, though you can make them use dialogs instead by setting editor:*use-in-place-completion* to nil.
There are several Editor commands that invoke in-place completion unconditionally:
Abbreviated in-place Complete Symbol
Completes the symbol before the point, taking the string as abbreviation.
Completes the symbol before the point
Echo Area: Complete the input in the echo area. For file input, does file completion.
Expand the file name at the current point.
In-Place Expand File Name with space
Expand the file name at the current point, allowing spaces.
See the LispWorks Editor User Guide for information on binding these commands to keyboard gestures. See call-editor for information on calling them from CAPI.
Keyboard input while the in-place window is displayed goes to the input pane, but some of the input gestures are redirected to the in-place window. By default, the following gestures are redirected:
Change the selection in the list of completions in the obvious way.
Perform the completion using the current selected item in the list. In non-file-completion, or in file-completion when the item is not a directory, the in-place window disappears. In file-completion when the selected item is a directory, the in-place window changes to display the list of files in the completed directory.
Causes the in-place window to disappear, without doing anything else. Note that if the text in the input pane was edited while the in-place window was displayed, these edits are not undone.
Toggles redirection of characters to the filter. A filter is a text-input-pane which filters the list of completions based on its contents. While the filter is on, the list of completions shows only the completions that match the filter.
While the filter is visible and enabled, all character input plus Backspace are redirected to the filter. The filter can be disabled by Control+Shift+Return, which means it still filters, but characters go to the the input pane.
The functionality of the in-place completion filter is the same as the standard filter for list-panel. For a full description of the pattern matching see "Regular expression searching" in the LispWorks Editor User Guide .
Control+Shift+R, Control+Shift+E, Control+Shift+C
Change the setting in the filter.
Other keyboard input goes to the input pane.
While the filter is off (the default), or when the filter is on and disabled, plain characters go to the input pane, and hence change the text in it.
When the filter is on and is enabled, plain characters go to the filter.
In a text-input-pane, performing a completion means replacing part of the text in the pane by the selected completion. In a file-completion, only the last part of the text (from the last directory separator) is replaced.
If a text-input-pane was made with complete-do-action true, once the completion was performed, if it is not file-completion and the completion is a directory, the callback of the pane is invoked.
In an editor-pane, while the in-place window is displayed, the editor highlights the part of the text that will be replaced. In non-file-completion it is the beginning of the "symbol", as seen by the editor, and the end of the "symbol". In a file-completion it is the part of the filename after the last directory separator.
Performing the completion in an editor-pane means replacing the highlighted text by the selected completion. The replacement is done as a single separate operation (for example Undo will undo the replacement separately from any previous changes).
Any operation that affects the text between the start of the relevant text (this is the start in a text-input-pane, and the highlighted area in an editor-pane) and the current cursor causes the in-place window to recompute the possible completions and display the new list. These operations include not only actual changes to the text, but also cursor movement.
In an editor-pane, if the insertion point moves out of the highlighted area then the in-place window goes away.
If the input pane loses the focus, the in-place window goes away, except on Motif.
You can add in-place completion to your application as described in this section.
A text-input-pane will do in-place completion if you pass either of these initargs:
:file-completion with value t or a pathname designator, or
:in-place-completion-function with value a suitable function designator
You can add a filter to the in-place window by passing the initarg :in-place-filter. Additionally you can control the functionality for file completion by passing :directories-only and :ignore-file-suffices. The keyword arguments :complete-do-action and :gesture-callbacks also interact with in-place completion.
The in-place completion can be invoked explicitly for a text-input-pane by calling text-input-pane-in-place-complete.
See the manual page for text-input-pane for details.
An editor-pane does in-place completion when your code calls the function editor:complete-in-place.
You can also implement in-place completion on arbitrary CAPI panes by calling prompt-with-list-non-focus.
CAPI User Guide and Reference Manual (Unix version) - 25 Feb 2015