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 4f6000239bd93208cf68c2d455c429e1254a9508..766e074b2243c2dae2ebbd050aac599f8f4e330b 100644 (file)
--- a/interface/wx/event.h
+++ b/interface/wx/event.h
@@ -1414,7 +1414,7 @@ public:
                 else
                 {
                     // It's a special key, deal with all the known ones:
-                    switch ( keycode )
+                    switch ( GetKeyCode() )
                     {
                         case WXK_LEFT:
                         case WXK_RIGHT:
@@ -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)}
@@ -2187,6 +2187,16 @@ public:
     wxClipboardTextEvent(wxEventType commandType = wxEVT_NULL, int id = 0);
 };
 
+/**
+    Possible axis values for mouse wheel scroll events.
+
+    @since 2.9.4
+ */
+enum wxMouseWheelAxis
+{
+    wxMOUSE_WHEEL_VERTICAL,     ///< Vertical scroll event.
+    wxMOUSE_WHEEL_HORIZONTAL    ///< Horizontal scroll event.
+};
 
 
 /**
@@ -2440,12 +2450,16 @@ public:
     int GetWheelRotation() const;
 
     /**
-        Gets the axis the wheel operation concerns; @c 0 is the Y axis as on
-        most mouse wheels, @c 1 is the X axis.
+        Gets the axis the wheel operation concerns.
 
-        Note that only some models of mouse have horizontal wheel axis.
+        Usually the mouse wheel is used to scroll vertically so @c
+        wxMOUSE_WHEEL_VERTICAL is returned but some mice (and most trackpads)
+        also allow to use the wheel to scroll horizontally in which case
+        @c wxMOUSE_WHEEL_HORIZONTAL is returned.
+
+        Notice that before wxWidgets 2.9.4 this method returned @c int.
     */
-    int GetWheelAxis() const;
+    wxMouseWheelAxis GetWheelAxis() const;
 
     /**
         Returns @true if the event was a mouse button event (not necessarily a button
@@ -2693,7 +2707,7 @@ public:
     wxClientData* GetClientObject() const;
 
     /**
-        Returns extra information dependant on the event objects type.
+        Returns extra information dependent on the event objects type.
 
         If the event comes from a listbox selection, it is a boolean
         determining whether the event was a selection (@true) or a
@@ -2929,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.
@@ -3475,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