synchronize GTK2 minimum version in docs

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

diff --git a/interface/wx/event.h b/interface/wx/event.h
index 0a9a64d0f88eb217f4ef1be30e02c3f5d75708e7..766e074b2243c2dae2ebbd050aac599f8f4e330b 100644 (file)
--- a/interface/wx/event.h
+++ b/interface/wx/event.h
@@ -2159,8 +2159,8 @@ public:
     text was copied or cut.
 
     @note
-    These events are currently only generated by wxTextCtrl under GTK+.
-    They are generated by all controls under Windows.
+    These events are currently only generated by wxTextCtrl in wxGTK and wxOSX
+    but are also generated by wxComboBox without wxCB_READONLY style in wxMSW.
 
     @beginEventTable{wxClipboardTextEvent}
     @event{EVT_TEXT_COPY(id, func)}
@@ -2943,6 +2943,14 @@ public:
     window (whether using the mouse or keyboard) and when it is done from the
     program itself using wxWindow::SetFocus.
 
+    The focus event handlers should almost invariably call wxEvent::Skip() on
+    their event argument to allow the default handling to take place. Failure
+    to do this may result in incorrect behaviour of the native controls. Also
+    note that wxEVT_KILL_FOCUS handler must not call wxWindow::SetFocus() as
+    this, again, is not supported by all native controls. If you need to do
+    this, consider using the @ref sec_delayed_action described in wxIdleEvent
+    documentation.
+
     @beginEventTable{wxFocusEvent}
     @event{EVT_SET_FOCUS(func)}
         Process a @c wxEVT_SET_FOCUS event.
@@ -3489,6 +3497,30 @@ enum wxIdleMode
     @library{wxbase}
     @category{events}
 
+    @section sec_delayed_action Delayed Action Mechanism
+
+    wxIdleEvent can be used to perform some action "at slightly later time".
+    This can be necessary in several circumstances when, for whatever reason,
+    something can't be done in the current event handler. For example, if a
+    mouse event handler is called with the mouse button pressed, the mouse can
+    be currently captured and some operations with it -- notably capturing it
+    again -- might be impossible or lead to undesirable results. If you still
+    want to capture it, you can do it from @c wxEVT_IDLE handler when it is
+    called the next time instead of doing it immediately.
+
+    This can be achieved in two different ways: when using static event tables,
+    you will need a flag indicating to the (always connected) idle event
+    handler whether the desired action should be performed. The originally
+    called handler would then set it to indicate that it should indeed be done
+    and the idle handler itself would reset it to prevent it from doing the
+    same action again.
+
+    Using dynamically connected event handlers things are even simpler as the
+    original event handler can simply wxEvtHandler::Connect() or
+    wxEvtHandler::Bind() the idle event handler which would only be executed
+    then and could wxEvtHandler::Disconnect() or wxEvtHandler::Unbind() itself.
+
+
     @see @ref overview_events, wxUpdateUIEvent, wxWindow::OnInternalIdle
 */
 class wxIdleEvent : public wxEvent