X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/3e97a905185a72c04a7feb67c7885ab4412100ee..6ac7ddd334c30a051ecd1d36132a35498f997d20:/interface/wx/event.h?ds=sidebyside

diff --git a/interface/wx/event.h b/interface/wx/event.h
index e2263ece27..238369e533 100644
--- a/interface/wx/event.h
+++ b/interface/wx/event.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        event.h
-// Purpose:     interface of wxEventHandler, wxEventBlocker and many
+// Purpose:     interface of wxEvtHandler, wxEventBlocker and many
 //              wxEvent-derived classes
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
@@ -8,7 +8,6 @@
 /////////////////////////////////////////////////////////////////////////////
 
 
-
 /**
     @class wxEvent
 
@@ -34,7 +33,26 @@ class wxEvent : public wxObject
 {
 public:
     /**
-        Constructor. Should not need to be used directly by an application.
+        Constructor.
+
+        Notice that events are usually created by wxWidgets itself and creating
+        e.g. a wxPaintEvent in your code and sending it to e.g. a wxTextCtrl
+        will not usually affect it at all as native controls have no specific
+        knowledge about wxWidgets events. However you may construct objects of
+        specific types and pass them to wxEvtHandler::ProcessEvent() if you
+        want to create your own custom control and want to process its events
+        in the same manner as the standard ones.
+
+        Also please notice that the order of parameters in this constructor is
+        different from almost all the derived classes which specify the event
+        type as the first argument.
+
+        @param id
+            The identifier of the object (window, timer, ...) which generated
+            this event.
+        @param eventType
+            The unique type of event, e.g. wxEVT_PAINT, wxEVT_SIZE or
+            wxEVT_COMMAND_BUTTON_CLICKED.
     */
     wxEvent(int id = 0, wxEventType eventType = wxEVT_NULL);
 
@@ -42,8 +60,8 @@ public:
         Returns a copy of the event.
 
         Any event that is posted to the wxWidgets event system for later action
-        (via wxEvtHandler::AddPendingEvent or wxPostEvent()) must implement
-        this method.
+        (via wxEvtHandler::AddPendingEvent, wxEvtHandler::QueueEvent or wxPostEvent())
+        must implement this method.
 
         All wxWidgets events fully implement this method, but any derived events
         implemented by the user should also implement this method just in case they
@@ -83,6 +101,10 @@ public:
         Gets the timestamp for the event. The timestamp is the time in milliseconds
         since some fixed moment (not necessarily the standard Unix Epoch, so only
         differences between the timestamps and not their absolute values usually make sense).
+
+        @warning
+        wxWidgets returns a non-NULL timestamp only for mouse and key events
+        (see wxMouseEvent and wxKeyEvent).
     */
     long GetTimestamp() const;
 
@@ -117,7 +139,7 @@ public:
     /**
         Sets the timestamp for the event.
     */
-    void SetTimestamp(long = 0);
+    void SetTimestamp(long timeStamp = 0);
 
     /**
         Test if this event should be propagated or not, i.e. if the propagation level
@@ -213,7 +235,7 @@ public:
         Note that the @a win window @b must remain alive until the
         wxEventBlocker object destruction.
     */
-    wxEventBlocker(wxWindow* win, wxEventType = wxEVT_ANY);
+    wxEventBlocker(wxWindow* win, wxEventType type = -1);
 
     /**
         Destructor. The blocker will remove itself from the chain of event handlers for
@@ -233,13 +255,13 @@ public:
     @class wxEvtHandler
 
     A class that can handle events from the windowing system.
-    wxWindow (and therefore all window classes) are derived from this class.
+    wxWindow is (and therefore all window classes are) derived from this class.
 
     When events are received, wxEvtHandler invokes the method listed in the
-    event table using itself as the object.  When using multiple inheritance
-    it is imperative that the wxEvtHandler(-derived) class be the first
-    class inherited such that the "this" pointer for the overall object
-    will be identical to the "this" pointer for the wxEvtHandler portion.
+    event table using itself as the object. When using multiple inheritance
+    <b>it is imperative that the wxEvtHandler(-derived) class is the first
+    class inherited</b> such that the @c this pointer for the overall object
+    will be identical to the @c this pointer of the wxEvtHandler portion.
 
     @library{wxbase}
     @category{events}
@@ -257,11 +279,17 @@ public:
     /**
         Destructor.
 
-        If the handler is part of a chain, the destructor will unlink itself and
-        restore the previous and next handlers so that they point to each other.
+        If the handler is part of a chain, the destructor will unlink itself
+        (see Unlink()).
     */
     virtual ~wxEvtHandler();
 
+
+    /**
+        @name Event queuing and processing
+    */
+    //@{
+
     /**
         Queue event for a later processing.
 
@@ -319,9 +347,9 @@ public:
         wxString object which happens because the wxString field in the
         original @a event object and its copy made internally by this function
         share the same string buffer internally. Use QueueEvent() to avoid
-        this. 
+        this.
 
-        A copy of event is made by the function, so the original can be deleted
+        A copy of @a event is made by the function, so the original can be deleted
         as soon as function returns (it is common that the original is created
         on the stack). This requires that the wxEvent::Clone() method be
         implemented by event so that it can be duplicated and stored until it
@@ -332,6 +360,107 @@ public:
     */
     virtual void AddPendingEvent(const wxEvent& event);
 
+    /**
+        Processes an event, searching event tables and calling zero or more suitable
+        event handler function(s).
+
+        Normally, your application would not call this function: it is called in the
+        wxWidgets implementation to dispatch incoming user interface events to the
+        framework (and application).
+
+        However, you might need to call it if implementing new functionality
+        (such as a new control) where you define new event types, as opposed to
+        allowing the user to override virtual functions.
+
+        An instance where you might actually override the ProcessEvent() function is where
+        you want to direct event processing to event handlers not normally noticed by
+        wxWidgets. For example, in the document/view architecture, documents and views
+        are potential event handlers. When an event reaches a frame, ProcessEvent() will
+        need to be called on the associated document and view in case event handler functions
+        are associated with these objects. The property classes library (wxProperty) also
+        overrides ProcessEvent() for similar reasons.
+
+        The normal order of event table searching is as follows:
+        -# If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled)
+           the function skips to step (6).
+        -# If the object is a wxWindow, ProcessEvent() is recursively called on the
+           window's wxValidator. If this returns @true, the function exits.
+        -# SearchEventTable() is called for this event handler. If this fails, the base
+           class table is tried, and so on until no more tables exist or an appropriate
+           function was found, in which case the function exits.
+        -# The search is applied down the entire chain of event handlers (usually the
+           chain has a length of one). This chain can be formed using wxEvtHandler::SetNextHandler():
+              @image html overview_eventhandling_chain.png
+           (referring to the image, if @c A->ProcessEvent is called and it doesn't handle
+            the event, @c B->ProcessEvent will be called and so on...).
+           Note that in the case of wxWindow you can build a stack of event handlers
+           (see wxWindow::PushEventHandler() for more info).
+           If any of the handlers of the chain return @true, the function exits.
+        -# If the object is a wxWindow and the event is a wxCommandEvent, ProcessEvent()
+           is recursively applied to the parent window's event handler.
+           If this returns @true, the function exits.
+        -# Finally, ProcessEvent() is called on the wxApp object.
+
+        @param event
+            Event to process.
+
+        @return @true if a suitable event handler function was found and
+                 executed, and the function did not call wxEvent::Skip.
+
+        @see SearchEventTable()
+    */
+    virtual bool ProcessEvent(wxEvent& event);
+
+    /**
+        Processes an event by calling ProcessEvent() and handles any exceptions
+        that occur in the process.
+        If an exception is thrown in event handler, wxApp::OnExceptionInMainLoop is called.
+
+        @param event
+            Event to process.
+
+        @return @true if the event was processed, @false if no handler was found
+                 or an exception was thrown.
+
+        @see wxWindow::HandleWindowEvent
+    */
+    bool SafelyProcessEvent(wxEvent& event);
+
+    /**
+        Searches the event table, executing an event handler function if an appropriate
+        one is found.
+
+        @param table
+            Event table to be searched.
+        @param event
+            Event to be matched against an event table entry.
+
+        @return @true if a suitable event handler function was found and
+                 executed, and the function did not call wxEvent::Skip.
+
+        @remarks This function looks through the object's event table and tries
+                 to find an entry that will match the event.
+                 An entry will match if:
+                 @li The event type matches, and
+                 @li the identifier or identifier range matches, or the event table
+                     entry's identifier is zero.
+
+                 If a suitable function is called but calls wxEvent::Skip, this
+                 function will fail, and searching will continue.
+
+        @see ProcessEvent()
+    */
+    virtual bool SearchEventTable(wxEventTable& table,
+                                  wxEvent& event);
+
+    //@}
+
+
+    /**
+        @name Connecting and disconnecting
+    */
+    //@{
+
     /**
         Connects the given function dynamically with the event handler, id and event type.
         This is an alternative to the use of static event tables.
@@ -417,8 +546,8 @@ public:
         @param eventSink
             Object whose member function should be called.
     */
-    bool Disconnect(wxEventType eventType = wxEVT_NULL,
-                    wxObjectEventFunction function = NULL,
+    bool Disconnect(wxEventType eventType,
+                    wxObjectEventFunction function,
                     wxObject* userData = NULL,
                     wxEvtHandler* eventSink = NULL);
 
@@ -440,11 +569,18 @@ public:
 
         This overload takes an additional range of source IDs.
     */
-    bool Disconnect(int id, int lastId = wxID_ANY,
-                    wxEventType eventType = wxEVT_NULL,
+    bool Disconnect(int id, int lastId,
+                    wxEventType eventType,
                     wxObjectEventFunction function = NULL,
                     wxObject* userData = NULL,
                     wxEvtHandler* eventSink = NULL);
+    //@}
+
+
+    /**
+        @name User-supplied data
+    */
+    //@{
 
     /**
         Returns user-supplied client data.
@@ -465,135 +601,60 @@ public:
     wxClientData* GetClientObject() const;
 
     /**
-        Returns @true if the event handler is enabled, @false otherwise.
+        Sets user-supplied client data.
 
-        @see SetEvtHandlerEnabled()
-    */
-    bool GetEvtHandlerEnabled() const;
+        @param data
+            Data to be associated with the event handler.
 
-    /**
-        Returns the pointer to the next handler in the chain.
+        @remarks Normally, any extra data the programmer wishes to associate
+                 with the object should be made available by deriving a new
+                 class with new data members. You must not call this method
+                 and SetClientObject on the same class - only one of them.
 
-        @see SetNextHandler(), GetPreviousHandler(), SetPreviousHandler(),
-             wxWindow::PushEventHandler, wxWindow::PopEventHandler
+        @see GetClientData()
     */
-    wxEvtHandler* GetNextHandler() const;
+    void SetClientData(void* data);
 
     /**
-        Returns the pointer to the previous handler in the chain.
+        Set the client data object. Any previous object will be deleted.
 
-        @see SetPreviousHandler(), GetNextHandler(), SetNextHandler(),
-             wxWindow::PushEventHandler, wxWindow::PopEventHandler
+        @see GetClientObject(), wxClientData
     */
-    wxEvtHandler* GetPreviousHandler() const;
-
-    /**
-        Processes an event, searching event tables and calling zero or more suitable
-        event handler function(s).
-
-        Normally, your application would not call this function: it is called in the
-        wxWidgets implementation to dispatch incoming user interface events to the
-        framework (and application).
-
-        However, you might need to call it if implementing new functionality
-        (such as a new control) where you define new event types, as opposed to
-        allowing the user to override virtual functions.
-
-        An instance where you might actually override the ProcessEvent function is where
-        you want to direct event processing to event handlers not normally noticed by
-        wxWidgets. For example, in the document/view architecture, documents and views
-        are potential event handlers. When an event reaches a frame, ProcessEvent will
-        need to be called on the associated document and view in case event handler functions
-        are associated with these objects. The property classes library (wxProperty) also
-        overrides ProcessEvent for similar reasons.
-
-        The normal order of event table searching is as follows:
-        -# If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled)
-            the function skips to step (6).
-        -# If the object is a wxWindow, ProcessEvent() is recursively called on the
-            window's wxValidator. If this returns @true, the function exits.
-        -# SearchEventTable() is called for this event handler. If this fails, the base
-            class table is tried, and so on until no more tables exist or an appropriate
-            function was found, in which case the function exits.
-        -# The search is applied down the entire chain of event handlers (usually the
-            chain has a length of one). If this succeeds, the function exits.
-        -# If the object is a wxWindow and the event is a wxCommandEvent, ProcessEvent()
-            is recursively applied to the parent window's event handler.
-            If this returns true, the function exits.
-        -# Finally, ProcessEvent() is called on the wxApp object.
-
-        @param event
-            Event to process.
+    void SetClientObject(wxClientData* data);
 
-        @return @true if a suitable event handler function was found and
-                 executed, and the function did not call wxEvent::Skip.
+    //@}
 
-        @see SearchEventTable()
-    */
-    virtual bool ProcessEvent(wxEvent& event);
 
     /**
-        Processes an event by calling ProcessEvent() and handles any exceptions
-        that occur in the process.
-        If an exception is thrown in event handler, wxApp::OnExceptionInMainLoop is called.
-
-        @param event
-            Event to process.
+        @name Event handler chaining
 
-        @return @true if the event was processed, @false if no handler was found
-                 or an exception was thrown.
-
-        @see wxWindow::HandleWindowEvent
+        wxEvtHandler can be arranged in a double-linked list of handlers
+        which is automatically iterated by ProcessEvent() if needed.
     */
-    bool SafelyProcessEvent(wxEvent& event);
+    //@{
 
     /**
-        Searches the event table, executing an event handler function if an appropriate
-        one is found.
-
-        @param table
-            Event table to be searched.
-        @param event
-            Event to be matched against an event table entry.
-
-        @return @true if a suitable event handler function was found and
-                 executed, and the function did not call wxEvent::Skip.
-
-        @remarks This function looks through the object's event table and tries
-                 to find an entry that will match the event.
-                 An entry will match if:
-                 @li The event type matches, and
-                 @li the identifier or identifier range matches, or the event table
-                     entry's identifier is zero.
-                 If a suitable function is called but calls wxEvent::Skip, this
-                 function will fail, and searching will continue.
+        Returns @true if the event handler is enabled, @false otherwise.
 
-        @see ProcessEvent()
+        @see SetEvtHandlerEnabled()
     */
-    virtual bool SearchEventTable(wxEventTable& table,
-                                  wxEvent& event);
+    bool GetEvtHandlerEnabled() const;
 
     /**
-        Sets user-supplied client data.
-
-        @param data
-            Data to be associated with the event handler.
-
-        @remarks Normally, any extra data the programmer wishes to associate
-                 with the object should be made available by deriving a new
-                 class with new data members. You must not call this method
-                 and SetClientObject on the same class - only one of them.
+        Returns the pointer to the next handler in the chain.
 
-        @see GetClientData()
+        @see SetNextHandler(), GetPreviousHandler(), SetPreviousHandler(),
+             wxWindow::PushEventHandler, wxWindow::PopEventHandler
     */
-    void SetClientData(void* data);
+    wxEvtHandler* GetNextHandler() const;
 
     /**
-        Set the client data object. Any previous object will be deleted.
+        Returns the pointer to the previous handler in the chain.
 
-        @see GetClientObject(), wxClientData
+        @see SetPreviousHandler(), GetNextHandler(), SetNextHandler(),
+             wxWindow::PushEventHandler, wxWindow::PopEventHandler
     */
-    void SetClientObject(wxClientData* data);
+    wxEvtHandler* GetPreviousHandler() const;
 
     /**
         Enables or disables the event handler.
@@ -612,21 +673,62 @@ public:
     /**
         Sets the pointer to the next handler.
 
+        @remarks
+        See ProcessEvent() for more info about how the chains of event handlers
+        are internally used.
+        Also remember that wxEvtHandler uses double-linked lists and thus if you
+        use this function, you should also call SetPreviousHandler() on the
+        argument passed to this function:
+        @code
+            handlerA->SetNextHandler(handlerB);
+            handlerB->SetPreviousHandler(handlerA);
+        @endcode
+
         @param handler
-            Event handler to be set as the next handler.
+            The event handler to be set as the next handler.
+            Cannot be @NULL.
 
-        @see GetNextHandler(), SetPreviousHandler(), GetPreviousHandler(),
-             wxWindow::PushEventHandler, wxWindow::PopEventHandler
+        @see @ref overview_eventhandling_processing
     */
-    void SetNextHandler(wxEvtHandler* handler);
+    virtual void SetNextHandler(wxEvtHandler* handler);
 
     /**
         Sets the pointer to the previous handler.
+        All remarks about SetNextHandler() apply to this function as well.
 
         @param handler
-            Event handler to be set as the previous handler.
+            The event handler to be set as the previous handler.
+            Cannot be @NULL.
+
+        @see @ref overview_eventhandling_processing
+    */
+    virtual void SetPreviousHandler(wxEvtHandler* handler);
+
+    /**
+        Unlinks this event handler from the chain it's part of (if any);
+        then links the "previous" event handler to the "next" one
+        (so that the chain won't be interrupted).
+
+        E.g. if before calling Unlink() you have the following chain:
+            @image html evthandler_unlink_before.png
+        then after calling @c B->Unlink() you'll have:
+            @image html evthandler_unlink_after.png
+
+        @since 2.9.0
     */
-    void SetPreviousHandler(wxEvtHandler* handler);
+    void Unlink();
+
+    /**
+        Returns @true if the next and the previous handler pointers of this
+        event handler instance are @NULL.
+
+        @since 2.9.0
+
+        @see SetPreviousHandler(), SetNextHandler()
+    */
+    bool IsUnlinked() const;
+
+    //@}
 };
 
 
@@ -646,7 +748,7 @@ public:
     Both key events provide untranslated key codes while the char event carries
     the translated one. The untranslated code for alphanumeric keys is always
     an upper case value. For the other keys it is one of @c WXK_XXX values
-    from the @ref page_keycodes.
+    from the ::wxKeyCode enumeration.
     The translated key is, in general, the character the user expects to appear
     as the result of the key combination when typing the text into a text entry
     zone, for example.
@@ -698,10 +800,13 @@ public:
            Process a wxEVT_CHAR event.
     @endEventTable
 
+    @see wxKeyboardState
+
     @library{wxcore}
     @category{events}
 */
-class wxKeyEvent : public wxEvent
+class wxKeyEvent : public wxEvent,
+                   public wxKeyboardState
 {
 public:
     /**
@@ -710,36 +815,10 @@ public:
     */
     wxKeyEvent(wxEventType keyEventType = wxEVT_NULL);
 
-    /**
-        Returns @true if the Alt key was down at the time of the key event.
-
-        Notice that GetModifiers() is easier to use correctly than this function
-        so you should consider using it in new code.
-    */
-    bool AltDown() const;
-
-    /**
-        CMD is a pseudo key which is the same as Control for PC and Unix
-        platforms but the special APPLE (a.k.a as COMMAND) key under Macs:
-        it makes often sense to use it instead of, say, ControlDown() because Cmd
-        key is used for the same thing under Mac as Ctrl elsewhere (but Ctrl still
-        exists, just not used for this purpose under Mac). So for non-Mac platforms
-        this is the same as ControlDown() and under Mac this is the same as MetaDown().
-    */
-    bool CmdDown() const;
-
-    /**
-        Returns @true if the control key was down at the time of the key event.
-
-        Notice that GetModifiers() is easier to use correctly than this function
-        so you should consider using it in new code.
-    */
-    bool ControlDown() const;
-
     /**
         Returns the virtual key code. ASCII events return normal ASCII values,
         while non-ASCII events return values such as @b WXK_LEFT for the left cursor
-        key. See @ref page_keycodes for a full list of the virtual key codes.
+        key. See ::wxKeyCode for a full list of the virtual key codes.
 
         Note that in Unicode build, the returned value is meaningful only if the
         user entered a character that can be represented in current locale's default
@@ -747,33 +826,6 @@ public:
     */
     int GetKeyCode() const;
 
-    /**
-        Return the bitmask of modifier keys which were pressed when this event
-        happened. See @ref page_keymodifiers for the full list of modifiers.
-
-        Notice that this function is easier to use correctly than, for example,
-        ControlDown() because when using the latter you also have to remember to
-        test that none of the other modifiers is pressed:
-
-        @code
-        if ( ControlDown() && !AltDown() && !ShiftDown() && !MetaDown() )
-            ... handle Ctrl-XXX ...
-        @endcode
-
-        and forgetting to do it can result in serious program bugs (e.g. program
-        not working with European keyboard layout where ALTGR key which is seen by
-        the program as combination of CTRL and ALT is used). On the other hand,
-        you can simply write:
-
-        @code
-        if ( GetModifiers() == wxMOD_CONTROL )
-            ... handle Ctrl-XXX ...
-        @endcode
-
-        with this function.
-    */
-    int GetModifiers() const;
-
     //@{
     /**
         Obtains the position (in client coordinates) at which the key was pressed.
@@ -817,33 +869,6 @@ public:
         Returns the Y position (in client coordinates) of the event.
     */
     wxCoord GetY() const;
-
-    /**
-        Returns @true if either CTRL or ALT keys was down at the time of the
-        key event.
-
-        Note that this function does not take into account neither SHIFT nor
-        META key states (the reason for ignoring the latter is that it is
-        common for NUMLOCK key to be configured as META under X but the key
-        presses even while NUMLOCK is on should be still processed normally).
-    */
-    bool HasModifiers() const;
-
-    /**
-        Returns @true if the Meta key was down at the time of the key event.
-
-        Notice that GetModifiers() is easier to use correctly than this function
-        so you should consider using it in new code.
-    */
-    bool MetaDown() const;
-
-    /**
-        Returns @true if the shift key was down at the time of the key event.
-
-        Notice that GetModifiers() is easier to use correctly than this function
-        so you should consider using it in new code.
-    */
-    bool ShiftDown() const;
 };
 
 
@@ -1084,6 +1109,9 @@ public:
         Constructor.
     */
     wxWindowCreateEvent(wxWindow* win = NULL);
+
+    /// Retutn the window being created.
+    wxWindow *GetWindow() const;
 };
 
 
@@ -1482,6 +1510,12 @@ public:
     parent window receives @c wxEVT_LEAVE_WINDOW event not only when the
     mouse leaves the window entirely but also when it enters one of its children.
 
+    The position associated with a mouse event is expressed in the window
+    coordinates of the window which generated the event, you can use
+    wxWindow::ClientToScreen() to convert it to screen coordinates and possibly
+    call wxWindow::ScreenToClient() next to convert it to window coordinates of
+    another window.
+
     @note Note that under Windows CE mouse enter and leave events are not natively
           supported by the system but are generated by wxWidgets itself. This has several
           drawbacks: the LEAVE_WINDOW event might be received some time after the mouse
@@ -1546,9 +1580,10 @@ public:
     @library{wxcore}
     @category{events}
 
-    @see wxKeyEvent::CmdDown
+    @see wxKeyEvent
 */
-class wxMouseEvent : public wxEvent
+class wxMouseEvent : public wxEvent,
+                     public wxMouseState
 {
 public:
     /**
@@ -1576,11 +1611,6 @@ public:
     */
     wxMouseEvent(wxEventType mouseEventType = wxEVT_NULL);
 
-    /**
-        Returns @true if the Alt key was down at the time of the event.
-    */
-    bool AltDown() const;
-
     /**
         Returns @true if the event was a first extra button double click.
     */
@@ -1659,18 +1689,6 @@ public:
     */
     bool ButtonUp(int = wxMOUSE_BTN_ANY) const;
 
-    /**
-        Same as MetaDown() under Mac, same as ControlDown() elsewhere.
-
-        @see wxKeyEvent::CmdDown
-    */
-    bool CmdDown() const;
-
-    /**
-        Returns @true if the control key was down at the time of the event.
-    */
-    bool ControlDown() const;
-
     /**
         Returns @true if this was a dragging event (motion while a button is depressed).
 
@@ -1753,6 +1771,14 @@ 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.
+
+        Note that only some models of mouse have horizontal wheel axis.
+    */
+    int GetWheelAxis() const;
+
     /**
         Returns X coordinate of the physical mouse event position.
     */
@@ -1865,11 +1891,6 @@ public:
         Returns @true if the right mouse button changed to up.
     */
     bool RightUp() const;
-
-    /**
-        Returns @true if the shift key was down at the time of the event.
-    */
-    bool ShiftDown() const;
 };
 
 
@@ -1943,71 +1964,71 @@ public:
         Process a command for a range of window identifiers, supplying the minimum and
         maximum window identifiers, command event identifier, and member function.
     @event{EVT_BUTTON(id, func)}
-        Process a wxEVT_COMMAND_BUTTON_CLICKED command, which is generated by a wxButton control.
+        Process a @c wxEVT_COMMAND_BUTTON_CLICKED command, which is generated by a wxButton control.
     @event{EVT_CHECKBOX(id, func)}
-        Process a wxEVT_COMMAND_CHECKBOX_CLICKED command, which is generated by a wxCheckBox control.
+        Process a @c wxEVT_COMMAND_CHECKBOX_CLICKED command, which is generated by a wxCheckBox control.
     @event{EVT_CHOICE(id, func)}
-        Process a wxEVT_COMMAND_CHOICE_SELECTED command, which is generated by a wxChoice control.
+        Process a @c wxEVT_COMMAND_CHOICE_SELECTED command, which is generated by a wxChoice control.
     @event{EVT_COMBOBOX(id, func)}
-        Process a wxEVT_COMMAND_COMBOBOX_SELECTED command, which is generated by a wxComboBox control.
+        Process a @c wxEVT_COMMAND_COMBOBOX_SELECTED command, which is generated by a wxComboBox control.
     @event{EVT_LISTBOX(id, func)}
-        Process a wxEVT_COMMAND_LISTBOX_SELECTED command, which is generated by a wxListBox control.
+        Process a @c wxEVT_COMMAND_LISTBOX_SELECTED command, which is generated by a wxListBox control.
     @event{EVT_LISTBOX_DCLICK(id, func)}
-        Process a wxEVT_COMMAND_LISTBOX_DOUBLECLICKED command, which is generated by a wxListBox control.
+        Process a @c wxEVT_COMMAND_LISTBOX_DOUBLECLICKED command, which is generated by a wxListBox control.
     @event{EVT_MENU(id, func)}
-        Process a wxEVT_COMMAND_MENU_SELECTED command, which is generated by a menu item.
+        Process a @c wxEVT_COMMAND_MENU_SELECTED command, which is generated by a menu item.
     @event{EVT_MENU_RANGE(id1, id2, func)}
-        Process a wxEVT_COMMAND_MENU_RANGE command, which is generated by a range of menu items.
+        Process a @c wxEVT_COMMAND_MENU_RANGE command, which is generated by a range of menu items.
     @event{EVT_CONTEXT_MENU(func)}
         Process the event generated when the user has requested a popup menu to appear by
         pressing a special keyboard key (under Windows) or by right clicking the mouse.
     @event{EVT_RADIOBOX(id, func)}
-        Process a wxEVT_COMMAND_RADIOBOX_SELECTED command, which is generated by a wxRadioBox control.
+        Process a @c wxEVT_COMMAND_RADIOBOX_SELECTED command, which is generated by a wxRadioBox control.
     @event{EVT_RADIOBUTTON(id, func)}
-        Process a wxEVT_COMMAND_RADIOBUTTON_SELECTED command, which is generated by a wxRadioButton control.
+        Process a @c wxEVT_COMMAND_RADIOBUTTON_SELECTED command, which is generated by a wxRadioButton control.
     @event{EVT_SCROLLBAR(id, func)}
-        Process a wxEVT_COMMAND_SCROLLBAR_UPDATED command, which is generated by a wxScrollBar
+        Process a @c wxEVT_COMMAND_SCROLLBAR_UPDATED command, which is generated by a wxScrollBar
         control. This is provided for compatibility only; more specific scrollbar event macros
         should be used instead (see wxScrollEvent).
     @event{EVT_SLIDER(id, func)}
-        Process a wxEVT_COMMAND_SLIDER_UPDATED command, which is generated by a wxSlider control.
+        Process a @c wxEVT_COMMAND_SLIDER_UPDATED command, which is generated by a wxSlider control.
     @event{EVT_TEXT(id, func)}
-        Process a wxEVT_COMMAND_TEXT_UPDATED command, which is generated by a wxTextCtrl control.
+        Process a @c wxEVT_COMMAND_TEXT_UPDATED command, which is generated by a wxTextCtrl control.
     @event{EVT_TEXT_ENTER(id, func)}
-        Process a wxEVT_COMMAND_TEXT_ENTER command, which is generated by a wxTextCtrl control.
+        Process a @c wxEVT_COMMAND_TEXT_ENTER command, which is generated by a wxTextCtrl control.
         Note that you must use wxTE_PROCESS_ENTER flag when creating the control if you want it
         to generate such events.
     @event{EVT_TEXT_MAXLEN(id, func)}
-        Process a wxEVT_COMMAND_TEXT_MAXLEN command, which is generated by a wxTextCtrl control
+        Process a @c wxEVT_COMMAND_TEXT_MAXLEN command, which is generated by a wxTextCtrl control
         when the user tries to enter more characters into it than the limit previously set
         with SetMaxLength().
     @event{EVT_TOGGLEBUTTON(id, func)}
-        Process a wxEVT_COMMAND_TOGGLEBUTTON_CLICKED event.
+        Process a @c wxEVT_COMMAND_TOGGLEBUTTON_CLICKED event.
     @event{EVT_TOOL(id, func)}
-        Process a wxEVT_COMMAND_TOOL_CLICKED event (a synonym for wxEVT_COMMAND_MENU_SELECTED).
+        Process a @c wxEVT_COMMAND_TOOL_CLICKED event (a synonym for @c wxEVT_COMMAND_MENU_SELECTED).
         Pass the id of the tool.
     @event{EVT_TOOL_RANGE(id1, id2, func)}
-        Process a wxEVT_COMMAND_TOOL_CLICKED event for a range of identifiers. Pass the ids of the tools.
+        Process a @c wxEVT_COMMAND_TOOL_CLICKED event for a range of identifiers. Pass the ids of the tools.
     @event{EVT_TOOL_RCLICKED(id, func)}
-        Process a wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the tool.
+        Process a @c wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the tool.
     @event{EVT_TOOL_RCLICKED_RANGE(id1, id2, func)}
-        Process a wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass the ids of the tools.
+        Process a @c wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass the ids of the tools.
     @event{EVT_TOOL_ENTER(id, func)}
-        Process a wxEVT_COMMAND_TOOL_ENTER event. Pass the id of the toolbar itself.
+        Process a @c wxEVT_COMMAND_TOOL_ENTER event. Pass the id of the toolbar itself.
         The value of wxCommandEvent::GetSelection() is the tool id, or -1 if the mouse cursor
         has moved off a tool.
     @event{EVT_COMMAND_LEFT_CLICK(id, func)}
-        Process a wxEVT_COMMAND_LEFT_CLICK command, which is generated by a control (Windows 95 and NT only).
+        Process a @c wxEVT_COMMAND_LEFT_CLICK command, which is generated by a control (wxMSW only).
     @event{EVT_COMMAND_LEFT_DCLICK(id, func)}
-        Process a wxEVT_COMMAND_LEFT_DCLICK command, which is generated by a control (Windows 95 and NT only).
+        Process a @c wxEVT_COMMAND_LEFT_DCLICK command, which is generated by a control (wxMSW only).
     @event{EVT_COMMAND_RIGHT_CLICK(id, func)}
-        Process a wxEVT_COMMAND_RIGHT_CLICK command, which is generated by a control (Windows 95 and NT only).
+        Process a @c wxEVT_COMMAND_RIGHT_CLICK command, which is generated by a control (wxMSW only).
     @event{EVT_COMMAND_SET_FOCUS(id, func)}
-        Process a wxEVT_COMMAND_SET_FOCUS command, which is generated by a control (Windows 95 and NT only).
+        Process a @c wxEVT_COMMAND_SET_FOCUS command, which is generated by a control (wxMSW only).
     @event{EVT_COMMAND_KILL_FOCUS(id, func)}
-        Process a wxEVT_COMMAND_KILL_FOCUS command, which is generated by a control (Windows 95 and NT only).
+        Process a @c wxEVT_COMMAND_KILL_FOCUS command, which is generated by a control (wxMSW only).
     @event{EVT_COMMAND_ENTER(id, func)}
-        Process a wxEVT_COMMAND_ENTER command, which is generated by a control.
+        Process a @c wxEVT_COMMAND_ENTER command, which is generated by a control.
     @endEventTable
 
     @library{wxcore}
@@ -2019,7 +2040,7 @@ public:
     /**
         Constructor.
     */
-    wxCommandEvent(wxEventType commandEventType = 0, int id = 0);
+    wxCommandEvent(wxEventType commandEventType = wxEVT_NULL, int id = 0);
 
     /**
         Returns client data pointer for a listbox or choice selection event
@@ -2431,13 +2452,10 @@ public:
 
 
 
-/**
-    Indicates how a wxHelpEvent was generated.
-*/
 enum wxHelpEventOrigin
 {
-    wxHE_ORIGIN_UNKNOWN = -1,    /**< unrecognized event source. */
-    wxHE_ORIGIN_KEYBOARD,        /**< event generated from F1 key press. */
+    wxHE_ORIGIN_UNKNOWN = -1,
+    wxHE_ORIGIN_KEYBOARD,
 
     /** event generated by wxContextHelp or from the [?] button on
         the title bar (Windows). */
@@ -2480,13 +2498,26 @@ enum wxHelpEventOrigin
 class wxHelpEvent : public wxCommandEvent
 {
 public:
+    /**
+        Indicates how a wxHelpEvent was generated.
+    */
+    enum Origin
+    {
+        Origin_Unknown,    /**< unrecognized event source. */
+        Origin_Keyboard,   /**< event generated from F1 key press. */
+
+        /** event generated by wxContextHelp or from the [?] button on
+            the title bar (Windows). */
+        Origin_HelpButton
+    };
+
     /**
         Constructor.
     */
     wxHelpEvent(wxEventType type = wxEVT_NULL,
                 wxWindowID winid = 0,
                 const wxPoint& pt = wxDefaultPosition,
-                wxHelpEventOrigin origin = wxHE_ORIGIN_UNKNOWN);
+                wxHelpEvent::Origin origin = Origin_Unknown);
 
     /**
         Returns the origin of the help event which is one of the ::wxHelpEventOrigin
@@ -2497,7 +2528,7 @@ public:
 
         @see SetOrigin()
     */
-    wxHelpEventOrigin GetOrigin() const;
+    wxHelpEvent::Origin GetOrigin() const;
 
     /**
         Returns the left-click position of the mouse, in screen coordinates.
@@ -2510,7 +2541,7 @@ public:
 
         @see GetOrigin()
     */
-    void SetOrigin(wxHelpEventOrigin);
+    void SetOrigin(wxHelpEvent::Origin origin);
 
     /**
         Sets the left-click position of the mouse, in screen coordinates.
@@ -2531,7 +2562,7 @@ public:
     events and use the event table macros mentioned below only for the scrollbar-like
     controls.
 
-    @section wxscrollevent_diff The difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED
+    @section scrollevent_diff The difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED
 
     The EVT_SCROLL_THUMBRELEASE event is only emitted when actually dragging the thumb
     using the mouse and releasing it (This EVT_SCROLL_THUMBRELEASE event is also followed
@@ -2769,17 +2800,23 @@ public:
 /**
     @class wxWindowDestroyEvent
 
-    This event is sent from the wxWindow destructor wxWindow::~wxWindow() when a
-    window is destroyed.
+    This event is sent as early as possible during the window destruction
+    process.
 
-    When a class derived from wxWindow is destroyed its destructor will have
-    already run by the time this event is sent. Therefore this event will not
-    usually be received at all.
+    For the top level windows, as early as possible means that this is done by
+    wxFrame or wxDialog destructor, i.e. after the destructor of the derived
+    class was executed and so any methods specific to the derived class can't
+    be called any more from this event handler. If you need to do this, you
+    must call wxWindow::SendDestroyEvent() from your derived class destructor.
 
-    To receive this event wxEvtHandler::Connect() must be used (using an event
-    table macro will not work). Since it is received after the destructor has run,
-    an object should not handle its own wxWindowDestroyEvent, but it can be used
-    to get notification of the destruction of another window.
+    For the child windows, this event is generated just before deleting the
+    window from wxWindow::Destroy() (which is also called when the parent
+    window is deleted) or from the window destructor if operator @c delete was
+    used directly (which is not recommended for this very reason).
+
+    It is usually pointless to handle this event in the window itself but it ca
+    be very useful to receive notifications about the window destruction in the
+    parent window or in any other object interested in this window.
 
     @library{wxcore}
     @category{events}
@@ -2793,6 +2830,9 @@ public:
         Constructor.
     */
     wxWindowDestroyEvent(wxWindow* win = NULL);
+
+    /// Retutn the window being destroyed.
+    wxWindow *GetWindow() const;
 };
 
 
@@ -2949,6 +2989,27 @@ public:
     This allows the wxWindow::Close function to return @true or @false depending
     on whether the close instruction was honoured or not.
 
+    Example of a wxCloseEvent handler:
+
+    @code
+        void MyFrame::OnClose(wxCloseEvent& event)
+        {
+            if ( event.CanVeto() && m_bFileNotSaved )
+            {
+                if ( wxMessageBox("The file has not been saved... continue closing?",
+                                  "Please confirm",
+                                  wxICON_QUESTION | wxYES_NO) != wxYES )
+                {
+                    event.Veto();
+                    return;
+                }
+            }
+
+            Destroy();  // you may also do:  event.Skip();
+                        // since the default event handler does call Destroy(), too
+        }
+    @endcode
+
     The EVT_END_SESSION event is slightly different as it is sent by the system
     when the user session is ending (e.g. because of log out or shutdown) and
     so all windows are being forcefully closed. At least under MSW, after the
@@ -3005,11 +3066,6 @@ public:
     */
     void SetCanVeto(bool canVeto);
 
-    /**
-        Sets the 'force' flag.
-    */
-    void SetForce(bool force) const;
-
     /**
         Sets the 'logging off' flag.
     */
@@ -3033,7 +3089,7 @@ public:
     these do not include menu command events, which are
     handled using wxCommandEvent objects.
 
-    The default handler for wxEVT_MENU_HIGHLIGHT displays help
+    The default handler for @c wxEVT_MENU_HIGHLIGHT displays help
     text in the first field of the status bar.
 
     @beginEventTable{wxMenuEvent}
@@ -3256,7 +3312,7 @@ public:
 /**
     @class wxSetCursorEvent
 
-    A SetCursorEvent is generated when the mouse cursor is about to be set as a
+    A wxSetCursorEvent is generated when the mouse cursor is about to be set as a
     result of mouse motion.
 
     This event gives the application the chance to perform specific mouse cursor
@@ -3317,9 +3373,65 @@ public:
 // Global functions/macros
 // ============================================================================
 
-/** @ingroup group_funcmacro_misc */
+/** @addtogroup group_funcmacro_events */
 //@{
 
+/**
+    A special event type usually used to indicate that some wxEvent has yet
+    no type assigned.
+*/
+wxEventType wxEVT_NULL;
+
+/**
+    Each wxEvent-derived class has an @e event-type associated.
+    See the macro DEFINE_EVENT_TYPE() for more info.
+
+    @see @ref overview_eventhandling_custom
+*/
+typedef int wxEventType;
+
+/**
+    Initializes a new event type using wxNewEventType().
+*/
+#define DEFINE_EVENT_TYPE(name)     const wxEventType name = wxNewEventType();
+
+/**
+    Generates a new unique event type.
+*/
+wxEventType wxNewEventType();
+
+/**
+    Use this macro inside a class declaration to declare a @e static event table
+    for that class.
+
+    In the implementation file you'll need to use the BEGIN_EVENT_TABLE()
+    and the END_EVENT_TABLE() macros, plus some additional @c EVT_xxx macro
+    to capture events.
+
+    @see @ref overview_eventhandling_eventtables
+*/
+#define DECLARE_EVENT_TABLE()
+
+/**
+    Use this macro in a source file to start listing @e static event handlers
+    for a specific class.
+
+    Use END_EVENT_TABLE() to terminate the event-declaration block.
+
+    @see @ref overview_eventhandling_eventtables
+*/
+#define BEGIN_EVENT_TABLE(theClass, baseClass)
+
+/**
+    Use this macro in a source file to end listing @e static event handlers
+    for a specific class.
+
+    Use BEGIN_EVENT_TABLE() to start the event-declaration block.
+
+    @see @ref overview_eventhandling_eventtables
+*/
+#define END_EVENT_TABLE()
+
 /**
     In a GUI application, this function posts @a event to the specified @e dest
     object using wxEvtHandler::AddPendingEvent().