Raises a non-focus window.
capi
prompt-with-list-non-focus items &key owner x alternative-x right y alternative-y bottom choice-class vertical-scroll print-function selection selected-item visible-items selection-callback action-callback destroy-callback list-updater gesture-callbacks add-gesture-callbacks alternative-bottom alternative-right widget-name filtering-gesture filtering-toggle &allow-other-keys => interface
items⇩ |
A sequence. |
owner⇩ |
A displayed CAPI pane. |
Integers, or one of the keywords :left , :right , :center and :centre . | |
Integers, or one of the keywords :top , :bottom , :center and :centre . | |
choice-class⇩ |
A subclass of list-panel. |
vertical-scroll⇩ |
A boolean. |
print-function⇩ |
A function designator or nil . |
selection⇩ |
An integer. |
selected-item⇩ |
An item. |
visible-items⇩ |
A positive integer. |
selection-callback⇩ |
A function designator or nil . |
action-callback⇩ |
A function designator or nil . |
destroy-callback⇩ |
A function designator or nil . |
list-updater⇩ |
A function designator or nil . |
gesture-callbacks⇩ |
A list of pairs of the form (gesture . callback) . |
add-gesture-callbacks⇩ | |
A list of pairs of the form (gesture . callback) . | |
alternative-bottom⇩ |
An integer, or one of the keywords :top , :bottom , :center and :centre , or t . |
alternative-right⇩ |
An integer, or one of the keywords :left , :right , :center and :centre , or t . |
widget-name⇩ |
A string. |
filtering-gesture⇩ |
A Gesture Spec. |
filtering-toggle⇩ |
A Gesture Spec. |
interface |
A non-focus-list-interface, or nil . |
The function prompt-with-list-non-focus
raises a non-focus window, displaying the items items in a list of class choice-class, which should be list-panel or a subclass.
The non-focus window does not take the input focus, and hence does not see any keyboard input unless this is passed to it by non-focus-maybe-capture-gesture. It responds to mouse gestures.
Note that even moving the selection in the list vertically in response to the arrow keys cannot happen without non-focus-maybe-capture-gesture.
owner is required, and must be a CAPI pane visible on the screen. The position of the non-focus window is determined relative to owner, and the callbacks are invoked in the process of owner.
x, y, right, bottom, alternative-x, alternative-y, alternative-right, and alternative-bottom are used for positioning the window. x, alternative-right, alternative-x and right are the horizontal keywords, and one of them determines the horizontal position as described below. y, alternative-bottom, alternative-y and bottom are the vertical keywords, and one of them determines the vertical position. The values :center
and :centre
are synonyms here.
x and y specify the positioning of the left and top sides of the window, except for :center
/:centre
. An integer means offset in pixels from the left or top of owner. :left
, :right
, :top
and :bottom
mean the left/right/top/bottom of owner. :center
means the center of the owner, and in this case it specifies the location of the center of the window in the x or y dimension. x must be supplied, unless right is supplied. y must be supplied, unless bottom is supplied.
right and bottom override x and y respectively. They specify the positioning of the right or bottom of the window, except for :center
/:centre
, where they are interpreted in the same way as x and y.
alternative-x, alternative-y, alternative-right, and alternative-bottom are used if positioning the window using x or right and y or bottom would place it outside of the screen, and are interpreted the same way as the non-alternative keywords. For example, both Editor completion and text-input-pane completion specify a y coordinate below the text, and alternative-bottom above the text. The decision to use the alternative variables is made independently in the horizontal and vertical directions. alternative-right and alternative-bottom can both take the special value t
, meaning the height or width of the screen.
The default value of choice-class is list-panel.
selection or selected-item can be used to specify the initially selected item in the list. If neither of these initargs is supplied, the first item is selected.
visible-items specifies the height of the list panel when the filter is not visible. The default value of visible-items is 20.
vertical-scroll is supplied to cl:make-instance when making the list. The default value of vertical-scroll is t
.
print-function is also supplied to cl:make-instance when making the list. The default value of print-function is nil
.
selection-callback, if non-nil, should be a function of two arguments, the selected item and the non-focus interface. selection-callback is called (in the process of owner) when an item is selected in the list panel. Note that callback-type does not affect the arguments passed to selection-callback.
action-callback, if non-nil, should also be a function of two arguments, the selected item and the non-focus interface. action-callback is called (in the process of owner) when an item is double-clicked in the list panel, or when Return
is passed to non-focus-maybe-capture-gesture (by default, see gesture-callbacks). Note that callback-type does not affect the arguments passed to action-callback.
destroy-callback, if non-nil, should be a function of one argument, the non-focus window (a CAPI interface). destroy-callback is called when the non-focus window is destroyed. It is invoked in the process of owner.
list-updater, if non-nil, should be a function with signature:
list-updater => result
list-updater is called in the process of owner whenever non-focus-update is called. result must be a list of items to put into the list panel, or one of the special values t
(meaning no effect) and :destroy
(meaning destroy the non-focus window).
gesture-callbacks and add-gesture-callbacks define gesture callbacks which the non-focus window can "capture" (when non-focus-maybe-capture-gesture is called). gesture-callbacks and add-gesture-callbacks should both be a list of pairs of the form (gesture . callback)
. Each gesture must be a gesture specifier, that is an object that sys:coerce-to-gesture-spec can coerce to a sys:gesture-spec. Each callback is either a callable (symbol or function) which takes one argument, the non-focus window, or a list of the form (function . arguments)
. Note that when it is a list, the window is not automatically passed to the function function amongst the arguments arguments. The gesture callbacks are used only when non-focus-maybe-capture-gesture is called.
add-gesture-callbacks adds more gesture callbacks to those that are implicitly defined for controlling the list panel (see non-focus-maybe-capture-gesture). gesture-callbacks, if supplied, replaces the gesture callbacks that are implicitly defined for the list panel. In both cases, a gesture callback that is defined explicitly overrides any implicitly define gesture callback.
filtering-gesture defines whether it is possible for the user to add a filter to the non-focus window with a keyboard gesture, and defines that gesture. The gesture is actually a toggle: it destroys a filter that is on, and adds a filter when none is present. When the filter is added, its text is reset and it is always enabled, that is it captures characters and Backspace
. While the filter is visible, the list panel displays only items that match the filter (see 5.3.6 Filters). The default value of filtering-gesture is a Gesture Spec matching Control+Return
.
filtering-toggle defines whether it is possible for the user to disable/enable the filter with a keyboard gesture, and defines that gesture. When a filter is visible and enabled, the non-focus window captures characters and Backspace
(when non-focus-maybe-capture-gesture is called) and passes them to the filter. When the filter is visible and disabled, characters and Backspace
are captured. The default value of filtering-toggle is a Gesture Spec matching Control+Shift+Return
.
widget-name has an effect only on GTK+ and Motif. It defines the widget name of the interface, which can then be used to define resources specific to the non-focus window. Note that the non-focus completers in editor-pane and text-input-pane use the default widget-name which is "non-focus-list-prompter"
, so defining resources for non-focus-list-prompter will affect them.
If items is nil
, prompt-with-list-non-focus
returns nil
without doing anything. Otherwise, it raises the non-focus window and returns the interface, which is of class non-focus-list-interface.
The non-focus window is "passive", because it does not see keyboard input. It is the responsibility of the caller to pass any keyboard input that the non-focus window needs to process to the window, by using non-focus-maybe-capture-gesture. In general, that should be all keyboard gestures, and non-focus-maybe-capture-gesture decides which gestures it wants to process.
The caller can also use non-focus-terminate, non-focus-update, non-focus-list-toggle-filter, non-focus-list-add-filter, non-focus-list-remove-filter and non-focus-list-toggle-enable-filter to control the non-focus window.
list-panel
non-focus-terminate
non-focus-update
non-focus-list-toggle-filter
non-focus-list-toggle-enable-filter
non-focus-maybe-capture-gesture
10.6 In-place completion
CAPI User Guide and Reference Manual (Unix version) - 01 Dec 2021 19:32:42