X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/1f1d2182ffe4feb82a1e674266f47d172ed3cb3c..06e9cf134f284d1ce992617bd63d3f781af70575:/interface/event.h diff --git a/interface/event.h b/interface/event.h index e97a4d699a..81ff87735c 100644 --- a/interface/event.h +++ b/interface/event.h @@ -1,2828 +1,3151 @@ ///////////////////////////////////////////////////////////////////////////// // Name: event.h -// Purpose: interface of wx*Event classes +// Purpose: interface of wxEventHandler, wxEventBlocker and many +// wxEvent-derived classes // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// -/** - @class wxKeyEvent - @wxheader{event.h} - - This event class contains information about keypress (character) events. - - Notice that there are three different kinds of keyboard events in wxWidgets: - key down and up events and char events. The difference between the first two - is clear - the first corresponds to a key press and the second to a key - release - otherwise they are identical. Just note that if the key is - maintained in a pressed state you will typically get a lot of (automatically - generated) down events but only one up so it is wrong to assume that there is - one up event corresponding to each down one. - - 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. - 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. - - A few examples to clarify this (all assume that CAPS LOCK is unpressed - and the standard US keyboard): when the @c 'A' key is pressed, the key down - event key code is equal to @c ASCII A == 65. But the char event key code - is @c ASCII a == 97. On the other hand, if you press both SHIFT and - @c 'A' keys simultaneously , the key code in key down event will still be - just @c 'A' while the char event key code parameter will now be @c 'A' - as well. - - Although in this simple case it is clear that the correct key code could be - found in the key down event handler by checking the value returned by - wxKeyEvent::ShiftDown(), in general you should use @c EVT_CHAR for this as - for non-alphanumeric keys the translation is keyboard-layout dependent and - can only be done properly by the system itself. - - Another kind of translation is done when the control key is pressed: for - example, for CTRL-A key press the key down event still carries the - same key code @c 'a' as usual but the char event will have key code of 1, - the ASCII value of this key combination. - You may discover how the other keys on your system behave interactively by - running the @ref page_samples_text wxWidgets sample and pressing some keys - in any of the text controls shown in it. - @b Tip: be sure to call @c event.Skip() for events that you don't process in - key event function, otherwise menu shortcuts may cease to work under Windows. +/** + @class wxEvent + @wxheader{event.h} - @note If a key down (@c EVT_KEY_DOWN) event is caught and the event handler - does not call @c event.Skip() then the corresponding char event - (@c EVT_CHAR) will not happen. - This is by design and enables the programs that handle both types of - events to be a bit simpler. + An event is a structure holding information about an event passed to a + callback or member function. - @note For Windows programmers: The key and char events in wxWidgets are - similar to but slightly different from Windows @c WM_KEYDOWN and - @c WM_CHAR events. In particular, Alt-x combination will generate a - char event in wxWidgets (unless it is used as an accelerator). + wxEvent used to be a multipurpose event object, and is an abstract base class + for other event classes (see below). + For more information about events, see the @ref overview_eventhandling overview. - @beginEventTable{wxKeyEvent} - @event{EVT_KEY_DOWN(func)}: - Process a wxEVT_KEY_DOWN event (any key has been pressed). - @event{EVT_KEY_UP(func)}: - Process a wxEVT_KEY_UP event (any key has been released). - @event{EVT_CHAR(func)}: - Process a wxEVT_CHAR event. - @endEventTable + @beginWxPerlOnly + In wxPerl custom event classes should be derived from + @c Wx::PlEvent and @c Wx::PlCommandEvent. + @endWxPerlOnly - @library{wxcore} + @library{wxbase} @category{events} + + @see wxCommandEvent, wxMouseEvent */ -class wxKeyEvent : public wxEvent +class wxEvent : public wxObject { public: /** - Constructor. - Currently, the only valid event types are @c wxEVT_CHAR and @c wxEVT_CHAR_HOOK. + Constructor. Should not need to be used directly by an application. */ - wxKeyEvent(wxEventType keyEventType = wxEVT_NULL); + wxEvent(int id = 0, wxEventType eventType = wxEVT_NULL); /** - Returns @true if the Alt key was down at the time of the key event. + Returns a copy of the event. - Notice that GetModifiers() is easier to use correctly than this function - so you should consider using it in new code. + Any event that is posted to the wxWidgets event system for later action (via + wxEvtHandler::AddPendingEvent 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 + (or some event derived from them) are ever posted. + + All wxWidgets events implement a copy constructor, so the easiest way of + implementing the Clone function is to implement a copy constructor for + a new event (call it MyEvent) and then define the Clone function like this: + + @code + wxEvent *Clone() const { return new MyEvent(*this); } + @endcode */ - bool AltDown() const; + virtual wxEvent* Clone() const = 0; /** - 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(). + Returns the object (usually a window) associated with the event, if any. */ - bool CmdDown() const; + wxObject* GetEventObject() 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. + Returns the identifier of the given event type, such as @c wxEVT_COMMAND_BUTTON_CLICKED. */ - bool ControlDown() const; + wxEventType GetEventType() 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. - - 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 - charset. You can obtain the corresponding Unicode character using GetUnicodeKey(). + Returns the identifier associated with this event, such as a button command id. */ - int GetKeyCode() const; + int GetId() 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. + Returns @true if the event handler should be skipped, @false otherwise. */ - int GetModifiers() const; + bool GetSkipped() const; - //@{ /** - Obtains the position (in client coordinates) at which the key was pressed. + 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). */ - wxPoint GetPosition() const; - void GetPosition(long* x, long* y) const; - //@} + long GetTimestamp() const; /** - Returns the raw key code for this event. This is a platform-dependent scan code - which should only be used in advanced applications. + Returns @true if the event is or is derived from wxCommandEvent else it returns @false. - @note Currently the raw key codes are not supported by all ports, use - @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available. + @note exists only for optimization purposes. */ - wxUint32 GetRawKeyCode() const; + bool IsCommandEvent() const; /** - Returns the low level key flags for this event. The flags are - platform-dependent and should only be used in advanced applications. + Sets the propagation level to the given value (for example returned from an + earlier call to wxEvent::StopPropagation). + */ + void ResumePropagation(int propagationLevel); - @note Currently the raw key flags are not supported by all ports, use - @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available. + /** + Sets the originating object. */ - wxUint32 GetRawKeyFlags() const; + void SetEventObject(wxObject* object); /** - Returns the Unicode character corresponding to this key event. + Sets the event type. + */ + void SetEventType(wxEventType type); - This function is only available in Unicode build, i.e. when - @c wxUSE_UNICODE is 1. + /** + Sets the identifier associated with this event, such as a button command id. */ - wxChar GetUnicodeKey() const; + void SetId(int id); /** - Returns the X position (in client coordinates) of the event. + Sets the timestamp for the event. */ - wxCoord GetX() const; + void SetTimestamp(long = 0); /** - Returns the Y position (in client coordinates) of the event. + Test if this event should be propagated or not, i.e. if the propagation level + is currently greater than 0. */ - wxCoord GetY() const; + bool ShouldPropagate() const; /** - Returns @true if either CTRL or ALT keys was down at the time of the - key event. + This method can be used inside an event handler to control whether further + event handlers bound to this event will be called after the current one returns. - 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). + Without Skip() (or equivalently if Skip(@false) is used), the event will not + be processed any more. If Skip(@true) is called, the event processing system + continues searching for a further handler function for this event, even though + it has been processed already in the current handler. + + In general, it is recommended to skip all non-command events to allow the + default handling to take place. The command events are, however, normally not + skipped as usually a single command such as a button click or menu item + selection must only be processed by one handler. */ - bool HasModifiers() const; + void Skip(bool skip = true); /** - Returns @true if the Meta key was down at the time of the key event. + Stop the event from propagating to its parent window. - Notice that GetModifiers() is easier to use correctly than this function - so you should consider using it in new code. + Returns the old propagation level value which may be later passed to + ResumePropagation() to allow propagating the event again. */ - bool MetaDown() const; + int StopPropagation(); +protected: /** - Returns @true if the shift key was down at the time of the key event. + Indicates how many levels the event can propagate. - Notice that GetModifiers() is easier to use correctly than this function - so you should consider using it in new code. - */ - bool ShiftDown() const; -}; + This member is protected and should typically only be set in the constructors + of the derived classes. It may be temporarily changed by StopPropagation() + and ResumePropagation() and tested with ShouldPropagate(). + The initial value is set to either @c wxEVENT_PROPAGATE_NONE (by default) + meaning that the event shouldn't be propagated at all or to + @c wxEVENT_PROPAGATE_MAX (for command events) meaning that it should be + propagated as much as necessary. + Any positive number means that the event should be propagated but no more than + the given number of times. E.g. the propagation level may be set to 1 to + propagate the event to its parent only, but not to its grandparent. + */ + int m_propagationLevel; +}; /** - @class wxJoystickEvent + @class wxEventBlocker @wxheader{event.h} - This event class contains information about joystick events, particularly - events received by windows. + This class is a special event handler which allows to discard + any event (or a set of event types) directed to a specific window. - @beginEventTable{wxJoystickEvent} - @style{EVT_JOY_BUTTON_DOWN(func)}: - Process a wxEVT_JOY_BUTTON_DOWN event. - @style{EVT_JOY_BUTTON_UP(func)}: - Process a wxEVT_JOY_BUTTON_UP event. - @style{EVT_JOY_MOVE(func)}: - Process a wxEVT_JOY_MOVE event. - @style{EVT_JOY_ZMOVE(func)}: - Process a wxEVT_JOY_ZMOVE event. - @style{EVT_JOYSTICK_EVENTS(func)}: - Processes all joystick events. - @endEventTable + Example: + + @code + void MyWindow::DoSomething() + { + { + // block all events directed to this window while + // we do the 1000 FunctionWhichSendsEvents() calls + wxEventBlocker blocker(this); + + for ( int i = 0; i 1000; i++ ) + FunctionWhichSendsEvents(i); + + } // ~wxEventBlocker called, old event handler is restored + + // the event generated by this call will be processed: + FunctionWhichSendsEvents(0) + } + @endcode @library{wxcore} @category{events} - @see wxJoystick + @see @ref overview_eventhandling, wxEvtHandler */ -class wxJoystickEvent : public wxEvent +class wxEventBlocker : public wxEvtHandler { public: /** - Constructor. + Constructs the blocker for the given window and for the given event type. + + If @a type is @c wxEVT_ANY, then all events for that window are blocked. + You can call Block() after creation to add other event types to the list + of events to block. + + Note that the @a win window @b must remain alive until the + wxEventBlocker object destruction. */ - wxJoystickEvent(wxEventType eventType = wxEVT_NULL, int state = 0, - int joystick = wxJOYSTICK1, - int change = 0); + wxEventBlocker(wxWindow* win, wxEventType = wxEVT_ANY); /** - Returns @true if the event was a down event from the specified button - (or any button). + Destructor. The blocker will remove itself from the chain of event handlers for + the window provided in the constructor, thus restoring normal processing of events. + */ + virtual ~wxEventBlocker(); - @param button - Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to - indicate any button down event. + /** + Adds to the list of event types which should be blocked the given @a eventType. */ - bool ButtonDown(int button = wxJOY_BUTTON_ANY) const; + void Block(wxEventType eventType); +}; + + + +/** + @class wxEvtHandler + @wxheader{event.h} + + A class that can handle events from the windowing system. + wxWindow (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. + + @library{wxbase} + @category{events} + + @see @ref overview_eventhandling +*/ +class wxEvtHandler : public wxObject +{ +public: + /** + Constructor. + */ + wxEvtHandler(); /** - Returns @true if the specified button (or any button) was in a down state. + Destructor. - @param button - Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to - indicate any button down event. + 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. */ - bool ButtonIsDown(int button = wxJOY_BUTTON_ANY) const; + virtual ~wxEvtHandler(); /** - Returns @true if the event was an up event from the specified button - (or any button). + This function posts an event to be processed later. - @param button - Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to - indicate any button down event. + The difference between sending an event (using the ProcessEvent + method) and posting it is that in the first case the event is + processed before the function returns, while in the second case, + the function returns immediately and the event will be processed + sometime later (usually during the next event loop iteration). + + A copy of 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 gets processed. + + This is also the method to call for inter-thread communication - it will post + events safely between different threads which means that this method is + thread-safe by using critical sections where needed. In a multi-threaded program, + you often need to inform the main GUI thread about the status of other working + threads and such notification should be done using this method. + + This method automatically wakes up idle handling if the underlying window + system is currently idle and thus would not send any idle events. + (Waking up idle handling is done calling ::wxWakeUpIdle.) + + @param event + Event to add to process queue. */ - bool ButtonUp(int button = wxJOY_BUTTON_ANY) const; + virtual void AddPendingEvent(const wxEvent& event); /** - Returns the identifier of the button changing state. + Connects the given function dynamically with the event handler, id and event type. + This is an alternative to the use of static event tables. - This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4. + See the @ref page_samples_event sample for usage. + + This specific overload allows you to connect an event handler to a @e range + of @e source IDs. + Do not confuse @e source IDs with event @e types: source IDs identify the + event generator objects (typically wxMenuItem or wxWindow objects) while the + event @e type identify which type of events should be handled by the + given @e function (an event generator object may generate many different + types of events!). + + @param id + The first ID of the identifier range to be associated with the event + handler function. + @param lastId + The last ID of the identifier range to be associated with the event + handler function. + @param eventType + The event type to be associated with this event handler. + @param function + The event handler function. Note that this function should + be explicitly converted to the correct type which can be done using a macro + called @c wxFooEventHandler for the handler for any @c wxFooEvent. + @param userData + Data to be associated with the event table entry. + @param eventSink + Object whose member function should be called. + If this is @NULL, @c *this will be used. */ - int GetButtonChange() const; + void Connect(int id, int lastId, wxEventType eventType, + wxObjectEventFunction function, + wxObject* userData = NULL, + wxEvtHandler* eventSink = NULL); /** - Returns the down state of the buttons. + See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) + overload for more info. - This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4. + This overload can be used to attach an event handler to a single source ID: + + Example: + @code + frame->Connect( wxID_EXIT, + wxEVT_COMMAND_MENU_SELECTED, + wxCommandEventHandler(MyFrame::OnQuit) ); + @endcode */ - int GetButtonState() const; + void Connect(int id, wxEventType eventType, + wxObjectEventFunction function, + wxObject* userData = NULL, + wxEvtHandler* eventSink = NULL); /** - Returns the identifier of the joystick generating the event - one of - wxJOYSTICK1 and wxJOYSTICK2. + See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) + overload for more info. + + This overload will connect the given event handler so that regardless of the + ID of the event source, the handler will be called. */ - int GetJoystick() const; + void Connect(wxEventType eventType, + wxObjectEventFunction function, + wxObject* userData = NULL, + wxEvtHandler* eventSink = NULL); /** - Returns the x, y position of the joystick event. + Disconnects the given function dynamically from the event handler, using the + specified parameters as search criteria and returning @true if a matching + function has been found and removed. + + This method can only disconnect functions which have been added using the + Connect() method. There is no way to disconnect functions connected using + the (static) event tables. + + @param eventType + The event type associated with this event handler. + @param function + The event handler function. + @param userData + Data associated with the event table entry. + @param eventSink + Object whose member function should be called. */ - wxPoint GetPosition() const; + bool Disconnect(wxEventType eventType = wxEVT_NULL, + wxObjectEventFunction function = NULL, + wxObject* userData = NULL, + wxEvtHandler* eventSink = NULL); /** - Returns the z position of the joystick event. + See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) + overload for more info. + + This overload takes the additional @a id parameter. */ - int GetZPosition() const; + bool Disconnect(int id = wxID_ANY, + wxEventType eventType = wxEVT_NULL, + wxObjectEventFunction function = NULL, + wxObject* userData = NULL, + wxEvtHandler* eventSink = NULL); /** - Returns @true if this was a button up or down event - (@e not 'is any button down?'). + See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) + overload for more info. + + This overload takes an additional range of source IDs. */ - bool IsButton() const; + bool Disconnect(int id, int lastId = wxID_ANY, + wxEventType eventType = wxEVT_NULL, + wxObjectEventFunction function = NULL, + wxObject* userData = NULL, + wxEvtHandler* eventSink = NULL); /** - Returns @true if this was an x, y move event. + Returns user-supplied client data. + + @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. + + @see SetClientData() */ - bool IsMove() const; + void* GetClientData() const; /** - Returns @true if this was a z move event. + Returns a pointer to the user-supplied client data object. + + @see SetClientObject(), wxClientData */ - bool IsZMove() const; -}; + wxClientData* GetClientObject() const; + /** + Returns @true if the event handler is enabled, @false otherwise. + @see SetEvtHandlerEnabled() + */ + bool GetEvtHandlerEnabled() const; -/** - @class wxScrollWinEvent - @wxheader{event.h} + /** + Returns the pointer to the next handler in the chain. - A scroll event holds information about events sent from scrolling windows. + @see SetNextHandler(), GetPreviousHandler(), SetPreviousHandler(), + wxWindow::PushEventHandler, wxWindow::PopEventHandler + */ + wxEvtHandler* GetNextHandler() const; + /** + Returns the pointer to the previous handler in the chain. - @beginEventTable{wxScrollWinEvent} - You can use the EVT_SCROLLWIN* macros for intercepting scroll window events - from the receiving window. - @event{EVT_SCROLLWIN(func)}: - Process all scroll events. - @event{EVT_SCROLLWIN_TOP(func)}: - Process wxEVT_SCROLLWIN_TOP scroll-to-top events. - @event{EVT_SCROLLWIN_BOTTOM(func)}: - Process wxEVT_SCROLLWIN_BOTTOM scroll-to-bottom events. - @event{EVT_SCROLLWIN_LINEUP(func)}: - Process wxEVT_SCROLLWIN_LINEUP line up events. - @event{EVT_SCROLLWIN_LINEDOWN(func)}: - Process wxEVT_SCROLLWIN_LINEDOWN line down events. - @event{EVT_SCROLLWIN_PAGEUP(func)}: - Process wxEVT_SCROLLWIN_PAGEUP page up events. - @event{EVT_SCROLLWIN_PAGEDOWN(func)}: - Process wxEVT_SCROLLWIN_PAGEDOWN page down events. - @event{EVT_SCROLLWIN_THUMBTRACK(func)}: - Process wxEVT_SCROLLWIN_THUMBTRACK thumbtrack events - (frequent events sent as the user drags the thumbtrack). - @event{EVT_SCROLLWIN_THUMBRELEASE(func)}: - Process wxEVT_SCROLLWIN_THUMBRELEASE thumb release events. - @endEventTable + @see SetPreviousHandler(), GetNextHandler(), SetNextHandler(), + wxWindow::PushEventHandler, wxWindow::PopEventHandler + */ + wxEvtHandler* GetPreviousHandler() const; + /** + Processes an event, searching event tables and calling zero or more suitable + event handler function(s). - @library{wxcore} - @category{events} + 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. + + @returns @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); - @see wxScrollEvent, @ref overview_eventhandling -*/ -class wxScrollWinEvent : public wxEvent -{ -public: /** - Constructor. + 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. + + @returns @true if the event was processed, @false if no handler was found + or an exception was thrown. + + @see wxWindow::HandleWindowEvent */ - wxScrollWinEvent(wxEventType commandType = wxEVT_NULL, int pos = 0, - int orientation = 0); + bool SafelyProcessEvent(wxEvent& event); /** - Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the - scrollbar. + Searches the event table, executing an event handler function if an appropriate + one is found. - @todo wxHORIZONTAL and wxVERTICAL should go in their own enum + @param table + Event table to be searched. + @param event + Event to be matched against an event table entry. + + @returns @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() */ - int GetOrientation() const; + virtual bool SearchEventTable(wxEventTable& table, + wxEvent& event); /** - Returns the position of the scrollbar for the thumb track and release events. + Sets user-supplied client data. - Note that this field can't be used for the other events, you need to query - the window itself for the current position in that case. + @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. + + @see GetClientData() */ - int GetPosition() const; -}; + void SetClientData(void* data); + /** + Set the client data object. Any previous object will be deleted. + @see GetClientObject(), wxClientData + */ + void SetClientObject(wxClientData* data); -/** - @class wxSysColourChangedEvent - @wxheader{event.h} + /** + Enables or disables the event handler. - This class is used for system colour change events, which are generated - when the user changes the colour settings using the control panel. - This is only appropriate under Windows. + @param enabled + @true if the event handler is to be enabled, @false if it is to be disabled. - @remarks - The default event handler for this event propagates the event to child windows, - since Windows only sends the events to top-level windows. - If intercepting this event for a top-level window, remember to call the base - class handler, or to pass the event on to the window's children explicitly. + @remarks You can use this function to avoid having to remove the event + handler from the chain, for example when implementing a + dialog editor and changing from edit to test mode. - @beginEventTable{wxSysColourChangedEvent} - @event{EVT_SYS_COLOUR_CHANGED(func)}: - Process a wxEVT_SYS_COLOUR_CHANGED event. - @endEventTable + @see GetEvtHandlerEnabled() + */ + void SetEvtHandlerEnabled(bool enabled); - @library{wxcore} - @category{events} + /** + Sets the pointer to the next handler. + + @param handler + Event handler to be set as the next handler. + + @see GetNextHandler(), SetPreviousHandler(), GetPreviousHandler(), + wxWindow::PushEventHandler, wxWindow::PopEventHandler + */ + void SetNextHandler(wxEvtHandler* handler); - @see @ref overview_eventhandling -*/ -class wxSysColourChangedEvent : public wxEvent -{ -public: /** - Constructor. + Sets the pointer to the previous handler. + + @param handler + Event handler to be set as the previous handler. */ - wxSysColourChangedEvent(); + void SetPreviousHandler(wxEvtHandler* handler); }; - /** - @class wxWindowCreateEvent + @class wxKeyEvent @wxheader{event.h} - This event is sent just after the actual window associated with a wxWindow - object has been created. + This event class contains information about keypress (character) events. - Since it is derived from wxCommandEvent, the event propagates up - the window hierarchy. + Notice that there are three different kinds of keyboard events in wxWidgets: + key down and up events and char events. The difference between the first two + is clear - the first corresponds to a key press and the second to a key + release - otherwise they are identical. Just note that if the key is + maintained in a pressed state you will typically get a lot of (automatically + generated) down events but only one up so it is wrong to assume that there is + one up event corresponding to each down one. - @beginEventTable{wxWindowCreateEvent} - @event{EVT_WINDOW_CREATE(func)}: - Process a wxEVT_CREATE event. + 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. + 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. + + A few examples to clarify this (all assume that CAPS LOCK is unpressed + and the standard US keyboard): when the @c 'A' key is pressed, the key down + event key code is equal to @c ASCII A == 65. But the char event key code + is @c ASCII a == 97. On the other hand, if you press both SHIFT and + @c 'A' keys simultaneously , the key code in key down event will still be + just @c 'A' while the char event key code parameter will now be @c 'A' + as well. + + Although in this simple case it is clear that the correct key code could be + found in the key down event handler by checking the value returned by + wxKeyEvent::ShiftDown(), in general you should use @c EVT_CHAR for this as + for non-alphanumeric keys the translation is keyboard-layout dependent and + can only be done properly by the system itself. + + Another kind of translation is done when the control key is pressed: for + example, for CTRL-A key press the key down event still carries the + same key code @c 'a' as usual but the char event will have key code of 1, + the ASCII value of this key combination. + + You may discover how the other keys on your system behave interactively by + running the @ref page_samples_text wxWidgets sample and pressing some keys + in any of the text controls shown in it. + + @b Tip: be sure to call @c event.Skip() for events that you don't process in + key event function, otherwise menu shortcuts may cease to work under Windows. + + @note If a key down (@c EVT_KEY_DOWN) event is caught and the event handler + does not call @c event.Skip() then the corresponding char event + (@c EVT_CHAR) will not happen. + This is by design and enables the programs that handle both types of + events to be a bit simpler. + + @note For Windows programmers: The key and char events in wxWidgets are + similar to but slightly different from Windows @c WM_KEYDOWN and + @c WM_CHAR events. In particular, Alt-x combination will generate a + char event in wxWidgets (unless it is used as an accelerator). + + + @beginEventTable{wxKeyEvent} + @event{EVT_KEY_DOWN(func)} + Process a wxEVT_KEY_DOWN event (any key has been pressed). + @event{EVT_KEY_UP(func)} + Process a wxEVT_KEY_UP event (any key has been released). + @event{EVT_CHAR(func)} + Process a wxEVT_CHAR event. @endEventTable @library{wxcore} @category{events} - - @see @ref overview_eventhandling, wxWindowDestroyEvent */ -class wxWindowCreateEvent : public wxCommandEvent +class wxKeyEvent : public wxEvent { public: /** Constructor. + Currently, the only valid event types are @c wxEVT_CHAR and @c wxEVT_CHAR_HOOK. */ - wxWindowCreateEvent(wxWindow* win = NULL); -}; + 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; -/** - @class wxPaintEvent - @wxheader{event.h} + /** + 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; - A paint event is sent when a window's contents needs to be repainted. + /** + Returns @true if the control key was down at the time of the key event. - Please notice that in general it is impossible to change the drawing of a - standard control (such as wxButton) and so you shouldn't attempt to handle - paint events for them as even if it might work on some platforms, this is - inherently not portable and won't work everywhere. + Notice that GetModifiers() is easier to use correctly than this function + so you should consider using it in new code. + */ + bool ControlDown() const; - @remarks - Note that in a paint event handler, the application must always create a - wxPaintDC object, even if you do not use it. Otherwise, under MS Windows, - refreshing for this and other windows will go wrong. - For example: - @code - void MyWindow::OnPaint(wxPaintEvent& event) - { - wxPaintDC dc(this); + /** + 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. - DrawMyDocument(dc); - } - @endcode - You can optimize painting by retrieving the rectangles that have been damaged - and only repainting these. The rectangles are in terms of the client area, - and are unscrolled, so you will need to do some calculations using the current - view position to obtain logical, scrolled units. - Here is an example of using the wxRegionIterator class: - @code - // Called when window needs to be repainted. - void MyWindow::OnPaint(wxPaintEvent& event) - { - wxPaintDC dc(this); + 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 + charset. You can obtain the corresponding Unicode character using GetUnicodeKey(). + */ + int GetKeyCode() const; - // Find Out where the window is scrolled to - int vbX,vbY; // Top left corner of client - GetViewStart(&vbX,&vbY); + /** + Return the bitmask of modifier keys which were pressed when this event + happened. See @ref page_keymodifiers for the full list of modifiers. - int vX,vY,vW,vH; // Dimensions of client area in pixels - wxRegionIterator upd(GetUpdateRegion()); // get the update rect list + 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: - while (upd) - { - vX = upd.GetX(); - vY = upd.GetY(); - vW = upd.GetW(); - vH = upd.GetH(); + @code + if ( ControlDown() && !AltDown() && !ShiftDown() && !MetaDown() ) + ... handle Ctrl-XXX ... + @endcode - // Alternatively we can do this: - // wxRect rect(upd.GetRect()); + 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: - // Repaint this rectangle - ...some code... + @code + if ( GetModifiers() == wxMOD_CONTROL ) + ... handle Ctrl-XXX ... + @endcode - upd ++ ; - } - } - @endcode + with this function. + */ + int GetModifiers() const; + //@{ + /** + Obtains the position (in client coordinates) at which the key was pressed. + */ + wxPoint GetPosition() const; + void GetPosition(long* x, long* y) const; + //@} - @beginEventTable{wxPaintEvent} - @event{EVT_PAINT(func)}: - Process a wxEVT_PAINT event. - @endEventTable + /** + Returns the raw key code for this event. This is a platform-dependent scan code + which should only be used in advanced applications. - @library{wxcore} - @category{events} + @note Currently the raw key codes are not supported by all ports, use + @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available. + */ + wxUint32 GetRawKeyCode() const; - @see @ref overview_eventhandling -*/ -class wxPaintEvent : public wxEvent -{ -public: /** - Constructor. + Returns the low level key flags for this event. The flags are + platform-dependent and should only be used in advanced applications. + + @note Currently the raw key flags are not supported by all ports, use + @ifdef_ wxHAS_RAW_KEY_CODES to determine if this feature is available. */ - wxPaintEvent(int id = 0); -}; + wxUint32 GetRawKeyFlags() const; + /** + Returns the Unicode character corresponding to this key event. + + This function is only available in Unicode build, i.e. when + @c wxUSE_UNICODE is 1. + */ + wxChar GetUnicodeKey() const; + /** + Returns the X position (in client coordinates) of the event. + */ + wxCoord GetX() const; + + /** + Returns the Y position (in client coordinates) of the event. + */ + wxCoord GetY() const; -/** - @class wxMaximizeEvent - @wxheader{event.h} + /** + Returns @true if either CTRL or ALT keys was down at the time of the + key event. - An event being sent when a top level window is maximized. Notice that it is - not sent when the window is restored to its original size after it had been - maximized, only a normal wxSizeEvent is generated in this case. + 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; - @beginEventTable{wxMaximizeEvent} - @event{EVT_MAXIMIZE(func)}: - Process a wxEVT_MAXIMIZE event. - @endEventTable + /** + Returns @true if the Meta key was down at the time of the key event. - @library{wxcore} - @category{events} + Notice that GetModifiers() is easier to use correctly than this function + so you should consider using it in new code. + */ + bool MetaDown() const; - @see @ref overview_eventhandling, wxTopLevelWindow::Maximize, - wxTopLevelWindow::IsMaximized -*/ -class wxMaximizeEvent : public wxEvent -{ -public: /** - Constructor. Only used by wxWidgets internally. + 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. */ - wxMaximizeEvent(int id = 0); + bool ShiftDown() const; }; /** - @class wxUpdateUIEvent + @class wxJoystickEvent @wxheader{event.h} - This class is used for pseudo-events which are called by wxWidgets - to give an application the chance to update various user interface elements. - - @remarks - Without update UI events, an application has to work hard to check/uncheck, - enable/disable, show/hide, and set the text for elements such as menu items - and toolbar buttons. The code for doing this has to be mixed up with the code - that is invoked when an action is invoked for a menu item or button. - With update UI events, you define an event handler to look at the state of the - application and change UI elements accordingly. wxWidgets will call your member - functions in idle time, so you don't have to worry where to call this code. - In addition to being a clearer and more declarative method, it also means you don't - have to worry whether you're updating a toolbar or menubar identifier. The same - handler can update a menu item and toolbar button, if the identifier is the same. - Instead of directly manipulating the menu or button, you call functions in the event - object, such as wxUpdateUIEvent::Check. wxWidgets will determine whether such a - call has been made, and which UI element to update. - These events will work for popup menus as well as menubars. Just before a menu is - popped up, wxMenu::UpdateUI is called to process any UI events for the window that - owns the menu. - If you find that the overhead of UI update processing is affecting your application, - you can do one or both of the following: - @li Call wxUpdateUIEvent::SetMode with a value of wxUPDATE_UI_PROCESS_SPECIFIED, - and set the extra style wxWS_EX_PROCESS_UI_UPDATES for every window that should - receive update events. No other windows will receive update events. - @li Call wxUpdateUIEvent::SetUpdateInterval with a millisecond value to set the delay - between updates. You may need to call wxWindow::UpdateWindowUI at critical points, - for example when a dialog is about to be shown, in case the user sees a slight - delay before windows are updated. - Note that although events are sent in idle time, defining a wxIdleEvent handler - for a window does not affect this because the events are sent from wxWindow::OnInternalIdle - which is always called in idle time. - wxWidgets tries to optimize update events on some platforms. - On Windows and GTK+, events for menubar items are only sent when the menu is about - to be shown, and not in idle time. + This event class contains information about joystick events, particularly + events received by windows. - @beginEventTable{wxUpdateUIEvent} - @event{EVT_UPDATE_UI(id, func)}: - Process a wxEVT_UPDATE_UI event for the command with the given id. - @event{EVT_UPDATE_UI_RANGE(id1, id2, func)}: - Process a wxEVT_UPDATE_UI event for any command with id included in the given range. + @beginEventTable{wxJoystickEvent} + @style{EVT_JOY_BUTTON_DOWN(func)} + Process a wxEVT_JOY_BUTTON_DOWN event. + @style{EVT_JOY_BUTTON_UP(func)} + Process a wxEVT_JOY_BUTTON_UP event. + @style{EVT_JOY_MOVE(func)} + Process a wxEVT_JOY_MOVE event. + @style{EVT_JOY_ZMOVE(func)} + Process a wxEVT_JOY_ZMOVE event. + @style{EVT_JOYSTICK_EVENTS(func)} + Processes all joystick events. @endEventTable - @library{wxcore} @category{events} - @see @ref overview_eventhandling + @see wxJoystick */ -class wxUpdateUIEvent : public wxCommandEvent +class wxJoystickEvent : public wxEvent { public: /** Constructor. */ - wxUpdateUIEvent(wxWindowID commandId = 0); + wxJoystickEvent(wxEventType eventType = wxEVT_NULL, int state = 0, + int joystick = wxJOYSTICK1, + int change = 0); /** - Returns @true if it is appropriate to update (send UI update events to) - this window. - This function looks at the mode used (see wxUpdateUIEvent::SetMode), - the wxWS_EX_PROCESS_UI_UPDATES flag in @e window, - the time update events were last sent in idle time, and - the update interval, to determine whether events should be sent to - this window now. By default this will always return @true because - the update mode is initially wxUPDATE_UI_PROCESS_ALL and - the interval is set to 0; so update events will be sent as - often as possible. You can reduce the frequency that events - are sent by changing the mode and/or setting an update interval. - - @see ResetUpdateTime(), SetUpdateInterval(), - SetMode() - */ - static bool CanUpdate(wxWindow* window); + Returns @true if the event was a down event from the specified button + (or any button). - /** - Check or uncheck the UI element. + @param button + Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to + indicate any button down event. */ - void Check(bool check); + bool ButtonDown(int button = wxJOY_BUTTON_ANY) const; /** - Enable or disable the UI element. - */ - void Enable(bool enable); + Returns @true if the specified button (or any button) was in a down state. - /** - Returns @true if the UI element should be checked. + @param button + Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to + indicate any button down event. */ - bool GetChecked() const; + bool ButtonIsDown(int button = wxJOY_BUTTON_ANY) const; /** - Returns @true if the UI element should be enabled. + Returns @true if the event was an up event from the specified button + (or any button). + + @param button + Can be @c wxJOY_BUTTONn where @c n is 1, 2, 3 or 4; or @c wxJOY_BUTTON_ANY to + indicate any button down event. */ - bool GetEnabled() const; + bool ButtonUp(int button = wxJOY_BUTTON_ANY) const; /** - Static function returning a value specifying how wxWidgets - will send update events: to all windows, or only to those which specify that - they - will process the events. - See SetMode(). + Returns the identifier of the button changing state. + + This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4. */ - static wxUpdateUIMode GetMode(); + int GetButtonChange() const; /** - Returns @true if the application has called Check(). For wxWidgets internal use - only. + Returns the down state of the buttons. + + This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4. */ - bool GetSetChecked() const; + int GetButtonState() const; /** - Returns @true if the application has called Enable(). For wxWidgets internal use - only. + Returns the identifier of the joystick generating the event - one of + wxJOYSTICK1 and wxJOYSTICK2. */ - bool GetSetEnabled() const; + int GetJoystick() const; /** - Returns @true if the application has called Show(). For wxWidgets internal use - only. + Returns the x, y position of the joystick event. */ - bool GetSetShown() const; + wxPoint GetPosition() const; /** - Returns @true if the application has called SetText(). For wxWidgets internal - use only. + Returns the z position of the joystick event. */ - bool GetSetText() const; + int GetZPosition() const; /** - Returns @true if the UI element should be shown. + Returns @true if this was a button up or down event + (@e not 'is any button down?'). */ - bool GetShown() const; + bool IsButton() const; /** - Returns the text that should be set for the UI element. + Returns @true if this was an x, y move event. */ - wxString GetText() const; + bool IsMove() const; /** - Returns the current interval between updates in milliseconds. - -1 disables updates, 0 updates as frequently as possible. - See SetUpdateInterval(). + Returns @true if this was a z move event. */ - static long GetUpdateInterval(); + bool IsZMove() const; +}; - /** - Used internally to reset the last-updated time to the - current time. It is assumed that update events are - normally sent in idle time, so this is called at the end of - idle processing. - @see CanUpdate(), SetUpdateInterval(), - SetMode() - */ - static void ResetUpdateTime(); - /** - Specify how wxWidgets will send update events: to - all windows, or only to those which specify that they - will process the events. - @a mode may be one of the following values. - The default is wxUPDATE_UI_PROCESS_ALL. - */ - static void SetMode(wxUpdateUIMode mode); +/** + @class wxScrollWinEvent + @wxheader{event.h} + + A scroll event holds information about events sent from scrolling windows. + + + @beginEventTable{wxScrollWinEvent} + You can use the EVT_SCROLLWIN* macros for intercepting scroll window events + from the receiving window. + @event{EVT_SCROLLWIN(func)} + Process all scroll events. + @event{EVT_SCROLLWIN_TOP(func)} + Process wxEVT_SCROLLWIN_TOP scroll-to-top events. + @event{EVT_SCROLLWIN_BOTTOM(func)} + Process wxEVT_SCROLLWIN_BOTTOM scroll-to-bottom events. + @event{EVT_SCROLLWIN_LINEUP(func)} + Process wxEVT_SCROLLWIN_LINEUP line up events. + @event{EVT_SCROLLWIN_LINEDOWN(func)} + Process wxEVT_SCROLLWIN_LINEDOWN line down events. + @event{EVT_SCROLLWIN_PAGEUP(func)} + Process wxEVT_SCROLLWIN_PAGEUP page up events. + @event{EVT_SCROLLWIN_PAGEDOWN(func)} + Process wxEVT_SCROLLWIN_PAGEDOWN page down events. + @event{EVT_SCROLLWIN_THUMBTRACK(func)} + Process wxEVT_SCROLLWIN_THUMBTRACK thumbtrack events + (frequent events sent as the user drags the thumbtrack). + @event{EVT_SCROLLWIN_THUMBRELEASE(func)} + Process wxEVT_SCROLLWIN_THUMBRELEASE thumb release events. + @endEventTable + + + @library{wxcore} + @category{events} + @see wxScrollEvent, @ref overview_eventhandling +*/ +class wxScrollWinEvent : public wxEvent +{ +public: /** - Sets the text for this UI element. + Constructor. */ - void SetText(const wxString& text); + wxScrollWinEvent(wxEventType commandType = wxEVT_NULL, int pos = 0, + int orientation = 0); /** - Sets the interval between updates in milliseconds. - Set to -1 to disable updates, or to 0 to update as frequently as possible. - The default is 0. - Use this to reduce the overhead of UI update events if your application - has a lot of windows. If you set the value to -1 or greater than 0, - you may also need to call wxWindow::UpdateWindowUI - at appropriate points in your application, such as when a dialog - is about to be shown. + Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the + scrollbar. + + @todo wxHORIZONTAL and wxVERTICAL should go in their own enum */ - static void SetUpdateInterval(long updateInterval); + int GetOrientation() const; /** - Show or hide the UI element. + Returns the position of the scrollbar for the thumb track and release events. + + Note that this field can't be used for the other events, you need to query + the window itself for the current position in that case. */ - void Show(bool show); + int GetPosition() const; }; /** - @class wxClipboardTextEvent + @class wxSysColourChangedEvent @wxheader{event.h} - This class represents the events generated by a control (typically a - wxTextCtrl but other windows can generate these events as - well) when its content gets copied or cut to, or pasted from the clipboard. - There are three types of corresponding events wxEVT_COMMAND_TEXT_COPY, - wxEVT_COMMAND_TEXT_CUT and wxEVT_COMMAND_TEXT_PASTE. - - If any of these events is processed (without being skipped) by an event - handler, the corresponding operation doesn't take place which allows to - prevent the text from being copied from or pasted to a control. It is also - possible to examine the clipboard contents in the PASTE event handler and - transform it in some way before inserting in a control -- for example, - changing its case or removing invalid characters. + This class is used for system colour change events, which are generated + when the user changes the colour settings using the control panel. + This is only appropriate under Windows. - Finally notice that a CUT event is always preceded by the COPY event which - makes it possible to only process the latter if it doesn't matter if the - text was copied or cut. + @remarks + The default event handler for this event propagates the event to child windows, + since Windows only sends the events to top-level windows. + If intercepting this event for a top-level window, remember to call the base + class handler, or to pass the event on to the window's children explicitly. - @beginEventTable{wxClipboardTextEvent} - @event{EVT_TEXT_COPY(id, func)}: - Some or all of the controls content was copied to the clipboard. - @event{EVT_TEXT_CUT(id, func)}: - Some or all of the controls content was cut (i.e. copied and - deleted). - @event{EVT_TEXT_PASTE(id, func)}: - Clipboard content was pasted into the control. + @beginEventTable{wxSysColourChangedEvent} + @event{EVT_SYS_COLOUR_CHANGED(func)} + Process a wxEVT_SYS_COLOUR_CHANGED event. @endEventTable - @note - These events are currently only generated by wxTextCtrl under GTK+. They - are generated by all controls under Windows. - @library{wxcore} @category{events} - @see wxClipboard + @see @ref overview_eventhandling */ -class wxClipboardTextEvent : public wxCommandEvent +class wxSysColourChangedEvent : public wxEvent { public: /** Constructor. */ - wxClipboardTextEvent(wxEventType commandType = wxEVT_NULL, int id = 0); + wxSysColourChangedEvent(); }; /** - @class wxMouseEvent + @class wxWindowCreateEvent @wxheader{event.h} - This event class contains information about the events generated by the mouse: - they include mouse buttons press and release events and mouse move events. - - All mouse events involving the buttons use @c wxMOUSE_BTN_LEFT for the - left mouse button, @c wxMOUSE_BTN_MIDDLE for the middle one and - @c wxMOUSE_BTN_RIGHT for the right one. And if the system supports more - buttons, the @c wxMOUSE_BTN_AUX1 and @c wxMOUSE_BTN_AUX2 events - can also be generated. Note that not all mice have even a middle button so a - portable application should avoid relying on the events from it (but the right - button click can be emulated using the left mouse button with the control key - under Mac platforms with a single button mouse). + This event is sent just after the actual window associated with a wxWindow + object has been created. - For the @c wxEVT_ENTER_WINDOW and @c wxEVT_LEAVE_WINDOW events - purposes, the mouse is considered to be inside the window if it is in the - window client area and not inside one of its children. In other words, the - 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. + Since it is derived from wxCommandEvent, the event propagates up + the window hierarchy. - @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 - left the window and the state variables for it may have changed during this - time. - - @note Note the difference between methods like - wxMouseEvent::LeftDown and - wxMouseEvent::LeftIsDown: the former returns @true - when the event corresponds to the left mouse button click while the latter - returns @true if the left mouse button is currently being pressed. For - example, when the user is dragging the mouse you can use - wxMouseEvent::LeftIsDown to test - whether the left mouse button is (still) depressed. Also, by convention, if - wxMouseEvent::LeftDown returns @true, - wxMouseEvent::LeftIsDown will also return @true in - wxWidgets whatever the underlying GUI behaviour is (which is - platform-dependent). The same applies, of course, to other mouse buttons as - well. + @beginEventTable{wxWindowCreateEvent} + @event{EVT_WINDOW_CREATE(func)} + Process a wxEVT_CREATE event. + @endEventTable @library{wxcore} @category{events} - @see wxKeyEvent::CmdDown + @see @ref overview_eventhandling, wxWindowDestroyEvent */ -class wxMouseEvent : public wxEvent +class wxWindowCreateEvent : public wxCommandEvent { public: /** - Constructor. Valid event types are: + Constructor. + */ + wxWindowCreateEvent(wxWindow* win = NULL); +}; - @b wxEVT_ENTER_WINDOW - @b wxEVT_LEAVE_WINDOW - @b wxEVT_LEFT_DOWN - @b wxEVT_LEFT_UP - @b wxEVT_LEFT_DCLICK - @b wxEVT_MIDDLE_DOWN - @b wxEVT_MIDDLE_UP - @b wxEVT_MIDDLE_DCLICK - @b wxEVT_RIGHT_DOWN - @b wxEVT_RIGHT_UP - @b wxEVT_RIGHT_DCLICK - @b wxEVT_MOUSE_AUX1_DOWN - @b wxEVT_MOUSE_AUX1_UP - @b wxEVT_MOUSE_AUX1_DCLICK - @b wxEVT_MOUSE_AUX2_DOWN - @b wxEVT_MOUSE_AUX2_UP - @b wxEVT_MOUSE_AUX2_DCLICK - @b wxEVT_MOTION - @b wxEVT_MOUSEWHEEL - */ - wxMouseEvent(wxEventType mouseEventType = 0); - /** - 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. - */ - bool Aux1DClick() const; +/** + @class wxPaintEvent + @wxheader{event.h} - /** - Returns @true if the first extra button mouse button changed to down. - */ - bool Aux1Down() const; + A paint event is sent when a window's contents needs to be repainted. - /** - Returns @true if the first extra button mouse button is currently down, - independent - of the current event type. - */ - bool Aux1IsDown() const; + Please notice that in general it is impossible to change the drawing of a + standard control (such as wxButton) and so you shouldn't attempt to handle + paint events for them as even if it might work on some platforms, this is + inherently not portable and won't work everywhere. - /** - Returns @true if the first extra button mouse button changed to up. - */ - bool Aux1Up() const; + @remarks + Note that in a paint event handler, the application must always create a + wxPaintDC object, even if you do not use it. Otherwise, under MS Windows, + refreshing for this and other windows will go wrong. + For example: + @code + void MyWindow::OnPaint(wxPaintEvent& event) + { + wxPaintDC dc(this); - /** - Returns @true if the event was a second extra button double click. - */ - bool Aux2DClick() const; + DrawMyDocument(dc); + } + @endcode + You can optimize painting by retrieving the rectangles that have been damaged + and only repainting these. The rectangles are in terms of the client area, + and are unscrolled, so you will need to do some calculations using the current + view position to obtain logical, scrolled units. + Here is an example of using the wxRegionIterator class: + @code + // Called when window needs to be repainted. + void MyWindow::OnPaint(wxPaintEvent& event) + { + wxPaintDC dc(this); - /** - Returns @true if the second extra button mouse button changed to down. - */ - bool Aux2Down() const; + // Find Out where the window is scrolled to + int vbX,vbY; // Top left corner of client + GetViewStart(&vbX,&vbY); - /** - Returns @true if the second extra button mouse button is currently down, - independent - of the current event type. - */ - bool Aux2IsDown() const; + int vX,vY,vW,vH; // Dimensions of client area in pixels + wxRegionIterator upd(GetUpdateRegion()); // get the update rect list - /** - Returns @true if the second extra button mouse button changed to up. - */ - bool Aux2Up() const; + while (upd) + { + vX = upd.GetX(); + vY = upd.GetY(); + vW = upd.GetW(); + vH = upd.GetH(); - /** - Returns @true if the identified mouse button is changing state. Valid - values of @a button are: + // Alternatively we can do this: + // wxRect rect(upd.GetRect()); - @c wxMOUSE_BTN_LEFT + // Repaint this rectangle + ...some code... - check if left button was pressed + upd ++ ; + } + } + @endcode - @c wxMOUSE_BTN_MIDDLE - check if middle button was pressed + @beginEventTable{wxPaintEvent} + @event{EVT_PAINT(func)} + Process a wxEVT_PAINT event. + @endEventTable - @c wxMOUSE_BTN_RIGHT + @library{wxcore} + @category{events} - check if right button was pressed + @see @ref overview_eventhandling +*/ +class wxPaintEvent : public wxEvent +{ +public: + /** + Constructor. + */ + wxPaintEvent(int id = 0); +}; - @c wxMOUSE_BTN_AUX1 - check if the first extra button was pressed - @c wxMOUSE_BTN_AUX2 +/** + @class wxMaximizeEvent + @wxheader{event.h} - check if the second extra button was pressed + An event being sent when a top level window is maximized. Notice that it is + not sent when the window is restored to its original size after it had been + maximized, only a normal wxSizeEvent is generated in this case. - @c wxMOUSE_BTN_ANY + @beginEventTable{wxMaximizeEvent} + @event{EVT_MAXIMIZE(func)} + Process a wxEVT_MAXIMIZE event. + @endEventTable - check if any button was pressed - */ - bool Button(int button) const; + @library{wxcore} + @category{events} + @see @ref overview_eventhandling, wxTopLevelWindow::Maximize, + wxTopLevelWindow::IsMaximized +*/ +class wxMaximizeEvent : public wxEvent +{ +public: /** - If the argument is omitted, this returns @true if the event was a mouse - double click event. Otherwise the argument specifies which double click event - was generated (see Button() for the possible - values). + Constructor. Only used by wxWidgets internally. */ - bool ButtonDClick(int but = wxMOUSE_BTN_ANY) const; + wxMaximizeEvent(int id = 0); +}; - /** - If the argument is omitted, this returns @true if the event was a mouse - button down event. Otherwise the argument specifies which button-down event - was generated (see Button() for the possible - values). - */ - bool ButtonDown(int = wxMOUSE_BTN_ANY) const; +/** + The possibles modes to pass to wxUpdateUIEvent::SetMode(). +*/ +enum wxUpdateUIMode +{ + /** Send UI update events to all windows. */ + wxUPDATE_UI_PROCESS_ALL, - /** - If the argument is omitted, this returns @true if the event was a mouse - button up event. Otherwise the argument specifies which button-up event - was generated (see Button() for the possible - values). - */ - bool ButtonUp(int = wxMOUSE_BTN_ANY) const; + /** Send UI update events to windows that have + the wxWS_EX_PROCESS_UI_UPDATES flag specified. */ + wxUPDATE_UI_PROCESS_SPECIFIED +}; - /** - Same as MetaDown() under Mac, same as - ControlDown() elsewhere. - @see wxKeyEvent::CmdDown - */ - bool CmdDown() const; +/** + @class wxUpdateUIEvent + @wxheader{event.h} - /** - Returns @true if the control key was down at the time of the event. - */ - bool ControlDown() const; + This class is used for pseudo-events which are called by wxWidgets + to give an application the chance to update various user interface elements. - /** - Returns @true if this was a dragging event (motion while a button is depressed). + Without update UI events, an application has to work hard to check/uncheck, + enable/disable, show/hide, and set the text for elements such as menu items + and toolbar buttons. The code for doing this has to be mixed up with the code + that is invoked when an action is invoked for a menu item or button. - @see Moving() - */ - bool Dragging() const; + With update UI events, you define an event handler to look at the state of the + application and change UI elements accordingly. wxWidgets will call your member + functions in idle time, so you don't have to worry where to call this code. - /** - Returns @true if the mouse was entering the window. - See also Leaving(). - */ - bool Entering() const; + In addition to being a clearer and more declarative method, it also means you don't + have to worry whether you're updating a toolbar or menubar identifier. The same + handler can update a menu item and toolbar button, if the identifier is the same. + Instead of directly manipulating the menu or button, you call functions in the event + object, such as wxUpdateUIEvent::Check. wxWidgets will determine whether such a + call has been made, and which UI element to update. - /** - Returns the mouse button which generated this event or @c wxMOUSE_BTN_NONE - if no button is involved (for mouse move, enter or leave event, for example). - Otherwise @c wxMOUSE_BTN_LEFT is returned for the left button down, up and - double click events, @c wxMOUSE_BTN_MIDDLE and @c wxMOUSE_BTN_RIGHT - for the same events for the middle and the right buttons respectively. - */ - int GetButton() const; + These events will work for popup menus as well as menubars. Just before a menu is + popped up, wxMenu::UpdateUI is called to process any UI events for the window that + owns the menu. - /** - Returns the number of mouse clicks for this event: 1 for a simple click, 2 - for a double-click, 3 for a triple-click and so on. - Currently this function is implemented only in wxMac and returns -1 for the - other platforms (you can still distinguish simple clicks from double-clicks as - they generate different kinds of events however). + If you find that the overhead of UI update processing is affecting your application, + you can do one or both of the following: + @li Call wxUpdateUIEvent::SetMode with a value of wxUPDATE_UI_PROCESS_SPECIFIED, + and set the extra style wxWS_EX_PROCESS_UI_UPDATES for every window that should + receive update events. No other windows will receive update events. + @li Call wxUpdateUIEvent::SetUpdateInterval with a millisecond value to set the delay + between updates. You may need to call wxWindow::UpdateWindowUI at critical points, + for example when a dialog is about to be shown, in case the user sees a slight + delay before windows are updated. - @wxsince{2.9.0} - */ - int GetClickCount() const; + Note that although events are sent in idle time, defining a wxIdleEvent handler + for a window does not affect this because the events are sent from wxWindow::OnInternalIdle + which is always called in idle time. - /** - Returns the configured number of lines (or whatever) to be scrolled per - wheel action. Defaults to three. - */ - int GetLinesPerAction() const; + wxWidgets tries to optimize update events on some platforms. + On Windows and GTK+, events for menubar items are only sent when the menu is about + to be shown, and not in idle time. - /** - Returns the logical mouse position in pixels (i.e. translated according to the - translation set for the DC, which usually indicates that the window has been - scrolled). - */ - wxPoint GetLogicalPosition(const wxDC& dc) const; - //@{ - /** - Sets *x and *y to the position at which the event occurred. - Returns the physical mouse position in pixels. - Note that if the mouse event has been artificially generated from a special - keyboard combination (e.g. under Windows when the "menu'' key is pressed), the - returned position is @c wxDefaultPosition. - */ - wxPoint GetPosition() const; - const void GetPosition(wxCoord* x, wxCoord* y) const; - const void GetPosition(long* x, long* y) const; - //@} + @beginEventTable{wxUpdateUIEvent} + @event{EVT_UPDATE_UI(id, func)} + Process a wxEVT_UPDATE_UI event for the command with the given id. + @event{EVT_UPDATE_UI_RANGE(id1, id2, func)} + Process a wxEVT_UPDATE_UI event for any command with id included in the given range. + @endEventTable - /** - Get wheel delta, normally 120. This is the threshold for action to be - taken, and one such action (for example, scrolling one increment) - should occur for each delta. - */ - int GetWheelDelta() const; + @library{wxcore} + @category{events} + @see @ref overview_eventhandling +*/ +class wxUpdateUIEvent : public wxCommandEvent +{ +public: /** - Get wheel rotation, positive or negative indicates direction of - rotation. Current devices all send an event when rotation is at least - +/-WheelDelta, but finer resolution devices can be created in the future. - Because of this you shouldn't assume that one event is equal to 1 line, but you - should be able to either do partial line scrolling or wait until several - events accumulate before scrolling. + Constructor. */ - int GetWheelRotation() const; + wxUpdateUIEvent(wxWindowID commandId = 0); /** - Returns X coordinate of the physical mouse event position. - */ - wxCoord GetX() const; + Returns @true if it is appropriate to update (send UI update events to) + this window. - /** - Returns Y coordinate of the physical mouse event position. - */ - wxCoord GetY() const; + This function looks at the mode used (see wxUpdateUIEvent::SetMode), + the wxWS_EX_PROCESS_UI_UPDATES flag in @a window, the time update events + were last sent in idle time, and the update interval, to determine whether + events should be sent to this window now. By default this will always + return @true because the update mode is initially wxUPDATE_UI_PROCESS_ALL + and the interval is set to 0; so update events will be sent as often as + possible. You can reduce the frequency that events are sent by changing the + mode and/or setting an update interval. - /** - Returns @true if the event was a mouse button event (not necessarily a button - down event - - that may be tested using @e ButtonDown). + @see ResetUpdateTime(), SetUpdateInterval(), SetMode() */ - bool IsButton() const; + static bool CanUpdate(wxWindow* window); /** - Returns @true if the system has been setup to do page scrolling with - the mouse wheel instead of line scrolling. + Check or uncheck the UI element. */ - bool IsPageScroll() const; + void Check(bool check); /** - Returns @true if the mouse was leaving the window. - See also Entering(). + Enable or disable the UI element. */ - bool Leaving() const; + void Enable(bool enable); /** - Returns @true if the event was a left double click. + Returns @true if the UI element should be checked. */ - bool LeftDClick() const; + bool GetChecked() const; /** - Returns @true if the left mouse button changed to down. + Returns @true if the UI element should be enabled. */ - bool LeftDown() const; + bool GetEnabled() const; /** - Returns @true if the left mouse button is currently down, independent - of the current event type. - Please notice that it is not the same as - LeftDown() which returns @true if the event was - generated by the left mouse button being pressed. Rather, it simply describes - the state of the left mouse button at the time when the event was generated - (so while it will be @true for a left click event, it can also be @true for - a right click if it happened while the left mouse button was pressed). - This event is usually used in the mouse event handlers which process "move - mouse" messages to determine whether the user is (still) dragging the mouse. - */ - bool LeftIsDown() const; + Static function returning a value specifying how wxWidgets will send update + events: to all windows, or only to those which specify that they will process + the events. - /** - Returns @true if the left mouse button changed to up. + @see SetMode() */ - bool LeftUp() const; + static wxUpdateUIMode GetMode(); /** - Returns @true if the Meta key was down at the time of the event. + Returns @true if the application has called Check(). + For wxWidgets internal use only. */ - bool MetaDown() const; + bool GetSetChecked() const; /** - Returns @true if the event was a middle double click. + Returns @true if the application has called Enable(). + For wxWidgets internal use only. */ - bool MiddleDClick() const; + bool GetSetEnabled() const; /** - Returns @true if the middle mouse button changed to down. + Returns @true if the application has called Show(). + For wxWidgets internal use only. */ - bool MiddleDown() const; + bool GetSetShown() const; /** - Returns @true if the middle mouse button is currently down, independent - of the current event type. + Returns @true if the application has called SetText(). + For wxWidgets internal use only. */ - bool MiddleIsDown() const; + bool GetSetText() const; /** - Returns @true if the middle mouse button changed to up. + Returns @true if the UI element should be shown. */ - bool MiddleUp() const; + bool GetShown() const; /** - Returns @true if this was a motion event and no mouse buttons were pressed. - If any mouse button is held pressed, then this method returns @false and - Dragging() returns @true. + Returns the text that should be set for the UI element. */ - bool Moving() const; + wxString GetText() const; /** - Returns @true if the event was a right double click. - */ - bool RightDClick() const; + Returns the current interval between updates in milliseconds. + The value -1 disables updates, 0 updates as frequently as possible. - /** - Returns @true if the right mouse button changed to down. + @see SetUpdateInterval(). */ - bool RightDown() const; + static long GetUpdateInterval(); /** - Returns @true if the right mouse button is currently down, independent - of the current event type. - */ - bool RightIsDown() const; + Used internally to reset the last-updated time to the current time. - /** - Returns @true if the right mouse button changed to up. - */ - bool RightUp() const; + It is assumed that update events are normally sent in idle time, so this + is called at the end of idle processing. - /** - Returns @true if the shift key was down at the time of the event. + @see CanUpdate(), SetUpdateInterval(), SetMode() */ - bool ShiftDown() const; + static void ResetUpdateTime(); /** - bool m_altDown - @true if the Alt key is pressed down. - */ + Specify how wxWidgets will send update events: to all windows, or only to + those which specify that they will process the events. - - /** - bool m_controlDown - @true if control key is pressed down. + @param mode + this parameter may be one of the ::wxUpdateUIMode enumeration values. + The default mode is wxUPDATE_UI_PROCESS_ALL. */ - + static void SetMode(wxUpdateUIMode mode); /** - bool m_leftDown - @true if the left mouse button is currently pressed down. + Sets the text for this UI element. */ - + void SetText(const wxString& text); /** - int m_linesPerAction - The configured number of lines (or whatever) to be scrolled per wheel - action. - */ + Sets the interval between updates in milliseconds. + Set to -1 to disable updates, or to 0 to update as frequently as possible. + The default is 0. - /** - bool m_metaDown - @true if the Meta key is pressed down. + Use this to reduce the overhead of UI update events if your application + has a lot of windows. If you set the value to -1 or greater than 0, + you may also need to call wxWindow::UpdateWindowUI at appropriate points + in your application, such as when a dialog is about to be shown. */ - + static void SetUpdateInterval(long updateInterval); /** - bool m_middleDown - @true if the middle mouse button is currently pressed down. + Show or hide the UI element. */ + void Show(bool show); +}; - /** - bool m_rightDown - @true if the right mouse button is currently pressed down. - */ +/** + @class wxClipboardTextEvent + @wxheader{event.h} - /** - bool m_shiftDown - @true if shift is pressed down. - */ + This class represents the events generated by a control (typically a + wxTextCtrl but other windows can generate these events as well) when its + content gets copied or cut to, or pasted from the clipboard. + There are three types of corresponding events wxEVT_COMMAND_TEXT_COPY, + wxEVT_COMMAND_TEXT_CUT and wxEVT_COMMAND_TEXT_PASTE. - /** - int m_wheelDelta - The wheel delta, normally 120. - */ + If any of these events is processed (without being skipped) by an event + handler, the corresponding operation doesn't take place which allows to + prevent the text from being copied from or pasted to a control. It is also + possible to examine the clipboard contents in the PASTE event handler and + transform it in some way before inserting in a control -- for example, + changing its case or removing invalid characters. + Finally notice that a CUT event is always preceded by the COPY event which + makes it possible to only process the latter if it doesn't matter if the + text was copied or cut. - /** - int m_wheelRotation - The distance the mouse wheel is rotated. - */ + @note + These events are currently only generated by wxTextCtrl under GTK+. + They are generated by all controls under Windows. + @beginEventTable{wxClipboardTextEvent} + @event{EVT_TEXT_COPY(id, func)} + Some or all of the controls content was copied to the clipboard. + @event{EVT_TEXT_CUT(id, func)} + Some or all of the controls content was cut (i.e. copied and + deleted). + @event{EVT_TEXT_PASTE(id, func)} + Clipboard content was pasted into the control. + @endEventTable - /** - long m_x - X-coordinate of the event. - */ + @library{wxcore} + @category{events} + @see wxClipboard +*/ +class wxClipboardTextEvent : public wxCommandEvent +{ +public: /** - long m_y - Y-coordinate of the event. + Constructor. */ + wxClipboardTextEvent(wxEventType commandType = wxEVT_NULL, int id = 0); }; /** - @class wxDropFilesEvent + @class wxMouseEvent @wxheader{event.h} - This class is used for drop files events, that is, when files have been dropped - onto the window. This functionality is currently only available under Windows. - The window must have previously been enabled for dropping by calling - wxWindow::DragAcceptFiles. + This event class contains information about the events generated by the mouse: + they include mouse buttons press and release events and mouse move events. + + All mouse events involving the buttons use @c wxMOUSE_BTN_LEFT for the + left mouse button, @c wxMOUSE_BTN_MIDDLE for the middle one and + @c wxMOUSE_BTN_RIGHT for the right one. And if the system supports more + buttons, the @c wxMOUSE_BTN_AUX1 and @c wxMOUSE_BTN_AUX2 events + can also be generated. Note that not all mice have even a middle button so a + portable application should avoid relying on the events from it (but the right + button click can be emulated using the left mouse button with the control key + under Mac platforms with a single button mouse). + + For the @c wxEVT_ENTER_WINDOW and @c wxEVT_LEAVE_WINDOW events + purposes, the mouse is considered to be inside the window if it is in the + window client area and not inside one of its children. In other words, the + 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. - Important note: this is a separate implementation to the more general - drag and drop implementation documented here(). It uses the - older, Windows message-based approach of dropping files. + @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 + left the window and the state variables for it may have changed during this time. + + @note Note the difference between methods like wxMouseEvent::LeftDown and + wxMouseEvent::LeftIsDown: the former returns @true when the event corresponds + to the left mouse button click while the latter returns @true if the left + mouse button is currently being pressed. For example, when the user is dragging + the mouse you can use wxMouseEvent::LeftIsDown to test whether the left mouse + button is (still) depressed. Also, by convention, if wxMouseEvent::LeftDown + returns @true, wxMouseEvent::LeftIsDown will also return @true in wxWidgets + whatever the underlying GUI behaviour is (which is platform-dependent). + The same applies, of course, to other mouse buttons as well. + + + @beginEventTable{wxMouseEvent} + @event{EVT_LEFT_DOWN(func)} + Process a wxEVT_LEFT_DOWN event. The handler of this event should normally + call event.Skip() to allow the default processing to take place as otherwise + the window under mouse wouldn't get the focus. + @event{EVT_LEFT_UP(func)} + Process a wxEVT_LEFT_UP event. + @event{EVT_LEFT_DCLICK(func)} + Process a wxEVT_LEFT_DCLICK event. + @event{EVT_MIDDLE_DOWN(func)} + Process a wxEVT_MIDDLE_DOWN event. + @event{EVT_MIDDLE_UP(func)} + Process a wxEVT_MIDDLE_UP event. + @event{EVT_MIDDLE_DCLICK(func)} + Process a wxEVT_MIDDLE_DCLICK event. + @event{EVT_RIGHT_DOWN(func)} + Process a wxEVT_RIGHT_DOWN event. + @event{EVT_RIGHT_UP(func)} + Process a wxEVT_RIGHT_UP event. + @event{EVT_RIGHT_DCLICK(func)} + Process a wxEVT_RIGHT_DCLICK event. + @event{EVT_MOUSE_AUX1_DOWN(func)} + Process a wxEVT_MOUSE_AUX1_DOWN event. + @event{EVT_MOUSE_AUX1_UP(func)} + Process a wxEVT_MOUSE_AUX1_UP event. + @event{EVT_MOUSE_AUX1_DCLICK(func)} + Process a wxEVT_MOUSE_AUX1_DCLICK event. + @event{EVT_MOUSE_AUX2_DOWN(func)} + Process a wxEVT_MOUSE_AUX2_DOWN event. + @event{EVT_MOUSE_AUX2_UP(func)} + Process a wxEVT_MOUSE_AUX2_UP event. + @event{EVT_MOUSE_AUX2_DCLICK(func)} + Process a wxEVT_MOUSE_AUX2_DCLICK event. + @event{EVT_MOTION(func)} + Process a wxEVT_MOTION event. + @event{EVT_ENTER_WINDOW(func)} + Process a wxEVT_ENTER_WINDOW event. + @event{EVT_LEAVE_WINDOW(func)} + Process a wxEVT_LEAVE_WINDOW event. + @event{EVT_MOUSEWHEEL(func)} + Process a wxEVT_MOUSEWHEEL event. + @event{EVT_MOUSE_EVENTS(func)} + Process all mouse events. + @endEventTable @library{wxcore} @category{events} - @see @ref overview_eventhandling + @see wxKeyEvent::CmdDown */ -class wxDropFilesEvent : public wxEvent +class wxMouseEvent : public wxEvent { public: /** - Constructor. - */ - wxDropFilesEvent(wxEventType id = 0, int noFiles = 0, - wxString* files = NULL); - - /** - Returns an array of filenames. - */ - wxString* GetFiles() const; - - /** - Returns the number of files dropped. - */ - int GetNumberOfFiles() const; - - /** - Returns the position at which the files were dropped. - Returns an array of filenames. - */ - wxPoint GetPosition() const; - - /** - wxString* m_files - An array of filenames. - */ + Constructor. Valid event types are: + @li wxEVT_ENTER_WINDOW + @li wxEVT_LEAVE_WINDOW + @li wxEVT_LEFT_DOWN + @li wxEVT_LEFT_UP + @li wxEVT_LEFT_DCLICK + @li wxEVT_MIDDLE_DOWN + @li wxEVT_MIDDLE_UP + @li wxEVT_MIDDLE_DCLICK + @li wxEVT_RIGHT_DOWN + @li wxEVT_RIGHT_UP + @li wxEVT_RIGHT_DCLICK + @li wxEVT_MOUSE_AUX1_DOWN + @li wxEVT_MOUSE_AUX1_UP + @li wxEVT_MOUSE_AUX1_DCLICK + @li wxEVT_MOUSE_AUX2_DOWN + @li wxEVT_MOUSE_AUX2_UP + @li wxEVT_MOUSE_AUX2_DCLICK + @li wxEVT_MOTION + @li wxEVT_MOUSEWHEEL + */ + wxMouseEvent(wxEventType mouseEventType = wxEVT_NULL); /** - int m_noFiles - The number of files dropped. + Returns @true if the Alt key was down at the time of the event. */ - + bool AltDown() const; /** - wxPoint m_pos - The point at which the drop took place. + Returns @true if the event was a first extra button double click. */ -}; - - - -/** - @class wxCommandEvent - @wxheader{event.h} - - This event class contains information about command events, which originate - from a variety of - simple controls. More complex controls, such as wxTreeCtrl, have separate - command event classes. + bool Aux1DClick() const; - @library{wxcore} - @category{events} -*/ -class wxCommandEvent : public wxEvent -{ -public: /** - Constructor. + Returns @true if the first extra button mouse button changed to down. */ - wxCommandEvent(wxEventType commandEventType = 0, int id = 0); + bool Aux1Down() const; /** - Deprecated, use IsChecked() instead. + Returns @true if the first extra button mouse button is currently down, + independent of the current event type. */ - bool Checked() const; + bool Aux1IsDown() const; /** - Returns client data pointer for a listbox or choice selection event - (not valid for a deselection). + Returns @true if the first extra button mouse button changed to up. */ - void* GetClientData() const; + bool Aux1Up() const; /** - Returns client object pointer for a listbox or choice selection event - (not valid for a deselection). + Returns @true if the event was a second extra button double click. */ - wxClientData* GetClientObject() const; + bool Aux2DClick() const; /** - Returns extra information dependant 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 - deselection (@false). A listbox deselection only occurs for - multiple-selection boxes, and in this case the index and string values - are indeterminate and the listbox must be examined by the application. + Returns @true if the second extra button mouse button changed to down. */ - long GetExtraLong() const; + bool Aux2Down() const; /** - 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. + Returns @true if the second extra button mouse button is currently down, + independent of the current event type. */ - int GetInt() const; + bool Aux2IsDown() const; /** - Returns item index for a listbox or choice selection event (not valid for - a deselection). + Returns @true if the second extra button mouse button changed to up. */ - int GetSelection() const; + bool Aux2Up() const; /** - Returns item string for a listbox or choice selection event (not valid for - a deselection). + Returns @true if the identified mouse button is changing state. + Valid values of @a button are: + + @li @c wxMOUSE_BTN_LEFT: check if left button was pressed + @li @c wxMOUSE_BTN_MIDDLE: check if middle button was pressed + @li @c wxMOUSE_BTN_RIGHT: check if right button was pressed + @li @c wxMOUSE_BTN_AUX1: check if the first extra button was pressed + @li @c wxMOUSE_BTN_AUX2: check if the second extra button was pressed + @li @c wxMOUSE_BTN_ANY: check if any button was pressed + + @todo introduce wxMouseButton enum */ - wxString GetString() const; + bool Button(int button) const; /** - This method can be used with checkbox and menu events: for the checkboxes, the - method returns @true for a selection event and @false for a - deselection one. For the menu events, this method indicates if the menu item - just has become checked or unchecked (and thus only makes sense for checkable - menu items). - Notice that this method can not be used with - wxCheckListBox currently. + If the argument is omitted, this returns @true if the event was a mouse + double click event. Otherwise the argument specifies which double click event + was generated (see Button() for the possible values). */ - bool IsChecked() const; + bool ButtonDClick(int but = wxMOUSE_BTN_ANY) const; /** - For a listbox or similar event, returns @true if it is a selection, @false if it - is a deselection. + If the argument is omitted, this returns @true if the event was a mouse + button down event. Otherwise the argument specifies which button-down event + was generated (see Button() for the possible values). */ - bool IsSelection() const; + bool ButtonDown(int = wxMOUSE_BTN_ANY) const; /** - Sets the client data for this event. + If the argument is omitted, this returns @true if the event was a mouse + button up event. Otherwise the argument specifies which button-up event + was generated (see Button() for the possible values). */ - void SetClientData(void* clientData); + bool ButtonUp(int = wxMOUSE_BTN_ANY) const; /** - Sets the client object for this event. The client object is not owned by the - event - object and the event object will not delete the client object in its destructor. - The client object must be owned and deleted by another object (e.g. a control) - that has longer life time than the event object. + Same as MetaDown() under Mac, same as ControlDown() elsewhere. + + @see wxKeyEvent::CmdDown */ - void SetClientObject(wxClientData* clientObject); + bool CmdDown() const; /** - Sets the @b m_extraLong member. + Returns @true if the control key was down at the time of the event. */ - void SetExtraLong(long extraLong); + bool ControlDown() const; /** - Sets the @b m_commandInt member. + Returns @true if this was a dragging event (motion while a button is depressed). + + @see Moving() */ - void SetInt(int intCommand); + bool Dragging() const; /** - Sets the @b m_commandString member. - */ - void SetString(const wxString& string); -}; + Returns @true if the mouse was entering the window. + @see Leaving() + */ + bool Entering() const; + /** + Returns the mouse button which generated this event or @c wxMOUSE_BTN_NONE + if no button is involved (for mouse move, enter or leave event, for example). + Otherwise @c wxMOUSE_BTN_LEFT is returned for the left button down, up and + double click events, @c wxMOUSE_BTN_MIDDLE and @c wxMOUSE_BTN_RIGHT + for the same events for the middle and the right buttons respectively. + */ + int GetButton() const; -/** - @class wxActivateEvent - @wxheader{event.h} + /** + Returns the number of mouse clicks for this event: 1 for a simple click, 2 + for a double-click, 3 for a triple-click and so on. - An activate event is sent when a window or application is being activated - or deactivated. + Currently this function is implemented only in wxMac and returns -1 for the + other platforms (you can still distinguish simple clicks from double-clicks as + they generate different kinds of events however). - @library{wxcore} - @category{events} + @since 2.9.0 + */ + int GetClickCount() const; - @see @ref overview_eventhandling, wxApp::IsActive -*/ -class wxActivateEvent : public wxEvent -{ -public: /** - Constructor. + Returns the configured number of lines (or whatever) to be scrolled per + wheel action. Defaults to three. */ - wxActivateEvent(wxEventType eventType = wxEVT_NULL, bool active = true, - int id = 0); + int GetLinesPerAction() const; /** - Returns @true if the application or window is being activated, @false otherwise. + Returns the logical mouse position in pixels (i.e. translated according to the + translation set for the DC, which usually indicates that the window has been + scrolled). */ - bool GetActive() const; -}; - + wxPoint GetLogicalPosition(const wxDC& dc) const; + //@{ + /** + Sets *x and *y to the position at which the event occurred. + Returns the physical mouse position in pixels. -/** - @class wxContextMenuEvent - @wxheader{event.h} + Note that if the mouse event has been artificially generated from a special + keyboard combination (e.g. under Windows when the "menu" key is pressed), the + returned position is ::wxDefaultPosition. + */ + wxPoint GetPosition() const; + void GetPosition(wxCoord* x, wxCoord* y) const; + void GetPosition(long* x, long* y) const; + //@} - This class is used for context menu events, sent to give - the application a chance to show a context (popup) menu. + /** + Get wheel delta, normally 120. - Note that if wxContextMenuEvent::GetPosition returns wxDefaultPosition, this - means that the event originated - from a keyboard context button event, and you should compute a suitable - position yourself, - for example by calling wxGetMousePosition(). + This is the threshold for action to be taken, and one such action + (for example, scrolling one increment) should occur for each delta. + */ + int GetWheelDelta() const; - When a keyboard context menu button is pressed on Windows, a right-click event - with default position is sent first, - and if this event is not processed, the context menu event is sent. So if you - process mouse events and you find your context menu event handler - is not being called, you could call wxEvent::Skip for mouse right-down events. + /** + Get wheel rotation, positive or negative indicates direction of rotation. - @library{wxcore} - @category{events} + Current devices all send an event when rotation is at least +/-WheelDelta, but + finer resolution devices can be created in the future. - @see @ref overview_wxcommandevent "Command events", @ref - overview_eventhandling -*/ -class wxContextMenuEvent : public wxCommandEvent -{ -public: - /** - Constructor. + Because of this you shouldn't assume that one event is equal to 1 line, but you + should be able to either do partial line scrolling or wait until several + events accumulate before scrolling. */ - wxContextMenuEvent(wxEventType id = 0, int id = 0, - const wxPoint& pos = wxDefaultPosition); + int GetWheelRotation() const; /** - Returns the position in screen coordinates at which the menu should be shown. - Use wxWindow::ScreenToClient to - convert to client coordinates. You can also omit a position from - wxWindow::PopupMenu in order to use - the current mouse pointer position. - If the event originated from a keyboard event, the value returned from this - function will be wxDefaultPosition. + Returns X coordinate of the physical mouse event position. */ - const wxPoint& GetPosition() const; + wxCoord GetX() const; /** - Sets the position at which the menu should be shown. + Returns Y coordinate of the physical mouse event position. */ - void SetPosition(const wxPoint& point); -}; - - - -/** - @class wxEraseEvent - @wxheader{event.h} - - An erase event is sent when a window's background needs to be repainted. - - On some platforms, such as GTK+, this event is simulated (simply generated just - before the - paint event) and may cause flicker. It is therefore recommended that - you set the text background colour explicitly in order to prevent flicker. - The default background colour under GTK+ is grey. - - 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. - - @library{wxcore} - @category{events} + wxCoord GetY() const; - @see @ref overview_eventhandling -*/ -class wxEraseEvent : public wxEvent -{ -public: /** - Constructor. + Returns @true if the event was a mouse button event (not necessarily a button + down event - that may be tested using ButtonDown()). */ - wxEraseEvent(int id = 0, wxDC* dc = NULL); + bool IsButton() const; /** - Returns the device context associated with the erase event to draw on. + Returns @true if the system has been setup to do page scrolling with + the mouse wheel instead of line scrolling. */ - wxDC* GetDC() const; -}; - - - -/** - @class wxFocusEvent - @wxheader{event.h} - - A focus event is sent when a window's focus changes. The window losing focus - receives a "kill focus'' event while the window gaining it gets a "set - focus'' one. + bool IsPageScroll() const; - Notice that the set focus event happens both when the user gives focus to the - window (whether using the mouse or keyboard) and when it is done from the - program itself using wxWindow::SetFocus. + /** + Returns @true if the mouse was leaving the window. - @library{wxcore} - @category{events} + @see Entering(). + */ + bool Leaving() const; - @see @ref overview_eventhandling -*/ -class wxFocusEvent : public wxEvent -{ -public: /** - Constructor. + Returns @true if the event was a left double click. */ - wxFocusEvent(wxEventType eventType = 0, int id = 0); + bool LeftDClick() const; /** - Returns the window associated with this event, that is the window which had the - focus before for the @c wxEVT_SET_FOCUS event and the window which is - going to receive focus for the @c wxEVT_KILL_FOCUS one. - Warning: the window pointer may be @NULL! + Returns @true if the left mouse button changed to down. */ -}; - - - -/** - @class wxChildFocusEvent - @wxheader{event.h} + bool LeftDown() const; - A child focus event is sent to a (parent-)window when one of its child windows - gains focus, - so that the window could restore the focus back to its corresponding child - if it loses it now and regains later. + /** + Returns @true if the left mouse button is currently down, independent + of the current event type. - Notice that child window is the direct child of the window receiving event. - Use wxWindow::FindFocus to retreive the window which is actually getting focus. + Please notice that it is not the same as LeftDown() which returns @true if the + event was generated by the left mouse button being pressed. Rather, it simply + describes the state of the left mouse button at the time when the event was + generated (so while it will be @true for a left click event, it can also be @true + for a right click if it happened while the left mouse button was pressed). - @library{wxcore} - @category{events} + This event is usually used in the mouse event handlers which process "move + mouse" messages to determine whether the user is (still) dragging the mouse. + */ + bool LeftIsDown() const; + + /** + Returns @true if the left mouse button changed to up. + */ + bool LeftUp() const; - @see @ref overview_eventhandling -*/ -class wxChildFocusEvent : public wxCommandEvent -{ -public: /** - Constructor. + Returns @true if the Meta key was down at the time of the event. + */ + bool MetaDown() const; - @param win - The direct child which is (or which contains the window which is) receiving - the focus. + /** + Returns @true if the event was a middle double click. */ - wxChildFocusEvent(wxWindow* win = NULL); + bool MiddleDClick() const; /** - Returns the direct child which receives the focus, or a (grand-)parent of the - control receiving the focus. - To get the actually focused control use wxWindow::FindFocus. + Returns @true if the middle mouse button changed to down. */ -}; + bool MiddleDown() const; + /** + Returns @true if the middle mouse button is currently down, independent + of the current event type. + */ + bool MiddleIsDown() const; + /** + Returns @true if the middle mouse button changed to up. + */ + bool MiddleUp() const; -/** - @class wxMouseCaptureLostEvent - @wxheader{event.h} + /** + Returns @true if this was a motion event and no mouse buttons were pressed. + If any mouse button is held pressed, then this method returns @false and + Dragging() returns @true. + */ + bool Moving() const; - An mouse capture lost event is sent to a window that obtained mouse capture, - which was subsequently loss due to "external" event, for example when a dialog - box is shown or if another application captures the mouse. + /** + Returns @true if the event was a right double click. + */ + bool RightDClick() const; - If this happens, this event is sent to all windows that are on capture stack - (i.e. called CaptureMouse, but didn't call ReleaseMouse yet). The event is - not sent if the capture changes because of a call to CaptureMouse or - ReleaseMouse. + /** + Returns @true if the right mouse button changed to down. + */ + bool RightDown() const; - This event is currently emitted under Windows only. + /** + Returns @true if the right mouse button is currently down, independent + of the current event type. + */ + bool RightIsDown() const; - @library{wxcore} - @category{events} + /** + Returns @true if the right mouse button changed to up. + */ + bool RightUp() const; - @see wxMouseCaptureChangedEvent, @ref overview_eventhandling, - wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture -*/ -class wxMouseCaptureLostEvent : public wxEvent -{ -public: /** - Constructor. + Returns @true if the shift key was down at the time of the event. */ - wxMouseCaptureLostEvent(wxWindowID windowId = 0); + bool ShiftDown() const; }; /** - @class wxNotifyEvent + @class wxDropFilesEvent @wxheader{event.h} - This class is not used by the event handlers by itself, but is a base class - for other event classes (such as wxNotebookEvent). + This class is used for drop files events, that is, when files have been dropped + onto the window. This functionality is currently only available under Windows. - It (or an object of a derived class) is sent when the controls state is being - changed and allows the program to wxNotifyEvent::Veto this - change if it wants to prevent it from happening. + The window must have previously been enabled for dropping by calling + wxWindow::DragAcceptFiles(). + + Important note: this is a separate implementation to the more general drag and drop + implementation documented in the @ref overview_dnd. It uses the older, Windows + message-based approach of dropping files. + + @beginEventTable{wxDropFilesEvent} + @event{EVT_DROP_FILES(func)} + Process a wxEVT_DROP_FILES event. + @endEventTable + + @onlyfor{wxmsw} @library{wxcore} @category{events} - @see wxNotebookEvent + @see @ref overview_eventhandling */ -class wxNotifyEvent : public wxCommandEvent +class wxDropFilesEvent : public wxEvent { public: /** - Constructor (used internally by wxWidgets only). + Constructor. */ - wxNotifyEvent(wxEventType eventType = wxEVT_NULL, int id = 0); + wxDropFilesEvent(wxEventType id = 0, int noFiles = 0, + wxString* files = NULL); /** - This is the opposite of Veto(): it explicitly - allows the event to be processed. For most events it is not necessary to call - this method as the events are allowed anyhow but some are forbidden by default - (this will be mentioned in the corresponding event description). + Returns an array of filenames. */ - void Allow(); + wxString* GetFiles() const; /** - Returns @true if the change is allowed (Veto() - hasn't been called) or @false otherwise (if it was). + Returns the number of files dropped. */ - bool IsAllowed() const; + int GetNumberOfFiles() const; /** - Prevents the change announced by this event from happening. - It is in general a good idea to notify the user about the reasons for vetoing - the change because otherwise the applications behaviour (which just refuses to - do what the user wants) might be quite surprising. + Returns the position at which the files were dropped. + Returns an array of filenames. */ - void Veto(); + wxPoint GetPosition() const; }; /** - @class wxHelpEvent + @class wxCommandEvent @wxheader{event.h} - A help event is sent when the user has requested context-sensitive help. - This can either be caused by the application requesting - context-sensitive help mode via wxContextHelp, or - (on MS Windows) by the system generating a WM_HELP message when the user - pressed F1 or clicked - on the query button in a dialog caption. - - A help event is sent to the window that the user clicked on, and is propagated - up the - window hierarchy until the event is processed or there are no more event - handlers. - The application should call wxEvent::GetId to check the identity of the - clicked-on window, - and then either show some suitable help or call wxEvent::Skip if the identifier - is unrecognised. - Calling Skip is important because it allows wxWidgets to generate further - events for ancestors - of the clicked-on window. Otherwise it would be impossible to show help for - container windows, - since processing would stop after the first window found. + This event class contains information about command events, which originate + from a variety of simple controls. + + More complex controls, such as wxTreeCtrl, have separate command event classes. + + @beginEventTable{wxCommandEvent} + @event{EVT_COMMAND(id, event, func)} + Process a command, supplying the window identifier, command event identifier, + and member function. + @event{EVT_COMMAND_RANGE(id1, id2, event, func)} + 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. + @event{EVT_CHECKBOX(id, func)} + Process a 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. + @event{EVT_COMBOBOX(id, func)} + Process a 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. + @event{EVT_LISTBOX_DCLICK(id, func)} + Process a 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. + @event{EVT_MENU_RANGE(id1, id2, func)} + Process a 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. + @event{EVT_RADIOBUTTON(id, func)} + Process a 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 + 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. + @event{EVT_TEXT(id, func)} + Process a 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. + 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 + 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. + @event{EVT_TOOL(id, func)} + Process a wxEVT_COMMAND_TOOL_CLICKED event (a synonym for 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. + @event{EVT_TOOL_RCLICKED(id, func)} + Process a 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. + @event{EVT_TOOL_ENTER(id, func)} + Process a 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). + @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). + @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). + @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). + @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). + @event{EVT_COMMAND_ENTER(id, func)} + Process a wxEVT_COMMAND_ENTER command, which is generated by a control. + @endEventTable @library{wxcore} @category{events} - - @see wxContextHelp, wxDialog, @ref overview_eventhandling */ -class wxHelpEvent : public wxCommandEvent +class wxCommandEvent : public wxEvent { public: - // how was this help event generated? - enum Origin - { - Origin_Unknown, // unrecognized event source - Origin_Keyboard, // event generated from F1 key press - Origin_HelpButton // event from [?] button on the title bar (Windows) - }; - /** Constructor. */ - wxHelpEvent(wxEventType type = wxEVT_NULL, - wxWindowID winid = 0, - const wxPoint& pt = wxDefaultPosition, - Origin origin = Origin_Unknown); + wxCommandEvent(wxEventType commandEventType = 0, int id = 0); /** - Returns the origin of the help event which is one of the following values: - - @b Origin_Unknown - - Unrecognized event source. - - @b Origin_Keyboard + Returns client data pointer for a listbox or choice selection event + (not valid for a deselection). + */ + void* GetClientData() const; - Event generated by @c F1 key press. + /** + Returns client object pointer for a listbox or choice selection event + (not valid for a deselection). + */ + wxClientData* GetClientObject() const; - @b Origin_HelpButton + /** + Returns extra information dependant on the event objects type. - Event generated by - wxContextHelp or using the "?" title bur button under - MS Windows. + If the event comes from a listbox selection, it is a boolean + determining whether the event was a selection (@true) or a + deselection (@false). A listbox deselection only occurs for + multiple-selection boxes, and in this case the index and string values + are indeterminate and the listbox must be examined by the application. + */ + long GetExtraLong() const; - The application may handle events generated using the keyboard or mouse - differently, e.g. by using wxGetMousePosition() - for the mouse events. + /** + 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. + */ + int GetInt() const; - @see SetOrigin() + /** + Returns item index for a listbox or choice selection event (not valid for + a deselection). */ - Origin GetOrigin() const; + int GetSelection() const; /** - Returns the left-click position of the mouse, in screen coordinates. This allows - the application to position the help appropriately. + Returns item string for a listbox or choice selection event (not valid for + a deselection). */ - const wxPoint& GetPosition() const; + wxString GetString() const; /** - Set the help event origin, only used internally by wxWidgets normally. + This method can be used with checkbox and menu events: for the checkboxes, the + method returns @true for a selection event and @false for a deselection one. + For the menu events, this method indicates if the menu item just has become + checked or unchecked (and thus only makes sense for checkable menu items). - @see GetOrigin() + Notice that this method can not be used with wxCheckListBox currently. */ - void SetOrigin(Origin); + bool IsChecked() const; /** - Sets the left-click position of the mouse, in screen coordinates. + For a listbox or similar event, returns @true if it is a selection, @false if it + is a deselection. */ - void SetPosition(const wxPoint& pt); -}; - - + bool IsSelection() const; -/** - @class wxScrollEvent - @wxheader{event.h} + /** + Sets the client data for this event. + */ + void SetClientData(void* clientData); - A scroll event holds information about events sent from stand-alone - scrollbars() and sliders(). Note that - starting from wxWidgets 2.1, scrolled windows send the - wxScrollWinEvent which does not derive from - wxCommandEvent, but from wxEvent directly - don't confuse these two kinds of - events and use the event table macros mentioned below only for the - scrollbar-like controls. + /** + Sets the client object for this event. The client object is not owned by the + event object and the event object will not delete the client object in its destructor. - @library{wxcore} - @category{events} + The client object must be owned and deleted by another object (e.g. a control) + that has longer life time than the event object. + */ + void SetClientObject(wxClientData* clientObject); - @see wxScrollBar, wxSlider, wxSpinButton, , wxScrollWinEvent, @ref - overview_eventhandling -*/ -class wxScrollEvent : public wxCommandEvent -{ -public: /** - Constructor. + Sets the @b m_extraLong member. */ - wxScrollEvent(wxEventType commandType = 0, int id = 0, int pos = 0, - int orientation = 0); + void SetExtraLong(long extraLong); /** - Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the - scrollbar. + Sets the @b m_commandInt member. */ - int GetOrientation() const; + void SetInt(int intCommand); /** - Returns the position of the scrollbar. + Sets the @b m_commandString member. */ - int GetPosition() const; + void SetString(const wxString& string); }; /** - @class wxIdleEvent + @class wxActivateEvent @wxheader{event.h} - This class is used for idle events, which are generated when the system becomes - idle. Note that, unless you do something specifically, the idle events are not - sent if the system remains idle once it has become it, e.g. only a single idle - event will be generated until something else resulting in more normal events - happens and only then is the next idle event sent again. If you need to ensure - a continuous stream of idle events, you can either use - wxIdleEvent::RequestMore method in your handler or call - wxWakeUpIdle() periodically (for example from timer - event), but note that both of these approaches (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. + An activate event is sent when a window or application is being activated + or deactivated. - @library{wxbase} + @beginEventTable{wxActivateEvent} + @event{EVT_ACTIVATE(func)} + Process a wxEVT_ACTIVATE event. + @event{EVT_ACTIVATE_APP(func)} + Process a wxEVT_ACTIVATE_APP event. + @event{EVT_HIBERNATE(func)} + Process a hibernate event, supplying the member function. This event applies + to wxApp only, and only on Windows SmartPhone and PocketPC. + It is generated when the system is low on memory; the application should free + up as much memory as possible, and restore full working state when it receives + a wxEVT_ACTIVATE or wxEVT_ACTIVATE_APP event. + @endEventTable + + + @library{wxcore} @category{events} - @see @ref overview_eventhandling, wxUpdateUIEvent, - wxWindow::OnInternalIdle + @see @ref overview_eventhandling, wxApp::IsActive */ -class wxIdleEvent : public wxEvent +class wxActivateEvent : public wxEvent { public: /** Constructor. */ - wxIdleEvent(); - - /** - Returns @true if it is appropriate to send idle events to - this window. - This function looks at the mode used (see wxIdleEvent::SetMode), - and the wxWS_EX_PROCESS_IDLE style in @a window to determine whether idle - events should be sent to - this window now. By default this will always return @true because - the update mode is initially wxIDLE_PROCESS_ALL. You can change the mode - to only send idle events to windows with the wxWS_EX_PROCESS_IDLE extra window - style set. - - @see SetMode() - */ - static bool CanSend(wxWindow* window); - - /** - Static function returning a value specifying how wxWidgets - will send idle events: to all windows, or only to those which specify that they - will process the events. - See SetMode(). - */ - static wxIdleMode GetMode(); - - /** - Returns @true if the OnIdle function processing this event requested more - processing time. - - @see RequestMore() - */ - bool MoreRequested() const; - - /** - Tells wxWidgets that more processing is required. This function can be called - by an OnIdle - handler for a window or window event handler to indicate that wxApp::OnIdle - should - forward the OnIdle event once more to the application windows. If no window - calls this function - during OnIdle, then the application will remain in a passive event loop (not - calling OnIdle) until a - new event is posted to the application by the windowing system. - - @see MoreRequested() - */ - void RequestMore(bool needMore = true); + wxActivateEvent(wxEventType eventType = wxEVT_NULL, bool active = true, + int id = 0); /** - Static function for specifying how wxWidgets will send idle events: to - all windows, or only to those which specify that they - will process the events. - @a mode can be one of the following values. - The default is wxIDLE_PROCESS_ALL. + Returns @true if the application or window is being activated, @false otherwise. */ - static void SetMode(wxIdleMode mode); + bool GetActive() const; }; /** - @class wxInitDialogEvent + @class wxContextMenuEvent @wxheader{event.h} - A wxInitDialogEvent is sent as a dialog or panel is being initialised. - Handlers for this event can transfer data to the window. - The default handler calls wxWindow::TransferDataToWindow. + This class is used for context menu events, sent to give + the application a chance to show a context (popup) menu. + + Note that if wxContextMenuEvent::GetPosition returns wxDefaultPosition, this + means that the event originated from a keyboard context button event, and you + should compute a suitable position yourself, for example by calling wxGetMousePosition(). + + When a keyboard context menu button is pressed on Windows, a right-click event + with default position is sent first, and if this event is not processed, the + context menu event is sent. So if you process mouse events and you find your + context menu event handler is not being called, you could call wxEvent::Skip() + for mouse right-down events. + + @beginEventTable{wxContextMenuEvent} + @event{EVT_CONTEXT_MENU(func)} + A right click (or other context menu command depending on platform) has been detected. + @endEventTable + @library{wxcore} @category{events} - @see @ref overview_eventhandling + @see wxCommandEvent, @ref overview_eventhandling */ -class wxInitDialogEvent : public wxEvent +class wxContextMenuEvent : public wxCommandEvent { public: /** Constructor. */ - wxInitDialogEvent(int id = 0); + wxContextMenuEvent(wxEventType id = wxEVT_NULL, int id = 0, + const wxPoint& pos = wxDefaultPosition); + + /** + Returns the position in screen coordinates at which the menu should be shown. + Use wxWindow::ScreenToClient to convert to client coordinates. + + You can also omit a position from wxWindow::PopupMenu in order to use + the current mouse pointer position. + + If the event originated from a keyboard event, the value returned from this + function will be wxDefaultPosition. + */ + const wxPoint& GetPosition() const; + + /** + Sets the position at which the menu should be shown. + */ + void SetPosition(const wxPoint& point); }; /** - @class wxWindowDestroyEvent + @class wxEraseEvent @wxheader{event.h} - This event is sent from the wxWindow destructor wxWindow::~wxWindow() when a - window is destroyed. + An erase event is sent when a window's background needs to be repainted. - 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. + On some platforms, such as GTK+, this event is simulated (simply generated just + before the paint event) and may cause flicker. It is therefore recommended that + you set the text background colour explicitly in order to prevent flicker. + The default background colour under GTK+ is grey. + + 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. - 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. + @beginEventTable{wxEraseEvent} + @event{EVT_ERASE_BACKGROUND(func)} + Process a wxEVT_ERASE_BACKGROUND event. + @endEventTable @library{wxcore} @category{events} - @see @ref overview_eventhandling, wxWindowCreateEvent + @see @ref overview_eventhandling */ -class wxWindowDestroyEvent : public wxCommandEvent +class wxEraseEvent : public wxEvent { public: /** Constructor. */ - wxWindowDestroyEvent(wxWindow* win = NULL); + wxEraseEvent(int id = 0, wxDC* dc = NULL); + + /** + Returns the device context associated with the erase event to draw on. + */ + wxDC* GetDC() const; }; /** - @class wxNavigationKeyEvent + @class wxFocusEvent @wxheader{event.h} - This event class contains information about navigation events, - generated by navigation keys such as tab and page down. + A focus event is sent when a window's focus changes. The window losing focus + receives a "kill focus" event while the window gaining it gets a "set focus" one. - 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. + Notice that the set focus event happens both when the user gives focus to the + window (whether using the mouse or keyboard) and when it is done from the + program itself using wxWindow::SetFocus. + + @beginEventTable{wxFocusEvent} + @event{EVT_SET_FOCUS(func)} + Process a wxEVT_SET_FOCUS event. + @event{EVT_KILL_FOCUS(func)} + Process a wxEVT_KILL_FOCUS event. + @endEventTable @library{wxcore} @category{events} - @see wxWindow::Navigate, wxWindow::NavigateIn + @see @ref overview_eventhandling */ -class wxNavigationKeyEvent +class wxFocusEvent : public wxEvent { public: - //@{ /** Constructor. */ - wxNavigationKeyEvent(); - wxNavigationKeyEvent(const wxNavigationKeyEvent& event); - //@} + wxFocusEvent(wxEventType eventType = wxEVT_NULL, int id = 0); /** - Returns the child that has the focus, or @NULL. - */ - wxWindow* GetCurrentFocus() const; + Returns the window associated with this event, that is the window which had the + focus before for the @c wxEVT_SET_FOCUS event and the window which is + going to receive focus for the @c wxEVT_KILL_FOCUS one. - /** - Returns @true if the navigation was in the forward direction. + Warning: the window pointer may be @NULL! */ - bool GetDirection() const; + wxWindow *GetWindow() const; +}; - /** - Returns @true if the navigation event was from a tab key. This is required - for proper navigation over radio buttons. - */ - bool IsFromTab() const; - /** - Returns @true if the navigation event represents a window change (for - example, from Ctrl-Page Down - in a notebook). - */ - bool IsWindowChange() const; - /** - Sets the current focus window member. - */ - void SetCurrentFocus(wxWindow* currentFocus); +/** + @class wxChildFocusEvent + @wxheader{event.h} - /** - Sets the direction to forward if @a direction is @true, or backward if @c - @false. - */ - void SetDirection(bool direction); + A child focus event is sent to a (parent-)window when one of its child windows + gains focus, so that the window could restore the focus back to its corresponding + child if it loses it now and regains later. - /** - Sets the flags. - */ - void SetFlags(long flags); + Notice that child window is the direct child of the window receiving event. + Use wxWindow::FindFocus() to retreive the window which is actually getting focus. + + @beginEventTable{wxChildFocusEvent} + @event{EVT_CHILD_FOCUS(func)} + Process a wxEVT_CHILD_FOCUS event. + @endEventTable + + @library{wxcore} + @category{events} + @see @ref overview_eventhandling +*/ +class wxChildFocusEvent : public wxCommandEvent +{ +public: /** - Marks the navigation event as from a tab key. + Constructor. + + @param win + The direct child which is (or which contains the window which is) receiving + the focus. */ - void SetFromTab(bool fromTab); + wxChildFocusEvent(wxWindow* win = NULL); /** - Marks the event as a window change event. + Returns the direct child which receives the focus, or a (grand-)parent of the + control receiving the focus. + + To get the actually focused control use wxWindow::FindFocus. */ - void SetWindowChange(bool windowChange); + wxWindow *GetWindow() const; }; /** - @class wxMouseCaptureChangedEvent + @class wxMouseCaptureLostEvent @wxheader{event.h} - An mouse capture changed event is sent to a window that loses its - mouse capture. This is called even if wxWindow::ReleaseCapture - was called by the application code. Handling this event allows - an application to cater for unexpected capture releases which - might otherwise confuse mouse handling code. + An mouse capture lost event is sent to a window that obtained mouse capture, + which was subsequently loss due to "external" event, for example when a dialog + box is shown or if another application captures the mouse. + + If this happens, this event is sent to all windows that are on capture stack + (i.e. called CaptureMouse, but didn't call ReleaseMouse yet). The event is + not sent if the capture changes because of a call to CaptureMouse or + ReleaseMouse. + + This event is currently emitted under Windows only. + + @beginEventTable{wxMouseCaptureLostEvent} + @event{EVT_MOUSE_CAPTURE_LOST(func)} + Process a wxEVT_MOUSE_CAPTURE_LOST event. + @endEventTable - This event is implemented under Windows only. + @onlyfor{wxmsw} @library{wxcore} @category{events} - @see wxMouseCaptureLostEvent, @ref overview_eventhandling, + @see wxMouseCaptureChangedEvent, @ref overview_eventhandling, wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture */ -class wxMouseCaptureChangedEvent : public wxEvent +class wxMouseCaptureLostEvent : public wxEvent { public: /** Constructor. */ - wxMouseCaptureChangedEvent(wxWindowID windowId = 0, - wxWindow* gainedCapture = NULL); - - /** - Returns the window that gained the capture, or @NULL if it was a non-wxWidgets - window. - */ - wxWindow* GetCapturedWindow() const; + wxMouseCaptureLostEvent(wxWindowID windowId = 0); }; /** - @class wxCloseEvent + @class wxNotifyEvent @wxheader{event.h} - This event class contains information about window and session close events. - - The handler function for EVT_CLOSE is called when the user has tried to close a - a frame - or dialog box using the window manager (X) or system menu (Windows). It can - also be invoked by the application itself programmatically, for example by - calling the wxWindow::Close function. - - You should check whether the application is forcing the deletion of the window - using wxCloseEvent::CanVeto. If this is @false, - you @e must destroy the window using wxWindow::Destroy. - If the return value is @true, it is up to you whether you respond by destroying - the window. + This class is not used by the event handlers by itself, but is a base class + for other event classes (such as wxNotebookEvent). - If you don't destroy the window, you should call wxCloseEvent::Veto to - let the calling code know that you did not destroy the window. This allows the - wxWindow::Close function - to return @true or @false depending on whether the close instruction was - honoured or not. + It (or an object of a derived class) is sent when the controls state is being + changed and allows the program to wxNotifyEvent::Veto() this change if it wants + to prevent it from happening. @library{wxcore} @category{events} - @see wxWindow::Close, @ref overview_windowdeletionoverview "Window deletion - overview" + @see wxNotebookEvent */ -class wxCloseEvent : public wxEvent +class wxNotifyEvent : public wxCommandEvent { public: /** - Constructor. + Constructor (used internally by wxWidgets only). */ - wxCloseEvent(wxEventType commandEventType = 0, int id = 0); + wxNotifyEvent(wxEventType eventType = wxEVT_NULL, int id = 0); /** - Returns @true if you can veto a system shutdown or a window close event. - Vetoing a window close event is not possible if the calling code wishes to - force the application to exit, and so this function must be called to check - this. + This is the opposite of Veto(): it explicitly allows the event to be processed. + For most events it is not necessary to call this method as the events are allowed + anyhow but some are forbidden by default (this will be mentioned in the corresponding + event description). */ - bool CanVeto() const; + void Allow(); /** - Returns @true if the user is just logging off or @false if the system is - shutting down. This method can only be called for end session and query end - session events, it doesn't make sense for close window event. + Returns @true if the change is allowed (Veto() hasn't been called) or @false + otherwise (if it was). */ - bool GetLoggingOff() const; + bool IsAllowed() const; /** - Sets the 'can veto' flag. - */ - void SetCanVeto(bool canVeto); + Prevents the change announced by this event from happening. - /** - Sets the 'force' flag. + It is in general a good idea to notify the user about the reasons for vetoing + the change because otherwise the applications behaviour (which just refuses to + do what the user wants) might be quite surprising. */ - void SetForce(bool force) const; + void Veto(); +}; + - /** - Sets the 'logging off' flag. - */ - void SetLoggingOff(bool loggingOff); - /** - Call this from your event handler to veto a system shutdown or to signal - to the calling application that a window close did not happen. - You can only veto a shutdown if CanVeto() returns - @true. - */ - void Veto(bool veto = true); -}; +/** + Indicates how a wxHelpEvent was generated. +*/ +enum wxHelpEventOrigin +{ + wxHE_ORIGIN_UNKNOWN = -1, /**< unrecognized event source. */ + wxHE_ORIGIN_KEYBOARD, /**< event generated from F1 key press. */ + /** event generated by wxContextHelp or from the [?] button on + the title bar (Windows). */ + wxHE_ORIGIN_HELPBUTTON +}; /** - @class wxMenuEvent + @class wxHelpEvent @wxheader{event.h} - This class is used for a variety of menu-related events. Note that - these do not include menu command events, which are - handled using wxCommandEvent objects. + A help event is sent when the user has requested context-sensitive help. + This can either be caused by the application requesting context-sensitive help mode + via wxContextHelp, or (on MS Windows) by the system generating a WM_HELP message when + the user pressed F1 or clicked on the query button in a dialog caption. - The default handler for wxEVT_MENU_HIGHLIGHT displays help - text in the first field of the status bar. + A help event is sent to the window that the user clicked on, and is propagated + up the window hierarchy until the event is processed or there are no more event + handlers. + + The application should call wxEvent::GetId to check the identity of the + clicked-on window, and then either show some suitable help or call wxEvent::Skip() + if the identifier is unrecognised. + + Calling Skip is important because it allows wxWidgets to generate further + events for ancestors of the clicked-on window. Otherwise it would be impossible to + show help for container windows, since processing would stop after the first window + found. + + @beginEventTable{wxHelpEvent} + @event{EVT_HELP(id, func)} + Process a wxEVT_HELP event. + @event{EVT_HELP_RANGE(id1, id2, func)} + Process a wxEVT_HELP event for a range of ids. + @endEventTable @library{wxcore} @category{events} - @see @ref overview_wxcommandevent "Command events", @ref - overview_eventhandling + @see wxContextHelp, wxDialog, @ref overview_eventhandling */ -class wxMenuEvent : public wxEvent +class wxHelpEvent : public wxCommandEvent { public: /** Constructor. */ - wxMenuEvent(wxEventType id = 0, int id = 0, wxMenu* menu = NULL); + wxHelpEvent(wxEventType type = wxEVT_NULL, + wxWindowID winid = 0, + const wxPoint& pt = wxDefaultPosition, + wxHelpEventOrigin origin = wxHE_ORIGIN_UNKNOWN); + + /** + Returns the origin of the help event which is one of the ::wxHelpEventOrigin + values. + + The application may handle events generated using the keyboard or mouse + differently, e.g. by using wxGetMousePosition() for the mouse events. + + @see SetOrigin() + */ + wxHelpEventOrigin GetOrigin() const; /** - 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 left-click position of the mouse, in screen coordinates. + This allows the application to position the help appropriately. */ - wxMenu* GetMenu() const; + const wxPoint& GetPosition() const; /** - Returns the menu identifier associated with the event. This method should be - only used with the @c HIGHLIGHT events. + Set the help event origin, only used internally by wxWidgets normally. + + @see GetOrigin() */ - int GetMenuId() const; + void SetOrigin(wxHelpEventOrigin); /** - Returns @true if the menu which is being opened or closed is a popup menu, - @false if it is a normal one. - This method should only be used with the @c OPEN and @c CLOSE events. + Sets the left-click position of the mouse, in screen coordinates. */ - bool IsPopup() const; + void SetPosition(const wxPoint& pt); }; /** - @class wxEventBlocker + @class wxScrollEvent @wxheader{event.h} - This class is a special event handler which allows to discard - any event (or a set of event types) directed to a specific window. + A scroll event holds information about events sent from stand-alone + scrollbars (see wxScrollBar) and sliders (see wxSlider). - Example: + Note that scrolled windows send the wxScrollWinEvent which does not derive from + wxCommandEvent, but from wxEvent directly - don't confuse these two kinds of + events and use the event table macros mentioned below only for the scrollbar-like + controls. - @code - { - // block all events directed to this window while - // we do the 1000 FuncWhichSendsEvents() calls - wxEventBlocker blocker(this); + @section wxscrollevent_diff The difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED - for ( int i = 0; i 1000; i++ ) - FuncWhichSendsEvents(i); + 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 + by an EVT_SCROLL_CHANGED event). - } // ~wxEventBlocker called, old event handler is restored + The EVT_SCROLL_CHANGED event also occurs when using the keyboard to change the thumb + position, and when clicking next to the thumb (In all these cases the EVT_SCROLL_THUMBRELEASE + event does not happen). - // the event generated by this call will be processed - FuncWhichSendsEvents(0) - @endcode + In short, the EVT_SCROLL_CHANGED event is triggered when scrolling/ moving has finished + independently of the way it had started. Please see the widgets sample ("Slider" page) + to see the difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED in action. + + @remarks + Note that unless specifying a scroll control identifier, you will need to test for scrollbar + orientation with wxScrollEvent::GetOrientation, since horizontal and vertical scroll events + are processed using the same event handler. + + @beginEventTable{wxScrollEvent} + You can use EVT_COMMAND_SCROLL... macros with window IDs for when intercepting + scroll events from controls, or EVT_SCROLL... macros without window IDs for + intercepting scroll events from the receiving window -- except for this, the + macros behave exactly the same. + @event{EVT_SCROLL(func)} + Process all scroll events. + @event{EVT_SCROLL_TOP(func)} + Process wxEVT_SCROLL_TOP scroll-to-top events (minimum position). + @event{EVT_SCROLL_BOTTOM(func)} + Process wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position). + @event{EVT_SCROLL_LINEUP(func)} + Process wxEVT_SCROLL_LINEUP line up events. + @event{EVT_SCROLL_LINEDOWN(func)} + Process wxEVT_SCROLL_LINEDOWN line down events. + @event{EVT_SCROLL_PAGEUP(func)} + Process wxEVT_SCROLL_PAGEUP page up events. + @event{EVT_SCROLL_PAGEDOWN(func)} + Process wxEVT_SCROLL_PAGEDOWN page down events. + @event{EVT_SCROLL_THUMBTRACK(func)} + Process wxEVT_SCROLL_THUMBTRACK thumbtrack events (frequent events sent as the + user drags the thumbtrack). + @event{EVT_SCROLL_THUMBRELEASE(func)} + Process wxEVT_SCROLL_THUMBRELEASE thumb release events. + @event{EVT_SCROLL_CHANGED(func)} + Process wxEVT_SCROLL_CHANGED end of scrolling events (MSW only). + @event{EVT_COMMAND_SCROLL(id, func)} + Process all scroll events. + @event{EVT_COMMAND_SCROLL_TOP(id, func)} + Process wxEVT_SCROLL_TOP scroll-to-top events (minimum position). + @event{EVT_COMMAND_SCROLL_BOTTOM(id, func)} + Process wxEVT_SCROLL_BOTTOM scroll-to-bottom events (maximum position). + @event{EVT_COMMAND_SCROLL_LINEUP(id, func)} + Process wxEVT_SCROLL_LINEUP line up events. + @event{EVT_COMMAND_SCROLL_LINEDOWN(id, func)} + Process wxEVT_SCROLL_LINEDOWN line down events. + @event{EVT_COMMAND_SCROLL_PAGEUP(id, func)} + Process wxEVT_SCROLL_PAGEUP page up events. + @event{EVT_COMMAND_SCROLL_PAGEDOWN(id, func)} + Process wxEVT_SCROLL_PAGEDOWN page down events. + @event{EVT_COMMAND_SCROLL_THUMBTRACK(id, func)} + Process wxEVT_SCROLL_THUMBTRACK thumbtrack events (frequent events sent + as the user drags the thumbtrack). + @event{EVT_COMMAND_SCROLL_THUMBRELEASE(func)} + Process wxEVT_SCROLL_THUMBRELEASE thumb release events. + @event{EVT_COMMAND_SCROLL_CHANGED(func)} + Process wxEVT_SCROLL_CHANGED end of scrolling events (MSW only). + @endEventTable @library{wxcore} @category{events} - @see @ref overview_eventhandling, wxEvtHandler + @see wxScrollBar, wxSlider, wxSpinButton, wxScrollWinEvent, @ref overview_eventhandling */ -class wxEventBlocker : public wxEvtHandler +class wxScrollEvent : public wxCommandEvent { public: /** - Constructs the blocker for the given window and for the given event type. - If @a type is @c wxEVT_ANY, then all events for that window are - blocked. You can call Block() after creation to - add other event types to the list of events to block. - Note that the @a win window @b must remain alive until the - wxEventBlocker object destruction. + Constructor. */ - wxEventBlocker(wxWindow* win, wxEventType = -0x000000001); + wxScrollEvent(wxEventType commandType = wxEVT_NULL, int id = 0, int pos = 0, + int orientation = 0); /** - Destructor. The blocker will remove itself from the chain of event handlers for - the window provided in the constructor, thus restoring normal processing of - events. + Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the + scrollbar. */ - virtual ~wxEventBlocker(); + int GetOrientation() const; /** - Adds to the list of event types which should be blocked the given @e eventType. + Returns the position of the scrollbar. */ - void Block(wxEventType eventType); + int GetPosition() const; }; +/** + See wxIdleEvent::SetMode() for more info. +*/ +enum wxIdleMode +{ + /** Send idle events to all windows */ + wxIDLE_PROCESS_ALL, + + /** Send idle events to windows that have the wxWS_EX_PROCESS_IDLE flag specified */ + wxIDLE_PROCESS_SPECIFIED +}; /** - @class wxEvtHandler + @class wxIdleEvent @wxheader{event.h} - A class that can handle events from the windowing system. - wxWindow (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. + This class is used for idle events, which are generated when the system becomes + idle. Note that, unless you do something specifically, the idle events are not + sent if the system remains idle once it has become it, e.g. only a single idle + event will be generated until something else resulting in more normal events + happens and only then is the next idle event sent again. + + If you need to ensure a continuous stream of idle events, you can either use + wxIdleEvent::RequestMore method in your handler or call wxWakeUpIdle() periodically + (for example from a timer event handler), but note that both of these approaches + (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. + + @beginEventTable{wxIdleEvent} + @event{EVT_IDLE(func)} + Process a wxEVT_IDLE event. + @endEventTable @library{wxbase} @category{events} - @see @ref overview_eventhandling + @see @ref overview_eventhandling, wxUpdateUIEvent, wxWindow::OnInternalIdle */ -class wxEvtHandler : public wxObject +class wxIdleEvent : public wxEvent { public: /** Constructor. */ - wxEvtHandler(); + wxIdleEvent(); /** - 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. - */ - virtual ~wxEvtHandler(); + Returns @true if it is appropriate to send idle events to this window. - /** - This function posts an event to be processed later. + This function looks at the mode used (see wxIdleEvent::SetMode), + and the wxWS_EX_PROCESS_IDLE style in @a window to determine whether idle + events should be sent to this window now. - @param event - Event to add to process queue. + By default this will always return @true because the update mode is initially + wxIDLE_PROCESS_ALL. You can change the mode to only send idle events to + windows with the wxWS_EX_PROCESS_IDLE extra window style set. - @remarks The difference between sending an event (using the ProcessEvent - method) and posting it is that in the first case the - event is processed before the function returns, while - in the second case, the function returns immediately - and the event will be processed sometime later (usually - during the next event loop iteration). + @see SetMode() */ - virtual void AddPendingEvent(const wxEvent& event); + static bool CanSend(wxWindow* window); - //@{ /** - Connects the given function dynamically with the event handler, id and event - type. This - is an alternative to the use of static event tables. See the 'event' or the old - 'dynamic' sample for usage. + Static function returning a value specifying how wxWidgets will send idle + events: to all windows, or only to those which specify that they + will process the events. - @param id - The identifier (or first of the identifier range) to be - associated with the event handler function. For the version not taking this - argument, it defaults to wxID_ANY. - @param lastId - The second part of the identifier range to be associated with the event - handler function. - @param eventType - The event type to be associated with this event handler. - @param function - The event handler function. Note that this function should - be explicitly converted to the correct type which can be done using a macro - called wxFooEventHandler for the handler for any wxFooEvent. - @param userData - Data to be associated with the event table entry. - @param eventSink - Object whose member function should be called. If this is @NULL, - this will be used. + @see SetMode(). */ - void Connect(int id, int lastId, wxEventType eventType, - wxObjectEventFunction function, - wxObject* userData = NULL, - wxEvtHandler* eventSink = NULL); - void Connect(int id, wxEventType eventType, - wxObjectEventFunction function, - wxObject* userData = NULL, - wxEvtHandler* eventSink = NULL); - void Connect(wxEventType eventType, - wxObjectEventFunction function, - wxObject* userData = NULL, - wxEvtHandler* eventSink = NULL); - //@} + static wxIdleMode GetMode(); - //@{ /** - Disconnects the given function dynamically from the event handler, using the - specified - parameters as search criteria and returning @true if a matching function has been - found and removed. This method can only disconnect functions which have been - added - using the Connect() method. There is no way - to disconnect functions connected using the (static) event tables. + Returns @true if the OnIdle function processing this event requested more + processing time. - @param id - The identifier (or first of the identifier range) associated with the event - handler function. - @param lastId - The second part of the identifier range associated with the event handler - function. - @param eventType - The event type associated with this event handler. - @param function - The event handler function. - @param userData - Data associated with the event table entry. - @param eventSink - Object whose member function should be called. + @see RequestMore() */ - bool Disconnect(wxEventType eventType = wxEVT_NULL, - wxObjectEventFunction function = NULL, - wxObject* userData = NULL, - wxEvtHandler* eventSink = NULL); - bool Disconnect(int id = wxID_ANY, - wxEventType eventType = wxEVT_NULL, - wxObjectEventFunction function = NULL, - wxObject* userData = NULL, - wxEvtHandler* eventSink = NULL); - bool Disconnect(int id, int lastId = wxID_ANY, - wxEventType eventType = wxEVT_NULL, - wxObjectEventFunction function = NULL, - wxObject* userData = NULL, - wxEvtHandler* eventSink = NULL); - //@} + bool MoreRequested() const; /** - Gets user-supplied client data. + Tells wxWidgets that more processing is required. - @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. + This function can be called by an OnIdle handler for a window or window event + handler to indicate that wxApp::OnIdle should forward the OnIdle event once + more to the application windows. - @see SetClientData() + If no window calls this function during OnIdle, then the application will + remain in a passive event loop (not calling OnIdle) until a new event is + posted to the application by the windowing system. + + @see MoreRequested() */ - void* GetClientData() const; + void RequestMore(bool needMore = true); /** - Get a pointer to the user-supplied client data object. + Static function for specifying how wxWidgets will send idle events: to + all windows, or only to those which specify that they will process the events. - @see SetClientObject(), wxClientData + @param mode + Can be one of the ::wxIdleMode values. + The default is wxIDLE_PROCESS_ALL. */ - wxClientData* GetClientObject() const; + static void SetMode(wxIdleMode mode); +}; - /** - Returns @true if the event handler is enabled, @false otherwise. - @see SetEvtHandlerEnabled() - */ - bool GetEvtHandlerEnabled() const; - /** - Gets the pointer to the next handler in the chain. +/** + @class wxInitDialogEvent + @wxheader{event.h} - @see SetNextHandler(), GetPreviousHandler(), - SetPreviousHandler(), wxWindow::PushEventHandler, - wxWindow::PopEventHandler - */ - wxEvtHandler* GetNextHandler() const; + A wxInitDialogEvent is sent as a dialog or panel is being initialised. + Handlers for this event can transfer data to the window. - /** - Gets the pointer to the previous handler in the chain. + The default handler calls wxWindow::TransferDataToWindow. - @see SetPreviousHandler(), GetNextHandler(), - SetNextHandler(), wxWindow::PushEventHandler, - wxWindow::PopEventHandler - */ - wxEvtHandler* GetPreviousHandler() const; + @beginEventTable{wxInitDialogEvent} + @event{EVT_INIT_DIALOG(func)} + Process a wxEVT_INIT_DIALOG event. + @endEventTable + + @library{wxcore} + @category{events} + @see @ref overview_eventhandling +*/ +class wxInitDialogEvent : public wxEvent +{ +public: /** - Processes an event, searching event tables and calling zero or more suitable - event handler function(s). + Constructor. + */ + wxInitDialogEvent(int id = 0); +}; - @param event - Event to process. - @returns @true if a suitable event handler function was found and - executed, and the function did not call wxEvent::Skip. - @remarks 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). +/** + @class wxWindowDestroyEvent + @wxheader{event.h} - @see SearchEventTable() - */ - virtual bool ProcessEvent(wxEvent& event); + This event is sent from the wxWindow destructor wxWindow::~wxWindow() when a + window is destroyed. - /** - 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. + 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. - @param event - Event to process. + 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. - @returns @true if the event was processed, @false if no handler was found - or an exception was thrown. + @library{wxcore} + @category{events} - @see wxWindow::HandleWindowEvent + @see @ref overview_eventhandling, wxWindowCreateEvent +*/ +class wxWindowDestroyEvent : public wxCommandEvent +{ +public: + /** + Constructor. */ - bool SafelyProcessEvent(wxEvent& event); + wxWindowDestroyEvent(wxWindow* win = NULL); +}; - /** - 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. +/** + The possible flag values for a wxNavigationKeyEvent. +*/ +enum wxNavigationKeyEventFlags +{ + wxNKEF_IS_BACKWARD = 0x0000, + wxNKEF_IS_FORWARD = 0x0001, + wxNKEF_WINCHANGE = 0x0002, + wxNKEF_FROMTAB = 0x0004 +}; - @returns @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. +/** + @class wxNavigationKeyEvent + @wxheader{event.h} - @see ProcessEvent() - */ - virtual bool SearchEventTable(wxEventTable& table, - wxEvent& event); + This event class contains information about navigation events, + generated by navigation keys such as tab and page down. - /** - Sets user-supplied client data. + 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. - @param data - Data to be associated with the event handler. + @beginEventTable{wxNavigationKeyEvent} + @event{EVT_NAVIGATION_KEY(func)} + Process a navigation key event. + @endEventTable - @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. + @library{wxcore} + @category{events} - @see GetClientData() - */ - void SetClientData(void* data); + @see wxWindow::Navigate, wxWindow::NavigateIn +*/ +class wxNavigationKeyEvent : public wxEvent +{ +public: + wxNavigationKeyEvent(); + wxNavigationKeyEvent(const wxNavigationKeyEvent& event); /** - Set the client data object. Any previous object will be deleted. - - @see GetClientObject(), wxClientData + Returns the child that has the focus, or @NULL. */ - void SetClientObject(wxClientData* data); + wxWindow* GetCurrentFocus() const; /** - Enables or disables the event handler. - - @param enabled - @true if the event handler is to be enabled, @false if it is to be disabled. + Returns @true if the navigation was in the forward direction. + */ + bool GetDirection() const; - @remarks You can use this function to avoid having to remove the event - handler from the chain, for example when implementing a - dialog editor and changing from edit to test mode. + /** + Returns @true if the navigation event was from a tab key. + This is required for proper navigation over radio buttons. + */ + bool IsFromTab() const; - @see GetEvtHandlerEnabled() + /** + Returns @true if the navigation event represents a window change + (for example, from Ctrl-Page Down in a notebook). */ - void SetEvtHandlerEnabled(bool enabled); + bool IsWindowChange() const; /** - Sets the pointer to the next handler. + Sets the current focus window member. + */ + void SetCurrentFocus(wxWindow* currentFocus); - @param handler - Event handler to be set as the next handler. + /** + Sets the direction to forward if @a direction is @true, or backward + if @false. + */ + void SetDirection(bool direction); - @see GetNextHandler(), SetPreviousHandler(), - GetPreviousHandler(), wxWindow::PushEventHandler, - wxWindow::PopEventHandler + /** + Sets the flags for this event. + The @a flags can be a combination of the ::wxNavigationKeyEventFlags values. */ - void SetNextHandler(wxEvtHandler* handler); + void SetFlags(long flags); /** - Sets the pointer to the previous handler. + Marks the navigation event as from a tab key. + */ + void SetFromTab(bool fromTab); - @param handler - Event handler to be set as the previous handler. + /** + Marks the event as a window change event. */ - void SetPreviousHandler(wxEvtHandler* handler); + void SetWindowChange(bool windowChange); }; /** - @class wxIconizeEvent + @class wxMouseCaptureChangedEvent @wxheader{event.h} - An event being sent when the frame is iconized (minimized) or restored. + An mouse capture changed event is sent to a window that loses its + mouse capture. This is called even if wxWindow::ReleaseCapture + was called by the application code. Handling this event allows + an application to cater for unexpected capture releases which + might otherwise confuse mouse handling code. - Currently only wxMSW and wxGTK generate such events. + @onlyfor{wxmsw} + + @beginEventTable{wxMouseCaptureChangedEvent} + @event{EVT_MOUSE_CAPTURE_CHANGED(func)} + Process a wxEVT_MOUSE_CAPTURE_CHANGED event. + @endEventTable @library{wxcore} @category{events} - @see @ref overview_eventhandling, wxTopLevelWindow::Iconize, - wxTopLevelWindow::IsIconized + @see wxMouseCaptureLostEvent, @ref overview_eventhandling, + wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture */ -class wxIconizeEvent : public wxEvent +class wxMouseCaptureChangedEvent : public wxEvent { public: /** Constructor. */ - wxIconizeEvent(int id = 0, bool iconized = true); + wxMouseCaptureChangedEvent(wxWindowID windowId = 0, + wxWindow* gainedCapture = NULL); /** - Returns @true if the frame has been iconized, @false if it has been - restored. + Returns the window that gained the capture, or @NULL if it was a + non-wxWidgets window. */ - bool Iconized() const; + wxWindow* GetCapturedWindow() const; }; /** - @class wxMoveEvent + @class wxCloseEvent @wxheader{event.h} - A move event holds information about move change events. + This event class contains information about window and session close events. + + The handler function for EVT_CLOSE is called when the user has tried to close a + a frame or dialog box using the window manager (X) or system menu (Windows). + It can also be invoked by the application itself programmatically, for example by + calling the wxWindow::Close function. + + You should check whether the application is forcing the deletion of the window + using wxCloseEvent::CanVeto. If this is @false, you @e must destroy the window + using wxWindow::Destroy. + + If the return value is @true, it is up to you whether you respond by destroying + the window. + + If you don't destroy the window, you should call wxCloseEvent::Veto to + let the calling code know that you did not destroy the window. + This allows the wxWindow::Close function to return @true or @false depending + on whether the close instruction was honoured or not. + + 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 + handler for this event is executed the program is simply killed by the + system. Because of this, the default handler for this event provided by + wxWidgets calls all the usual cleanup code (including wxApp::OnExit()) so + that it could still be executed and exit()s the process itself, without + waiting for being killed. If this behaviour is for some reason undesirable, + make sure that you define a handler for this event in your wxApp-derived + class and do not call @c event.Skip() in it (but be aware that the system + will still kill your application). + + @beginEventTable{wxCloseEvent} + @event{EVT_CLOSE(func)} + Process a close event, supplying the member function. + This event applies to wxFrame and wxDialog classes. + @event{EVT_QUERY_END_SESSION(func)} + Process a query end session event, supplying the member function. + This event can be handled in wxApp-derived class only. + @event{EVT_END_SESSION(func)} + Process an end session event, supplying the member function. + This event can be handled in wxApp-derived class only. + @endEventTable @library{wxcore} @category{events} - @see wxPoint, @ref overview_eventhandling + @see wxWindow::Close, @ref overview_windowdeletion */ -class wxMoveEvent : public wxEvent +class wxCloseEvent : public wxEvent { public: /** Constructor. */ - wxMoveEvent(const wxPoint& pt, int id = 0); + wxCloseEvent(wxEventType commandEventType = wxEVT_NULL, int id = 0); /** - Returns the position of the window generating the move change event. + Returns @true if you can veto a system shutdown or a window close event. + Vetoing a window close event is not possible if the calling code wishes to + force the application to exit, and so this function must be called to check this. */ - wxPoint GetPosition() const; + bool CanVeto() const; + + /** + Returns @true if the user is just logging off or @false if the system is + shutting down. This method can only be called for end session and query end + session events, it doesn't make sense for close window event. + */ + bool GetLoggingOff() const; + + /** + Sets the 'can veto' flag. + */ + void SetCanVeto(bool canVeto); + + /** + Sets the 'force' flag. + */ + void SetForce(bool force) const; + + /** + Sets the 'logging off' flag. + */ + void SetLoggingOff(bool loggingOff); + + /** + Call this from your event handler to veto a system shutdown or to signal + to the calling application that a window close did not happen. + + You can only veto a shutdown if CanVeto() returns @true. + */ + void Veto(bool veto = true); }; /** - @class wxEvent + @class wxMenuEvent @wxheader{event.h} - An event is a structure holding information about an event passed to a - callback or member function. @b wxEvent used to be a multipurpose - event object, and is an abstract base class for other event classes (see below). + This class is used for a variety of menu-related events. Note that + these do not include menu command events, which are + handled using wxCommandEvent objects. - For more information about events, see the @ref overview_eventhandling. + The default handler for wxEVT_MENU_HIGHLIGHT displays help + text in the first field of the status bar. - @b wxPerl note: In wxPerl custom event classes should be derived from - @c Wx::PlEvent and @c Wx::PlCommandEvent. + @beginEventTable{wxMenuEvent} + @event{EVT_MENU_OPEN(func)} + A menu is about to be opened. On Windows, this is only sent once for each + navigation of the menubar (up until all menus have closed). + @event{EVT_MENU_CLOSE(func)} + A menu has been just closed. + @event{EVT_MENU_HIGHLIGHT(id, func)} + The menu item with the specified id has been highlighted: used to show + help prompts in the status bar by wxFrame + @event{EVT_MENU_HIGHLIGHT_ALL(func)} + A menu item has been highlighted, i.e. the currently selected menu item has changed. + @endEventTable - @library{wxbase} + @library{wxcore} @category{events} - @see wxCommandEvent, wxMouseEvent + @see wxCommandEvent, @ref overview_eventhandling */ -class wxEvent : public wxObject +class wxMenuEvent : public wxEvent { public: /** - Constructor. Should not need to be used directly by an application. + Constructor. */ - wxEvent(int id = 0, wxEventType eventType = wxEVT_NULL); + wxMenuEvent(wxEventType id = wxEVT_NULL, int id = 0, wxMenu* menu = NULL); /** - 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. All wxWidgets - events fully implement this method, but any derived events implemented by the - user should also implement this method just in case they (or some event - derived from them) are ever posted. - All wxWidgets events implement a copy constructor, so the easiest way of - implementing the Clone function is to implement a copy constructor for - a new event (call it MyEvent) and then define the Clone function like this: + 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. */ - virtual wxEvent* Clone() const = 0; + wxMenu* GetMenu() const; /** - Returns the object (usually a window) associated with the - event, if any. + Returns the menu identifier associated with the event. + This method should be only used with the @c HIGHLIGHT events. */ - wxObject* GetEventObject() const; + int GetMenuId() const; /** - Returns the identifier of the given event type, - such as @c wxEVT_COMMAND_BUTTON_CLICKED. - */ - wxEventType GetEventType() const; + Returns @true if the menu which is being opened or closed is a popup menu, + @false if it is a normal one. - /** - Returns the identifier associated with this event, such as a button command id. + This method should only be used with the @c OPEN and @c CLOSE events. */ - int GetId() const; + bool IsPopup() const; +}; - /** - Returns @true if the event handler should be skipped, @false otherwise. - */ - bool GetSkipped() const; - /** - 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). - */ - long GetTimestamp() const; +/** + @class wxIconizeEvent + @wxheader{event.h} - /** - Returns @true if the event is or is derived from - wxCommandEvent else it returns @false. - Note: Exists only for optimization purposes. - */ - bool IsCommandEvent() const; + An event being sent when the frame is iconized (minimized) or restored. - /** - Sets the propagation level to the given value (for example returned from an - earlier call to wxEvent::StopPropagation). - */ - void ResumePropagation(int propagationLevel); + Currently only wxMSW and wxGTK generate such events. - /** - Sets the originating object. - */ - void SetEventObject(wxObject* object); + @onlyfor{wxmsw,wxgtk} - /** - Sets the event type. - */ - void SetEventType(wxEventType type); + @beginEventTable{wxIconizeEvent} + @event{EVT_ICONIZE(func)} + Process a wxEVT_ICONIZE event. + @endEventTable - /** - Sets the identifier associated with this event, such as a button command id. - */ - void SetId(int id); + @library{wxcore} + @category{events} + @see @ref overview_eventhandling, wxTopLevelWindow::Iconize, + wxTopLevelWindow::IsIconized +*/ +class wxIconizeEvent : public wxEvent +{ +public: /** - Sets the timestamp for the event. + Constructor. */ - void SetTimestamp(long = 0); + wxIconizeEvent(int id = 0, bool iconized = true); /** - Test if this event should be propagated or not, i.e. if the propagation level - is currently greater than 0. + Returns @true if the frame has been iconized, @false if it has been + restored. */ - bool ShouldPropagate() const; + bool Iconized() const; +}; - /** - This method can be used inside an event handler to control whether further - event handlers bound to this event will be called after the current one - returns. Without Skip() (or equivalently if Skip(@false) is used), - the event will not be processed any more. If Skip(@true) is called, the event - processing system continues searching for a further handler function for this - event, even though it has been processed already in the current handler. - In general, it is recommended to skip all non-command events to allow the - default handling to take place. The command events are, however, normally not - skipped as usually a single command such as a button click or menu item - selection must only be processed by one handler. - */ - void Skip(bool skip = true); + +/** + @class wxMoveEvent + @wxheader{event.h} + + A move event holds information about move change events. + + @beginEventTable{wxMoveEvent} + @event{EVT_MOVE(func)} + Process a wxEVT_MOVE event, which is generated when a window is moved. + @event{EVT_MOVE_START(func)} + Process a wxEVT_MOVE_START event, which is generated when the user starts + to move or size a window. wxMSW only. + @event{EVT_MOVE_END(func)} + Process a wxEVT_MOVE_END event, which is generated when the user stops + moving or sizing a window. wxMSW only. + @endEventTable + + @library{wxcore} + @category{events} + + @see wxPoint, @ref overview_eventhandling +*/ +class wxMoveEvent : public wxEvent +{ +public: /** - Stop the event from propagating to its parent window. - Returns the old propagation level value which may be later passed to - ResumePropagation() to allow propagating the - event again. + Constructor. */ - int StopPropagation(); + wxMoveEvent(const wxPoint& pt, int id = 0); /** - int m_propagationLevel - Indicates how many levels the event can propagate. This member is protected and - should typically only be set in the constructors of the derived classes. It - may be temporarily changed by StopPropagation() - and ResumePropagation() and tested with - ShouldPropagate(). - The initial value is set to either @c wxEVENT_PROPAGATE_NONE (by - default) meaning that the event shouldn't be propagated at all or to - @c wxEVENT_PROPAGATE_MAX (for command events) meaning that it should be - propagated as much as necessary. - Any positive number means that the event should be propagated but no more than - the given number of times. E.g. the propagation level may be set to 1 to - propagate the event to its parent only, but not to its grandparent. + Returns the position of the window generating the move change event. */ + wxPoint GetPosition() const; }; - /** @class wxSizeEvent @wxheader{event.h} @@ -2831,20 +3154,20 @@ public: The EVT_SIZE handler function will be called when the window has been resized. - You may wish to use this for frames to resize their child windows as - appropriate. + You may wish to use this for frames to resize their child windows as appropriate. - Note that the size passed is of - the whole window: call wxWindow::GetClientSize for the area which may be - used by the application. + Note that the size passed is of the whole window: call wxWindow::GetClientSize + for the area which may be used by the application. When a window is resized, usually only a small part of the window is damaged - and you - may only need to repaint that area. However, if your drawing depends on the - 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. + and you may only need to repaint that area. However, if your drawing depends on the + 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. + + @beginEventTable{wxSizeEvent} + @event{EVT_SIZE(func)} + Process a wxEVT_SIZE event. + @endEventTable @library{wxcore} @category{events} @@ -2872,10 +3195,16 @@ public: @wxheader{event.h} A SetCursorEvent 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 processing based on the current position of the mouse - within the window. Use wxSetCursorEvent::SetCursor to - specify the cursor you want to be displayed. + result of mouse motion. + + This event gives the application the chance to perform specific mouse cursor + processing based on the current position of the mouse within the window. + Use wxSetCursorEvent::SetCursor to specify the cursor you want to be displayed. + + @beginEventTable{wxSetCursorEvent} + @event{EVT_SET_CURSOR(func)} + Process a wxEVT_SET_CURSOR event. + @endEventTable @library{wxcore} @category{events}