{"size": 2833, "ext": "scrbl", "max_stars_repo_path": "gui-doc/scribblings/gui/timer-class.scrbl", "max_stars_repo_name": "jjsimpso/gui", "max_stars_repo_stars_event_min_datetime": "2015-03-17T22:11:52.000Z", "max_stars_repo_stars_event_max_datetime": "2022-03-12T15:09:34.000Z", "max_issues_repo_path": "gui-doc/scribblings/gui/timer-class.scrbl", "max_issues_repo_name": "jjsimpso/gui", "max_issues_repo_issues_event_min_datetime": "2015-01-09T15:53:25.000Z", "max_issues_repo_issues_event_max_datetime": "2022-03-31T16:21:29.000Z", "max_forks_repo_path": "gui-doc/scribblings/gui/timer-class.scrbl", "max_forks_repo_name": "jjsimpso/gui", "max_forks_repo_forks_event_min_datetime": "2015-01-08T13:03:07.000Z", "max_forks_repo_forks_event_max_datetime": "2022-03-26T21:49:09.000Z"}
{"max_stars_count": 65, "max_issues_count": 231, "max_forks_count": 89, "avg_line_length": 32.1931818182, "max_line_length": 95, "alphanum_fraction": 0.7229085775}
#lang scribble/doc
@(require "common.rkt")

@defclass/title[timer% object% ()]{

A @racket[timer%] object encapsulates an event-based alarm. To use a
 timer, either instantiate it with a @racket[timer-callback] thunk to
 perform the alarm-based action, or derive a new class and override
 the @method[timer% notify] method to perform the alarm-based
 action. Start a timer with @method[timer% start] and stop it with
 @method[timer% stop]. Supplying an initial @racket[interval] (in
 milliseconds) when creating a timer also starts the timer.

Timers have a relatively high priority in the event queue. Thus, if
 the timer delay is set low enough, repeated notification for a timer
 can preempt user activities (which might be directed at stopping the
 timer). For timers with relatively short delays, call @racket[yield]
 within the @method[timer% notify] procedure to allow guaranteed event
 processing.

See @secref["eventspaceinfo"] for more information about event
 priorities.


@defconstructor[([notify-callback (-> any) void]
                 [interval (or/c (integer-in 0 1000000000) #f) #f]
                 [just-once? any/c #f])]{

The @racket[notify-callback] thunk is called by the default
@method[timer% notify] method when the timer expires.

If @racket[interval] is @racket[#f] (the default), the timer is not
 started; in that case, @method[timer% start] must be called
 explicitly. If @racket[interval] is a number (in milliseconds), then
 @method[timer% start] is called with @racket[interval] and
 @racket[just-once?].

}


@defmethod[(interval)
           (integer-in 0 1000000000)]{

Returns the number of milliseconds between each timer expiration (when
 the timer is running).

}

@defmethod[(notify)
           void?]{

@methspec{

Called (on an event boundary) when the timer's alarm expires.

}
@methimpl{

Calls the @racket[notify-callback] procedure that was provided when the
 object was created.

}}

@defmethod[(start [msec (integer-in 0 1000000000)]
                  [just-once? any/c #f])
           void?]{

Starts (or restarts) the timer. If the timer is already running, its alarm time is not changed.

The timer's alarm expires after @racket[msec] milliseconds, at which point
@method[timer% notify] is called (on an event boundary). If
@racket[just-once?] is true, the timer calls its @method[timer% notify]
callback when the alarm expires and the timer is stopped. If
@racket[just-once?] is @racket[#f], the timer is re-started when the @method[timer% notify]
callback returns; it stops only once @method[timer% stop] is called explicitly.

}

@defmethod[(stop)
           void?]{

Stops the timer. A stopped timer never calls
@method[timer% notify]. If the timer has expired but the call to
@method[timer% notify] has not yet been dispatched, the call is removed from the event queue.

}}

