From fcf44097a481ad56acf3fe74febc195d61f55c17 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Mon, 17 Jan 2011 09:03:05 -0700 Subject: [PATCH] document the fact that event callbacks are now delimited by a prompt using the default continuation prompt tag original commit: 7545d7d18fd0119e441d36ac516b89dc14693861 --- collects/scribblings/gui/win-overview.scrbl | 42 ++++++++++++------- doc/release-notes/gracket/HISTORY.txt | 9 ++++ doc/release-notes/racket/Draw_and_GUI_5_1.txt | 5 +++ 3 files changed, 41 insertions(+), 15 deletions(-) diff --git a/collects/scribblings/gui/win-overview.scrbl b/collects/scribblings/gui/win-overview.scrbl index 13208dd0..9fc65796 100644 --- a/collects/scribblings/gui/win-overview.scrbl +++ b/collects/scribblings/gui/win-overview.scrbl @@ -862,7 +862,7 @@ An eventspace's event queue is actually a priority queue with events Although a programmer has no direct control over the order in which events are dispatched, a programmer can control the timing of - dispatches by setting the event dispatch handler via the + dispatches by setting the @deftech{event dispatch handler} via the @scheme[event-dispatch-handler] parameter. This parameter and other eventspace procedures are described in more detail in @secref["eventspace-funcs"]. @@ -923,13 +923,26 @@ An eventspace is a @techlink[#:doc reference-doc]{synchronizable parent. (Note that the blocking state of an eventspace is unrelated to whether an event is ready for dispatching.) -@subsection[#:tag "evtcontjump"]{Exceptions and Continuation Jumps} +@subsection[#:tag "evtcontjump"]{Exceptions, Continuations, and Jumps} -Whenever the system dispatches an event, the call to the handler - procedure is wrapped so that full continuation jumps are not allowed - to escape from the dispatch, and escape continuation jumps are - blocked at the dispatch site. The following @scheme[block] procedure - illustrates how the system blocks escape continuation jumps: +Whenever the system dispatches an event, the call to the handler is + wrapped with a @deftech{continuation prompt} that delimits + continuations captured by the handler (see + @racket[call-with-continuation-prompt]). For example, if a button + callback captures a continuation, then applying the continuation + later reinstalls only the work to be done by the handler up until the + point that it returns; the dispatch machinery to invoke the button + callback is not included in the continuation. The delimited + continuation prompt is installed outside the call to the @tech{event + dispatch handler}, so any captured continuation includes the + invocation of the @tech{event dispatch handler}. + +An event-handling callback (and the @tech{event dispatch handler}) is + further wrapped with a @deftech{continuation barrier} and a + @racket[dynamic-wind] that blocks jumps (using continuation prompts + other than the default one) that escape past the dispatch site. The + following @scheme[block] procedure illustrates how the system blocks + escape continuation jumps: @def+int[ (define (block f) @@ -947,12 +960,9 @@ Whenever the system dispatches an event, the call to the handler (let/ec k (block (lambda () (k 10))) 11) ] -Calls to the event dispatch handler are also protected with - @scheme[block]. - This blocking of continuation jumps complicates the interaction between @scheme[with-handlers] and @scheme[yield] (or the default - event dispatch handler). For example, in evaluating the expression + @tech{event dispatch handler}). For example, in evaluating the expression @schemeblock[ (with-handlers ([(lambda (x) #t) @@ -971,9 +981,9 @@ the @scheme["error during yield"] handler is @italic{never} called, sense that control jumps out of the event handler, but @scheme[yield] may dispatch another event rather than escaping or returning. -The following expression demonstrates a more useful way to handle - exceptions within @scheme[yield], for the rare cases where - such handling is useful: +The following expression demonstrates a more effective way to handle + exceptions within @scheme[yield], for the rare cases where such + handling is useful: @schemeblock[ (let/ec k @@ -1022,4 +1032,6 @@ animation frame with @method[canvas<%> suspend-flush] and are not flushed to the screen. Use @method[canvas<%> flush] to ensure that canvas content is flushed when it is ready if a @method[canvas<%> suspend-flush] will soon follow, because the process of flushing to -the screen can be starved if flushing is frequently suspend. +the screen can be starved if flushing is frequently suspend. The +method @xmethod[canvas% refresh-now] conveniently encapsulates this +sequence. diff --git a/doc/release-notes/gracket/HISTORY.txt b/doc/release-notes/gracket/HISTORY.txt index 51602102..75948fb3 100644 --- a/doc/release-notes/gracket/HISTORY.txt +++ b/doc/release-notes/gracket/HISTORY.txt @@ -1,3 +1,12 @@ +Version 5.1, February 2011 + +The GRacket executable is now a thin wrapper on the Racket executable, +with the drawing and GUI libraries re-implemented as plain Racket +libraries. See "Draw_and_GUI_5_1.txt" in the Racket release-notes +directory. These notes will be discontinued. + +---------------------------------------------------------------------- + Version 5.0.2, October 2010 Minor bug fixes diff --git a/doc/release-notes/racket/Draw_and_GUI_5_1.txt b/doc/release-notes/racket/Draw_and_GUI_5_1.txt index 44c2dad2..e45603c6 100644 --- a/doc/release-notes/racket/Draw_and_GUI_5_1.txt +++ b/doc/release-notes/racket/Draw_and_GUI_5_1.txt @@ -148,6 +148,11 @@ content of the combo-box popup menu, but the default implementation no longer triggers the popup menu; instead, the popup behavior is built into the control. +Event callbacks are delimited by a continuation prompt using the +default continuation prompt tag. As a result, continuations can be +usufully captured during one event callback and applied during other +callbacks or outside of an even callback. + Removed Functions -----------------