All Manuals > CAPI User Guide and Reference Manual > 21 CAPI Reference Entries

filtering-layout Class


A layout that can be used for filtering.





The argument for the callbacks. If it is nil the top-level-interface of the layout is used.
A function of one argument (the callback-object).
A function of one argument (the callback-object).
Additional gesture-callbacks to the text-input-pane inside the layout.
A string specifying the initial text of the filter, or nil.
A string, t or nil.
A string, t or nil.
A list of additional filter specifications.
:short, :medium or :long.



The class filtering-layout can be used to display a filter pane for some other pane, such as a list-panel.

The main part of a filtering layout is a text-input-pane which allows the user to enter a string, which is intended to be used for filtering. The user can control how it is used by a menu (or special keystroke) that allows her to specify whether:

The filtering layout defines the parameters to use, and calls the callbacks to perform the filtering. It does not do any filtering itself.

change-callback is called whenever the text in the filter changes. Also if callback is not supplied, then change-callback is called instead.

callback is called whenever there is any change in the state of the filter: the user presses Return, makes a selection from the menu, clicks the Confirm button or changes the selection in any of the added filters. If callback is not supplied, then change-callback is called instead.

To actually do the filtering, the using code needs to call filtering-layout-match-object-and-exclude-p, which returns as multiple values a precompiled regexp and a flag specifying whether to exclude matches. The regexp should be used to perform the filtering, typically by using lispworks:find-regexp-in-string. Note that filtering-layout-match-object-and-exclude-p returns nil when there is no string in the text-input-pane, and that even when the filter is set to plain match it returns a regexp (which matches a plain string).

You supply a filtering-layout amongst the panes of your interface definition (not its layouts). The description of a filtering-layout is set by the initialize-instance method of the class, and therefore the description cannot be passed as an initarg and should not be manipulated.

filtering-layout-state returns a "state" object which can be used later to set the state of any filtering-layout by (setf capi:filtering-layout-state). When setting the state, the value can also be a string or nil. A string means setting the filter string to it and making the filtering state be plain string, includes matches, and case-insensitive. nil means the same as the empty string.

matches-title controls whether the filtering-layout contains a display-pane (the "matches pane") showing the number of matches. If matches-title is a string, it provides the title of the matches pane. If matches-title is t the title is Matches:. Note that the actual text in the matches pane must be set by the caller by (setf capi:filtering-layout-matches-text).

If help-string is non-nil then the filter has a Help button which raises a default help text if help-string is t, or the text of help-string if it is a string.

If label-style is :short the filter menu has a short title. For example if the filter is set for case-sensitive plain inclusive matching the short label is PMC. If label-style is :medium then this label would be Filter:C. Any other value of label-style would make a long label Plain Match Cased.

When added-filters is non-nil, it adds panes (check-button or option-pane) to the filtering-layout. Each element of added-filters must be one of:

A cons of a string and some object.

This specifies a check-button, with the string as its text, plus an associated object.

A list of conses, where each cons is a cons of a string and some object.

This specifies an option-pane, where the string of each cons specifies the text of an item in the option-pane, plus an associated object for the item.

The check-button and option-pane panes are displayed in the same row as the filter.

The third return value of filtering-layout-match-object-and-exclude-p contains the associated objects from each selected check-button (but not from any unselected check-button) and from the selected item of each option-pane.


A filtering-layout is used when a list-panel is made with the :filter initarg.

(defvar *things* (list "Foo" "Bar" "Baz" 'car 'cdr))
(capi:define-interface my-interface ()
  ((things :reader my-things
           :initform *things*))
    :reader my-interface-list-panel
    :items things
    :visible-min-height `(:character ,(length *things*)))
    :change-callback 'update-my-interface
    :reader my-interface-filtering))
    '(my-filtering my-things-list-panel)))
  (:default-initargs :title "Filtering example")
(defun update-my-interface (my-interface)
  (let* ((things (my-things my-interface))
          (multiple-value-bind (regexp excludep)
               (my-interface-filtering my-interface)
            (if regexp
                (loop for thing in things
                      when (if (find-regexp-in-string
                                (string thing))
                               (not excludep)
                      collect thing)
    (setf (capi:collection-items
           (my-interface-list-panel my-interface))
See also


CAPI User Guide and Reference Manual (Macintosh version) - 01 Dec 2021 19:31:27