/////////////////////////////////////////////////////////////////////////////
// Name: event.h
-// Purpose: interface of wxEvent-derived classes,
-// see event_base.h for wxEvtHandler and wxEvent.
+// Purpose: interface of wxEvtHandler, wxEventBlocker and many
+// wxEvent-derived classes
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
+#if wxUSE_BASE
+
+/**
+ The predefined constants for the number of times we propagate event
+ upwards window child-parent chain.
+*/
+enum wxEventPropagation
+{
+ /// don't propagate it at all
+ wxEVENT_PROPAGATE_NONE = 0,
+
+ /// propagate it until it is processed
+ wxEVENT_PROPAGATE_MAX = INT_MAX
+};
+
+/**
+ The different categories for a wxEvent; see wxEvent::GetEventCategory.
+
+ @note They are used as OR-combinable flags by wxEventLoopBase::YieldFor.
+*/
+enum wxEventCategory
+{
+ /**
+ This is the category for those events which are generated to update
+ the appearance of the GUI but which (usually) do not comport data
+ processing, i.e. which do not provide input or output data
+ (e.g. size events, scroll events, etc).
+ They are events NOT directly generated by the user's input devices.
+ */
+ wxEVT_CATEGORY_UI = 1,
+
+ /**
+ This category groups those events which are generated directly from the
+ user through input devices like mouse and keyboard and usually result in
+ data to be processed from the application
+ (e.g. mouse clicks, key presses, etc).
+ */
+ wxEVT_CATEGORY_USER_INPUT = 2,
+
+ /// This category is for wxSocketEvent
+ wxEVT_CATEGORY_SOCKET = 4,
+
+ /// This category is for wxTimerEvent
+ wxEVT_CATEGORY_TIMER = 8,
+
+ /**
+ This category is for any event used to send notifications from the
+ secondary threads to the main one or in general for notifications among
+ different threads (which may or may not be user-generated).
+ See e.g. wxThreadEvent.
+ */
+ wxEVT_CATEGORY_THREAD = 16,
+
+ /**
+ This mask is used in wxEventLoopBase::YieldFor to specify that all event
+ categories should be processed.
+ */
+ wxEVT_CATEGORY_ALL =
+ wxEVT_CATEGORY_UI|wxEVT_CATEGORY_USER_INPUT|wxEVT_CATEGORY_SOCKET| \
+ wxEVT_CATEGORY_TIMER|wxEVT_CATEGORY_THREAD
+};
+
+/**
+ @class wxEvent
+
+ An event is a structure holding information about an event passed to a
+ callback or member function.
+
+ wxEvent used to be a multipurpose event object, and is an abstract base class
+ for other event classes (see below).
+
+ For more information about events, see the @ref overview_events overview.
+
+ @beginWxPerlOnly
+ In wxPerl custom event classes should be derived from
+ @c Wx::PlEvent and @c Wx::PlCommandEvent.
+ @endWxPerlOnly
+
+ @library{wxbase}
+ @category{events}
+
+ @see wxCommandEvent, wxMouseEvent
+*/
+class wxEvent : public wxObject
+{
+public:
+ /**
+ Constructor.
+
+ Notice that events are usually created by wxWidgets itself and creating
+ e.g. a wxPaintEvent in your code and sending it to e.g. a wxTextCtrl
+ will not usually affect it at all as native controls have no specific
+ knowledge about wxWidgets events. However you may construct objects of
+ specific types and pass them to wxEvtHandler::ProcessEvent() if you
+ want to create your own custom control and want to process its events
+ in the same manner as the standard ones.
+
+ Also please notice that the order of parameters in this constructor is
+ different from almost all the derived classes which specify the event
+ type as the first argument.
+
+ @param id
+ The identifier of the object (window, timer, ...) which generated
+ this event.
+ @param eventType
+ The unique type of event, e.g. @c wxEVT_PAINT, @c wxEVT_SIZE or
+ @c wxEVT_BUTTON.
+ */
+ wxEvent(int id = 0, wxEventType eventType = wxEVT_NULL);
+
+ /**
+ Returns a copy of the event.
+
+ Any event that is posted to the wxWidgets event system for later action
+ (via wxEvtHandler::AddPendingEvent, wxEvtHandler::QueueEvent or wxPostEvent())
+ must implement this method.
+
+ All wxWidgets events fully implement this method, but any derived events
+ implemented by the user should also implement this method just in case they
+ (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
+ */
+ virtual wxEvent* Clone() const = 0;
+
+ /**
+ Returns the object (usually a window) associated with the event, if any.
+ */
+ wxObject* GetEventObject() const;
+
+ /**
+ Returns the identifier of the given event type, such as @c wxEVT_BUTTON.
+ */
+ wxEventType GetEventType() const;
+
+ /**
+ Returns a generic category for this event.
+ wxEvent implementation returns @c wxEVT_CATEGORY_UI by default.
+
+ This function is used to selectively process events in wxEventLoopBase::YieldFor.
+ */
+ virtual wxEventCategory GetEventCategory() const;
+
+ /**
+ Returns the identifier associated with this event, such as a button command id.
+ */
+ int GetId() const;
+
+ /**
+ Return the user data associated with a dynamically connected event handler.
+
+ wxEvtHandler::Connect() and wxEvtHandler::Bind() allow associating
+ optional @c userData pointer with the handler and this method returns
+ the value of this pointer.
+
+ The returned pointer is owned by wxWidgets and must not be deleted.
+
+ @since 2.9.5
+ */
+ wxObject *GetEventUserData() 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).
+
+ @warning
+ wxWidgets returns a non-NULL timestamp only for mouse and key events
+ (see wxMouseEvent and wxKeyEvent).
+ */
+ long GetTimestamp() const;
+
+ /**
+ Returns @true if the event is or is derived from wxCommandEvent else it returns @false.
+
+ @note exists only for optimization purposes.
+ */
+ bool IsCommandEvent() const;
+
+ /**
+ Sets the propagation level to the given value (for example returned from an
+ earlier call to wxEvent::StopPropagation).
+ */
+ void ResumePropagation(int propagationLevel);
+
+ /**
+ Sets the originating object.
+ */
+ void SetEventObject(wxObject* object);
+
+ /**
+ Sets the event type.
+ */
+ void SetEventType(wxEventType type);
+
+ /**
+ Sets the identifier associated with this event, such as a button command id.
+ */
+ void SetId(int id);
+
+ /**
+ Sets the timestamp for the event.
+ */
+ void SetTimestamp(long timeStamp = 0);
+
+ /**
+ Test if this event should be propagated or not, i.e.\ if the propagation level
+ is currently greater than 0.
+ */
+ bool ShouldPropagate() 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);
+
+ /**
+ 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:
+ /**
+ 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.
+ */
+ int m_propagationLevel;
+};
+
+#endif // wxUSE_BASE
+
+#if wxUSE_GUI
/**
@class wxEventBlocker
{
public:
/**
- Constructs the blocker for the given window and for the given event type.
+ 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 type = -1);
+
+ /**
+ 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();
+
+ /**
+ Adds to the list of event types which should be blocked the given @a eventType.
+ */
+ void Block(wxEventType eventType);
+};
+
+
+
+/**
+ Helper class to temporarily change an event to not propagate.
+*/
+class wxPropagationDisabler
+{
+public:
+ wxPropagationDisabler(wxEvent& event);
+ ~wxPropagationDisabler();
+};
+
+
+/**
+ Helper class to temporarily lower propagation level.
+*/
+class wxPropagateOnce
+{
+public:
+ wxPropagateOnce(wxEvent& event);
+ ~wxPropagateOnce();
+};
+
+#endif // wxUSE_GUI
+
+#if wxUSE_BASE
+
+/**
+ @class wxEvtHandler
+
+ A class that can handle events from the windowing system.
+ wxWindow is (and therefore all window classes are) derived from this class.
+
+ When events are received, wxEvtHandler invokes the method listed in the
+ event table using itself as the object. When using multiple inheritance
+ <b>it is imperative that the wxEvtHandler(-derived) class is the first
+ class inherited</b> such that the @c this pointer for the overall object
+ will be identical to the @c this pointer of the wxEvtHandler portion.
+
+ @library{wxbase}
+ @category{events}
+
+ @see @ref overview_events_processing, wxEventBlocker, wxEventLoopBase
+*/
+class wxEvtHandler : public wxObject, public wxTrackable
+{
+public:
+ /**
+ Constructor.
+ */
+ wxEvtHandler();
+
+ /**
+ Destructor.
+
+ If the handler is part of a chain, the destructor will unlink itself
+ (see Unlink()).
+ */
+ virtual ~wxEvtHandler();
+
+
+ /**
+ @name Event queuing and processing
+ */
+ //@{
+
+ /**
+ Queue event for a later processing.
+
+ This method is similar to ProcessEvent() but while the latter is
+ synchronous, i.e. the event is processed immediately, before the
+ function returns, this one is asynchronous and returns immediately
+ while the event will be processed at some later time (usually during
+ the next event loop iteration).
+
+ Another important difference is that this method takes ownership of the
+ @a event parameter, i.e. it will delete it itself. This implies that
+ the event should be allocated on the heap and that the pointer can't be
+ used any more after the function returns (as it can be deleted at any
+ moment).
+
+ QueueEvent() can be used for inter-thread communication from the worker
+ threads to the main thread, it is safe in the sense that it uses
+ locking internally and avoids the problem mentioned in AddPendingEvent()
+ documentation by ensuring that the @a event object is not used by the
+ calling thread any more. Care should still be taken to avoid that some
+ fields of this object are used by it, notably any wxString members of
+ the event object must not be shallow copies of another wxString object
+ as this would result in them still using the same string buffer behind
+ the scenes. For example:
+ @code
+ void FunctionInAWorkerThread(const wxString& str)
+ {
+ wxCommandEvent* evt = new wxCommandEvent;
+
+ // NOT evt->SetString(str) as this would be a shallow copy
+ evt->SetString(str.c_str()); // make a deep copy
+
+ wxTheApp->QueueEvent( evt );
+ }
+ @endcode
+
+ Note that you can use wxThreadEvent instead of wxCommandEvent
+ to avoid this problem:
+ @code
+ void FunctionInAWorkerThread(const wxString& str)
+ {
+ wxThreadEvent evt;
+ evt->SetString(str);
+
+ // wxThreadEvent::Clone() makes sure that the internal wxString
+ // member is not shared by other wxString instances:
+ wxTheApp->QueueEvent( evt.Clone() );
+ }
+ @endcode
+
+ Finally notice that this method automatically wakes up the event loop
+ if it is currently idle by calling ::wxWakeUpIdle() so there is no need
+ to do it manually when using it.
+
+ @since 2.9.0
+
+ @param event
+ A heap-allocated event to be queued, QueueEvent() takes ownership
+ of it. This parameter shouldn't be @c NULL.
+ */
+ virtual void QueueEvent(wxEvent *event);
+
+ /**
+ Post an event to be processed later.
+
+ This function is similar to QueueEvent() but can't be used to post
+ events from worker threads for the event objects with wxString fields
+ (i.e. in practice most of them) because of an unsafe use of the same
+ wxString object which happens because the wxString field in the
+ original @a event object and its copy made internally by this function
+ share the same string buffer internally. Use QueueEvent() to avoid
+ this.
+
+ A copy of @a event is made by the function, so the original can be deleted
+ as soon as function returns (it is common that the original is created
+ on the stack). This requires that the wxEvent::Clone() method be
+ implemented by event so that it can be duplicated and stored until it
+ gets processed.
+
+ @param event
+ Event to add to the pending events queue.
+ */
+ virtual void AddPendingEvent(const wxEvent& event);
+
+ /**
+ Asynchronously call the given method.
+
+ Calling this function on an object schedules an asynchronous call to
+ the method specified as CallAfter() argument at a (slightly) later
+ time. This is useful when processing some events as certain actions
+ typically can't be performed inside their handlers, e.g. you shouldn't
+ show a modal dialog from a mouse click event handler as this would
+ break the mouse capture state -- but you can call a method showing
+ this message dialog after the current event handler completes.
+
+ The method being called must be the method of the object on which
+ CallAfter() itself is called.
+
+ Notice that it is safe to use CallAfter() from other, non-GUI,
+ threads, but that the method will be always called in the main, GUI,
+ thread context.
+
+ Example of use:
+ @code
+ class MyFrame : public wxFrame {
+ void OnClick(wxMouseEvent& event) {
+ CallAfter(&MyFrame::ShowPosition, event.GetPosition());
+ }
+
+ void ShowPosition(const wxPoint& pos) {
+ if ( wxMessageBox(
+ wxString::Format("Perform click at (%d, %d)?",
+ pos.x, pos.y), "", wxYES_NO) == wxYES )
+ {
+ ... do take this click into account ...
+ }
+ }
+ };
+ @endcode
+
+ @param method The method to call.
+ @param x1 The (optional) first parameter to pass to the method.
+ @param x2 The (optional) second parameter to pass to the method.
+
+ Note that currently only up to 2 arguments can be passed.
+
+ @note This method is not available with Visual C++ before version 8
+ (Visual Studio 2005) as earlier versions of the compiler don't
+ have the required support for C++ templates to implement it.
+
+ @since 2.9.5
+ */
+ template<typename T, typename T1, ...>
+ void CallAfter(void (T::*method)(T1, ...), T1 x1, ...);
+
+ /**
+ 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.
+
+ Notice that you don't usually need to override ProcessEvent() to
+ customize the event handling, overriding the specially provided
+ TryBefore() and TryAfter() functions is usually enough. For example,
+ wxMDIParentFrame may override TryBefore() to ensure that the menu
+ events are processed in the active child frame before being processed
+ in the parent frame itself.
+
+ The normal order of event table searching is as follows:
+ -# wxApp::FilterEvent() is called. If it returns anything but @c -1
+ (default) the processing stops here.
+ -# TryBefore() is called (this is where wxValidator are taken into
+ account for wxWindow objects). If this returns @true, the function exits.
+ -# If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled)
+ the function skips to step (7).
+ -# Dynamic event table of the handlers bound using Bind<>() is
+ searched. If a handler is found, it is executed and the function
+ returns @true unless the handler used wxEvent::Skip() to indicate
+ that it didn't handle the event in which case the search continues.
+ -# Static events table of the handlers bound using event table
+ macros is searched for this event handler. If this fails, the base
+ class event table is tried, and so on until no more tables
+ exist or an appropriate function was found. If a handler is found,
+ the same logic as in the previous step applies.
+ -# The search is applied down the entire chain of event handlers (usually the
+ chain has a length of one). This chain can be formed using wxEvtHandler::SetNextHandler():
+ @image html overview_events_chain.png
+ (referring to the image, if @c A->ProcessEvent is called and it doesn't handle
+ the event, @c B->ProcessEvent will be called and so on...).
+ Note that in the case of wxWindow you can build a stack of event handlers
+ (see wxWindow::PushEventHandler() for more info).
+ If any of the handlers of the chain return @true, the function exits.
+ -# TryAfter() is called: for the wxWindow object this may propagate the
+ event to the window parent (recursively). If the event is still not
+ processed, ProcessEvent() on wxTheApp object is called as the last
+ step.
+
+ Notice that steps (2)-(6) are performed in ProcessEventLocally()
+ which is called by this function.
+
+ @param event
+ Event to process.
+ @return
+ @true if a suitable event handler function was found and executed,
+ and the function did not call wxEvent::Skip.
+
+ @see SearchEventTable()
+ */
+ virtual bool ProcessEvent(wxEvent& event);
+
+ /**
+ Try to process the event in this handler and all those chained to it.
+
+ As explained in ProcessEvent() documentation, the event handlers may be
+ chained in a doubly-linked list. This function tries to process the
+ event in this handler (including performing any pre-processing done in
+ TryBefore(), e.g. applying validators) and all those following it in
+ the chain until the event is processed or the chain is exhausted.
+
+ This function is called from ProcessEvent() and, in turn, calls
+ TryBefore() and TryAfter(). It is not virtual and so cannot be
+ overridden but can, and should, be called to forward an event to
+ another handler instead of ProcessEvent() which would result in a
+ duplicate call to TryAfter(), e.g. resulting in all unprocessed events
+ being sent to the application object multiple times.
+
+ @since 2.9.1
+
+ @param event
+ Event to process.
+ @return
+ @true if this handler of one of those chained to it processed the
+ event.
+ */
+ bool ProcessEventLocally(wxEvent& event);
+
+ /**
+ Processes an event by calling ProcessEvent() and handles any exceptions
+ that occur in the process.
+ If an exception is thrown in event handler, wxApp::OnExceptionInMainLoop is called.
+
+ @param event
+ Event to process.
+
+ @return @true if the event was processed, @false if no handler was found
+ or an exception was thrown.
+
+ @see wxWindow::HandleWindowEvent
+ */
+ bool SafelyProcessEvent(wxEvent& event);
+
+ /**
+ Processes the pending events previously queued using QueueEvent() or
+ AddPendingEvent(); you must call this function only if you are sure
+ there are pending events for this handler, otherwise a @c wxCHECK
+ will fail.
+
+ The real processing still happens in ProcessEvent() which is called by this
+ function.
+
+ Note that this function needs a valid application object (see
+ wxAppConsole::GetInstance()) because wxApp holds the list of the event
+ handlers with pending events and this function manipulates that list.
+ */
+ void ProcessPendingEvents();
+
+ /**
+ Deletes all events queued on this event handler using QueueEvent() or
+ AddPendingEvent().
+
+ Use with care because the events which are deleted are (obviously) not
+ processed and this may have unwanted consequences (e.g. user actions events
+ will be lost).
+ */
+ void DeletePendingEvents();
+
+ /**
+ Searches the event table, executing an event handler function if an appropriate
+ one is found.
+
+ @param table
+ Event table to be searched.
+ @param event
+ Event to be matched against an event table entry.
+
+ @return @true if a suitable event handler function was found and
+ executed, and the function did not call wxEvent::Skip.
+
+ @remarks This function looks through the object's event table and tries
+ to find an entry that will match the event.
+ An entry will match if:
+ @li The event type matches, and
+ @li the identifier or identifier range matches, or the event table
+ entry's identifier is zero.
+
+ If a suitable function is called but calls wxEvent::Skip, this
+ function will fail, and searching will continue.
+
+ @todo this function in the header is listed as an "implementation only" function;
+ are we sure we want to document it?
+
+ @see ProcessEvent()
+ */
+ virtual bool SearchEventTable(wxEventTable& table,
+ wxEvent& event);
+
+ //@}
+
+
+ /**
+ @name Connecting and disconnecting
+ */
+ //@{
+
+ /**
+ Connects the given function dynamically with the event handler, id and
+ event type.
+
+ Notice that Bind() provides a more flexible and safer way to do the
+ same thing as Connect(), please use it in any new code -- while
+ Connect() is not formally deprecated due to its existing widespread
+ usage, it has no advantages compared to Bind().
+
+ This is an alternative to the use of static event tables. It is more
+ flexible as it allows to connect events generated by some object to an
+ event handler defined in a different object of a different class (which
+ is impossible to do directly with the event tables -- the events can be
+ only handled in another object if they are propagated upwards to it).
+ Do make sure to specify the correct @a eventSink when connecting to an
+ event of a different object.
+
+ See @ref overview_events_bind for more detailed explanation
+ of this function and the @ref page_samples_event sample for usage
+ examples.
+
+ This specific overload allows you to connect an event handler to a @e range
+ of @e source IDs.
+ Do not confuse @e source IDs with event @e types: source IDs identify the
+ event generator objects (typically wxMenuItem or wxWindow objects) while the
+ event @e type identify which type of events should be handled by the
+ given @e function (an event generator object may generate many different
+ types of events!).
+
+ @param id
+ The first ID of the identifier range to be associated with the event
+ handler function.
+ @param lastId
+ The last ID of the identifier range to be associated with the event
+ handler function.
+ @param eventType
+ The event type to be associated with this event handler.
+ @param function
+ The event handler function. Note that this function should
+ be explicitly converted to the correct type which can be done using a macro
+ called @c wxFooEventHandler for the handler for any @c wxFooEvent.
+ @param userData
+ Optional data to be associated with the event table entry.
+ wxWidgets will take ownership of this pointer, i.e. it will be
+ destroyed when the event handler is disconnected or at the program
+ termination. This pointer can be retrieved using
+ wxEvent::GetEventUserData() later.
+ @param eventSink
+ Object whose member function should be called. It must be specified
+ when connecting an event generated by one object to a member
+ function of a different object. If it is omitted, @c this is used.
+
+ @beginWxPerlOnly
+ In wxPerl this function takes 4 arguments: @a id, @a lastid,
+ @a type, @a method; if @a method is undef, the handler is
+ disconnected.}
+ @endWxPerlOnly
+
+ @see Bind<>()
+ */
+ void Connect(int id, int lastId, wxEventType eventType,
+ wxObjectEventFunction function,
+ wxObject* userData = NULL,
+ wxEvtHandler* eventSink = NULL);
+
+ /**
+ 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_MENU,
+ wxCommandEventHandler(MyFrame::OnQuit) );
+ @endcode
+
+ @beginWxPerlOnly
+ Not supported by wxPerl.
+ @endWxPerlOnly
+ */
+ void Connect(int id, wxEventType eventType,
+ wxObjectEventFunction function,
+ wxObject* userData = NULL,
+ wxEvtHandler* eventSink = NULL);
+
+ /**
+ 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.
+
+ @beginWxPerlOnly
+ Not supported by wxPerl.
+ @endWxPerlOnly
+ */
+ 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.
+
+ @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.
+
+ @beginWxPerlOnly
+ Not supported by wxPerl.
+ @endWxPerlOnly
+ */
+ bool Disconnect(wxEventType eventType,
+ wxObjectEventFunction function,
+ wxObject* userData = NULL,
+ wxEvtHandler* eventSink = NULL);
+
+ /**
+ See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
+ overload for more info.
+
+ This overload takes the additional @a id parameter.
+
+ @beginWxPerlOnly
+ Not supported by wxPerl.
+ @endWxPerlOnly
+ */
+ bool Disconnect(int id = wxID_ANY,
+ wxEventType eventType = wxEVT_NULL,
+ wxObjectEventFunction function = NULL,
+ wxObject* userData = NULL,
+ wxEvtHandler* eventSink = NULL);
+
+ /**
+ See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
+ overload for more info.
+
+ This overload takes an additional range of source IDs.
+
+ @beginWxPerlOnly
+ In wxPerl this function takes 3 arguments: @a id,
+ @a lastid, @a type.
+ @endWxPerlOnly
+ */
+ bool Disconnect(int id, int lastId,
+ wxEventType eventType,
+ wxObjectEventFunction function = NULL,
+ wxObject* userData = NULL,
+ wxEvtHandler* eventSink = NULL);
+ //@}
+
+
+ /**
+ @name Binding and Unbinding
+ */
+ //@{
+
+ /**
+ Binds the given function, functor or method dynamically with the event.
+
+ This offers basically the same functionality as Connect(), but it is
+ more flexible as it also allows you to use ordinary functions and
+ arbitrary functors as event handlers. It is also less restrictive then
+ Connect() because you can use an arbitrary method as an event handler,
+ whereas Connect() requires a wxEvtHandler derived handler.
+
+ See @ref overview_events_bind for more detailed explanation
+ of this function and the @ref page_samples_event sample for usage
+ examples.
+
+ @param eventType
+ The event type to be associated with this event handler.
+ @param functor
+ The event handler functor. This can be an ordinary function but also
+ an arbitrary functor like boost::function<>.
+ @param id
+ The first ID of the identifier range to be associated with the event
+ handler.
+ @param lastId
+ The last ID of the identifier range to be associated with the event
+ handler.
+ @param userData
+ Optional data to be associated with the event table entry.
+ wxWidgets will take ownership of this pointer, i.e. it will be
+ destroyed when the event handler is disconnected or at the program
+ termination. This pointer can be retrieved using
+ wxEvent::GetEventUserData() later.
+
+ @see @ref overview_cpp_rtti_disabled
+
+ @since 2.9.0
+ */
+ template <typename EventTag, typename Functor>
+ void Bind(const EventTag& eventType,
+ Functor functor,
+ int id = wxID_ANY,
+ int lastId = wxID_ANY,
+ wxObject *userData = NULL);
+
+ /**
+ See the Bind<>(const EventTag&, Functor, int, int, wxObject*) overload for
+ more info.
+
+ This overload will bind the given method as the event handler.
+
+ @param eventType
+ The event type to be associated with this event handler.
+ @param method
+ The event handler method. This can be an arbitrary method (doesn't need
+ to be from a wxEvtHandler derived class).
+ @param handler
+ Object whose method should be called. It must always be specified
+ so it can be checked at compile time whether the given method is an
+ actual member of the given handler.
+ @param id
+ The first ID of the identifier range to be associated with the event
+ handler.
+ @param lastId
+ The last ID of the identifier range to be associated with the event
+ handler.
+ @param userData
+ Optional data to be associated with the event table entry.
+ wxWidgets will take ownership of this pointer, i.e. it will be
+ destroyed when the event handler is disconnected or at the program
+ termination. This pointer can be retrieved using
+ wxEvent::GetEventUserData() later.
+
+ @see @ref overview_cpp_rtti_disabled
+
+ @since 2.9.0
+ */
+ template <typename EventTag, typename Class, typename EventArg, typename EventHandler>
+ void Bind(const EventTag &eventType,
+ void (Class::*method)(EventArg &),
+ EventHandler *handler,
+ int id = wxID_ANY,
+ int lastId = wxID_ANY,
+ wxObject *userData = NULL);
+ /**
+ Unbinds the given function, functor or method 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 unbind functions, functors or methods which have
+ been added using the Bind<>() method. There is no way to unbind
+ functions bound using the (static) event tables.
+
+ @param eventType
+ The event type associated with this event handler.
+ @param functor
+ The event handler functor. This can be an ordinary function but also
+ an arbitrary functor like boost::function<>.
+ @param id
+ The first ID of the identifier range associated with the event
+ handler.
+ @param lastId
+ The last ID of the identifier range associated with the event
+ handler.
+ @param userData
+ Data associated with the event table entry.
+
+ @see @ref overview_cpp_rtti_disabled
+
+ @since 2.9.0
+ */
+ template <typename EventTag, typename Functor>
+ bool Unbind(const EventTag& eventType,
+ Functor functor,
+ int id = wxID_ANY,
+ int lastId = wxID_ANY,
+ wxObject *userData = NULL);
+
+ /**
+ See the Unbind<>(const EventTag&, Functor, int, int, wxObject*)
+ overload for more info.
+
+ This overload unbinds the given method from the event..
+
+ @param eventType
+ The event type associated with this event handler.
+ @param method
+ The event handler method associated with this event.
+ @param handler
+ Object whose method was called.
+ @param id
+ The first ID of the identifier range associated with the event
+ handler.
+ @param lastId
+ The last ID of the identifier range associated with the event
+ handler.
+ @param userData
+ Data associated with the event table entry.
+
+ @see @ref overview_cpp_rtti_disabled
+
+ @since 2.9.0
+ */
+ template <typename EventTag, typename Class, typename EventArg, typename EventHandler>
+ bool Unbind(const EventTag &eventType,
+ void (Class::*method)(EventArg&),
+ EventHandler *handler,
+ int id = wxID_ANY,
+ int lastId = wxID_ANY,
+ wxObject *userData = NULL );
+ //@}
+ /**
+ @name User-supplied data
+ */
+ //@{
+
+ /**
+ 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()
+ */
+ void* GetClientData() const;
+
+ /**
+ Returns a pointer to the user-supplied client data object.
+
+ @see SetClientObject(), wxClientData
+ */
+ wxClientData* GetClientObject() 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()
+ */
+ void SetClientData(void* data);
+
+ /**
+ Set the client data object. Any previous object will be deleted.
+
+ @see GetClientObject(), wxClientData
+ */
+ void SetClientObject(wxClientData* data);
+
+ //@}
+
+
+ /**
+ @name Event handler chaining
+
+ wxEvtHandler can be arranged in a double-linked list of handlers
+ which is automatically iterated by ProcessEvent() if needed.
+ */
+ //@{
+
+ /**
+ Returns @true if the event handler is enabled, @false otherwise.
+
+ @see SetEvtHandlerEnabled()
+ */
+ bool GetEvtHandlerEnabled() const;
+
+ /**
+ Returns the pointer to the next handler in the chain.
+
+ @see SetNextHandler(), GetPreviousHandler(), SetPreviousHandler(),
+ wxWindow::PushEventHandler, wxWindow::PopEventHandler
+ */
+ wxEvtHandler* GetNextHandler() const;
+
+ /**
+ Returns the pointer to the previous handler in the chain.
+
+ @see SetPreviousHandler(), GetNextHandler(), SetNextHandler(),
+ wxWindow::PushEventHandler, wxWindow::PopEventHandler
+ */
+ wxEvtHandler* GetPreviousHandler() 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()
+ */
+ void SetEvtHandlerEnabled(bool enabled);
+
+ /**
+ Sets the pointer to the next handler.
+
+ @remarks
+ See ProcessEvent() for more info about how the chains of event handlers
+ are internally used.
+ Also remember that wxEvtHandler uses double-linked lists and thus if you
+ use this function, you should also call SetPreviousHandler() on the
+ argument passed to this function:
+ @code
+ handlerA->SetNextHandler(handlerB);
+ handlerB->SetPreviousHandler(handlerA);
+ @endcode
+
+ @param handler
+ The event handler to be set as the next handler.
+ Cannot be @NULL.
+
+ @see @ref overview_events_processing
+ */
+ virtual void SetNextHandler(wxEvtHandler* handler);
+
+ /**
+ Sets the pointer to the previous handler.
+ All remarks about SetNextHandler() apply to this function as well.
+
+ @param handler
+ The event handler to be set as the previous handler.
+ Cannot be @NULL.
+
+ @see @ref overview_events_processing
+ */
+ virtual void SetPreviousHandler(wxEvtHandler* handler);
+
+ /**
+ Unlinks this event handler from the chain it's part of (if any);
+ then links the "previous" event handler to the "next" one
+ (so that the chain won't be interrupted).
+
+ E.g. if before calling Unlink() you have the following chain:
+ @image html evthandler_unlink_before.png
+ then after calling @c B->Unlink() you'll have:
+ @image html evthandler_unlink_after.png
+
+ @since 2.9.0
+ */
+ void Unlink();
+
+ /**
+ Returns @true if the next and the previous handler pointers of this
+ event handler instance are @NULL.
+
+ @since 2.9.0
+
+ @see SetPreviousHandler(), SetNextHandler()
+ */
+ bool IsUnlinked() const;
+
+ //@}
+
+ /**
+ @name Global event filters.
+
+ Methods for working with the global list of event filters.
+
+ Event filters can be defined to pre-process all the events that happen
+ in an application, see wxEventFilter documentation for more information.
+ */
+ //@{
+
+ /**
+ Add an event filter whose FilterEvent() method will be called for each
+ and every event processed by wxWidgets.
- 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.
+ The filters are called in LIFO order and wxApp is registered as an
+ event filter by default. The pointer must remain valid until it's
+ removed with RemoveFilter() and is not deleted by wxEvtHandler.
- Note that the @a win window @b must remain alive until the
- wxEventBlocker object destruction.
- */
- wxEventBlocker(wxWindow* win, wxEventType type = -1);
+ @since 2.9.3
+ */
+ static void AddFilter(wxEventFilter* filter);
/**
- 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();
+ Remove a filter previously installed with AddFilter().
+
+ It's an error to remove a filter that hadn't been previously added or
+ was already removed.
+
+ @since 2.9.3
+ */
+ static void RemoveFilter(wxEventFilter* filter);
+
+ //@}
+protected:
/**
- Adds to the list of event types which should be blocked the given @a eventType.
- */
- void Block(wxEventType eventType);
-};
+ Method called by ProcessEvent() before examining this object event
+ tables.
+ This method can be overridden to hook into the event processing logic
+ as early as possible. You should usually call the base class version
+ when overriding this method, even if wxEvtHandler itself does nothing
+ here, some derived classes do use this method, e.g. wxWindow implements
+ support for wxValidator in it.
+ Example:
+ @code
+ class MyClass : public BaseClass // inheriting from wxEvtHandler
+ {
+ ...
+ protected:
+ virtual bool TryBefore(wxEvent& event)
+ {
+ if ( MyPreProcess(event) )
+ return true;
-/**
- Helper class to temporarily change an event to not propagate.
-*/
-class wxPropagationDisabler
-{
-public:
- wxPropagationDisabler(wxEvent& event);
- ~wxPropagationDisabler();
-};
+ return BaseClass::TryBefore(event);
+ }
+ };
+ @endcode
+ @see ProcessEvent()
+ */
+ virtual bool TryBefore(wxEvent& event);
-/**
- Helper class to temporarily lower propagation level.
-*/
-class wxPropagateOnce
-{
-public:
- wxPropagateOnce(wxEvent& event);
- ~wxPropagateOnce();
+ /**
+ Method called by ProcessEvent() as last resort.
+
+ This method can be overridden to implement post-processing for the
+ events which were not processed anywhere else.
+
+ The base class version handles forwarding the unprocessed events to
+ wxApp at wxEvtHandler level and propagating them upwards the window
+ child-parent chain at wxWindow level and so should usually be called
+ when overriding this method:
+ @code
+ class MyClass : public BaseClass // inheriting from wxEvtHandler
+ {
+ ...
+ protected:
+ virtual bool TryAfter(wxEvent& event)
+ {
+ if ( BaseClass::TryAfter(event) )
+ return true;
+
+ return MyPostProcess(event);
+ }
+ };
+ @endcode
+
+ @see ProcessEvent()
+ */
+ virtual bool TryAfter(wxEvent& event);
};
+#endif // wxUSE_BASE
+#if wxUSE_GUI
/**
Flags for categories of keys.
else // No Unicode equivalent.
{
// It's a special key, deal with all the known ones:
- switch ( GetKeyCode() )
+ switch ( event.GetKeyCode() )
{
case WXK_LEFT:
case WXK_RIGHT:
/**
Obtains the position (in client coordinates) at which the key was pressed.
- Notice that this position is simply the current mouse pointer position
- and has no special relationship to the key event itself.
+ Notice that under most platforms this position is simply the current
+ mouse pointer position and has no special relationship to the key event
+ itself.
+
+ @a x and @a y may be @NULL if the corresponding coordinate is not
+ needed.
*/
wxPoint GetPosition() const;
- void GetPosition(long* x, long* y) const;
+ void GetPosition(wxCoord* x, wxCoord* y) const;
//@}
/**
/**
Constructor.
*/
- wxScrollWinEvent(wxEventType commandType = wxEVT_NULL, int pos = 0,
- int orientation = 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;
+
+ void SetOrientation(int orient);
+ void SetPosition(int pos);
+};
+
+
+
+/**
+ @class wxSysColourChangedEvent
+
+ 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.
+
+ @remarks
+ The default event handler for this event propagates the event to child windows,
+ since Windows only sends the events to top-level windows.
+ If intercepting this event for a top-level window, remember to call the base
+ class handler, or to pass the event on to the window's children explicitly.
+
+ @beginEventTable{wxSysColourChangedEvent}
+ @event{EVT_SYS_COLOUR_CHANGED(func)}
+ Process a @c wxEVT_SYS_COLOUR_CHANGED event.
+ @endEventTable
+
+ @library{wxcore}
+ @category{events}
+
+ @see @ref overview_events
+*/
+class wxSysColourChangedEvent : public wxEvent
+{
+public:
+ /**
+ Constructor.
+ */
+ wxSysColourChangedEvent();
+};
+
+
+
+/**
+ @class wxCommandEvent
+
+ This event class contains information about command events, which originate
+ from a variety of simple controls.
+
+ Note that wxCommandEvents and wxCommandEvent-derived event classes by default
+ and unlike other wxEvent-derived classes propagate upward from the source
+ window (the window which emits the event) up to the first parent which processes
+ the event. Be sure to read @ref overview_events_propagation.
+
+ 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 @c wxEVT_BUTTON command, which is generated by a wxButton control.
+ @event{EVT_CHECKBOX(id, func)}
+ Process a @c wxEVT_CHECKBOX command, which is generated by a wxCheckBox control.
+ @event{EVT_CHOICE(id, func)}
+ Process a @c wxEVT_CHOICE command, which is generated by a wxChoice control.
+ @event{EVT_COMBOBOX(id, func)}
+ Process a @c wxEVT_COMBOBOX command, which is generated by a wxComboBox control.
+ @event{EVT_LISTBOX(id, func)}
+ Process a @c wxEVT_LISTBOX command, which is generated by a wxListBox control.
+ @event{EVT_LISTBOX_DCLICK(id, func)}
+ Process a @c wxEVT_LISTBOX_DCLICK command, which is generated by a wxListBox control.
+ @event{EVT_CHECKLISTBOX(id, func)}
+ Process a @c wxEVT_CHECKLISTBOX command, which is generated by a wxCheckListBox control.
+ @event{EVT_MENU(id, func)}
+ Process a @c wxEVT_MENU command, which is generated by a menu item.
+ @event{EVT_MENU_RANGE(id1, id2, func)}
+ Process a @c wxEVT_MENU 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 @c wxEVT_RADIOBOX command, which is generated by a wxRadioBox control.
+ @event{EVT_RADIOBUTTON(id, func)}
+ Process a @c wxEVT_RADIOBUTTON command, which is generated by a wxRadioButton control.
+ @event{EVT_SCROLLBAR(id, func)}
+ Process a @c wxEVT_SCROLLBAR 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 @c wxEVT_SLIDER command, which is generated by a wxSlider control.
+ @event{EVT_TEXT(id, func)}
+ Process a @c wxEVT_TEXT command, which is generated by a wxTextCtrl control.
+ @event{EVT_TEXT_ENTER(id, func)}
+ Process a @c wxEVT_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 @c wxEVT_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 @c wxEVT_TOGGLEBUTTON event.
+ @event{EVT_TOOL(id, func)}
+ Process a @c wxEVT_TOOL event (a synonym for @c wxEVT_MENU).
+ Pass the id of the tool.
+ @event{EVT_TOOL_RANGE(id1, id2, func)}
+ Process a @c wxEVT_TOOL event for a range of identifiers. Pass the ids of the tools.
+ @event{EVT_TOOL_RCLICKED(id, func)}
+ Process a @c wxEVT_TOOL_RCLICKED event. Pass the id of the tool. (Not available on wxOSX.)
+ @event{EVT_TOOL_RCLICKED_RANGE(id1, id2, func)}
+ Process a @c wxEVT_TOOL_RCLICKED event for a range of ids. Pass the ids of the tools. (Not available on wxOSX.)
+ @event{EVT_TOOL_ENTER(id, func)}
+ Process a @c wxEVT_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. (Not available on wxOSX.)
+ @event{EVT_COMMAND_LEFT_CLICK(id, func)}
+ Process a @c wxEVT_COMMAND_LEFT_CLICK command, which is generated by a control (wxMSW only).
+ @event{EVT_COMMAND_LEFT_DCLICK(id, func)}
+ Process a @c wxEVT_COMMAND_LEFT_DCLICK command, which is generated by a control (wxMSW only).
+ @event{EVT_COMMAND_RIGHT_CLICK(id, func)}
+ Process a @c wxEVT_COMMAND_RIGHT_CLICK command, which is generated by a control (wxMSW only).
+ @event{EVT_COMMAND_SET_FOCUS(id, func)}
+ Process a @c wxEVT_COMMAND_SET_FOCUS command, which is generated by a control (wxMSW only).
+ @event{EVT_COMMAND_KILL_FOCUS(id, func)}
+ Process a @c wxEVT_COMMAND_KILL_FOCUS command, which is generated by a control (wxMSW only).
+ @event{EVT_COMMAND_ENTER(id, func)}
+ Process a @c wxEVT_COMMAND_ENTER command, which is generated by a control.
+ @endEventTable
+
+ @library{wxcore}
+ @category{events}
+*/
+class wxCommandEvent : public wxEvent
+{
+public:
+ /**
+ Constructor.
+ */
+ wxCommandEvent(wxEventType commandEventType = wxEVT_NULL, int id = 0);
+
+ /**
+ Returns client data pointer for a listbox or choice selection event
+ (not valid for a deselection).
+ */
+ void* GetClientData() const;
+
+ /**
+ Returns client object pointer for a listbox or choice selection event
+ (not valid for a deselection).
+ */
+ wxClientData* GetClientObject() const;
+
+ /**
+ Returns extra information dependent 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.
+ */
+ long GetExtraLong() 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.
+
+ For a menu item, this method returns -1 if the item is not checkable or
+ a boolean value (true or false) for checkable items indicating the new
+ state of the item.
+ */
+ int GetInt() const;
+
+ /**
+ Returns item index for a listbox or choice selection event (not valid for
+ a deselection).
+ */
+ int GetSelection() const;
+
+ /**
+ Returns item string for a listbox or choice selection event. If one
+ or several items have been deselected, returns the index of the first
+ deselected item. If some items have been selected and others deselected
+ at the same time, it will return the index of the first selected item.
+ */
+ wxString GetString() 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 cannot be used with wxCheckListBox currently.
+ */
+ bool IsChecked() const;
/**
- Returns wxHORIZONTAL or wxVERTICAL, depending on the orientation of the
- scrollbar.
-
- @todo wxHORIZONTAL and wxVERTICAL should go in their own enum
+ For a listbox or similar event, returns @true if it is a selection, @false
+ if it is a deselection. If some items have been selected and others deselected
+ at the same time, it will return @true.
*/
- int GetOrientation() const;
+ bool IsSelection() 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.
+ Sets the client data for this event.
*/
- int GetPosition() const;
-
- void SetOrientation(int orient);
- void SetPosition(int pos);
-};
-
-
-
-/**
- @class wxSysColourChangedEvent
+ void SetClientData(void* clientData);
- 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.
+ /**
+ 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.
- @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.
+ The client object must be owned and deleted by another object (e.g. a control)
+ that has longer life time than the event object.
+ */
+ void SetClientObject(wxClientData* clientObject);
- @beginEventTable{wxSysColourChangedEvent}
- @event{EVT_SYS_COLOUR_CHANGED(func)}
- Process a @c wxEVT_SYS_COLOUR_CHANGED event.
- @endEventTable
+ /**
+ Sets the @b m_extraLong member.
+ */
+ void SetExtraLong(long extraLong);
- @library{wxcore}
- @category{events}
+ /**
+ Sets the @b m_commandInt member.
+ */
+ void SetInt(int intCommand);
- @see @ref overview_events
-*/
-class wxSysColourChangedEvent : public wxEvent
-{
-public:
/**
- Constructor.
+ Sets the @b m_commandString member.
*/
- wxSysColourChangedEvent();
+ void SetString(const wxString& string);
};
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 @c wxEVT_COMMAND_TEXT_COPY,
- @c wxEVT_COMMAND_TEXT_CUT and @c wxEVT_COMMAND_TEXT_PASTE.
+ There are three types of corresponding events @c wxEVT_TEXT_COPY,
+ @c wxEVT_TEXT_CUT and @c wxEVT_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
/**
Returns the configured number of lines (or whatever) to be scrolled per
- wheel action. Defaults to three.
+ wheel action.
+
+ Default value under most platforms is three.
+
+ @see GetColumnsPerAction()
*/
int GetLinesPerAction() const;
/**
- Returns the logical mouse position in pixels (i.e. translated according to the
+ Returns the configured number of columns (or whatever) to be scrolled per
+ wheel action.
+
+ Default value under most platforms is three.
+
+ @see GetLinesPerAction()
+
+ @since 2.9.5
+ */
+ int GetColumnsPerAction() const;
+
+ /**
+ Returns the logical mouse position in pixels (i.e.\ translated according to the
translation set for the DC, which usually indicates that the window has been
scrolled).
*/
bool LeftDClick() const;
/**
- Returns @true if the left mouse button changed to down.
- */
- bool LeftDown() const;
-
- /**
- Returns @true if the left mouse button changed to up.
- */
- bool LeftUp() const;
-
- /**
- Returns @true if the Meta key was down at the time of the event.
- */
- 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;
-
- /**
- Returns @true if the middle mouse button changed to up.
- */
- bool MiddleUp() 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.
- */
- bool Moving() const;
-
- /**
- Returns @true if the event was a right double click.
- */
- bool RightDClick() const;
-
- /**
- Returns @true if the right mouse button changed to down.
- */
- bool RightDown() const;
-
- /**
- Returns @true if the right mouse button changed to up.
- */
- bool RightUp() const;
-};
-
-
-
-/**
- @class wxDropFilesEvent
-
- 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 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 @c wxEVT_DROP_FILES event.
- @endEventTable
-
- @onlyfor{wxmsw}
-
- @library{wxcore}
- @category{events}
-
- @see @ref overview_events
-*/
-class wxDropFilesEvent : public wxEvent
-{
-public:
- /**
- Constructor.
- */
- wxDropFilesEvent(wxEventType id = 0, int noFiles = 0,
- wxString* files = NULL);
-
- /**
- Returns an array of filenames.
- */
- wxString* GetFiles() const;
-
- /**
- Returns the number of files dropped.
- */
- int GetNumberOfFiles() const;
-
- /**
- Returns the position at which the files were dropped.
- Returns an array of filenames.
- */
- wxPoint GetPosition() const;
-};
-
-
-
-/**
- @class wxCommandEvent
-
- This event class contains information about command events, which originate
- from a variety of simple controls.
-
- Note that wxCommandEvents and wxCommandEvent-derived event classes by default
- and unlike other wxEvent-derived classes propagate upward from the source
- window (the window which emits the event) up to the first parent which processes
- the event. Be sure to read @ref overview_events_propagation.
-
- 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 @c wxEVT_COMMAND_BUTTON_CLICKED command, which is generated by a wxButton control.
- @event{EVT_CHECKBOX(id, func)}
- Process a @c wxEVT_COMMAND_CHECKBOX_CLICKED command, which is generated by a wxCheckBox control.
- @event{EVT_CHOICE(id, func)}
- Process a @c wxEVT_COMMAND_CHOICE_SELECTED command, which is generated by a wxChoice control.
- @event{EVT_COMBOBOX(id, func)}
- Process a @c wxEVT_COMMAND_COMBOBOX_SELECTED command, which is generated by a wxComboBox control.
- @event{EVT_LISTBOX(id, func)}
- Process a @c wxEVT_COMMAND_LISTBOX_SELECTED command, which is generated by a wxListBox control.
- @event{EVT_LISTBOX_DCLICK(id, func)}
- Process a @c wxEVT_COMMAND_LISTBOX_DOUBLECLICKED command, which is generated by a wxListBox control.
- @event{EVT_CHECKLISTBOX(id, func)}
- Process a @c wxEVT_COMMAND_CHECKLISTBOX_TOGGLED command, which is generated by a wxCheckListBox control.
- @event{EVT_MENU(id, func)}
- Process a @c wxEVT_COMMAND_MENU_SELECTED command, which is generated by a menu item.
- @event{EVT_MENU_RANGE(id1, id2, func)}
- Process a @c wxEVT_COMMAND_MENU_RANGE command, which is generated by a range of menu items.
- @event{EVT_CONTEXT_MENU(func)}
- Process the event generated when the user has requested a popup menu to appear by
- pressing a special keyboard key (under Windows) or by right clicking the mouse.
- @event{EVT_RADIOBOX(id, func)}
- Process a @c wxEVT_COMMAND_RADIOBOX_SELECTED command, which is generated by a wxRadioBox control.
- @event{EVT_RADIOBUTTON(id, func)}
- Process a @c wxEVT_COMMAND_RADIOBUTTON_SELECTED command, which is generated by a wxRadioButton control.
- @event{EVT_SCROLLBAR(id, func)}
- Process a @c wxEVT_COMMAND_SCROLLBAR_UPDATED command, which is generated by a wxScrollBar
- control. This is provided for compatibility only; more specific scrollbar event macros
- should be used instead (see wxScrollEvent).
- @event{EVT_SLIDER(id, func)}
- Process a @c wxEVT_COMMAND_SLIDER_UPDATED command, which is generated by a wxSlider control.
- @event{EVT_TEXT(id, func)}
- Process a @c wxEVT_COMMAND_TEXT_UPDATED command, which is generated by a wxTextCtrl control.
- @event{EVT_TEXT_ENTER(id, func)}
- Process a @c wxEVT_COMMAND_TEXT_ENTER command, which is generated by a wxTextCtrl control.
- Note that you must use wxTE_PROCESS_ENTER flag when creating the control if you want it
- to generate such events.
- @event{EVT_TEXT_MAXLEN(id, func)}
- Process a @c wxEVT_COMMAND_TEXT_MAXLEN command, which is generated by a wxTextCtrl control
- when the user tries to enter more characters into it than the limit previously set
- with SetMaxLength().
- @event{EVT_TOGGLEBUTTON(id, func)}
- Process a @c wxEVT_COMMAND_TOGGLEBUTTON_CLICKED event.
- @event{EVT_TOOL(id, func)}
- Process a @c wxEVT_COMMAND_TOOL_CLICKED event (a synonym for @c wxEVT_COMMAND_MENU_SELECTED).
- Pass the id of the tool.
- @event{EVT_TOOL_RANGE(id1, id2, func)}
- Process a @c wxEVT_COMMAND_TOOL_CLICKED event for a range of identifiers. Pass the ids of the tools.
- @event{EVT_TOOL_RCLICKED(id, func)}
- Process a @c wxEVT_COMMAND_TOOL_RCLICKED event. Pass the id of the tool. (Not available on wxOSX.)
- @event{EVT_TOOL_RCLICKED_RANGE(id1, id2, func)}
- Process a @c wxEVT_COMMAND_TOOL_RCLICKED event for a range of ids. Pass the ids of the tools. (Not available on wxOSX.)
- @event{EVT_TOOL_ENTER(id, func)}
- Process a @c wxEVT_COMMAND_TOOL_ENTER event. Pass the id of the toolbar itself.
- The value of wxCommandEvent::GetSelection() is the tool id, or -1 if the mouse cursor
- has moved off a tool. (Not available on wxOSX.)
- @event{EVT_COMMAND_LEFT_CLICK(id, func)}
- Process a @c wxEVT_COMMAND_LEFT_CLICK command, which is generated by a control (wxMSW only).
- @event{EVT_COMMAND_LEFT_DCLICK(id, func)}
- Process a @c wxEVT_COMMAND_LEFT_DCLICK command, which is generated by a control (wxMSW only).
- @event{EVT_COMMAND_RIGHT_CLICK(id, func)}
- Process a @c wxEVT_COMMAND_RIGHT_CLICK command, which is generated by a control (wxMSW only).
- @event{EVT_COMMAND_SET_FOCUS(id, func)}
- Process a @c wxEVT_COMMAND_SET_FOCUS command, which is generated by a control (wxMSW only).
- @event{EVT_COMMAND_KILL_FOCUS(id, func)}
- Process a @c wxEVT_COMMAND_KILL_FOCUS command, which is generated by a control (wxMSW only).
- @event{EVT_COMMAND_ENTER(id, func)}
- Process a @c wxEVT_COMMAND_ENTER command, which is generated by a control.
- @endEventTable
-
- @library{wxcore}
- @category{events}
-*/
-class wxCommandEvent : public wxEvent
-{
-public:
- /**
- Constructor.
+ Returns @true if the left mouse button changed to down.
*/
- wxCommandEvent(wxEventType commandEventType = wxEVT_NULL, int id = 0);
+ bool LeftDown() const;
/**
- Returns client data pointer for a listbox or choice selection event
- (not valid for a deselection).
+ Returns @true if the left mouse button changed to up.
*/
- void* GetClientData() const;
+ bool LeftUp() const;
/**
- Returns client object pointer for a listbox or choice selection event
- (not valid for a deselection).
+ Returns @true if the Meta key was down at the time of the event.
*/
- wxClientData* GetClientObject() const;
+ bool MetaDown() const;
/**
- Returns extra information dependent 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 event was a middle double click.
*/
- long GetExtraLong() const;
+ bool MiddleDClick() 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.
-
- For a menu item, this method returns -1 if the item is not checkable or
- a boolean value (true or false) for checkable items indicating the new
- state of the item.
+ Returns @true if the middle mouse button changed to down.
*/
- int GetInt() const;
+ bool MiddleDown() const;
/**
- Returns item index for a listbox or choice selection event (not valid for
- a deselection).
+ Returns @true if the middle mouse button changed to up.
*/
- int GetSelection() const;
+ bool MiddleUp() const;
/**
- Returns item string for a listbox or choice selection event. If one
- or several items have been deselected, returns the index of the first
- deselected item. If some items have been selected and others deselected
- at the same time, it will return the index of the first selected item.
+ 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.
*/
- wxString GetString() const;
+ bool Moving() 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 cannot be used with wxCheckListBox currently.
+ Returns @true if the event was a right double click.
*/
- bool IsChecked() const;
+ bool RightDClick() const;
/**
- For a listbox or similar event, returns @true if it is a selection, @false
- if it is a deselection. If some items have been selected and others deselected
- at the same time, it will return @true.
+ Returns @true if the right mouse button changed to down.
*/
- bool IsSelection() const;
+ bool RightDown() const;
/**
- Sets the client data for this event.
+ Returns @true if the right mouse button changed to up.
*/
- void SetClientData(void* clientData);
+ bool RightUp() 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.
+
+/**
+ @class wxDropFilesEvent
+
+ 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 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 @c wxEVT_DROP_FILES event.
+ @endEventTable
+
+ @onlyfor{wxmsw}
+
+ @library{wxcore}
+ @category{events}
+
+ @see @ref overview_events
+*/
+class wxDropFilesEvent : public wxEvent
+{
+public:
+ /**
+ Constructor.
*/
- void SetClientObject(wxClientData* clientObject);
+ wxDropFilesEvent(wxEventType id = 0, int noFiles = 0,
+ wxString* files = NULL);
/**
- Sets the @b m_extraLong member.
+ Returns an array of filenames.
*/
- void SetExtraLong(long extraLong);
+ wxString* GetFiles() const;
/**
- Sets the @b m_commandInt member.
+ Returns the number of files dropped.
*/
- void SetInt(int intCommand);
+ int GetNumberOfFiles() const;
/**
- Sets the @b m_commandString member.
+ Returns the position at which the files were dropped.
+ Returns an array of filenames.
*/
- void SetString(const wxString& string);
+ wxPoint GetPosition() const;
};
void SetPosition(int pos);
};
+#endif // wxUSE_GUI
+
+#if wxUSE_BASE
+
+/**
+ 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 wxIdleEvent
+
+ 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, including even the hidden
+ ones because they may be shown if some condition is met from their @c
+ wxEVT_IDLE (or related @c wxEVT_UPDATE_UI) handler. The children of hidden
+ windows do not receive idle events however as they can't change their state
+ in any way noticeable by the user. Finally, the global wxApp object also
+ receives these events, as usual, so it can be used for any global idle time
+ processing.
+
+ If sending idle events to all windows is causing a significant overhead in
+ your application, you can call wxIdleEvent::SetMode with the value
+ wxIDLE_PROCESS_SPECIFIED, and set the wxWS_EX_PROCESS_IDLE extra window
+ style for every window which should receive idle events, all the other ones
+ will not receive them in this case.
+
+ @beginEventTable{wxIdleEvent}
+ @event{EVT_IDLE(func)}
+ Process a @c wxEVT_IDLE event.
+ @endEventTable
+
+ @library{wxbase}
+ @category{events}
+
+ @section sec_delayed_action Delayed Action Mechanism
+
+ wxIdleEvent can be used to perform some action "at slightly later time".
+ This can be necessary in several circumstances when, for whatever reason,
+ something can't be done in the current event handler. For example, if a
+ mouse event handler is called with the mouse button pressed, the mouse can
+ be currently captured and some operations with it -- notably capturing it
+ again -- might be impossible or lead to undesirable results. If you still
+ want to capture it, you can do it from @c wxEVT_IDLE handler when it is
+ called the next time instead of doing it immediately.
+
+ This can be achieved in two different ways: when using static event tables,
+ you will need a flag indicating to the (always connected) idle event
+ handler whether the desired action should be performed. The originally
+ called handler would then set it to indicate that it should indeed be done
+ and the idle handler itself would reset it to prevent it from doing the
+ same action again.
+
+ Using dynamically connected event handlers things are even simpler as the
+ original event handler can simply wxEvtHandler::Connect() or
+ wxEvtHandler::Bind() the idle event handler which would only be executed
+ then and could wxEvtHandler::Disconnect() or wxEvtHandler::Unbind() itself.
+
+
+ @see @ref overview_events, wxUpdateUIEvent, wxWindow::OnInternalIdle
+*/
+class wxIdleEvent : public wxEvent
+{
+public:
+ /**
+ Constructor.
+ */
+ wxIdleEvent();
+
+ /**
+ Static function returning a value specifying how wxWidgets will send idle
+ events: to all windows, or only to those which specify that they
+ will process the events.
+
+ @see SetMode().
+ */
+ static wxIdleMode GetMode();
+
+ /**
+ Returns @true if the OnIdle function processing this event requested more
+ processing time.
+
+ @see RequestMore()
+ */
+ bool MoreRequested() const;
+
+ /**
+ Tells wxWidgets that more processing is required.
+
+ This function can be called by an OnIdle handler for a window or window event
+ handler to indicate that wxApp::OnIdle should forward the OnIdle event once
+ more to the application windows.
+
+ If no window calls this function during OnIdle, then the application will
+ remain in a passive event loop (not calling OnIdle) until a new event is
+ posted to the application by the windowing system.
+
+ @see MoreRequested()
+ */
+ void RequestMore(bool needMore = true);
+
+ /**
+ 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.
+ @param mode
+ Can be one of the ::wxIdleMode values.
+ The default is wxIDLE_PROCESS_ALL.
+ */
+ static void SetMode(wxIdleMode mode);
+};
+
+#endif // wxUSE_BASE
+
+#if wxUSE_GUI
/**
@class wxInitDialogEvent
@library{wxcore}
@category{events}
- @see ::wxSetCursor, wxWindow::wxSetCursor
+ @see ::wxSetCursor, wxWindow::SetCursor
*/
class wxSetCursorEvent : public wxEvent
{
void SetCursor(const wxCursor& cursor);
};
-
+#endif // wxUSE_GUI
// ============================================================================
// Global functions/macros
/** @addtogroup group_funcmacro_events */
//@{
+#if wxUSE_BASE
+
+/**
+ A value uniquely identifying the type of the event.
+
+ The values of this type should only be created using wxNewEventType().
+
+ See the macro DEFINE_EVENT_TYPE() for more info.
+
+ @see @ref overview_events
+*/
+typedef int wxEventType;
+
+/**
+ A special event type usually used to indicate that some wxEvent has yet
+ no type assigned.
+*/
+wxEventType wxEVT_NULL;
+
+wxEventType wxEVT_ANY;
+
+/**
+ Generates a new unique event type.
+
+ Usually this function is only used by wxDEFINE_EVENT() and not called
+ directly.
+*/
+wxEventType wxNewEventType();
+
+/**
+ Define a new event type associated with the specified event class.
+
+ This macro defines a new unique event type @a name associated with the
+ event class @a cls.
+
+ For example:
+ @code
+ wxDEFINE_EVENT(MY_COMMAND_EVENT, wxCommandEvent);
+
+ class MyCustomEvent : public wxEvent { ... };
+ wxDEFINE_EVENT(MY_CUSTOM_EVENT, MyCustomEvent);
+ @endcode
+
+ @see wxDECLARE_EVENT(), @ref overview_events_custom
+ */
+#define wxDEFINE_EVENT(name, cls) \
+ const wxEventTypeTag< cls > name(wxNewEventType())
+
+/**
+ Declares a custom event type.
+
+ This macro declares a variable called @a name which must be defined
+ elsewhere using wxDEFINE_EVENT().
+
+ The class @a cls must be the wxEvent-derived class associated with the
+ events of this type and its full declaration must be visible from the point
+ of use of this macro.
+
+ For example:
+ @code
+ wxDECLARE_EVENT(MY_COMMAND_EVENT, wxCommandEvent);
+
+ class MyCustomEvent : public wxEvent { ... };
+ wxDECLARE_EVENT(MY_CUSTOM_EVENT, MyCustomEvent);
+ @endcode
+ */
+#define wxDECLARE_EVENT(name, cls) \
+ wxDECLARE_EXPORTED_EVENT(wxEMPTY_PARAMETER_VALUE, name, cls)
+
+/**
+ Variant of wxDECLARE_EVENT() used for event types defined inside a shared
+ library.
+
+ This is mostly used by wxWidgets internally, e.g.
+ @code
+ wxDECLARE_EXPORTED_EVENT(WXDLLIMPEXP_CORE, wxEVT_BUTTON, wxCommandEvent)
+ @endcode
+ */
+#define wxDECLARE_EXPORTED_EVENT( expdecl, name, cls ) \
+ extern const expdecl wxEventTypeTag< cls > name;
+
+/**
+ Helper macro for definition of custom event table macros.
+
+ This macro must only be used if wxEVENTS_COMPATIBILITY_2_8 is 1, otherwise
+ it is better and more clear to just use the address of the function
+ directly as this is all this macro does in this case. However it needs to
+ explicitly cast @a func to @a functype, which is the type of wxEvtHandler
+ member function taking the custom event argument when
+ wxEVENTS_COMPATIBILITY_2_8 is 0.
+
+ See wx__DECLARE_EVT0 for an example of use.
+
+ @see @ref overview_events_custom_ownclass
+ */
+#define wxEVENT_HANDLER_CAST(functype, func) (&func)
+
+/**
+ This macro is used to define event table macros for handling custom
+ events.
+
+ Example of use:
+ @code
+ class MyEvent : public wxEvent { ... };
+
+ // note that this is not necessary unless using old compilers: for the
+ // reasonably new ones just use &func instead of MyEventHandler(func)
+ typedef void (wxEvtHandler::*MyEventFunction)(MyEvent&);
+ #define MyEventHandler(func) wxEVENT_HANDLER_CAST(MyEventFunction, func)
+
+ wxDEFINE_EVENT(MY_EVENT_TYPE, MyEvent);
+
+ #define EVT_MY(id, func) \
+ wx__DECLARE_EVT1(MY_EVENT_TYPE, id, MyEventHandler(func))
+
+ ...
+
+ wxBEGIN_EVENT_TABLE(MyFrame, wxFrame)
+ EVT_MY(wxID_ANY, MyFrame::OnMyEvent)
+ wxEND_EVENT_TABLE()
+ @endcode
+
+ @param evt
+ The event type to handle.
+ @param id
+ The identifier of events to handle.
+ @param fn
+ The event handler method.
+ */
+#define wx__DECLARE_EVT1(evt, id, fn) \
+ wx__DECLARE_EVT2(evt, id, wxID_ANY, fn)
+
+/**
+ Generalized version of the wx__DECLARE_EVT1() macro taking a range of
+ IDs instead of a single one.
+ Argument @a id1 is the first identifier of the range, @a id2 is the
+ second identifier of the range.
+*/
+#define wx__DECLARE_EVT2(evt, id1, id2, fn) \
+ DECLARE_EVENT_TABLE_ENTRY(evt, id1, id2, fn, NULL),
+
+/**
+ Simplified version of the wx__DECLARE_EVT1() macro, to be used when the
+ event type must be handled regardless of the ID associated with the
+ specific event instances.
+*/
+#define wx__DECLARE_EVT0(evt, fn) \
+ wx__DECLARE_EVT1(evt, wxID_ANY, fn)
+
+/**
+ Use this macro inside a class declaration to declare a @e static event table
+ for that class.
+
+ In the implementation file you'll need to use the wxBEGIN_EVENT_TABLE()
+ and the wxEND_EVENT_TABLE() macros, plus some additional @c EVT_xxx macro
+ to capture events.
+
+ Note that this macro requires a final semicolon.
+
+ @see @ref overview_events_eventtables
+*/
+#define wxDECLARE_EVENT_TABLE()
+
+/**
+ Use this macro in a source file to start listing @e static event handlers
+ for a specific class.
+
+ Use wxEND_EVENT_TABLE() to terminate the event-declaration block.
+
+ @see @ref overview_events_eventtables
+*/
+#define wxBEGIN_EVENT_TABLE(theClass, baseClass)
-wxEventType wxEVT_COMMAND_BUTTON_CLICKED;
-wxEventType wxEVT_COMMAND_CHECKBOX_CLICKED;
-wxEventType wxEVT_COMMAND_CHOICE_SELECTED;
-wxEventType wxEVT_COMMAND_LISTBOX_SELECTED;
-wxEventType wxEVT_COMMAND_LISTBOX_DOUBLECLICKED;
-wxEventType wxEVT_COMMAND_CHECKLISTBOX_TOGGLED;
-wxEventType wxEVT_COMMAND_MENU_SELECTED;
-wxEventType wxEVT_COMMAND_SLIDER_UPDATED;
-wxEventType wxEVT_COMMAND_RADIOBOX_SELECTED;
-wxEventType wxEVT_COMMAND_RADIOBUTTON_SELECTED;
-wxEventType wxEVT_COMMAND_SCROLLBAR_UPDATED;
-wxEventType wxEVT_COMMAND_VLBOX_SELECTED;
-wxEventType wxEVT_COMMAND_COMBOBOX_SELECTED;
-wxEventType wxEVT_COMMAND_TOOL_RCLICKED;
-wxEventType wxEVT_COMMAND_TOOL_DROPDOWN_CLICKED;
-wxEventType wxEVT_COMMAND_TOOL_ENTER;
-wxEventType wxEVT_COMMAND_COMBOBOX_DROPDOWN;
-wxEventType wxEVT_COMMAND_COMBOBOX_CLOSEUP;
+/**
+ Use this macro in a source file to end listing @e static event handlers
+ for a specific class.
+
+ Use wxBEGIN_EVENT_TABLE() to start the event-declaration block.
+
+ @see @ref overview_events_eventtables
+*/
+#define wxEND_EVENT_TABLE()
+
+/**
+ In a GUI application, this function posts @a event to the specified @e dest
+ object using wxEvtHandler::AddPendingEvent().
+
+ Otherwise, it dispatches @a event immediately using
+ wxEvtHandler::ProcessEvent(). See the respective documentation for details
+ (and caveats). Because of limitation of wxEvtHandler::AddPendingEvent()
+ this function is not thread-safe for event objects having wxString fields,
+ use wxQueueEvent() instead.
+
+ @header{wx/event.h}
+*/
+void wxPostEvent(wxEvtHandler* dest, const wxEvent& event);
+
+/**
+ Queue an event for processing on the given object.
+
+ This is a wrapper around wxEvtHandler::QueueEvent(), see its documentation
+ for more details.
+
+ @header{wx/event.h}
+
+ @param dest
+ The object to queue the event on, can't be @c NULL.
+ @param event
+ The heap-allocated and non-@c NULL event to queue, the function takes
+ ownership of it.
+ */
+void wxQueueEvent(wxEvtHandler* dest, wxEvent *event);
+
+#endif // wxUSE_BASE
+
+#if wxUSE_GUI
+
+wxEventType wxEVT_BUTTON;
+wxEventType wxEVT_CHECKBOX;
+wxEventType wxEVT_CHOICE;
+wxEventType wxEVT_LISTBOX;
+wxEventType wxEVT_LISTBOX_DCLICK;
+wxEventType wxEVT_CHECKLISTBOX;
+wxEventType wxEVT_MENU;
+wxEventType wxEVT_SLIDER;
+wxEventType wxEVT_RADIOBOX;
+wxEventType wxEVT_RADIOBUTTON;
+wxEventType wxEVT_SCROLLBAR;
+wxEventType wxEVT_VLBOX;
+wxEventType wxEVT_COMBOBOX;
+wxEventType wxEVT_TOOL_RCLICKED;
+wxEventType wxEVT_TOOL_DROPDOWN;
+wxEventType wxEVT_TOOL_ENTER;
+wxEventType wxEVT_COMBOBOX_DROPDOWN;
+wxEventType wxEVT_COMBOBOX_CLOSEUP;
wxEventType wxEVT_THREAD;
wxEventType wxEVT_LEFT_DOWN;
wxEventType wxEVT_LEFT_UP;
wxEventType wxEVT_MOVE_START;
wxEventType wxEVT_MOVE_END;
wxEventType wxEVT_HIBERNATE;
-wxEventType wxEVT_COMMAND_TEXT_COPY;
-wxEventType wxEVT_COMMAND_TEXT_CUT;
-wxEventType wxEVT_COMMAND_TEXT_PASTE;
+wxEventType wxEVT_TEXT_COPY;
+wxEventType wxEVT_TEXT_CUT;
+wxEventType wxEVT_TEXT_PASTE;
wxEventType wxEVT_COMMAND_LEFT_CLICK;
wxEventType wxEVT_COMMAND_LEFT_DCLICK;
wxEventType wxEVT_COMMAND_RIGHT_CLICK;
wxEventType wxEVT_COMMAND_ENTER;
wxEventType wxEVT_HELP;
wxEventType wxEVT_DETAILED_HELP;
-wxEventType wxEVT_COMMAND_TEXT_UPDATED;
-wxEventType wxEVT_COMMAND_TEXT_ENTER;
-wxEventType wxEVT_COMMAND_TOOL_CLICKED;
+wxEventType wxEVT_TOOL;
wxEventType wxEVT_WINDOW_MODAL_DIALOG_CLOSED;
-
+#endif // wxUSE_GUI
//@}
projects / wxWidgets.git / blobdiff