page: add call-with-page-change-evt

Author: Bogdanp

marionette-doc/scribblings/marionette.scrbl

@@ -389,10 +389,10 @@ separately.
 @defproc[(page-change-evt [page page?]) (evt/c void?)]{
   Returns a synchronizable event that becomes ready for synchronization
   when the page contents have changed (for example, when the user
-  navigates to another page). The synchronization result of a page
-  change event is @racket[void]. Once a page change event has
-  synchronized, a new event must be created in order to observe further
-  page changes.
+  navigates to another page). The synchronization result of a
+  @deftech{page change event} is @racket[void]. Once a page change
+  event has synchronized, a new event must be created in order to
+  observe further page changes.
 
   When selected for synchronization, a page change event spawns a
   background thread to poll the page for changes. The thread will run
@@ -412,6 +412,16 @@ separately.
   @history[#:added "1.5"]
 }
 
+@defproc[(call-with-page-change-evt [p page?] [proc (-> page-change-evt? any)]) any]{
+  Calls @racket[proc] with a @tech{page change event} for @racket[p],
+  abandoning it when @racket[proc] returns or whenever control escapes
+  the dynamic extent of the call. Whenever control re-enters the dynamic
+  extent of a call to @racket[call-with-page-change-evt], a new page
+  change event is created.
+
+  @history[#:added "1.6"]
+}
+
 @subsection[#:tag "reference/element"]{Element}
 
 @deftech{Elements} represent individual elements on a specific page.

marionette-lib/info.rkt

@@ -1,7 +1,7 @@
 #lang info
 
 (define license 'BSD-3-Clause)
-(define version "1.5")
+(define version "1.6")
 (define collection "marionette")
 (define deps
   '("base"

marionette-lib/page.rkt

@@ -314,7 +314,8 @@
 (provide
  page-change-evt?
  page-change-evt
- abandon-page-change-evt)
+ abandon-page-change-evt
+ call-with-page-change-evt)
 
 (struct page-change-evt (p token [abandoned? #:mutable])
   #:name -page-change-evt
@@ -347,6 +348,16 @@
   (set-page-change-evt-abandoned?! e #t)
   (sync/enable-break e))
 
+(define (call-with-page-change-evt p proc)
+  (define e #f)
+  (dynamic-wind
+    (lambda ()
+      (set! e (page-change-evt p)))
+    (lambda ()
+      (proc e))
+    (lambda ()
+      (abandon-page-change-evt e))))
+
 ;; element ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
 (provide