#lang scribble/doc
@(require scribble/manual
          scribble/eval
          (for-label "calm-evt.ss"))


@title{calm-evt: event wrapper that calms an event's delivery.}

@defmodule[(planet "calm-evt.ss" ("dyoo" "calm-evt.plt" 1 0))]

@scheme[calm-evt] wraps around events and calms them down.  It's meant
to be similar to the behavior of
@link["http://www.flapjax-lang.org/docs/#calm_e" "calm-e"] in the
Flapjax language.


@section{Example}


@examples[
(module exercise-calm-evt mzscheme
  (require (lib "mred.ss" "mred")
           (lib "class.ss")
           (lib "async-channel.ss")
           (planet "calm-evt.ss" ("dyoo" "calm-evt.plt" 1)))
  
  (provide test)
  
  (define text%/changed-notification
    (class text%
      (inherit get-text)
      (define notify-channel (make-async-channel))
      
      (define/public (get-notify-channel)
        notify-channel)
      
      (define/augment (after-insert pos len)
        (inner (void) after-insert pos len)
        (async-channel-put notify-channel (get-text)))
      
      (define/augment (after-delete pos len)
        (inner (void) after-delete pos len)
        (async-channel-put notify-channel (get-text)))
      
      (super-new)))

  
  (define (test)
    (parameterize ([current-eventspace (make-eventspace)])
      (define f (new frame% [label ""]))
      (define t (new text%/changed-notification))
      (define c (new editor-canvas%
                     [parent f]
                     [editor t]))
      (send f show #t)
      
      (thread
       (lambda ()
         (define delayed-change-evt 
           (make-calm-evt (send t get-notify-channel)))
         (let loop ()
           (sync (handle-evt delayed-change-evt
                             (lambda (val)
                               (printf "~s~n" val))))
           (loop))))
      (void))))
]

Run the @scheme[test] function, and then start typing in the new
frame.  Changes in the text will be printed out, but only after a
period of inactivity.



@section{API}

A @scheme[calm-evt] can be used as an argument to @scheme[sync].  Its
result is the result of the event that it wraps.


@defproc[(make-calm-evt [wrapped-evt evt?] 
                        [delay-in-milliseconds natural-number/c 1000]) 
         calm-evt?]{
Creates a new @scheme[calm-evt] that wraps around the @scheme[wrapped-evt].
}

@defproc[(calm-evt? [datum any/c]) boolean?]{
Returns true if the datum is a @scheme[calm-evt].
}