filtering-layout Class

Summary

A layout that can be used for filtering.

Package

capi

Superclasses

row-layout

Initargs

Accessors

filtering-layout-state
filtering-layout-matches-text

Description

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 string is used as a regular expression or plain string (Control+R).
• The filter excludes matches or includes matches (Control+E).
• Filtering is case-sensitive or case-insensitive (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:

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.

Notes

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

Examples

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

See also

filtering-layout-match-object-and-exclude-p