X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e23e368bc473cc6b5415850a388f737725053713..ee1377e1fa364f364b9a896c786c95ef177164cf:/interface/wx/event.h?ds=sidebyside diff --git a/interface/wx/event.h b/interface/wx/event.h index f8cd19f9ec..639f8bdb59 100644 --- a/interface/wx/event.h +++ b/interface/wx/event.h @@ -318,6 +318,29 @@ public: +/** + Helper class to temporarily change an event to not propagate. +*/ +class wxPropagationDisabler +{ +public: + wxPropagationDisabler(wxEvent& event); + ~wxPropagationDisabler(); +}; + + +/** + Helper class to temporarily lower propagation level. +*/ +class wxPropagateOnce +{ +public: + wxPropagateOnce(wxEvent& event); + ~wxPropagateOnce(); +}; + + + /** @class wxEvtHandler @@ -1065,6 +1088,40 @@ public: //@} + /** + @name Global event filters. + + Methods for working with the global list of event filters. + + Event filters can be defined to pre-process all the events that happen + in an application, see wxEventFilter documentation for more information. + */ + //@{ + + /** + Add an event filter whose FilterEvent() method will be called for each + and every event processed by wxWidgets. + + The filters are called in LIFO order and wxApp is registered as an + event filter by default. The pointer must remain valid until it's + removed with RemoveFilter() and is not deleted by wxEvtHandler. + + @since 2.9.3 + */ + static void AddFilter(wxEventFilter* filter); + + /** + Remove a filter previously installed with AddFilter(). + + It's an error to remove a filter that hadn't been previously added or + was already removed. + + @since 2.9.3 + */ + static void RemoveFilter(wxEventFilter* filter); + + //@} + protected: /** Method called by ProcessEvent() before examining this object event @@ -1300,23 +1357,35 @@ enum wxKeyCategoryFlags @beginEventTable{wxKeyEvent} @event{EVT_KEY_DOWN(func)} - Process a @c wxEVT_KEY_DOWN event (any key has been pressed). + Process a @c wxEVT_KEY_DOWN event (any key has been pressed). If this + event is handled and not skipped, @c wxEVT_CHAR will not be generated + at all for this key press (but @c wxEVT_KEY_UP will be). @event{EVT_KEY_UP(func)} Process a @c wxEVT_KEY_UP event (any key has been released). @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(), no further keyboard events are - generated. 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. Also please note - that currently this event is not generated by wxOSX/Cocoa port. + 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 @@ -1459,10 +1528,55 @@ 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; }; +enum +{ + wxJOYSTICK1, + wxJOYSTICK2 +}; + +// Which button is down? +enum +{ + wxJOY_BUTTON_ANY = -1, + wxJOY_BUTTON1 = 1, + wxJOY_BUTTON2 = 2, + wxJOY_BUTTON3 = 4, + wxJOY_BUTTON4 = 8 +}; + + /** @class wxJoystickEvent @@ -1548,11 +1662,15 @@ public: /** Returns the x, y position of the joystick event. + + These coordinates are valid for all the events except wxEVT_JOY_ZMOVE. */ wxPoint GetPosition() const; /** Returns the z position of the joystick event. + + This method can only be used for wxEVT_JOY_ZMOVE events. */ int GetZPosition() const; @@ -2789,12 +2907,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)} @@ -2816,6 +2930,8 @@ public: /** Returns the device context associated with the erase event to draw on. + + The returned pointer is never @NULL. */ wxDC* GetDC() const; }; @@ -3775,9 +3891,12 @@ public: wxMenuEvent(wxEventType type = wxEVT_NULL, int id = 0, wxMenu* menu = NULL); /** - Returns the menu which is being opened or closed. This method should only be - used with the @c OPEN and @c CLOSE events and even for them the - returned pointer may be @NULL in some ports. + Returns the menu which is being opened or closed. + + This method can only be used with the @c OPEN and @c CLOSE events. + + The returned value is never @NULL in the ports implementing this + function, which currently includes all the major ones. */ wxMenu* GetMenu() const; @@ -3948,6 +4067,10 @@ public: size of the window, you may need to clear the DC explicitly and repaint the whole window. In which case, you may need to call wxWindow::Refresh to invalidate the entire window. + @b Important : Sizers ( see @ref overview_sizer ) rely on size events to function + correctly. Therefore, in a sizer-based layout, do not forget to call Skip on all + size events you catch (and don't catch size events at all when you don't need to). + @beginEventTable{wxSizeEvent} @event{EVT_SIZE(func)} Process a @c wxEVT_SIZE event. @@ -4383,6 +4506,7 @@ wxEventType wxEVT_HELP; wxEventType wxEVT_DETAILED_HELP; wxEventType wxEVT_COMMAND_TEXT_UPDATED; wxEventType wxEVT_COMMAND_TOOL_CLICKED; +wxEventType wxEVT_WINDOW_MODAL_DIALOG_CLOSED;