#lang scribble/manual
@(require scribble/eval
          (for-label racket/base framework/notify racket/contract
                     racket/class))

@(define the-eval (make-base-eval))
@(the-eval '(require racket/class (prefix-in notify: framework/private/notify)))

@title[#:tag "gui-notify"]{Notify-boxes}

@defmodule[framework/notify]

@defclass[notify:notify-box% object% ()]{

A notify-box contains a mutable cell. The notify-box notifies its
listeners when the contents of the cell is changed.

@examples[#:eval the-eval
(define nb (new notify:notify-box% (value 'apple)))
(send nb get)
(send nb set 'orange)
(send nb listen (lambda (v) (printf "New value: ~s\n" v)))
(send nb set 'potato)
]

@defconstructor[([value any/c])]{
  Creates a notify-box initially containing @racket[value].
}
@defmethod[(get) any/c]{
  Gets the value currently stored in the notify-box.
}
@defmethod[(set [v any/c]) void?]{
  Updates the value stored in the notify-box and notifies the listeners.
}
@defmethod[(listen [listener (-> any/c any)]) void?]{
  Adds a callback to be invoked on the new value when the notify-box's
  contents change.
}
@defmethod[(remove-listener [listener (-> any/c any)]) void?]{
  Removes a previously-added callback.
}
@defmethod[(remove-all-listeners) void?]{
  Removes all previously registered callbacks.
}

@history[#:added "1.18"]{}
}

@defproc[(notify:notify-box/pref
          [proc (case-> (-> any/c) (-> any/c void?))]
          [#:readonly? readonly? boolean? #f])
         (is-a?/c notify:notify-box%)]{

Creates a notify-box with an initial value of @racket[(proc)]. Unless
@racket[readonly?] is true, @racket[proc] is invoked on the new value
when the notify-box is updated.

Useful for tying a notify-box to a preference or parameter. Of course,
changes made directly to the underlying parameter or state are not
reflected in the notify-box.

@examples[#:eval the-eval
(define animal (make-parameter 'ant))
(define nb (notify:notify-box/pref animal))
(send nb listen (lambda (v) (printf "New value: ~s\n" v)))
(send nb set 'bee)
(animal 'cow)
(send nb get)
(send nb set 'deer)
(animal)
]

@history[#:added "1.18"]{}
}

@defform[(notify:define-notify name value-expr)
         #:contracts ([value-expr (is-a?/c notify:notify-box%)])]{

Class-body form. Declares @racket[name] as a field and
@racketidfont{get-@racket[name]}, @racketidfont{set-@racket[name]},
and @racketidfont{listen-@racket[name]} as methods that delegate to
the @method[notify:notify-box% get], @method[notify:notify-box% set], and
@method[notify:notify-box% listen] methods of @racket[value].

The @racket[value-expr] argument must evaluate to a notify-box, not
just the initial contents for a notify box.

Useful for aggregating many notify-boxes together into one
``configuration'' object.

@examples[#:eval the-eval
(define config%
  (class object%
    (notify:define-notify food (new notify:notify-box% (value 'apple)))
    (notify:define-notify animal (new notify:notify-box% (value 'ant)))
    (super-new)))
(define c (new config%))
(send c listen-food
        (lambda (v) (when (eq? v 'honey) (send c set-animal 'bear))))
(let ([food (get-field food c)])
  (send food set 'honey))
(send c get-animal)
]

@history[#:added "1.18"]{}
}

@defproc[(notify:menu-option/notify-box
          [parent (or/c (is-a?/c menu%) (is-a?/c popup-menu%))]
          [label label-string?]
          [notify-box (is-a?/c notify:notify-box%)])
         (is-a?/c checkable-menu-item%)]{

Creates a @racket[checkable-menu-item%] tied to @racket[notify-box]. The menu item is
checked whenever @racket[(send notify-box get)] is true. Clicking the
menu item toggles the value of @racket[notify-box] and invokes its listeners.

@history[#:added "1.18"]{}
}

@defproc[(notify:check-box/notify-box
          [parent (or/c (is-a?/c frame%) (is-a?/c dialog%)
                        (is-a?/c panel%) (is-a?/c pane%))]
          [label label-string?]
          [notify-box (is-a?/c notify:notify-box%)])
         (is-a?/c check-box%)]{

Creates a @racket[check-box%] tied to @racket[notify-box]. The
check-box is checked whenever @racket[(send notify-box get)] is
true. Clicking the check box toggles the value of @racket[notify-box]
and invokes its listeners.

@history[#:added "1.18"]{}
}

@defproc[(notify:choice/notify-box
          [parent (or/c (is-a?/c frame%) (is-a?/c dialog%)
                        (is-a?/c panel%) (is-a?/c pane%))]
          [label label-string?]
          [choices (listof label-string?)]
          [notify-box (is-a?/c notify:notify-box%)])
         (is-a?/c choice%)]{

Creates a @racket[choice%] tied to @racket[notify-box]. The choice
control has the value @racket[(send notify-box get)] selected, and
selecting a different choice updates @racket[notify-box] and invokes
its listeners.

If the value of @racket[notify-box] is not in @racket[choices], either
initially or upon an update, an error is raised.

@history[#:added "1.18"]{}
}

@defproc[(notify:menu-group/notify-box
          [parent (or/c (is-a?/c menu%) (is-a?/c popup-menu%))]
          [labels (listof label-string?)]
          [notify-box (is-a?/c notify:notify-box%)])
         (listof (is-a?/c checkable-menu-item%))]{

Returns a list of @racket[checkable-menu-item%] controls tied to
@racket[notify-box]. A menu item is checked when its label is
@racket[(send notify-box get)]. Clicking a menu item updates
@racket[notify-box] to its label and invokes @racket[notify-box]'s
listeners.

@history[#:added "1.18"]{}
}


@close-eval[the-eval]
