/////////////////////////////////////////////////////////////////////////////
// Name: event.h
-// Purpose: interface of wxKeyEvent
+// 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 overview_keycodes "keycodes table". 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.
+/**
+ @class wxEvent
+ @wxheader{event.h}
- You may discover how the other keys on your system behave interactively by
- running the text() wxWidgets sample and pressing some keys
- in any of the text controls shown in it.
+ An event is a structure holding information about an event passed to a
+ callback or member function.
- @b 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.
+ wxEvent used to be a multipurpose event object, and is an abstract base class
+ for other event classes (see below).
- @b 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).
+ For more information about events, see the @ref overview_eventhandling overview.
- @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.
+ @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 wxEVT_CHAR and
- wxEVT_CHAR_HOOK.
+ Constructor. Should not need to be used directly by an application.
*/
- wxKeyEvent(WXTYPE keyEventType);
+ wxEvent(int id = 0, wxEventType eventType = 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.
+ 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:
+
+ @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 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 overview_keymodifiers "key modifier constants" 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:
-
- 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
-
- 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;
- 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.
- @b NB: Currently the raw key codes are not supported by all ports, use
- @c #ifdef wxHAS_RAW_KEY_CODES to determine if this feature is available.
+ Returns @true if the event is or is derived from wxCommandEvent else it returns @false.
+
+ @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.
- @b NB: Currently the raw key flags are not supported by all ports, use
- @c #ifdef wxHAS_RAW_KEY_CODES to determine if this feature is available.
+ Sets the propagation level to the given value (for example returned from an
+ earlier call to wxEvent::StopPropagation).
*/
- wxUint32 GetRawKeyFlags() const;
+ void ResumePropagation(int propagationLevel);
/**
- 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.
+ Sets the originating object.
*/
- wxChar GetUnicodeKey() const;
+ void SetEventObject(wxObject* object);
/**
- Returns the X position (in client coordinates) of the event.
+ Sets the event type.
*/
- long GetX() const;
+ void SetEventType(wxEventType type);
/**
- Returns the Y (in client coordinates) position of the event.
+ Sets the identifier associated with this event, such as a button command id.
*/
- long GetY() const;
+ void SetId(int id);
/**
- Returns @true if either CTRL or ALT keys was down
- at the time of the key event. Note that this function does not take into
- account neither SHIFT nor META key states (the reason for ignoring
- the latter is that it is common for NUMLOCK key to be configured as
- META under X but the key presses even while NUMLOCK is on should
- be still processed normally).
+ Sets the timestamp for the event.
*/
- bool HasModifiers() const;
+ void SetTimestamp(long = 0);
/**
- Returns @true if the Meta key was down at the time of the key event.
- Notice that GetModifiers() is easier to use
- correctly than this function so you should consider using it in new code.
+ Test if this event should be propagated or not, i.e. if the propagation level
+ is currently greater than 0.
*/
- bool MetaDown() const;
+ bool ShouldPropagate() const;
/**
- Returns @true if the shift key was down at the time of the key event.
- Notice that GetModifiers() is easier to use
- correctly than this function so you should consider using it in new code.
+ 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.
*/
- bool ShiftDown() const;
+ void Skip(bool skip = true);
/**
- bool m_altDown
- @b Deprecated: Please use GetModifiers()
- instead!
- @true if the Alt key is pressed down.
- */
+ 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.
+ */
+ int StopPropagation();
+protected:
/**
- bool m_controlDown
- @b Deprecated: Please use GetModifiers()
- instead!
- @true if control is pressed down.
- */
+ 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().
- /**
- long m_keyCode
- @b Deprecated: Please use GetKeyCode()
- instead!
- Virtual keycode. See Keycodes() for a list of identifiers.
+ 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 wxEventBlocker
+ @wxheader{event.h}
- /**
- bool m_metaDown
- @b Deprecated: Please use GetModifiers()
- instead!
- @true if the Meta key is pressed down.
- */
+ This class is a special event handler which allows to discard
+ any event (or a set of event types) directed to a specific window.
+ Example:
- /**
- bool m_shiftDown
- @b Deprecated: Please use GetModifiers()
- instead!
- @true if shift is pressed down.
- */
+ @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 @ref overview_eventhandling, wxEvtHandler
+*/
+class wxEventBlocker : public wxEvtHandler
+{
+public:
/**
- int m_x
- @b Deprecated: Please use GetX() instead!
- X position of the event.
+ 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.
*/
+ wxEventBlocker(wxWindow* win, wxEventType = wxEVT_ANY);
+ /**
+ 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();
/**
- int m_y
- @b Deprecated: Please use GetY() instead!
- Y position of the event.
+ Adds to the list of event types which should be blocked the given @a eventType.
*/
+ void Block(wxEventType eventType);
};
/**
- @class wxJoystickEvent
+ @class wxEvtHandler
@wxheader{event.h}
- This event class contains information about mouse events, particularly
- events received by windows.
+ A class that can handle events from the windowing system.
+ wxWindow (and therefore all window classes) are derived from this class.
- @library{wxcore}
+ 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 wxJoystick
+ @see @ref overview_eventhandling
*/
-class wxJoystickEvent : public wxEvent
+class wxEvtHandler : public wxObject
{
public:
/**
Constructor.
*/
- wxJoystickEvent(WXTYPE eventType = 0, int state = 0,
- int joystick = wxJOYSTICK1,
- int change = 0);
+ wxEvtHandler();
/**
- Returns @true if the event was a down event from the specified button (or any
- button).
+ Destructor.
- @param button
- Can be wxJOY_BUTTONn where n is 1, 2, 3 or 4; or 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 ButtonDown(int button = wxJOY_BUTTON_ANY) const;
+ virtual ~wxEvtHandler();
/**
- Returns @true if the specified button (or any button) was in a down state.
+ This function posts an event to be processed later.
- @param button
- Can be wxJOY_BUTTONn where n is 1, 2, 3 or 4; or wxJOY_BUTTON_ANY to
- indicate any button down event.
- */
- bool ButtonIsDown(int button = wxJOY_BUTTON_ANY) const;
+ 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).
- /**
- Returns @true if the event was an up event from the specified button (or any
- button).
+ 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.
- @param button
- Can be wxJOY_BUTTONn where n is 1, 2, 3 or 4; or wxJOY_BUTTON_ANY to
- indicate any button down event.
- */
- bool ButtonUp(int button = wxJOY_BUTTON_ANY) const;
+ 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.
- /**
- Returns the identifier of the button changing state. This is a wxJOY_BUTTONn
- identifier, where
- n is one of 1, 2, 3, 4.
- */
- int GetButtonChange() const;
+ 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.)
- /**
- Returns the down state of the buttons. This is a bitlist of wxJOY_BUTTONn
- identifiers, where
- n is one of 1, 2, 3, 4.
+ @param event
+ Event to add to process queue.
*/
- int GetButtonState() const;
+ virtual void AddPendingEvent(const wxEvent& event);
/**
- Returns the identifier of the joystick generating the event - one of
- wxJOYSTICK1 and wxJOYSTICK2.
- */
- int GetJoystick() const;
+ Connects the given function dynamically with the event handler, id and event type.
+ This is an alternative to the use of static event tables.
- /**
- Returns the x, y position of the joystick event.
- */
- wxPoint GetPosition() const;
+ See the @ref page_samples_event sample for usage.
- /**
- Returns the z position of the joystick event.
- */
- int GetZPosition() const;
+ 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!).
- /**
- Returns @true if this was a button up or down event (@e not 'is any button
- down?').
+ @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.
*/
- bool IsButton() const;
+ void Connect(int id, int lastId, wxEventType eventType,
+ wxObjectEventFunction function,
+ wxObject* userData = NULL,
+ wxEvtHandler* eventSink = NULL);
/**
- Returns @true if this was an x, y move event.
+ See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
+ overload for more info.
+
+ 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
*/
- bool IsMove() const;
+ void Connect(int id, wxEventType eventType,
+ wxObjectEventFunction function,
+ wxObject* userData = NULL,
+ wxEvtHandler* eventSink = NULL);
/**
- Returns @true if this was a z move event.
+ 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.
*/
- bool IsZMove() const;
-};
+ void Connect(wxEventType eventType,
+ wxObjectEventFunction function,
+ wxObject* userData = NULL,
+ wxEvtHandler* eventSink = NULL);
+ /**
+ 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.
-/**
- @class wxScrollWinEvent
- @wxheader{event.h}
+ @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.
+ */
+ bool Disconnect(wxEventType eventType = wxEVT_NULL,
+ wxObjectEventFunction function = NULL,
+ wxObject* userData = NULL,
+ wxEvtHandler* eventSink = NULL);
- A scroll event holds information about events sent from scrolling windows.
+ /**
+ See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
+ overload for more info.
- @library{wxcore}
- @category{events}
+ This overload takes the additional @a id parameter.
+ */
+ bool Disconnect(int id = wxID_ANY,
+ wxEventType eventType = wxEVT_NULL,
+ wxObjectEventFunction function = NULL,
+ wxObject* userData = NULL,
+ wxEvtHandler* eventSink = NULL);
- @see wxScrollEvent, @ref overview_eventhandlingoverview
-*/
-class wxScrollWinEvent : public wxEvent
-{
-public:
/**
- Constructor.
+ See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
+ overload for more info.
+
+ This overload takes an additional range of source IDs.
*/
- wxScrollWinEvent(WXTYPE commandType = 0, int pos = 0,
- int orientation = 0);
+ bool Disconnect(int id, int lastId = wxID_ANY,
+ wxEventType eventType = wxEVT_NULL,
+ wxObjectEventFunction function = NULL,
+ wxObject* userData = NULL,
+ wxEvtHandler* eventSink = NULL);
/**
- Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the
- scrollbar.
+ 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()
*/
- int GetOrientation() const;
+ void* GetClientData() const;
/**
- 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.
+ Returns a pointer to the user-supplied client data object.
+
+ @see SetClientObject(), wxClientData
*/
- int GetPosition() const;
-};
+ wxClientData* GetClientObject() const;
+ /**
+ Returns @true if the event handler is enabled, @false otherwise.
+ @see SetEvtHandlerEnabled()
+ */
+ bool GetEvtHandlerEnabled() const;
-/**
- @class wxSysColourChangedEvent
- @wxheader{event.h}
+ /**
+ Returns the pointer to the next handler in the chain.
- 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.
+ @see SetNextHandler(), GetPreviousHandler(), SetPreviousHandler(),
+ wxWindow::PushEventHandler, wxWindow::PopEventHandler
+ */
+ wxEvtHandler* GetNextHandler() const;
- @library{wxcore}
- @category{events}
+ /**
+ Returns the pointer to the previous handler in the chain.
+
+ @see SetPreviousHandler(), GetNextHandler(), SetNextHandler(),
+ wxWindow::PushEventHandler, wxWindow::PopEventHandler
+ */
+ wxEvtHandler* GetPreviousHandler() const;
- @see @ref overview_eventhandlingoverview
-*/
-class wxSysColourChangedEvent : public wxEvent
-{
-public:
/**
- Constructor.
+ Processes an event, searching event tables and calling zero or more suitable
+ event handler function(s).
+
+ Normally, your application would not call this function: it is called in the
+ wxWidgets implementation to dispatch incoming user interface events to the
+ framework (and application).
+
+ However, you might need to call it if implementing new functionality
+ (such as a new control) where you define new event types, as opposed to
+ allowing the user to override virtual functions.
+
+ An instance where you might actually override the ProcessEvent function is where
+ you want to direct event processing to event handlers not normally noticed by
+ wxWidgets. For example, in the document/view architecture, documents and views
+ are potential event handlers. When an event reaches a frame, ProcessEvent will
+ need to be called on the associated document and view in case event handler functions
+ are associated with these objects. The property classes library (wxProperty) also
+ overrides ProcessEvent for similar reasons.
+
+ The normal order of event table searching is as follows:
+ -# If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled)
+ the function skips to step (6).
+ -# If the object is a wxWindow, ProcessEvent() is recursively called on the
+ window's wxValidator. If this returns @true, the function exits.
+ -# SearchEventTable() is called for this event handler. If this fails, the base
+ class table is tried, and so on until no more tables exist or an appropriate
+ function was found, in which case the function exits.
+ -# The search is applied down the entire chain of event handlers (usually the
+ chain has a length of one). If this succeeds, the function exits.
+ -# If the object is a wxWindow and the event is a wxCommandEvent, ProcessEvent()
+ is recursively applied to the parent window's event handler.
+ If this returns true, the function exits.
+ -# Finally, ProcessEvent() is called on the wxApp object.
+
+ @param event
+ Event to process.
+
+ @returns @true if a suitable event handler function was found and
+ executed, and the function did not call wxEvent::Skip.
+
+ @see SearchEventTable()
*/
- wxSysColourChangedEvent();
-};
+ virtual bool ProcessEvent(wxEvent& event);
+ /**
+ Processes an event by calling ProcessEvent() and handles any exceptions
+ that occur in the process.
+ If an exception is thrown in event handler, wxApp::OnExceptionInMainLoop is called.
+ @param event
+ Event to process.
-/**
- @class wxWindowCreateEvent
- @wxheader{event.h}
+ @returns @true if the event was processed, @false if no handler was found
+ or an exception was thrown.
- This event is sent just after the actual window associated with a wxWindow
- object
- has been created. Since it is derived from wxCommandEvent, the event propagates
- up
- the window hierarchy.
+ @see wxWindow::HandleWindowEvent
+ */
+ bool SafelyProcessEvent(wxEvent& event);
- @library{wxcore}
- @category{events}
+ /**
+ 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.
+
+ @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()
+ */
+ virtual bool SearchEventTable(wxEventTable& table,
+ wxEvent& event);
- @see @ref overview_eventhandlingoverview, wxWindowDestroyEvent
-*/
-class wxWindowCreateEvent : public wxCommandEvent
-{
-public:
/**
- Constructor.
+ Sets user-supplied client data.
+
+ @param data
+ Data to be associated with the event handler.
+
+ @remarks Normally, any extra data the programmer wishes to associate
+ with the object should be made available by deriving a new
+ class with new data members. You must not call this method
+ and SetClientObject on the same class - only one of them.
+
+ @see GetClientData()
*/
- wxWindowCreateEvent(wxWindow* win = NULL);
-};
+ void SetClientData(void* data);
+
+ /**
+ Set the client data object. Any previous object will be deleted.
+
+ @see GetClientObject(), wxClientData
+ */
+ void SetClientObject(wxClientData* data);
+ /**
+ Enables or disables the event handler.
+
+ @param enabled
+ @true if the event handler is to be enabled, @false if it is to be disabled.
+
+ @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.
+
+ @see GetEvtHandlerEnabled()
+ */
+ void SetEvtHandlerEnabled(bool enabled);
+
+ /**
+ 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);
+
+ /**
+ Sets the pointer to the previous handler.
+
+ @param handler
+ Event handler to be set as the previous handler.
+ */
+ void SetPreviousHandler(wxEvtHandler* handler);
+};
/**
- @class wxPaintEvent
+ @class wxKeyEvent
@wxheader{event.h}
- A paint event is sent when a window's contents needs to be repainted.
+ This event class contains information about keypress (character) events.
- 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 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.
+
+ @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_eventhandlingoverview
*/
-class wxPaintEvent : public wxEvent
+class wxKeyEvent : public wxEvent
{
public:
/**
Constructor.
+ Currently, the only valid event types are @c wxEVT_CHAR and @c wxEVT_CHAR_HOOK.
*/
- wxPaintEvent(int id = 0);
-};
+ 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 wxMaximizeEvent
- @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;
- 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.
+ /**
+ Returns @true if the control key was down at the time of the key event.
+
+ Notice that GetModifiers() is easier to use correctly than this function
+ so you should consider using it in new code.
+ */
+ bool ControlDown() const;
+
+ /**
+ Returns the virtual key code. ASCII events return normal ASCII values,
+ while non-ASCII events return values such as @b WXK_LEFT for the left cursor
+ key. See @ref page_keycodes for a full list of the virtual key codes.
+
+ 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;
+
+ /**
+ Return the bitmask of modifier keys which were pressed when this event
+ happened. See @ref page_keymodifiers for the full list of modifiers.
+
+ Notice that this function is easier to use correctly than, for example,
+ ControlDown() because when using the latter you also have to remember to
+ test that none of the other modifiers is pressed:
+
+ @code
+ if ( ControlDown() && !AltDown() && !ShiftDown() && !MetaDown() )
+ ... handle Ctrl-XXX ...
+ @endcode
+
+ and forgetting to do it can result in serious program bugs (e.g. program
+ not working with European keyboard layout where ALTGR key which is seen by
+ the program as combination of CTRL and ALT is used). On the other hand,
+ you can simply write:
+
+ @code
+ if ( GetModifiers() == wxMOD_CONTROL )
+ ... handle Ctrl-XXX ...
+ @endcode
+
+ with this function.
+ */
+ int GetModifiers() const;
+
+ //@{
+ /**
+ Obtains the position (in client coordinates) at which the key was pressed.
+ */
+ wxPoint GetPosition() const;
+ void GetPosition(long* x, long* y) const;
+ //@}
+
+ /**
+ Returns the raw key code for this event. This is a platform-dependent scan code
+ which should only be used in advanced applications.
+
+ @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;
+
+ /**
+ 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.
+ */
+ 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;
+
+ /**
+ Returns @true if either CTRL or ALT keys was down at the time of the
+ key event.
+
+ Note that this function does not take into account neither SHIFT nor
+ META key states (the reason for ignoring the latter is that it is
+ common for NUMLOCK key to be configured as META under X but the key
+ presses even while NUMLOCK is on should be still processed normally).
+ */
+ bool HasModifiers() const;
+
+ /**
+ Returns @true if the Meta key was down at the time of the key event.
- @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_eventhandlingoverview, 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.
+ This event class contains information about joystick events, particularly
+ events received by windows.
+
+ @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_eventhandlingoverview
+ @see wxJoystick
*/
-class wxUpdateUIEvent : public wxCommandEvent
+class wxJoystickEvent : public wxEvent
{
public:
/**
Constructor.
*/
- wxUpdateUIEvent(wxWindowID commandId = 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);
-
- /**
- Check or uncheck the UI element.
- */
- void Check(bool check);
+ wxJoystickEvent(wxEventType eventType = wxEVT_NULL, int state = 0,
+ int joystick = wxJOYSTICK1,
+ int change = 0);
/**
- Enable or disable the UI element.
- */
- void Enable(bool enable);
+ Returns @true if the event was a down event from the specified button
+ (or any button).
- /**
- 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 ButtonDown(int button = wxJOY_BUTTON_ANY) const;
/**
- Returns @true if the UI element should be enabled.
- */
- bool GetEnabled() const;
+ Returns @true if the specified button (or any button) was in a down state.
- /**
- 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().
+ @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.
*/
- static wxUpdateUIMode GetMode();
+ bool ButtonIsDown(int button = wxJOY_BUTTON_ANY) const;
/**
- Returns @true if the application has called Check(). For wxWidgets internal use
- only.
- */
- bool GetSetChecked() const;
+ Returns @true if the event was an up event from the specified button
+ (or any button).
- /**
- Returns @true if the application has called Enable(). For wxWidgets internal use
- only.
+ @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 GetSetEnabled() const;
+ bool ButtonUp(int button = wxJOY_BUTTON_ANY) const;
/**
- Returns @true if the application has called Show(). For wxWidgets internal use
- only.
- */
- bool GetSetShown() const;
+ Returns the identifier of the button changing state.
- /**
- Returns @true if the application has called SetText(). For wxWidgets internal
- use only.
+ This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4.
*/
- bool GetSetText() const;
+ int GetButtonChange() const;
/**
- Returns @true if the UI element should be shown.
- */
- bool GetShown() const;
+ Returns the down state of the buttons.
- /**
- Returns the text that should be set for the UI element.
+ This is a @c wxJOY_BUTTONn identifier, where @c n is one of 1, 2, 3, 4.
*/
- wxString GetText() const;
+ int GetButtonState() const;
/**
- Returns the current interval between updates in milliseconds.
- -1 disables updates, 0 updates as frequently as possible.
- See SetUpdateInterval().
+ Returns the identifier of the joystick generating the event - one of
+ wxJOYSTICK1 and wxJOYSTICK2.
*/
- static long GetUpdateInterval();
+ int GetJoystick() 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()
+ Returns the x, y position of the joystick event.
*/
- static void ResetUpdateTime();
+ wxPoint GetPosition() const;
/**
- 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.
+ Returns the z position of the joystick event.
*/
- static void SetMode(wxUpdateUIMode mode);
+ int GetZPosition() const;
/**
- Sets the text for this UI element.
+ Returns @true if this was a button up or down event
+ (@e not 'is any button down?').
*/
- void SetText(const wxString& text);
+ bool IsButton() const;
/**
- 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 @true if this was an x, y move event.
*/
- static void SetUpdateInterval(long updateInterval);
+ bool IsMove() const;
/**
- Show or hide the UI element.
+ Returns @true if this was a z move event.
*/
- void Show(bool show);
+ bool IsZMove() const;
};
/**
- @class wxClipboardTextEvent
+ @class wxScrollWinEvent
@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.
+ A scroll event holds information about events sent from scrolling 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.
- @beginEventTable
- @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{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
- @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 wxScrollEvent, @ref overview_eventhandling
*/
-class wxClipboardTextEvent : public wxCommandEvent
+class wxScrollWinEvent : public wxEvent
{
public:
/**
Constructor.
*/
- wxClipboardTextEvent(wxEventType commandType = wxEVT_NULL, int id = 0);
+ wxScrollWinEvent(wxEventType commandType = wxEVT_NULL, int pos = 0,
+ int orientation = 0);
+
+ /**
+ Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the
+ scrollbar.
+
+ @todo wxHORIZONTAL and wxVERTICAL should go in their own enum
+ */
+ int GetOrientation() const;
+
+ /**
+ 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.
+ */
+ int GetPosition() const;
};
/**
- @class wxMouseEvent
+ @class wxSysColourChangedEvent
@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 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.
- 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.
+ @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.
- @b NB: 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.
-
- @b NB: 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{wxSysColourChangedEvent}
+ @event{EVT_SYS_COLOUR_CHANGED(func)}
+ Process a wxEVT_SYS_COLOUR_CHANGED event.
+ @endEventTable
@library{wxcore}
@category{events}
- @see wxKeyEvent::CmdDown
+ @see @ref overview_eventhandling
*/
-class wxMouseEvent : public wxEvent
+class wxSysColourChangedEvent : public wxEvent
{
public:
/**
- Constructor. Valid event types are:
-
- @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(WXTYPE mouseEventType = 0);
-
- /**
- Returns @true if the Alt key was down at the time of the event.
+ Constructor.
*/
- bool AltDown();
+ wxSysColourChangedEvent();
+};
- /**
- Returns @true if the event was a first extra button double click.
- */
- bool Aux1DClick() const;
- /**
- Returns @true if the first extra button mouse button changed to down.
- */
- bool Aux1Down() const;
- /**
- Returns @true if the first extra button mouse button is currently down,
- independent
- of the current event type.
- */
- bool Aux1IsDown() const;
+/**
+ @class wxWindowCreateEvent
+ @wxheader{event.h}
- /**
- Returns @true if the first extra button mouse button changed to up.
- */
- bool Aux1Up() const;
+ This event is sent just after the actual window associated with a wxWindow
+ object has been created.
- /**
- Returns @true if the event was a second extra button double click.
- */
- bool Aux2DClick() const;
+ Since it is derived from wxCommandEvent, the event propagates up
+ the window hierarchy.
- /**
- Returns @true if the second extra button mouse button changed to down.
- */
- bool Aux2Down() const;
+ @beginEventTable{wxWindowCreateEvent}
+ @event{EVT_WINDOW_CREATE(func)}
+ Process a wxEVT_CREATE event.
+ @endEventTable
- /**
- Returns @true if the second extra button mouse button is currently down,
- independent
- of the current event type.
- */
- bool Aux2IsDown() const;
+ @library{wxcore}
+ @category{events}
+ @see @ref overview_eventhandling, wxWindowDestroyEvent
+*/
+class wxWindowCreateEvent : public wxCommandEvent
+{
+public:
/**
- Returns @true if the second extra button mouse button changed to up.
+ Constructor.
*/
- bool Aux2Up() const;
-
- /**
- Returns @true if the identified mouse button is changing state. Valid
- values of @a button are:
-
- @c wxMOUSE_BTN_LEFT
-
- check if left button was pressed
-
- @c wxMOUSE_BTN_MIDDLE
-
- check if middle button was pressed
-
- @c wxMOUSE_BTN_RIGHT
-
- check if right button was pressed
-
- @c wxMOUSE_BTN_AUX1
-
- check if the first extra button was pressed
+ wxWindowCreateEvent(wxWindow* win = NULL);
+};
- @c wxMOUSE_BTN_AUX2
- check if the second extra button was pressed
- @c wxMOUSE_BTN_ANY
+/**
+ @class wxPaintEvent
+ @wxheader{event.h}
- check if any button was pressed
- */
- bool Button(int button);
+ A paint event is sent when a window's contents needs to be repainted.
- /**
- 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 ButtonDClick(int but = wxMOUSE_BTN_ANY);
+ 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.
+
+ @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);
- /**
- 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 but = -1);
+ 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);
- /**
- 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 but = -1);
+ // Find Out where the window is scrolled to
+ int vbX,vbY; // Top left corner of client
+ GetViewStart(&vbX,&vbY);
- /**
- Same as MetaDown() under Mac, same as
- ControlDown() elsewhere.
+ int vX,vY,vW,vH; // Dimensions of client area in pixels
+ wxRegionIterator upd(GetUpdateRegion()); // get the update rect list
- @see wxKeyEvent::CmdDown
- */
- bool CmdDown() const;
+ while (upd)
+ {
+ vX = upd.GetX();
+ vY = upd.GetY();
+ vW = upd.GetW();
+ vH = upd.GetH();
- /**
- Returns @true if the control key was down at the time of the event.
- */
- bool ControlDown();
+ // Alternatively we can do this:
+ // wxRect rect(upd.GetRect());
- /**
- Returns @true if this was a dragging event (motion while a button is depressed).
+ // Repaint this rectangle
+ ...some code...
- @see Moving()
- */
- bool Dragging();
+ upd ++ ;
+ }
+ }
+ @endcode
- /**
- Returns @true if the mouse was entering the window.
- See also Leaving().
- */
- bool Entering();
+ @beginEventTable{wxPaintEvent}
+ @event{EVT_PAINT(func)}
+ Process a wxEVT_PAINT event.
+ @endEventTable
+
+ @library{wxcore}
+ @category{events}
+
+ @see @ref overview_eventhandling
+*/
+class wxPaintEvent : public wxEvent
+{
+public:
/**
- 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.
+ Constructor.
*/
- int GetButton() const;
+ wxPaintEvent(int id = 0);
+};
- /**
- 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).
- @wxsince{2.9.0}
- */
- int GetClickCount() const;
- /**
- Returns the configured number of lines (or whatever) to be scrolled per
- wheel action. Defaults to three.
- */
- int GetLinesPerAction() const;
+/**
+ @class wxMaximizeEvent
+ @wxheader{event.h}
- /**
- 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;
+ 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.
- //@{
- /**
- 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{wxMaximizeEvent}
+ @event{EVT_MAXIMIZE(func)}
+ Process a wxEVT_MAXIMIZE event.
+ @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, wxTopLevelWindow::Maximize,
+ wxTopLevelWindow::IsMaximized
+*/
+class wxMaximizeEvent : public wxEvent
+{
+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. Only used by wxWidgets internally.
*/
- int GetWheelRotation() const;
+ wxMaximizeEvent(int id = 0);
+};
- /**
- Returns X coordinate of the physical mouse event position.
- */
- long GetX() const;
+/**
+ The possibles modes to pass to wxUpdateUIEvent::SetMode().
+*/
+enum wxUpdateUIMode
+{
+ /** Send UI update events to all windows. */
+ wxUPDATE_UI_PROCESS_ALL,
- /**
- Returns Y coordinate of the physical mouse event position.
- */
- long GetY();
+ /** Send UI update events to windows that have
+ the wxWS_EX_PROCESS_UI_UPDATES flag specified. */
+ wxUPDATE_UI_PROCESS_SPECIFIED
+};
- /**
- Returns @true if the event was a mouse button event (not necessarily a button
- down event -
- that may be tested using @e ButtonDown).
- */
- bool IsButton() const;
- /**
- Returns @true if the system has been setup to do page scrolling with
- the mouse wheel instead of line scrolling.
- */
- bool IsPageScroll() const;
+/**
+ @class wxUpdateUIEvent
+ @wxheader{event.h}
- /**
- Returns @true if the mouse was leaving the window.
- See also Entering().
- */
- bool Leaving() 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 the event was a left double click.
- */
- bool LeftDClick() const;
+ 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.
+
+
+ @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
- /**
- Returns @true if the left mouse button changed to down.
- */
- bool LeftDown() const;
+ @library{wxcore}
+ @category{events}
+ @see @ref overview_eventhandling
+*/
+class wxUpdateUIEvent : public wxCommandEvent
+{
+public:
/**
- 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.
+ Constructor.
*/
- bool LeftIsDown() const;
+ wxUpdateUIEvent(wxWindowID commandId = 0);
/**
- Returns @true if the left mouse button changed to up.
- */
- bool LeftUp() const;
+ Returns @true if it is appropriate to update (send UI update events to)
+ this window.
- /**
- Returns @true if the Meta key was down at the time of the event.
- */
- bool MetaDown() 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 middle double click.
+ @see ResetUpdateTime(), SetUpdateInterval(), SetMode()
*/
- bool MiddleDClick() const;
+ static bool CanUpdate(wxWindow* window);
/**
- Returns @true if the middle mouse button changed to down.
+ Check or uncheck the UI element.
*/
- bool MiddleDown() const;
+ void Check(bool check);
/**
- Returns @true if the middle mouse button is currently down, independent
- of the current event type.
+ Enable or disable the UI element.
*/
- bool MiddleIsDown() const;
+ void Enable(bool enable);
/**
- Returns @true if the middle mouse button changed to up.
+ Returns @true if the UI element should be checked.
*/
- bool MiddleUp() const;
+ bool GetChecked() 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 @true if the UI element should be enabled.
*/
- bool Moving() const;
+ bool GetEnabled() const;
/**
- Returns @true if the event was a right double click.
- */
- bool RightDClick() 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 right mouse button changed to down.
+ @see SetMode()
*/
- bool RightDown() const;
+ static wxUpdateUIMode GetMode();
/**
- Returns @true if the right mouse button is currently down, independent
- of the current event type.
+ Returns @true if the application has called Check().
+ For wxWidgets internal use only.
*/
- bool RightIsDown() const;
+ bool GetSetChecked() const;
/**
- Returns @true if the right mouse button changed to up.
+ Returns @true if the application has called Enable().
+ For wxWidgets internal use only.
*/
- bool RightUp() const;
+ bool GetSetEnabled() const;
/**
- Returns @true if the shift key was down at the time of the event.
+ Returns @true if the application has called Show().
+ For wxWidgets internal use only.
*/
- bool ShiftDown() const;
+ bool GetSetShown() const;
/**
- bool m_altDown
- @true if the Alt key is pressed down.
+ Returns @true if the application has called SetText().
+ For wxWidgets internal use only.
*/
-
+ bool GetSetText() const;
/**
- bool m_controlDown
- @true if control key is pressed down.
+ Returns @true if the UI element should be shown.
*/
-
+ bool GetShown() const;
/**
- bool m_leftDown
- @true if the left mouse button is currently pressed down.
+ Returns the text that should be set for the UI element.
*/
-
+ wxString GetText() const;
/**
- int m_linesPerAction
- The configured number of lines (or whatever) to be scrolled per wheel
- action.
- */
-
+ Returns the current interval between updates in milliseconds.
+ The value -1 disables updates, 0 updates as frequently as possible.
- /**
- bool m_metaDown
- @true if the Meta key is pressed down.
+ @see SetUpdateInterval().
*/
-
+ static long GetUpdateInterval();
/**
- bool m_middleDown
- @true if the middle mouse button is currently pressed down.
- */
+ 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.
- /**
- bool m_rightDown
- @true if the right mouse button is currently pressed down.
+ @see CanUpdate(), SetUpdateInterval(), SetMode()
*/
-
+ static void ResetUpdateTime();
/**
- bool m_shiftDown
- @true if shift 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.
+ @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);
/**
- int m_wheelDelta
- The wheel delta, normally 120.
+ Sets the text for this UI element.
*/
-
+ void SetText(const wxString& text);
/**
- int m_wheelRotation
- The distance the mouse wheel is rotated.
- */
+ 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.
- /**
- long m_x
- X-coordinate of the event.
+ 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);
/**
- long m_y
- Y-coordinate of the event.
+ Show or hide the UI element.
*/
+ void Show(bool show);
};
/**
- @class wxDropFilesEvent
+ @class wxClipboardTextEvent
@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.
-
- 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.
-
- @library{wxcore}
- @category{events}
-
- @see @ref overview_eventhandlingoverview
-*/
-class wxDropFilesEvent : public wxEvent
-{
-public:
- /**
- Constructor.
- */
- wxDropFilesEvent(WXTYPE id = 0, int noFiles = 0,
- wxString* files = NULL);
+ 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.
- /**
- Returns an array of filenames.
- */
- wxString* GetFiles() const;
+ There are three types of corresponding events wxEVT_COMMAND_TEXT_COPY,
+ wxEVT_COMMAND_TEXT_CUT and wxEVT_COMMAND_TEXT_PASTE.
- /**
- Returns the number of files dropped.
- */
- int GetNumberOfFiles() const;
+ 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.
- /**
- Returns the position at which the files were dropped.
- Returns an array of filenames.
- */
- wxPoint GetPosition() const;
+ 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.
- /**
- wxString* m_files
- An array of filenames.
- */
+ @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
- /**
- int m_noFiles
- The number of files dropped.
- */
+ @library{wxcore}
+ @category{events}
+ @see wxClipboard
+*/
+class wxClipboardTextEvent : public wxCommandEvent
+{
+public:
/**
- wxPoint m_pos
- The point at which the drop took place.
+ Constructor.
*/
+ wxClipboardTextEvent(wxEventType commandType = wxEVT_NULL, int id = 0);
};
/**
- @class wxCommandEvent
+ @class wxMouseEvent
@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.
+ 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.
+
+ @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 wxKeyEvent::CmdDown
*/
-class wxCommandEvent : public wxEvent
+class wxMouseEvent : public wxEvent
{
public:
/**
- Constructor.
- */
- wxCommandEvent(WXTYPE commandEventType = 0, int id = 0);
+ Constructor. Valid event types are:
- /**
- Deprecated, use IsChecked() instead.
- */
- bool Checked() const;
+ @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);
/**
- Returns client data pointer for a listbox or choice selection event
- (not valid for a deselection).
+ Returns @true if the Alt key was down at the time of the event.
*/
- void* GetClientData();
+ bool AltDown() const;
/**
- Returns client object pointer for a listbox or choice selection event
- (not valid for a deselection).
+ Returns @true if the event was a first extra button double click.
*/
- wxClientData* GetClientObject();
+ bool Aux1DClick() 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 first extra button mouse button changed to down.
*/
- long GetExtraLong();
+ bool Aux1Down() 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 first extra button mouse button is currently down,
+ independent of the current event type.
*/
- int GetInt();
+ bool Aux1IsDown() const;
/**
- Returns item index for a listbox or choice selection event (not valid for
- a deselection).
+ Returns @true if the first extra button mouse button changed to up.
*/
- int GetSelection();
+ bool Aux1Up() const;
/**
- Returns item string for a listbox or choice selection event (not valid for
- a deselection).
+ Returns @true if the event was a second extra button double click.
*/
- wxString GetString();
+ bool Aux2DClick() 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.
+ Returns @true if the second extra button mouse button changed to down.
*/
- bool IsChecked() const;
+ bool Aux2Down() const;
/**
- For a listbox or similar event, returns @true if it is a selection, @false if it
- is a deselection.
+ Returns @true if the second extra button mouse button is currently down,
+ independent of the current event type.
*/
- bool IsSelection();
+ bool Aux2IsDown() const;
/**
- Sets the client data for this event.
+ Returns @true if the second extra button mouse button changed to up.
*/
- void SetClientData(void* clientData);
+ bool Aux2Up() 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.
+ 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
*/
- void SetClientObject(wxClientData* clientObject);
+ bool Button(int button) const;
/**
- Sets the @b m_extraLong member.
+ 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).
*/
- void SetExtraLong(long extraLong);
+ bool ButtonDClick(int but = wxMOUSE_BTN_ANY) const;
/**
- Sets the @b m_commandInt member.
+ 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).
*/
- void SetInt(int intCommand);
+ bool ButtonDown(int = wxMOUSE_BTN_ANY) const;
/**
- Sets the @b m_commandString member.
+ 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 SetString(const wxString& string);
-};
-
-
-
-/**
- @class wxActivateEvent
- @wxheader{event.h}
-
- An activate event is sent when a window or application is being activated
- or deactivated.
-
- @library{wxcore}
- @category{events}
+ bool ButtonUp(int = wxMOUSE_BTN_ANY) const;
- @see @ref overview_eventhandlingoverview, wxApp::IsActive
-*/
-class wxActivateEvent : public wxEvent
-{
-public:
/**
- Constructor.
+ Same as MetaDown() under Mac, same as ControlDown() elsewhere.
+
+ @see wxKeyEvent::CmdDown
*/
- wxActivateEvent(WXTYPE eventType = 0, bool active = true,
- int id = 0);
+ bool CmdDown() const;
/**
- Returns @true if the application or window is being activated, @false otherwise.
+ Returns @true if the control key was down at the time of the event.
*/
- bool GetActive() const;
-};
-
-
-
-/**
- @class wxContextMenuEvent
- @wxheader{event.h}
-
- 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.
-
- @library{wxcore}
- @category{events}
+ bool ControlDown() const;
- @see @ref overview_wxcommandevent "Command events", @ref
- overview_eventhandlingoverview
-*/
-class wxContextMenuEvent : public wxCommandEvent
-{
-public:
/**
- Constructor.
+ Returns @true if this was a dragging event (motion while a button is depressed).
+
+ @see Moving()
*/
- wxContextMenuEvent(WXTYPE id = 0, int id = 0,
- const wxPoint& pos = wxDefaultPosition);
+ bool Dragging() 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 @true if the mouse was entering the window.
+
+ @see Leaving()
*/
- wxPoint GetPosition() const;
+ bool Entering() const;
/**
- Sets the position at which the menu should be shown.
+ 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.
*/
- 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.
+ int GetButton() const;
- To intercept this event, use the EVT_ERASE_BACKGROUND macro in an event table
- definition.
+ /**
+ 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.
- 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.
+ 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}
+ @wxsince{2.9.0}
+ */
+ int GetClickCount() const;
- @see @ref overview_eventhandlingoverview
-*/
-class wxEraseEvent : public wxEvent
-{
-public:
/**
- Constructor.
+ Returns the configured number of lines (or whatever) to be scrolled per
+ wheel action. Defaults to three.
*/
- wxEraseEvent(int id = 0, wxDC* dc = NULL);
+ int GetLinesPerAction() const;
/**
- Returns the device context associated with the erase event to draw on.
+ 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).
*/
- wxDC* GetDC() 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.
+ 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;
+ //@}
-/**
- @class wxFocusEvent
- @wxheader{event.h}
+ /**
+ Get wheel delta, normally 120.
- 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 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;
- 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.
+ /**
+ 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.
+
+ 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.
+ */
+ int GetWheelRotation() const;
- @see @ref overview_eventhandlingoverview
-*/
-class wxFocusEvent : public wxEvent
-{
-public:
/**
- Constructor.
+ Returns X coordinate of the physical mouse event position.
*/
- wxFocusEvent(WXTYPE eventType = 0, int id = 0);
+ wxCoord GetX() 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 Y coordinate of the physical mouse event position.
*/
-};
-
-
-
-/**
- @class wxChildFocusEvent
- @wxheader{event.h}
-
- 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.
+ wxCoord GetY() const;
- 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.
+ /**
+ Returns @true if the event was a mouse button event (not necessarily a button
+ down event - that may be tested using ButtonDown()).
+ */
+ bool IsButton() const;
- @library{wxcore}
- @category{events}
+ /**
+ Returns @true if the system has been setup to do page scrolling with
+ the mouse wheel instead of line scrolling.
+ */
+ bool IsPageScroll() const;
- @see @ref overview_eventhandlingoverview
-*/
-class wxChildFocusEvent : public wxCommandEvent
-{
-public:
/**
- Constructor.
+ Returns @true if the mouse was leaving the window.
- @param win
- The direct child which is (or which contains the window which is) receiving
- the focus.
+ @see Entering().
*/
- wxChildFocusEvent(wxWindow* win = NULL);
+ bool Leaving() 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 event was a left double click.
*/
-};
-
-
+ bool LeftDClick() const;
-/**
- @class wxMouseCaptureLostEvent
- @wxheader{event.h}
+ /**
+ Returns @true if the left mouse button changed to down.
+ */
+ bool LeftDown() 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 left mouse button is currently down, independent
+ of the current event type.
- 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.
+ 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 currently emitted under Windows only.
+ 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;
- @library{wxcore}
- @category{events}
+ /**
+ Returns @true if the left mouse button changed to up.
+ */
+ bool LeftUp() const;
- @see wxMouseCaptureChangedEvent, @ref overview_eventhandlingoverview,
- wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture
-*/
-class wxMouseCaptureLostEvent : public wxEvent
-{
-public:
/**
- Constructor.
+ Returns @true if the Meta key was down at the time of the event.
*/
- wxMouseCaptureLostEvent(wxWindowID windowId = 0);
-};
+ bool MetaDown() const;
+ /**
+ Returns @true if the event was a middle double click.
+ */
+ bool MiddleDClick() const;
+ /**
+ Returns @true if the middle mouse button changed to down.
+ */
+ bool MiddleDown() const;
-/**
- @class wxNotifyEvent
- @wxheader{event.h}
+ /**
+ Returns @true if the middle mouse button is currently down, independent
+ of the current event type.
+ */
+ bool MiddleIsDown() const;
- This class is not used by the event handlers by itself, but is a base class
- for other event classes (such as wxNotebookEvent).
+ /**
+ Returns @true if the middle mouse button changed to up.
+ */
+ bool MiddleUp() const;
- 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.
+ /**
+ 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;
- @library{wxcore}
- @category{events}
+ /**
+ Returns @true if the event was a right double click.
+ */
+ bool RightDClick() const;
- @see wxNotebookEvent
-*/
-class wxNotifyEvent : public wxCommandEvent
-{
-public:
/**
- Constructor (used internally by wxWidgets only).
+ Returns @true if the right mouse button changed to down.
*/
- wxNotifyEvent(wxEventType eventType = wxEVT_NULL, int id = 0);
+ bool RightDown() const;
/**
- 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 @true if the right mouse button is currently down, independent
+ of the current event type.
*/
- void Allow();
+ bool RightIsDown() const;
/**
- Returns @true if the change is allowed (Veto()
- hasn't been called) or @false otherwise (if it was).
+ Returns @true if the right mouse button changed to up.
*/
- bool IsAllowed() const;
+ bool RightUp() 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 @true if the shift key was down at the time of the event.
*/
- void Veto();
+ bool ShiftDown() const;
};
/**
- @class wxHelpEvent
+ @class wxDropFilesEvent
@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.
+ 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.
- 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.
+ 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{FIXME}
+ @category{events}
- @see wxContextHelp, wxDialog, @ref overview_eventhandlingoverview
+ @see @ref overview_eventhandling
*/
-class wxHelpEvent : public wxCommandEvent
+class wxDropFilesEvent : public wxEvent
{
public:
/**
Constructor.
*/
- wxHelpEvent(WXTYPE eventType = 0, wxWindowID id = 0,
- const wxPoint& point);
-
- /**
- Returns the origin of the help event which is one of the following values:
-
- @b Origin_Unknown
-
- Unrecognized event source.
-
- @b Origin_Keyboard
-
- Event generated by @c F1 key press.
-
- @b Origin_HelpButton
-
- Event generated by
- wxContextHelp or using the "?" title bur button under
- MS Windows.
-
- The application may handle events generated using the keyboard or mouse
- differently, e.g. by using wxGetMousePosition()
- for the mouse events.
-
- @see SetOrigin()
- */
- wxHelpEvent::Origin GetOrigin() const;
+ wxDropFilesEvent(wxEventType id = 0, int noFiles = 0,
+ wxString* files = NULL);
/**
- Returns the left-click position of the mouse, in screen coordinates. This allows
- the application to position the help appropriately.
+ Returns an array of filenames.
*/
- const wxPoint GetPosition() const;
+ wxString* GetFiles() const;
/**
- Set the help event origin, only used internally by wxWidgets normally.
-
- @see GetOrigin()
+ Returns the number of files dropped.
*/
- void SetOrigin(wxHelpEvent::Origin origin);
+ int GetNumberOfFiles() const;
/**
- Sets the left-click position of the mouse, in screen coordinates.
+ Returns the position at which the files were dropped.
+ Returns an array of filenames.
*/
- void SetPosition(const wxPoint& pt);
+ wxPoint GetPosition() const;
};
/**
- @class wxScrollEvent
+ @class wxCommandEvent
@wxheader{event.h}
- 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.
+ 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 wxScrollBar, wxSlider, wxSpinButton, , wxScrollWinEvent, @ref
- overview_eventhandlingoverview
*/
-class wxScrollEvent : public wxCommandEvent
+class wxCommandEvent : public wxEvent
{
public:
/**
Constructor.
*/
- wxScrollEvent(WXTYPE commandType = 0, int id = 0, int pos = 0,
- int orientation = 0);
+ wxCommandEvent(wxEventType commandEventType = 0, int id = 0);
/**
- Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the
- scrollbar.
+ Returns client data pointer for a listbox or choice selection event
+ (not valid for a deselection).
*/
- int GetOrientation() const;
+ void* GetClientData() const;
/**
- Returns the position of the scrollbar.
+ Returns client object pointer for a listbox or choice selection event
+ (not valid for a deselection).
*/
- int GetPosition() const;
-};
-
+ wxClientData* GetClientObject() const;
+ /**
+ Returns extra information dependant on the event objects type.
-/**
- @class wxIdleEvent
- @wxheader{event.h}
+ 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;
- 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.
+ /**
+ 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;
- @library{wxbase}
- @category{events}
+ /**
+ Returns item index for a listbox or choice selection event (not valid for
+ a deselection).
+ */
+ int GetSelection() const;
- @see @ref overview_eventhandlingoverview, wxUpdateUIEvent,
- wxWindow::OnInternalIdle
-*/
-class wxIdleEvent : public wxEvent
-{
-public:
/**
- Constructor.
+ Returns item string for a listbox or choice selection event (not valid for
+ a deselection).
*/
- wxIdleEvent();
+ wxString GetString() const;
/**
- 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.
+ 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 SetMode()
+ Notice that this method can not be used with wxCheckListBox currently.
*/
- static bool CanSend(wxWindow* window);
+ bool IsChecked() const;
/**
- 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().
+ For a listbox or similar event, returns @true if it is a selection, @false if it
+ is a deselection.
*/
- static wxIdleMode GetMode();
+ bool IsSelection() const;
+
+ /**
+ Sets the client data for this event.
+ */
+ void SetClientData(void* clientData);
/**
- Returns @true if the OnIdle function processing this event requested more
- processing time.
+ 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.
- @see RequestMore()
+ The client object must be owned and deleted by another object (e.g. a control)
+ that has longer life time than the event object.
*/
- bool MoreRequested() const;
+ void SetClientObject(wxClientData* clientObject);
/**
- 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.
+ Sets the @b m_extraLong member.
+ */
+ void SetExtraLong(long extraLong);
- @see MoreRequested()
+ /**
+ Sets the @b m_commandInt member.
*/
- void RequestMore(bool needMore = true);
+ void SetInt(int intCommand);
/**
- 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.
+ Sets the @b m_commandString member.
*/
- static void SetMode(wxIdleMode mode);
+ void SetString(const wxString& string);
};
/**
- @class wxInitDialogEvent
+ @class wxActivateEvent
@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.
+ An activate event is sent when a window or application is being activated
+ or deactivated.
+
+ @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_eventhandlingoverview
+ @see @ref overview_eventhandling, wxApp::IsActive
*/
-class wxInitDialogEvent : public wxEvent
+class wxActivateEvent : public wxEvent
{
public:
/**
Constructor.
*/
- wxInitDialogEvent(int id = 0);
+ wxActivateEvent(wxEventType eventType = wxEVT_NULL, bool active = true,
+ int id = 0);
+
+ /**
+ Returns @true if the application or window is being activated, @false otherwise.
+ */
+ bool GetActive() const;
};
/**
- @class wxWindowDestroyEvent
+ @class wxContextMenuEvent
@wxheader{event.h}
- This event is sent from the wxWindow destructor wxWindow::~wxWindow() when a
- window is destroyed.
+ This class is used for context menu events, sent to give
+ the application a chance to show a context (popup) menu.
- 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.
+ 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
- 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.
@library{wxcore}
@category{events}
- @see @ref overview_eventhandlingoverview, wxWindowCreateEvent
+ @see wxCommandEvent, @ref overview_eventhandling
*/
-class wxWindowDestroyEvent : public wxCommandEvent
+class wxContextMenuEvent : public wxCommandEvent
{
public:
/**
Constructor.
*/
- wxWindowDestroyEvent(wxWindow* win = NULL);
+ 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 wxNavigationKeyEvent
+ @class wxEraseEvent
@wxheader{event.h}
- This event class contains information about navigation events,
- generated by navigation keys such as tab and page down.
+ An erase event is sent when a window's background needs to be repainted.
- 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.
+ 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.
+
+ @beginEventTable{wxEraseEvent}
+ @event{EVT_ERASE_BACKGROUND(func)}
+ Process a wxEVT_ERASE_BACKGROUND event.
+ @endEventTable
@library{wxcore}
@category{events}
- @see wxWindow::Navigate, wxWindow::NavigateIn
+ @see @ref overview_eventhandling
*/
-class wxNavigationKeyEvent
+class wxEraseEvent : public wxEvent
{
public:
- //@{
/**
Constructor.
*/
- wxNavigationKeyEvent();
- wxNavigationKeyEvent(const wxNavigationKeyEvent& event);
- //@}
+ wxEraseEvent(int id = 0, wxDC* dc = NULL);
/**
- Returns the child that has the focus, or @NULL.
+ Returns the device context associated with the erase event to draw on.
*/
- wxWindow* GetCurrentFocus() const;
+ wxDC* GetDC() const;
+};
- /**
- Returns @true if the navigation was in the forward direction.
- */
- bool GetDirection() 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;
+/**
+ @class wxFocusEvent
+ @wxheader{event.h}
- /**
- Sets the current focus window member.
- */
- void SetCurrentFocus(wxWindow* currentFocus);
+ 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.
- /**
- Sets the direction to forward if @a direction is @true, or backward if @c
- @false.
- */
- void SetDirection(bool direction);
+ 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.
- /**
- Sets the flags.
- */
- void SetFlags(long flags);
+ @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 @ref overview_eventhandling
+*/
+class wxFocusEvent : public wxEvent
+{
+public:
/**
- Marks the navigation event as from a tab key.
+ Constructor.
*/
- void SetFromTab(bool fromTab);
+ wxFocusEvent(wxEventType eventType = wxEVT_NULL, int id = 0);
/**
- Marks the event as a window change event.
+ 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!
*/
- void SetWindowChange(bool windowChange);
+ wxWindow *GetWindow() const;
};
/**
- @class wxMouseCaptureChangedEvent
+ @class wxChildFocusEvent
@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.
+ 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.
+
+ 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.
- This event is implemented under Windows only.
+ @beginEventTable{wxChildFocusEvent}
+ @event{EVT_CHILD_FOCUS(func)}
+ Process a wxEVT_CHILD_FOCUS event.
+ @endEventTable
@library{wxcore}
@category{events}
- @see wxMouseCaptureLostEvent, @ref overview_eventhandlingoverview,
- wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture
+ @see @ref overview_eventhandling
*/
-class wxMouseCaptureChangedEvent : public wxEvent
+class wxChildFocusEvent : public wxCommandEvent
{
public:
/**
Constructor.
+
+ @param win
+ The direct child which is (or which contains the window which is) receiving
+ the focus.
*/
- wxMouseCaptureChangedEvent(wxWindowID windowId = 0,
- wxWindow* gainedCapture = NULL);
+ wxChildFocusEvent(wxWindow* win = NULL);
/**
- Returns the window that gained the capture, or @NULL if it was a non-wxWidgets
- window.
+ 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.
*/
- wxWindow* GetCapturedWindow() const;
+ wxWindow *GetWindow() const;
};
/**
- @class wxCloseEvent
+ @class wxMouseCaptureLostEvent
@wxheader{event.h}
- This event class contains information about window and session close events.
+ 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.
- 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.
+ 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.
- 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 event is currently emitted under Windows only.
- 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.
+ @beginEventTable{wxMouseCaptureLostEvent}
+ @event{EVT_MOUSE_CAPTURE_LOST(func)}
+ Process a wxEVT_MOUSE_CAPTURE_LOST event.
+ @endEventTable
+
+ @onlyfor{wxmsw}
@library{wxcore}
@category{events}
- @see wxWindow::Close, @ref overview_windowdeletionoverview "Window deletion
- overview"
+ @see wxMouseCaptureChangedEvent, @ref overview_eventhandling,
+ wxWindow::CaptureMouse, wxWindow::ReleaseMouse, wxWindow::GetCapture
*/
-class wxCloseEvent : public wxEvent
+class wxMouseCaptureLostEvent : public wxEvent
{
public:
/**
Constructor.
*/
- wxCloseEvent(WXTYPE commandEventType = 0, int id = 0);
+ wxMouseCaptureLostEvent(wxWindowID windowId = 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.
- */
- bool CanVeto();
- /**
- 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;
+/**
+ @class wxNotifyEvent
+ @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).
+
+ 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 wxNotebookEvent
+*/
+class wxNotifyEvent : public wxCommandEvent
+{
+public:
/**
- Sets the 'can veto' flag.
+ Constructor (used internally by wxWidgets only).
*/
- void SetCanVeto(bool canVeto);
+ wxNotifyEvent(wxEventType eventType = wxEVT_NULL, int id = 0);
/**
- Sets the 'force' flag.
+ 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).
*/
- void SetForce(bool force) const;
+ void Allow();
/**
- Sets the 'logging off' flag.
+ Returns @true if the change is allowed (Veto() hasn't been called) or @false
+ otherwise (if it was).
*/
- void SetLoggingOff(bool loggingOff) const;
+ bool IsAllowed() const;
/**
- 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.
+ 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.
*/
- void Veto(bool veto = true);
+ void Veto();
};
+
/**
- @class wxMenuEvent
+ 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 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.
+
+ 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 default handler for wxEVT_MENU_HIGHLIGHT displays help
- text in the first field of the status bar.
+ 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_eventhandlingoverview
+ @see wxContextHelp, wxDialog, @ref overview_eventhandling
*/
-class wxMenuEvent : public wxEvent
+class wxHelpEvent : public wxCommandEvent
{
public:
/**
Constructor.
*/
- wxMenuEvent(WXTYPE 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 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 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()
*/
- wxMenu* GetMenu() const;
+ wxHelpEventOrigin GetOrigin() const;
/**
- Returns the menu identifier associated with the event. This method should be
- only used with the @c HIGHLIGHT events.
+ Returns the left-click position of the mouse, in screen coordinates.
+ This allows the application to position the help appropriately.
*/
- int GetMenuId() const;
+ const wxPoint& GetPosition() const;
/**
- 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.
+ Set the help event origin, only used internally by wxWidgets normally.
+
+ @see GetOrigin()
*/
- bool IsPopup() const;
+ void SetOrigin(wxHelpEventOrigin);
+
+ /**
+ Sets the left-click position of the mouse, in screen coordinates.
+ */
+ 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.
-
- Example:
-
- @code
- {
- // block all events directed to this window while
- // we do the 1000 FuncWhichSendsEvents() calls
- wxEventBlocker blocker(this);
-
- for ( int i = 0; i 1000; i++ )
- FuncWhichSendsEvents(i);
-
- } // ~wxEventBlocker called, old event handler is restored
+ A scroll event holds information about events sent from stand-alone
+ scrollbars (see wxScrollBar) and sliders (see wxSlider).
- // the event generated by this call will be processed
- FuncWhichSendsEvents(0)
- @endcode
+ 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.
+
+ @section wxscrollevent_diff The difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED
+
+ The EVT_SCROLL_THUMBRELEASE event is only emitted when actually dragging the thumb
+ using the mouse and releasing it (This EVT_SCROLL_THUMBRELEASE event is also followed
+ by an EVT_SCROLL_CHANGED event).
+
+ 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).
+
+ 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{FIXME}
+ @category{events}
- @see @ref overview_eventhandlingoverview, 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 type = wxEVT_ANY);
+ 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.
*/
- ~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{FIXME}
+ @category{events}
- @see @ref overview_eventhandlingoverview
+ @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.
- */
- ~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();
+ 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();
- /**
- 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();
+ 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();
+ @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}
+
+ This event class contains information about navigation events,
+ generated by navigation keys such as tab and page down.
+
+ 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.
+
+ @beginEventTable{wxNavigationKeyEvent}
+ @event{EVT_NAVIGATION_KEY(func)}
+ Process a navigation key event.
+ @endEventTable
+
+ @library{wxcore}
+ @category{events}
+
+ @see wxWindow::Navigate, wxWindow::NavigateIn
+*/
+class wxNavigationKeyEvent : public wxEvent
+{
+public:
+ wxNavigationKeyEvent();
+ wxNavigationKeyEvent(const wxNavigationKeyEvent& event);
- @see ProcessEvent()
+ /**
+ Returns the child that has the focus, or @NULL.
*/
- virtual bool SearchEventTable(wxEventTable& table,
- wxEvent& event);
+ wxWindow* GetCurrentFocus() const;
/**
- Sets user-supplied client data.
-
- @param data
- Data to be associated with the event handler.
-
- @remarks Normally, any extra data the programmer wishes to associate with
- the object should be made available by deriving a new
- class with new data members. You must not call this
- method and SetClientObject on the same class - only one
- of them.
-
- @see GetClientData()
+ Returns @true if the navigation was in the forward direction.
*/
- void SetClientData(void* data);
+ bool GetDirection() const;
/**
- Set the client data object. Any previous object will be deleted.
-
- @see GetClientObject(), wxClientData
+ Returns @true if the navigation event was from a tab key.
+ This is required for proper navigation over radio buttons.
*/
- void SetClientObject(wxClientData* data);
+ bool IsFromTab() 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.
-
- @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.
-
- @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_eventhandlingoverview, 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.
+
+ @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 applies to wxApp only.
+ @event{EVT_END_SESSION(func)}
+ Process an end session event, supplying the member function.
+ This event applies to wxApp only.
+ @endEventTable
@library{wxcore}
@category{events}
- @see wxPoint, @ref overview_eventhandlingoverview
+ @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_eventhandlingoverview.
+ 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;
+ 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();
+ int GetMenuId() const;
/**
- Returns the identifier of the given event type,
- such as @c wxEVT_COMMAND_BUTTON_CLICKED.
- */
- wxEventType GetEventType();
+ 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();
+/**
+ @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 timeStamp);
+ 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}
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}
- @see wxSize, @ref overview_eventhandlingoverview
+ @see wxSize, @ref overview_eventhandling
*/
class wxSizeEvent : public wxEvent
{
@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{FIXME}
+ @category{events}
@see ::wxSetCursor, wxWindow::wxSetCursor
*/
/**
Returns a reference to the cursor specified by this event.
*/
- wxCursor GetCursor() const;
+ const wxCursor& GetCursor() const;
/**
Returns the X coordinate of the mouse in client coordinates.
projects / wxWidgets.git / blobdiff