Function

Summary

Raises a non-focus window.

Signature

prompt-with-list-non-focus items &key owner x y 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-y alternative-x alternative-bottom alternative-right widget-name filtering-gesture filtering-toggle &allow-other-keys => interface

Arguments

owner

A displayed CAPI pane.

x , y

Integers.

alternative-x , alternative-y

Integers.

alternative-bottom , alternative-right

Integers or t .

choice-class

A subclass of list-panel.

selection

An integer.

selected-item

An item.

visible-items

A positive integer.

vertical-scroll

A boolean.

print-function

A function designator or nil .

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 ) .

filtering-gesture

A Gesture Spec.

filtering-toggle

A Gesture Spec.

widget-name

A string.

Values

interface

A non-focus-list-interface, or nil .

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 and y are required pixel coordinates with respect to owner of the top left corner of the non-focus window.

alternative-bottom , alternative-right , alternative-x and alternative-y specify alternative locations for use when positioning the window at x or y would cause it to be off the screen. If alternative-bottom or alternative-right are specified, they specify alternative bottom or alternative right. For example, both Editor completion and text-input-pane completion specify a y coordinate below the text, and alternative-bottom above the text.

alternative-bottom and alternative-right can also take the special value t , which denotes the height or width of the screen.

alternative-x and alternative-y can be used to specify alternative x and alternative y . alternative-bottom overrides alternative-y and alternative-right overrides alternative-x .

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 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 diplays only items that match the filter. 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 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