prompt-with-list-non-focus Function

Summary

Raises a non-focus window.

Package

capi

Signature

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

Arguments

Values

Description

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.

See also

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