[wxWidgets.git] / interface / wx / mousemanager.h

///////////////////////////////////////////////////////////////////////////////
// Name:        wx/mousemanager.h
// Purpose:     documentation of wxMouseEventsManager class
// Author:      Vadim Zeitlin
// Created:     2009-04-20
// RCS-ID:      $Id$
// Copyright:   (c) 2009 Vadim Zeitlin <vadim@wxwidgets.org>
// Licence:     wxWindows licence
///////////////////////////////////////////////////////////////////////////////

/**
    @class wxMouseEventsManager

    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{core}
    @category{events}
 */
class wxMouseEventsManager : public wxEvtHandler
{
public:
    /**
        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).
     */
    wxMouseEventsManager(wxWindow *win);

protected:
    /**
        Must be overridden to return the item at the given position.

        @param pos
            The position to test, in physical coordinates.
        @return
            The index of the item at the given position or wxNOT_FOUND if there
            is no item there.
     */
    virtual int MouseHitTest(const wxPoint& pos) = 0;

    /**
        Must be overridden to react to mouse clicks.

        This method is called when the user clicked (i.e. pressed and released
        mouse over the @e 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.

        @param item
            The item which was clicked.
        @return
            @true if the mouse event was processed and @false otherwise.
     */
    virtual bool MouseClicked(int item) = 0;

    /**
        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.

        @param item
            The item which is going to be dragged.
        @param pos
            The position from where it is being dragged.
        @return
            @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 bool MouseDragBegin(int item, const wxPoint& pos) = 0;

    /**
        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.

        @param item
            The item being dragged.
        @param pos
            The current position of the item.

        @see MouseDragEnd()
     */
    virtual void MouseDragging(int item, const wxPoint& pos) = 0;

    /**
        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.

        @param item
            The item which was dragged and now dropped.
        @param pos
            The position at which the item was dropped.

        @see MouseDragBegin(), MouseDragging()
     */
    virtual void MouseDragEnd(int item, const wxPoint& pos) = 0;

    /**
        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 wxMouseCaptureLostEvent
     */
    virtual void MouseDragCancelled(int item) = 0;


    /**
        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.

        @param item
            The item being pressed.
     */
    virtual void MouseClickBegin(int item);

    /**
        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 MouseDragCancelled(), wxMouseCaptureLostEvent
     */
    virtual void MouseClickCancelled(int item);
};
Commit	Line	Data
bca8c756 VZ	1	///////////////////////////////////////////////////////////////////////////////
	2	// Name: wx/mousemanager.h
	3	// Purpose: documentation of wxMouseEventsManager class
	4	// Author: Vadim Zeitlin
	5	// Created: 2009-04-20
	6	// RCS-ID: $Id$
	7	// Copyright: (c) 2009 Vadim Zeitlin <vadim@wxwidgets.org>
	8	// Licence: wxWindows licence
	9	///////////////////////////////////////////////////////////////////////////////
	10
	11	/**
	12	@class wxMouseEventsManager
	13
	14	Helper for handling mouse input events in windows containing multiple
	15	items.
	16
	17	This class handles mouse events and synthesizes high-level notifications
	18	such as clicks and drag events from low level mouse button presses and
	19	mouse movement events. It is useful because handling the mouse events is
	20	less obvious than might seem at a first glance: for example, clicks on an
	21	object should only be generated if the mouse was both pressed and released
	22	over it and not just released (so it requires storing the previous state)
	23	and dragging shouldn't start before the mouse moves away far enough.
	24
	25	This class encapsulates all these dull details for controls containing
	26	multiple items which can be identified by a positive integer index and you
	27	just need to implement its pure virtual functions to use it.
	28
	29	Notice that this class supposes that all items can be identified by an
	30	integer "index" but it doesn't need to be an ordinal index of the item
	31	(although this is the most common case) -- it can be any value which can
	32	be used to uniquely identify an item.
	33
	34	@library{core}
	35	@category{events}
	36	*/
	37	class wxMouseEventsManager : public wxEvtHandler
	38	{
	39	public:
	40	/**
	41	Constructor creates the manager for the window.
	42
	43	A mouse event manager is always associated with a window and must be
	44	destroyed by the window when it is destroyed (it doesn't need to be
	45	allocated on the heap however).
	46	*/
	47	wxMouseEventsManager(wxWindow *win);
	48
	49	protected:
	50	/**
	51	Must be overridden to return the item at the given position.
	52
	53	@param pos
	54	The position to test, in physical coordinates.
	55	@return
	56	The index of the item at the given position or wxNOT_FOUND if there
	57	is no item there.
	58	*/
	59	virtual int MouseHitTest(const wxPoint& pos) = 0;
	60
	61	/**
	62	Must be overridden to react to mouse clicks.
	63
	64	This method is called when the user clicked (i.e. pressed and released
65	mouse over the @e same item) and should normally generate a
66	notification about this click and return true if it was handled or
67	false otherwise, determining whether the original mouse event is
68	skipped or not.
69
70	@param item
71	The item which was clicked.
72	@return
73	@true if the mouse event was processed and @false otherwise.
74	*/
75	virtual bool MouseClicked(int item) = 0;
76
77	/**
78	Must be overridden to allow or deny dragging of the item.
79
80	This method is called when the user attempts to start dragging the
81	given item.
82
83	@param item
84	The item which is going to be dragged.
85	@param pos
86	The position from where it is being dragged.
87	@return
88	@true to allow the item to be dragged (in which case
89	MouseDragging() and MouseDragEnd() will be called later, unless
90	MouseDragCancelled() is called instead) or @false to forbid it.
91	*/
92	virtual bool MouseDragBegin(int item, const wxPoint& pos) = 0;
93
94	/**
95	Must be overridden to provide feed back while an item is being dragged.
96
97	This method is called while the item is being dragged and should
98	normally update the feedback shown on screen (usually this is done
99	using wxOverlay).
100
101	Notice that this method will never be called for the items for which
102	MouseDragBegin() returns @false. Consequently, if MouseDragBegin()
103	always returns @false you can do nothing in this method.
104
105	@param item
106	The item being dragged.
107	@param pos
108	The current position of the item.
109
110	@see MouseDragEnd()
111	*/
112	virtual void MouseDragging(int item, const wxPoint& pos) = 0;
113
114	/**
115	Must be overridden to handle item drop.
116
117	This method is called when the mouse is released after dragging the
118	item. Normally the item should be positioned at the new location.
119
120	@param item
121	The item which was dragged and now dropped.
122	@param pos
123	The position at which the item was dropped.
124
125	@see MouseDragBegin(), MouseDragging()
126	*/
127	virtual void MouseDragEnd(int item, const wxPoint& pos) = 0;
128
129	/**
130	Must be overridden to handle cancellation of mouse dragging.
131
132	This method is called when mouse capture is lost while dragging the
133	item and normally should remove the visual feedback drawn by
134	MouseDragging() as well as reset any internal variables set in
135	MouseDragBegin().
136
137	@see wxMouseCaptureLostEvent
138	*/
139	virtual void MouseDragCancelled(int item) = 0;
140
141
142	/**
143	May be overridden to update the state of an item when it is pressed.
144
145	This method is called when the item is becomes pressed and can be used
146	to change its appearance when this happens. It is mostly useful for
147	button-like items and doesn't need to be overridden if the items
148	shouldn't change their appearance when pressed.
149
150	@param item
151	The item being pressed.
152	*/
153	virtual void MouseClickBegin(int item);
154
155	/**
156	Must be overridden to reset the item appearance changed by
157	MouseClickBegin().
158
159	This method is called if the mouse capture was lost while the item was
160	pressed and must be overridden to restore the default item appearance
161	if it was changed in MouseClickBegin().
162
163	@see MouseDragCancelled(), wxMouseCaptureLostEvent
164	*/
165	virtual void MouseClickCancelled(int item);
166	};