Document that setting colours for native controls might not work.

[wxWidgets.git] / interface / wx / event.h

diff --git a/interface/wx/event.h b/interface/wx/event.h
index db03625d00ebbe54cbeefdefc502104ae7620d15..5cb9c497aa53d11c9d1ae44e1c5b4019284c32ad 100644 (file)
--- a/interface/wx/event.h
+++ b/interface/wx/event.h
@@ -1365,17 +1365,27 @@ enum wxKeyCategoryFlags
     @event{EVT_CHAR(func)}
         Process a @c wxEVT_CHAR event.
     @event{EVT_CHAR_HOOK(func)}
-        Process a @c wxEVT_CHAR_HOOK event which is sent to the active
-        wxTopLevelWindow (i.e. the one containing the currently focused window)
-        or wxApp global object if there is no active window before any other
-        keyboard events are generated giving the parent window the opportunity
-        to intercept all the keyboard entry. If the event is handled, i.e. the
-        handler doesn't call wxEvent::Skip(), neither @c wxEVT_KEY_DOWN nor @c
-        wxEVT_CHAR events will be generated (although @c wxEVT_KEY_UP still
-        will be). Notice that this event is not generated when the mouse is
-        captured as it is considered that the window which has the capture
-        should receive all the keyboard events too without allowing its parent
-        wxTopLevelWindow to interfere with their processing.
+        Process a @c wxEVT_CHAR_HOOK event. Unlike all the other key events,
+        this event is propagated upwards the window hierarchy which allows
+        intercepting it in the parent window of the focused window to which it
+        is sent initially (if there is no focused window, this event is sent to
+        the wxApp global object). It is also generated before any other key
+        events and so gives the parent window an opportunity to modify the
+        keyboard handling of its children, e.g. it is used internally by
+        wxWidgets in some ports to intercept pressing Esc key in any child of a
+        dialog to close the dialog itself when it's pressed. By default, if
+        this event is handled, i.e. the handler doesn't call wxEvent::Skip(),
+        neither @c wxEVT_KEY_DOWN nor @c wxEVT_CHAR events will be generated
+        (although @c wxEVT_KEY_UP still will be), i.e. it replaces the normal
+        key events. However by calling the special DoAllowNextEvent() method
+        you can handle @c wxEVT_CHAR_HOOK and still allow normal events
+        generation. This is something that is rarely useful but can be required
+        if you need to prevent a parent @c wxEVT_CHAR_HOOK handler from running
+        without suppressing the normal key events. Finally notice that this
+        event is not generated when the mouse is captured as it is considered
+        that the window which has the capture should receive all the keyboard
+        events too without allowing its parent wxTopLevelWindow to interfere
+        with their processing.
     @endEventTable
 
     @see wxKeyboardState
@@ -1518,6 +1528,34 @@ public:
         Returns the Y position (in client coordinates) of the event.
     */
     wxCoord GetY() const;
+
+    /**
+        Allow normal key events generation.
+
+        Can be called from @c wxEVT_CHAR_HOOK handler to indicate that the
+        generation of normal events should @em not be suppressed, as it happens
+        by default when this event is handled.
+
+        The intended use of this method is to allow some window object to
+        prevent @c wxEVT_CHAR_HOOK handler in its parent window from running by
+        defining its own handler for this event. Without calling this method,
+        this would result in not generating @c wxEVT_KEY_DOWN nor @c wxEVT_CHAR
+        events at all but by calling it you can ensure that these events would
+        still be generated, even if @c wxEVT_CHAR_HOOK event was handled.
+
+        @since 2.9.3
+     */
+    void DoAllowNextEvent();
+
+    /**
+        Returns @true if DoAllowNextEvent() had been called, @false by default.
+
+        This method is used by wxWidgets itself to determine whether the normal
+        key events should be generated after @c wxEVT_CHAR_HOOK processing.
+
+        @since 2.9.3
+     */
+    bool IsNextEventAllowed() const;
 };
 
 
@@ -2848,12 +2886,8 @@ public:
     To intercept this event, use the EVT_ERASE_BACKGROUND macro in an event table
     definition.
 
-    You must call wxEraseEvent::GetDC and use the returned device context if it is
-    non-@NULL. If it is @NULL, create your own temporary wxClientDC object.
-
-    @remarks
-        Use the device context returned by GetDC to draw on, don't create
-        a wxPaintDC in the event handler.
+    You must use the device context returned by GetDC() to draw on, don't create
+    a wxPaintDC in the event handler.
 
     @beginEventTable{wxEraseEvent}
     @event{EVT_ERASE_BACKGROUND(func)}
@@ -2875,6 +2909,8 @@ public:
 
     /**
         Returns the device context associated with the erase event to draw on.
+
+        The returned pointer is never @NULL.
     */
     wxDC* GetDC() const;
 };