Version: 3.0.2
wxMouseEventsManager Class Referenceabstract

#include <wx/mousemanager.h>

+ Inheritance diagram for wxMouseEventsManager:

Detailed Description

Helper for handling mouse input events in windows containing multiple items.

This class handles mouse events and synthesizes high-level notifications such as clicks and drag events from low level mouse button presses and mouse movement events. It is useful because handling the mouse events is less obvious than might seem at a first glance: for example, clicks on an object should only be generated if the mouse was both pressed and released over it and not just released (so it requires storing the previous state) and dragging shouldn't start before the mouse moves away far enough.

This class encapsulates all these dull details for controls containing multiple items which can be identified by a positive integer index and you just need to implement its pure virtual functions to use it.

Notice that this class supposes that all items can be identified by an integer "index" but it doesn't need to be an ordinal index of the item (although this is the most common case) – it can be any value which can be used to uniquely identify an item.

Library:  wxCore
Category:  Events

Public Member Functions

 wxMouseEventsManager ()
 Default constructor.
 
 wxMouseEventsManager (wxWindow *win)
 Constructor creates the manager for the window.
 
bool Create (wxWindow *win)
 Finishes initialization of the object created using default constructor.
 
- Public Member Functions inherited from wxEvtHandler
 wxEvtHandler ()
 Constructor.
 
virtual ~wxEvtHandler ()
 Destructor.
 
virtual void QueueEvent (wxEvent *event)
 Queue event for a later processing.
 
virtual void AddPendingEvent (const wxEvent &event)
 Post an event to be processed later.
 
template<typename T , typename T1 , ... >
void CallAfter (void(T::*method)(T1,...), T1 x1,...)
 Asynchronously call the given method.
 
template<typename T >
void CallAfter (const T &functor)
 Asynchronously call the given functor.
 
virtual bool ProcessEvent (wxEvent &event)
 Processes an event, searching event tables and calling zero or more suitable event handler function(s).
 
bool ProcessEventLocally (wxEvent &event)
 Try to process the event in this handler and all those chained to it.
 
bool SafelyProcessEvent (wxEvent &event)
 Processes an event by calling ProcessEvent() and handles any exceptions that occur in the process.
 
void ProcessPendingEvents ()
 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 wxCHECK will fail.
 
void DeletePendingEvents ()
 Deletes all events queued on this event handler using QueueEvent() or AddPendingEvent().
 
virtual bool SearchEventTable (wxEventTable &table, wxEvent &event)
 Searches the event table, executing an event handler function if an appropriate one is found.
 
void Connect (int id, int lastId, wxEventType eventType, wxObjectEventFunction function, wxObject *userData=NULL, wxEvtHandler *eventSink=NULL)
 Connects the given function dynamically with the event handler, id and event type.
 
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.
 
void Connect (wxEventType eventType, wxObjectEventFunction function, wxObject *userData=NULL, wxEvtHandler *eventSink=NULL)
 See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) overload for more info.
 
bool Disconnect (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.
 
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.
 
bool Disconnect (int id, int lastId, wxEventType eventType, wxObjectEventFunction function=NULL, wxObject *userData=NULL, wxEvtHandler *eventSink=NULL)
 See the Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*) overload for more info.
 
template<typename EventTag , typename Functor >
void Bind (const EventTag &eventType, Functor functor, int id=wxID_ANY, int lastId=wxID_ANY, wxObject *userData=NULL)
 Binds the given function, functor or method dynamically with the event.
 
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)
 See the Bind<>(const EventTag&, Functor, int, int, wxObject*) overload for more info.
 
template<typename EventTag , typename Functor >
bool Unbind (const EventTag &eventType, Functor functor, 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.
 
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)
 See the Unbind<>(const EventTag&, Functor, int, int, wxObject*) overload for more info.
 
void * GetClientData () const
 Returns user-supplied client data.
 
wxClientDataGetClientObject () const
 Returns a pointer to the user-supplied client data object.
 
void SetClientData (void *data)
 Sets user-supplied client data.
 
void SetClientObject (wxClientData *data)
 Set the client data object.
 
bool GetEvtHandlerEnabled () const
 Returns true if the event handler is enabled, false otherwise.
 
wxEvtHandlerGetNextHandler () const
 Returns the pointer to the next handler in the chain.
 
wxEvtHandlerGetPreviousHandler () const
 Returns the pointer to the previous handler in the chain.
 
void SetEvtHandlerEnabled (bool enabled)
 Enables or disables the event handler.
 
virtual void SetNextHandler (wxEvtHandler *handler)
 Sets the pointer to the next handler.
 
virtual void SetPreviousHandler (wxEvtHandler *handler)
 Sets the pointer to the previous handler.
 
void Unlink ()
 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).
 
bool IsUnlinked () const
 Returns true if the next and the previous handler pointers of this event handler instance are NULL.
 
- Public Member Functions inherited from wxObject
 wxObject ()
 Default ctor; initializes to NULL the internal reference data.
 
 wxObject (const wxObject &other)
 Copy ctor.
 
virtual ~wxObject ()
 Destructor.
 
virtual wxClassInfoGetClassInfo () const
 This virtual function is redefined for every class that requires run-time type information, when using the wxDECLARE_CLASS macro (or similar).
 
wxObjectRefDataGetRefData () const
 Returns the wxObject::m_refData pointer, i.e. the data referenced by this object.
 
bool IsKindOf (const wxClassInfo *info) const
 Determines whether this class is a subclass of (or the same class as) the given class.
 
bool IsSameAs (const wxObject &obj) const
 Returns true if this object has the same data pointer as obj.
 
void Ref (const wxObject &clone)
 Makes this object refer to the data in clone.
 
void SetRefData (wxObjectRefData *data)
 Sets the wxObject::m_refData pointer.
 
void UnRef ()
 Decrements the reference count in the associated data, and if it is zero, deletes the data.
 
void UnShare ()
 This is the same of AllocExclusive() but this method is public.
 
void operator delete (void *buf)
 The delete operator is defined for debugging versions of the library only, when the identifier WXDEBUG is defined.
 
void * operator new (size_t size, const wxString &filename=NULL, int lineNum=0)
 The new operator is defined for debugging versions of the library only, when the identifier WXDEBUG is defined.
 

Protected Member Functions

virtual int MouseHitTest (const wxPoint &pos)=0
 Must be overridden to return the item at the given position.
 
virtual bool MouseClicked (int item)=0
 Must be overridden to react to mouse clicks.
 
virtual bool MouseDragBegin (int item, const wxPoint &pos)=0
 Must be overridden to allow or deny dragging of the item.
 
virtual void MouseDragging (int item, const wxPoint &pos)=0
 Must be overridden to provide feed back while an item is being dragged.
 
virtual void MouseDragEnd (int item, const wxPoint &pos)=0
 Must be overridden to handle item drop.
 
virtual void MouseDragCancelled (int item)=0
 Must be overridden to handle cancellation of mouse dragging.
 
virtual void MouseClickBegin (int item)
 May be overridden to update the state of an item when it is pressed.
 
virtual void MouseClickCancelled (int item)
 Must be overridden to reset the item appearance changed by MouseClickBegin().
 
- Protected Member Functions inherited from wxEvtHandler
virtual bool TryBefore (wxEvent &event)
 Method called by ProcessEvent() before examining this object event tables.
 
virtual bool TryAfter (wxEvent &event)
 Method called by ProcessEvent() as last resort.
 
- Protected Member Functions inherited from wxObject
void AllocExclusive ()
 Ensure that this object's data is not shared with any other object.
 
virtual wxObjectRefDataCreateRefData () const
 Creates a new instance of the wxObjectRefData-derived class specific to this object and returns it.
 
virtual wxObjectRefDataCloneRefData (const wxObjectRefData *data) const
 Creates a new instance of the wxObjectRefData-derived class specific to this object and initializes it copying data.
 

Additional Inherited Members

- Static Public Member Functions inherited from wxEvtHandler
static void AddFilter (wxEventFilter *filter)
 Add an event filter whose FilterEvent() method will be called for each and every event processed by wxWidgets.
 
static void RemoveFilter (wxEventFilter *filter)
 Remove a filter previously installed with AddFilter().
 
- Protected Attributes inherited from wxObject
wxObjectRefDatam_refData
 Pointer to an object which is the object's reference-counted data.
 

Constructor & Destructor Documentation

wxMouseEventsManager::wxMouseEventsManager ( )

Default constructor.

You must call Create() to finish initializing the mouse events manager. If possible, avoid the use of this constructor in favour of the other one which fully initializes the mouse events manager immediately.

wxMouseEventsManager::wxMouseEventsManager ( wxWindow win)

Constructor creates the manager for the window.

A mouse event manager is always associated with a window and must be destroyed by the window when it is destroyed (it doesn't need to be allocated on the heap however).

Member Function Documentation

bool wxMouseEventsManager::Create ( wxWindow win)

Finishes initialization of the object created using default constructor.

Currently always returns true.

virtual void wxMouseEventsManager::MouseClickBegin ( int  item)
protectedvirtual

May be overridden to update the state of an item when it is pressed.

This method is called when the item is becomes pressed and can be used to change its appearance when this happens. It is mostly useful for button-like items and doesn't need to be overridden if the items shouldn't change their appearance when pressed.

Parameters
itemThe item being pressed.
virtual void wxMouseEventsManager::MouseClickCancelled ( int  item)
protectedvirtual

Must be overridden to reset the item appearance changed by MouseClickBegin().

This method is called if the mouse capture was lost while the item was pressed and must be overridden to restore the default item appearance if it was changed in MouseClickBegin().

See Also
MouseDragCancelled(), wxMouseCaptureLostEvent
virtual bool wxMouseEventsManager::MouseClicked ( int  item)
protectedpure virtual

Must be overridden to react to mouse clicks.

This method is called when the user clicked (i.e. pressed and released mouse over the same item) and should normally generate a notification about this click and return true if it was handled or false otherwise, determining whether the original mouse event is skipped or not.

Parameters
itemThe item which was clicked.
Returns
true if the mouse event was processed and false otherwise.
virtual bool wxMouseEventsManager::MouseDragBegin ( int  item,
const wxPoint pos 
)
protectedpure virtual

Must be overridden to allow or deny dragging of the item.

This method is called when the user attempts to start dragging the given item.

Parameters
itemThe item which is going to be dragged.
posThe position from where it is being dragged.
Returns
true to allow the item to be dragged (in which case MouseDragging() and MouseDragEnd() will be called later, unless MouseDragCancelled() is called instead) or false to forbid it.
virtual void wxMouseEventsManager::MouseDragCancelled ( int  item)
protectedpure virtual

Must be overridden to handle cancellation of mouse dragging.

This method is called when mouse capture is lost while dragging the item and normally should remove the visual feedback drawn by MouseDragging() as well as reset any internal variables set in MouseDragBegin().

See Also
wxMouseCaptureLostEvent
virtual void wxMouseEventsManager::MouseDragEnd ( int  item,
const wxPoint pos 
)
protectedpure virtual

Must be overridden to handle item drop.

This method is called when the mouse is released after dragging the item. Normally the item should be positioned at the new location.

Parameters
itemThe item which was dragged and now dropped.
posThe position at which the item was dropped.
See Also
MouseDragBegin(), MouseDragging()
virtual void wxMouseEventsManager::MouseDragging ( int  item,
const wxPoint pos 
)
protectedpure virtual

Must be overridden to provide feed back while an item is being dragged.

This method is called while the item is being dragged and should normally update the feedback shown on screen (usually this is done using wxOverlay).

Notice that this method will never be called for the items for which MouseDragBegin() returns false. Consequently, if MouseDragBegin() always returns false you can do nothing in this method.

Parameters
itemThe item being dragged.
posThe current position of the item.
See Also
MouseDragEnd()
virtual int wxMouseEventsManager::MouseHitTest ( const wxPoint pos)
protectedpure virtual

Must be overridden to return the item at the given position.

Parameters
posThe position to test, in physical coordinates.
Returns
The index of the item at the given position or wxNOT_FOUND if there is no item there.