From e2a0fd02ef89da7d8efbfe26739ca82d8a42c7ad Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Sat, 5 Feb 2011 16:48:04 -0700 Subject: [PATCH] document limitations of `on-subwindow-event' and `on-subwindow-char' Merge to 5.1 --- collects/scribblings/gui/window-intf.scrbl | 18 +++++++++++++++--- doc/release-notes/racket/Draw_and_GUI_5_1.txt | 5 +++++ 2 files changed, 20 insertions(+), 3 deletions(-) diff --git a/collects/scribblings/gui/window-intf.scrbl b/collects/scribblings/gui/window-intf.scrbl index 3c3645b89f..17318469af 100644 --- a/collects/scribblings/gui/window-intf.scrbl +++ b/collects/scribblings/gui/window-intf.scrbl @@ -374,6 +374,14 @@ Called when this window or a child window receives a keyboard event. @method[window<%> on-subwindow-char] method returns @scheme[#f], the event is passed on to the receiver's normal key-handling mechanism. +The @scheme[event] argument is the event that was generated for the + @scheme[receiver] window. + +The atomicity limitation @method[window<%> on-subwindow-event] applies + to @method[window<%> on-subwindow-char] as well. That is, an insufficiently cooperative + @method[window<%> on-subwindow-char] method can effectively disable + a control's handling of key events, even when it returns @racket[#f] + BEWARE: The default @xmethod[frame% on-subwindow-char] and @xmethod[dialog% on-subwindow-char] methods consume certain keyboard events (e.g., arrow keys, Enter) used @@ -382,9 +390,6 @@ BEWARE: The default reach the ``receiver'' child unless the default frame or dialog method is overridden. -The @scheme[event] argument is the event that was generated for the - @scheme[receiver] window. - } @methimpl{ @@ -409,6 +414,13 @@ Called when this window or a child window receives a mouse event. The @scheme[event] argument is the event that was generated for the @scheme[receiver] window. +If the @method[window<%> on-subwindow-event] method chain does not complete + atomically (i.e., without requiring other threads to run) or does not complete + fast enough, then the corresponding event may not be delivered to a target + control, such as a button. In other words, an insufficiently cooperative + @method[window<%> on-subwindow-event] method can effectively disable a + control's handling of mouse events, even when it returns @racket[#f]. + } @methimpl{ 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 63c19627ee..128f037bd4 100644 --- a/doc/release-notes/racket/Draw_and_GUI_5_1.txt +++ b/doc/release-notes/racket/Draw_and_GUI_5_1.txt @@ -155,6 +155,11 @@ callbacks or outside of an even callback. The continuation barrier and jump-defeating `dynamic-wind' that formerly guarded callbacks has been removed. +The `on-subwindow-char' and `on-subwindow-event' methods for controls +are somewhat more restructed in the actions they can take without +disabling the control's handling of key and mouse events. See the +documentation for more information. + Registry Functions -----------------