gtk and cocoa: add flush method to canvas% and fix periodic flush

collects/mred/private/mrcanvas.rkt

@@ -66,6 +66,7 @@
                          (send wx begin-refresh-sequence))]
         [resume-flush (lambda ()
                         (send wx end-refresh-sequence))]
+        [flush (lambda () (send wx flush))]
 
 	[set-canvas-background
 	 (entry-point

collects/mred/private/wx/cocoa/dc.rkt

@@ -67,6 +67,9 @@
       ;; is at then end of `do-backing-flush'.
       (send canvas queue-backing-flush))
 
+    (define/override (flush)
+      (send canvas flush))
+
     (define/override (request-delay)
       (request-flush-delay (send canvas get-flush-window)))
     (define/override (cancel-delay req)

collects/mred/private/wx/cocoa/queue.rkt

@@ -348,6 +348,7 @@
  (lambda () (check-one-event #f #f)))
 
 (define (try-to-sync-refresh)
+  ;; atomically => outside of the event loop
   (atomically
    (pre-event-sync #t)))
 

collects/mred/private/wx/gtk/canvas.rkt

@@ -328,7 +328,10 @@
                                  scroll-width
                                  0)))
 
-     (define/override (direct-update?) #f)
+     ;; Direct update is ok for a canvas, and it
+     ;; allows pushing updates to the screen even
+     ;; if the eventspace thread is busy indefinitely
+     (define/override (direct-update?) #t)
 
      (define/public (get-dc) dc)
 
@@ -377,15 +380,18 @@
      (define/public (end-refresh-sequence)
        (send dc resume-flush))
 
+     ;; The `flush' method should be improved to flush local
+     ;; to the enclosing frame, instead of flushing globally.
+     (define/public (flush)
+       (flush-display))
+
      (define/override (refresh)
        (queue-paint))
 
      (define/public (queue-backing-flush)
        ;; called atomically
        (unless for-gl?
-         (gtk_widget_queue_draw client-gtk)
+         (gtk_widget_queue_draw client-gtk)))
-         ;; peridodically flush to the screen:
-         (schedule-periodic-backing-flush)))
      
      (define/override (reset-child-dcs)
        (when (dc . is-a? . dc%)

collects/mred/private/wx/gtk/dc.rkt

@@ -125,6 +125,9 @@
       (end-delay)
       (send canvas queue-backing-flush))
 
+    (define/override (flush)
+      (send canvas flush))
+
     (define/override (request-delay)
       (request-flush-delay (send canvas get-flush-window)))
     (define/override (cancel-delay req)

collects/mred/private/wx/win32/canvas.rkt

@@ -252,6 +252,11 @@
      (define/public (end-refresh-sequence)
        (send dc resume-flush))
      
+     ;; The `flush' method should be improved to flush local
+     ;; to the enclosing frame, instead of flushing globally.
+     (define/public (flush)
+       (flush-display))
+
      ;; Improve this method to flush locally
      ;; instead of globally:
      (define/public (flush)

collects/mred/private/wx/win32/dc.rkt

@@ -99,6 +99,9 @@
       (end-delay)
       (send canvas queue-backing-flush))
 
+    (define/override (flush)
+      (send canvas flush))
+
     (define/override (request-delay)
       (request-flush-delay canvas))
     (define/override (cancel-delay req)

collects/racket/draw/private/dc.rkt

@@ -569,6 +569,7 @@
 
     (def/public (suspend-flush) (void))
     (def/public (resume-flush) (void))
+    (def/public (flush) (void))
 
     (def/public (set-text-mode [(symbol-in solid transparent) mode])
       (set! text-mode mode))

collects/scribblings/gui/canvas-class.scrbl

@@ -94,6 +94,7 @@ The @scheme[gl-config] argument determines properties of an OpenGL
 
 }
 
+
 @defmethod[(get-scroll-page [which (one-of/c 'horizontal 'vertical)])
            (integer-in 1 1000000)]{
 
@@ -284,11 +285,6 @@ This method is called only when manual
 }
 
 
-@defmethod[(resume-flush) void?]{
-
-See @method[canvas% suspend-flush].}
-
-
 @defmethod[(scroll [h-value (or/c (real-in 0.0 1.0) false/c)]
                    [v-value (or/c (real-in 0.0 1.0) false/c)])
            void?]{
@@ -389,22 +385,6 @@ init-manual-scrollbars].
 }
 
 
-@defmethod[(suspend-flush) void?]{
-
-Drawing to a canvas's drawing context actually renders into an
-offscreen buffer. The buffer is automatically flushed to the screen by
-a background thread, unless flushing has been disabled for the canvas.
-The @method[canvas% suspend-flush] method suspends flushing for a
-canvas until a matching @method[canvas% resume-flush] calls; calls to
-@method[canvas% suspend-flush] and @method[canvas% resume-flush] can
-be nested, in which case flushing is suspended until the outermost
-@method[canvas% suspend-flush] is balanced by a @method[canvas%
-resume-flush].
-
-On some platforms, beware that suspending flushing for a canvas can
-discourage refreshes for other windows in the same frame.}
-
-
 @defmethod[(swap-gl-buffers)
            void?]{
 Calls

collects/scribblings/gui/canvas-intf.scrbl

@@ -48,6 +48,11 @@ For an @scheme[editor-canvas%] object, handling of Tab, arrow, Enter,
 }
 
 
+@defmethod[(flush) void?]{
+
+Like @racket[flush-display], but constrained if possible to the canvas.}
+
+
 @defmethod[(get-canvas-background)
            (or/c (is-a?/c color%) false/c)]{
 Returns the color currently used to ``erase'' the canvas content before
@@ -184,6 +189,12 @@ Does nothing.
 }}
 
 
+@defmethod[(resume-flush) void?]{
+
+See @method[canvas<%> suspend-flush].}
+
+
+
 @defmethod[(set-canvas-background [color (is-a?/c color%)])
            void?]{
 
@@ -209,6 +220,24 @@ Under Mac OS X, enables or disables space for a resize tab at the
 
 }
 
+
+@defmethod[(suspend-flush) void?]{
+
+Drawing to a canvas's drawing context actually renders into an
+offscreen buffer. The buffer is automatically flushed to the screen by
+a background thread, explicitly via the @method[canvas<%> flush] method, 
+or explicitly via @racket[flush-display] --- unless flushing has been disabled for the canvas.
+The @method[canvas<%> suspend-flush] method suspends flushing for a
+canvas until a matching @method[canvas<%> resume-flush] calls; calls to
+@method[canvas<%> suspend-flush] and @method[canvas<%> resume-flush] can
+be nested, in which case flushing is suspended until the outermost
+@method[canvas<%> suspend-flush] is balanced by a @method[canvas<%>
+resume-flush].
+
+On some platforms, beware that suspending flushing for a canvas can
+discourage refreshes for other windows in the same frame.}
+
+
 @defmethod[(warp-pointer [x (integer-in 0 10000)]
                          [y (integer-in 0 10000)])
            void?]{

collects/scribblings/gui/dc-intf.scrbl

@@ -446,6 +446,15 @@ For printer or PostScript output, an exception is raised if
 
 }
 
+
+@defmethod[(flush) void?]{
+
+Calls the @xmethod[canvas<%> flush] method for
+@racket[canvas<%>] output, and has no effect for other kinds of
+drawing contexts.}
+
+
+
 @defmethod[(get-alpha)
            (real-in 0 1)]{
 
@@ -733,6 +742,14 @@ Returns @scheme[#t] if the drawing context is usable.
 
 }
 
+
+@defmethod[(resume-flush) void?]{
+
+Calls the @xmethod[canvas<%> resume-flush] method for
+@racket[canvas<%>] output, and has no effect for other kinds of
+drawing contexts.}
+
+
 @defmethod[(rotate [angle real?]) void?]{
 
 Adds a rotation of @racket[angle] radians to the drawing context's
@@ -1059,6 +1076,14 @@ For printer or PostScript output, an exception is raised if
 
 }
 
+
+@defmethod[(suspend-flush) void?]{
+
+Calls the @xmethod[canvas<%> suspend-flush] method for
+@racket[canvas<%>] output, and has no effect for other kinds of
+drawing contexts.}
+
+
 @defmethod[(transform [m (vector/c real? real? real? real? real? real?)])
            void?]{
 

collects/scribblings/gui/global-draw-funcs.scrbl

@@ -6,11 +6,13 @@
 @defproc[(flush-display)
          void?]{
 
-Under X and Mac OS X, flushes pending display messages such that the
+Flushes canvas offscreen drawing and other updates onto the
- user's display reflects the actual state of the windows. Under
+ screen.
- Windows, the procedure has no effect.
+
+Normally, drawing is automatically flushed to the screen. Use
+@racket[flush-display] sparingly to force updates to the screen when
+other actions depend on updating the display.}
 
-}
 
 @defproc[(get-display-depth)
          exact-nonnegative-integer?]{

doc/release-notes/racket/Draw_and_GUI_X_Y.txt

@@ -59,10 +59,10 @@ Canvases
 --------
 
 Drawing to a canvas always draws into a bitmap that is kept offscreen
-and periodically flushed onto the screen. The new `suspend-flush' and
+and periodically flushed onto the screen. The new `suspend-flush',
-`resume-flush' methods of `canvas%' provide some control over the
+`resume-flush', and `flush' methods of `canvas%' provide some control
-timing of the flushes, which in many cases avoids the need for
+over the timing of the flushes, which in many cases avoids the need
-(additional) double buffering of canvas content.
+for (additional) double buffering of canvas content.
 
 OpenGL drawing in a canvas requires supplying 'gl as a style when
 creating the `canvas%' instance. OpenGL and normal dc<%> drawing no