{"size": 5081, "ext": "scrbl", "max_stars_repo_path": "scribblings/search-list-box.scrbl", "max_stars_repo_name": "spdegabrielle/search-list-box", "max_stars_repo_stars_event_min_datetime": "2021-11-18T02:47:52.000Z", "max_stars_repo_stars_event_max_datetime": "2021-11-18T02:47:52.000Z", "max_issues_repo_path": "scribblings/search-list-box.scrbl", "max_issues_repo_name": "spdegabrielle/search-list-box", "max_issues_repo_issues_event_min_datetime": "2020-07-29T17:25:47.000Z", "max_issues_repo_issues_event_max_datetime": "2022-01-10T13:26:27.000Z", "max_forks_repo_path": "scribblings/search-list-box.scrbl", "max_forks_repo_name": "spdegabrielle/search-list-box", "max_forks_repo_forks_event_min_datetime": "2021-11-17T22:15:19.000Z", "max_forks_repo_forks_event_max_datetime": "2021-11-17T22:15:19.000Z"}
{"max_stars_count": 1, "max_issues_count": 7, "max_forks_count": 1, "avg_line_length": 38.2030075188, "max_line_length": 100, "alphanum_fraction": 0.6012595946}
#lang scribble/manual
@(require (for-label search-list-box
                     racket/gui)
          scribble/extract
          racket/runtime-path
          racket/file
          pict)

@(define-runtime-path search-list-box.png "../img/search-list-box.png")
@(define-runtime-path minimal.rkt "../examples/minimal.rkt")

@title{Search-list-box}
@author{Laurent Orseau}

@defmodule[search-list-box]


A @racket[list-box%] with a search @racket[text-field%]. See some examples
@hyperlink["https://github.com/Metaxal/search-list-box/tree/master/examples"]{here}.

@(centered (bitmap search-list-box.png))

Features:
@itemlist[
 @item{The search function can be customized.}
 @item{Can navigate between the text-field and the list-box with arrow keys.}
 @item{In the text field, press enter to validate; in the list-box press space.}
 @item{Pressing Escape in the list-box returns to the text-field.}
 @item{The filter function can be customized.}]

@defclass[search-list-box-frame% frame% ()]{
 @defconstructor[([message (or/c label-string? #f) #f]
                  [width (or/c dimension-integer? #f) 400]
                  [height (or/c dimension-integer? #f) 400]
                  [contents list? '()]
                  [filter (-> string? label-string? any/c) default-filter]
                  [key (-> any/c string?) ~a]
                  [callback
                   (-> (or/c number? #f)
                       (or/c label-string? #f)
                       any/c
                       any)
                   (λ (idx label content) (void))]
                  [close-on-escape? boolean? #t]
                  [show? boolean? #t])]{
Creates a simple frame that contains a single @racket[search-list-box%].
See @racket[search-list-box%] and @racket[frame%] for a description of the arguments;
All the initialization arguments of @racket[frame%] are also available.
The argument @racketid[message] is the label for the @racket[text-field%], whereas
the argument @racketid[label] is the label for the @racket[frame%].

Minimal example:
@(apply typeset-code (list (file->string minimal.rkt)))
}

@defmethod[(get-search-list-box) (is-a?/c search-list-box%)]{
Returns the @racket[search-list-box%] contained in the frame.}

@defmethod[(set-status [str label-string?]) void?]{
Sets the status message to @racketid[str].}
}

@defclass[search-list-box% vertical-panel% ()]{

 @defconstructor[([label (or/c label-string? #f) #f]
                  [text-field-mixin
                   (-> (subclass?/c text-field%)
                       (subclass?/c text-field%))
                   (λ (x) x)]
                  [list-box-mixin
                   (-> (subclass?/c list-box%)
                       (subclass?/c list-box%))
                   (λ (x) x)]
                  [filter
                   (-> string? label-string? any/c)
                   default-filter]
                  [key
                   (-> any/c string?)
                   ~a]
                  [callback
                   (-> (or/c number? #f)
                       (or/c label-string? #f)
                       any/c
                       any)
                   (λ (idx label content) (void))]
                  [close-on-escape
                   (or/c #f
                         (is-a?/c frame%)
                         (is-a?/c dialog%))
                   #f])]{
The @racket[search-list-box%] constructor also accepts all optional arguments
  of @racket[vertical-panel%].

The @racketid[key] argument builds a label string from a element of @racketid[contents].
By default is just displays the elements of @racketid[contents] as a string.

The @racketid[callback] takes the currently selected index in the list-box (or the first one if
none is selected), the corresponding displayed label-string and the corresponding content element in
@racketid[contents].

The @racketid[filter] argument allows the user to replace the default filter.

If a @racket[frame%] or @racket[dialog%] is passed to @racketid[close-on-escape],
then upon pressing @racketid[escape] in the text-field the frame or dialog is closed.
}

 @defmethod[(get-list-box) (is-a?/c list-box%)]{
 Returns the internal @racket[list-box%].}
 @defmethod[(get-text-field) (is-a?/c text-field%)]{
 Returns the internal @racket[text-field%].}
 @defmethod[(set-text [str string?]) void?]{
 Sets the text in the @racket[text-field%] to @racketid[str].}
 @defmethod[(set-contents [conts list?]) void?]{
 Replaces the current contents of the list box with @racketid[conts].
 The @racketid[key] and @racketid[filter] are not changed.}
}

@defproc[(default-filter [str string?] [lbl label-string?]) any/c]{
 Equivalent to
 @racketblock[
 (string-contains?
  (string-downcase str)
  (string-downcase lbl))]}

@defproc[(word-filter [str string?] [lbl label-string?]) any/c]{
 Splits @racket[str] into words (space separated), and matches @racket[lbl]
against all words in no order, with both strings downcased.}

@defproc[(regexp-filter [str string?] [lbl label-string?]) any/c]{
 Matches @racket[(string-downcase lbl)] to @racket[(pregexp str)].}


