A layout that can be used for filtering.
capi
:callback-object |
The argument for the callbacks. If it is nil the top-level-interface of the layout is used. |
:change-callback |
A function of one argument (the callback-object). |
:callback |
A function of one argument (the callback-object). |
:gesture-callbacks |
Additional gesture-callbacks to the text-input-pane inside the layout. |
:text |
A string specifying the initial text of the filter, or nil . |
:matches-title |
A string, t or nil . |
:help-string |
A string, t or nil . |
:added-filters | |
:label-style | :short , :medium or :long . |
filtering-layout-state
filtering-layout-matches-text
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:
Control+R
).Control+E
).Control+C
).
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*)) (:panes (my-things-list-panel capi:list-panel :reader my-interface-list-panel :items things :visible-min-height `(:character ,(length *things*))) (my-filtering capi:filtering-layout :change-callback 'update-my-interface :reader my-interface-filtering)) (:layouts (a-layout capi:column-layout '(my-filtering my-things-list-panel))) (:default-initargs :title "Filtering example") ) (defun update-my-interface (my-interface) (let* ((things (my-things my-interface)) (filtered-things (multiple-value-bind (regexp excludep) (capi:filtering-layout-match-object-and-exclude-p (my-interface-filtering my-interface) nil) (if regexp (loop for thing in things when (if (find-regexp-in-string regexp (string thing)) (not excludep) excludep) collect thing) things)))) (setf (capi:collection-items (my-interface-list-panel my-interface)) filtered-things)))
CAPI User Guide and Reference Manual (Unix version) - 01 Dec 2021 19:32:42