X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/aacbb5dc43ec99d4a5b5cbdfd34ee0112ad58ba1..d2ae3af890800b7844df1673e6c9ae0e63b3dd68:/interface/wx/event.h diff --git a/interface/wx/event.h b/interface/wx/event.h index 6d7b85754d..3bcdf8f45f 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; @@ -2608,6 +2726,10 @@ public: Returns the integer identifier corresponding to a listbox, choice or radiobox selection (only if the event was a selection, not a deselection), or a boolean value representing the value of a checkbox. + + For a menu item, this method returns -1 if the item is not checkable or + a boolean value (true or false) for checkable items indicating the new + state of the item. */ int GetInt() const; @@ -2785,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)} @@ -2812,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; }; @@ -3023,27 +3143,29 @@ public: /** @class wxThreadEvent - This class adds some simple functionalities to wxCommandEvent conceived - for inter-threads communications. + This class adds some simple functionality to wxEvent to facilitate + inter-thread communication. - This event is not natively emitted by any control/class: this is just - an helper class for the user. + This event is not natively emitted by any control/class: it is just + a helper class for the user. Its most important feature is the GetEventCategory() implementation which - allows thread events to @b NOT be processed by wxEventLoopBase::YieldFor calls + allows thread events @b NOT to be processed by wxEventLoopBase::YieldFor calls (unless the @c wxEVT_CATEGORY_THREAD is specified - which is never in wx code). @library{wxcore} @category{events,threading} @see @ref overview_thread, wxEventLoopBase::YieldFor + + @since 2.9.0 */ -class wxThreadEvent : public wxCommandEvent +class wxThreadEvent : public wxEvent { public: /** Constructor. */ - wxThreadEvent(wxEventType eventType = wxEVT_COMMAND_THREAD, int id = wxID_ANY); + wxThreadEvent(wxEventType eventType = wxEVT_THREAD, int id = wxID_ANY); /** Clones this event making sure that all internal members which use @@ -3090,6 +3212,37 @@ public: */ template T GetPayload() const; + + /** + Returns extra information integer value. + */ + long GetExtraLong() const; + + /** + Returns stored integer value. + */ + int GetInt() const; + + /** + Returns stored string value. + */ + wxString GetString() const; + + + /** + Sets the extra information value. + */ + void SetExtraLong(long extraLong); + + /** + Sets the integer value. + */ + void SetInt(int intCommand); + + /** + Sets the string value. + */ + void SetString(const wxString& string); }; @@ -3319,11 +3472,19 @@ enum wxIdleMode (and especially the first one) increase the system load and so should be avoided if possible. - By default, idle events are sent to all windows (and also wxApp, as usual). - If this is causing a significant overhead in your application, you can call - wxIdleEvent::SetMode with the value wxIDLE_PROCESS_SPECIFIED, and set the - wxWS_EX_PROCESS_IDLE extra window style for every window which should receive - idle events. + By default, idle events are sent to all windows, including even the hidden + ones because they may be shown if some condition is met from their @c + wxEVT_IDLE (or related @c wxEVT_UPDATE_UI) handler. The children of hidden + windows do not receive idle events however as they can't change their state + in any way noticeable by the user. Finally, the global wxApp object also + receives these events, as usual, so it can be used for any global idle time + processing. + + If sending idle events to all windows is causing a significant overhead in + your application, you can call wxIdleEvent::SetMode with the value + wxIDLE_PROCESS_SPECIFIED, and set the wxWS_EX_PROCESS_IDLE extra window + style for every window which should receive idle events, all the other ones + will not receive them in this case. @beginEventTable{wxIdleEvent} @event{EVT_IDLE(func)} @@ -3464,8 +3625,8 @@ public: This event is mainly used by wxWidgets implementations. A wxNavigationKeyEvent handler is automatically provided by wxWidgets - when you make a class into a control container with the macro - WX_DECLARE_CONTROL_CONTAINER. + when you enable keyboard navigation inside a window by inheriting it from + wxNavigationEnabled<>. @beginEventTable{wxNavigationKeyEvent} @event{EVT_NAVIGATION_KEY(func)} @@ -3738,9 +3899,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; @@ -3865,6 +4029,9 @@ public: @event{EVT_MOVE_START(func)} Process a @c wxEVT_MOVE_START event, which is generated when the user starts to move or size a window. wxMSW only. + @event{EVT_MOVING(func)} + Process a @c wxEVT_MOVING event, which is generated while the user is + moving the window. wxMSW only. @event{EVT_MOVE_END(func)} Process a @c wxEVT_MOVE_END event, which is generated when the user stops moving or sizing a window. wxMSW only. @@ -3911,6 +4078,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. @@ -4244,7 +4415,7 @@ wxEventType wxEVT_COMMAND_TOOL_DROPDOWN_CLICKED; wxEventType wxEVT_COMMAND_TOOL_ENTER; wxEventType wxEVT_COMMAND_COMBOBOX_DROPDOWN; wxEventType wxEVT_COMMAND_COMBOBOX_CLOSEUP; -wxEventType wxEVT_COMMAND_THREAD; +wxEventType wxEVT_THREAD; wxEventType wxEVT_LEFT_DOWN; wxEventType wxEVT_LEFT_UP; wxEventType wxEVT_MIDDLE_DOWN; @@ -4346,6 +4517,7 @@ wxEventType wxEVT_HELP; wxEventType wxEVT_DETAILED_HELP; wxEventType wxEVT_COMMAND_TEXT_UPDATED; wxEventType wxEVT_COMMAND_TOOL_CLICKED; +wxEventType wxEVT_WINDOW_MODAL_DIALOG_CLOSED;