Class

Summary

A layout that can be used for filtering.

Package

capi

Superclasses

row-layout

Initargs

: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 ). It is called whenever the text in the filter changes. Also if callback is not supplied, change-callback is called instead.

:callback

A function of one argument (the callback-object ). It is called when the user presses Return, makes a selection from the menu, or clicks the Confirm button. If callback is not supplied, change-callback is called instead.

:gesture-callbacks

Additional gesture-callbacks to the text-input-pane inside the filtering-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.

:label-style

:short, :medium or :long.

Accessors

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

Description

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.

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 .

Notes

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

Example

(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