X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/5de76427c87d8289f5c343cef16e9375056fc49f..43e995b6e39d41fd8a26f8bb9e6a6ef54bbcd324:/docs/latex/wx/mouseevt.tex?ds=sidebyside diff --git a/docs/latex/wx/mouseevt.tex b/docs/latex/wx/mouseevt.tex index a116241989..f8ccc69ed6 100644 --- a/docs/latex/wx/mouseevt.tex +++ b/docs/latex/wx/mouseevt.tex @@ -1,12 +1,42 @@ \section{\class{wxMouseEvent}}\label{wxmouseevent} -This event class contains information about mouse events. -See \helpref{wxWindow::OnMouseEvent}{wxwindowonmouseevent}. +This event class contains information about the events generated by the mouse: +they include mouse buttons press and release events and mouse move events. + +All mouse events involving the buttons use {\tt wxMOUSE\_BTN\_LEFT} for the +left mouse button, {\tt wxMOUSE\_BTN\_MIDDLE} for the middle one and +{\tt wxMOUSE\_BTN\_RIGHT} for the right one. Note that not all mice have a +middle button so a portable application should avoid relying on the events from +it. + +{\bf NB:} Note that under Windows CE mouse enter and leave events are not natively supported +by the system but are generated by wxWidgets itself. This has several +drawbacks: the LEAVE\_WINDOW event might be received some time after the mouse +left the window and the state variables for it may have changed during this +time. + +{\bf NB:} Note the difference between methods like +\helpref{LeftDown}{wxmouseeventleftdown} and +\helpref{LeftIsDown}{wxmouseeventleftisdown}: the former returns {\tt true} +when the event corresponds to the left mouse button click while the latter +returns {\tt true} if the left mouse button is currently being pressed. For +example, when the user is dragging the mouse you can use +\helpref{LeftIsDown}{wxmouseeventleftisdown} to test +whether the left mouse button is (still) depressed. Also, by convention, if +\helpref{LeftDown}{wxmouseeventleftdown} returns {\tt true}, +\helpref{LeftIsDown}{wxmouseeventleftisdown} will also return {\tt true} in +wxWidgets whatever the underlying GUI behaviour is (which is +platform-dependent). The same applies, of course, to other mouse buttons as +well. \wxheading{Derived from} \helpref{wxEvent}{wxevent} +\wxheading{Include files} + + + \wxheading{Event table macros} To process a mouse event, use these event handler macros to direct input to member @@ -14,7 +44,10 @@ functions that take a wxMouseEvent argument. \twocolwidtha{7cm} \begin{twocollist}\itemsep=0pt -\twocolitem{{\bf EVT\_LEFT\_DOWN(func)}}{Process a wxEVT\_LEFT\_DOWN event.} +\twocolitem{{\bf EVT\_LEFT\_DOWN(func)}}{Process a wxEVT\_LEFT\_DOWN event. The +handler of this event should normally call \helpref{event.Skip()}{wxeventskip} to +allow the default processing to take place as otherwise the window under mouse +wouldn't get the focus.} \twocolitem{{\bf EVT\_LEFT\_UP(func)}}{Process a wxEVT\_LEFT\_UP event.} \twocolitem{{\bf EVT\_LEFT\_DCLICK(func)}}{Process a wxEVT\_LEFT\_DCLICK event.} \twocolitem{{\bf EVT\_MIDDLE\_DOWN(func)}}{Process a wxEVT\_MIDDLE\_DOWN event.} @@ -26,74 +59,102 @@ functions that take a wxMouseEvent argument. \twocolitem{{\bf EVT\_MOTION(func)}}{Process a wxEVT\_MOTION event.} \twocolitem{{\bf EVT\_ENTER\_WINDOW(func)}}{Process a wxEVT\_ENTER\_WINDOW event.} \twocolitem{{\bf EVT\_LEAVE\_WINDOW(func)}}{Process a wxEVT\_LEAVE\_WINDOW event.} +\twocolitem{{\bf EVT\_MOUSEWHEEL(func)}}{Process a wxEVT\_MOUSEWHEEL event.} \twocolitem{{\bf EVT\_MOUSE\_EVENTS(func)}}{Process all mouse events.} \end{twocollist}% \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxMouseEvent::m\_altDown} + +\membersection{wxMouseEvent::m\_altDown}\label{wxmouseeventmaltdown} \member{bool}{m\_altDown} -TRUE if the Alt key is pressed down. +true if the Alt key is pressed down. -\membersection{wxMouseEvent::m\_controlDown} + +\membersection{wxMouseEvent::m\_controlDown}\label{wxmouseeventmcontroldown} \member{bool}{m\_controlDown} -TRUE if control key is pressed down. +true if control key is pressed down. + -\membersection{wxMouseEvent::m\_leftDown} +\membersection{wxMouseEvent::m\_leftDown}\label{wxmouseeventmleftdown} \member{bool}{m\_leftDown} -TRUE if the left mouse button is currently pressed down. +true if the left mouse button is currently pressed down. -\membersection{wxMouseEvent::m\_middleDown} -\member{bool}{m\_middleDown} +\membersection{wxMouseEvent::m\_middleDown}\label{wxmouseeventmmiddledown} -TRUE if the middle mouse button is currently pressed down. +\member{bool}{m\_middleDown} -\membersection{wxMouseEvent::m\_rightDown} +true if the middle mouse button is currently pressed down. -\member{bool}{m\_rightDown} -TRUE if the right mouse button is currently pressed down. +\membersection{wxMouseEvent::m\_rightDown}\label{wxmouseeventmrightdown} -\membersection{wxMouseEvent::m\_leftDown} +\member{bool}{m\_rightDown} -\member{bool}{m\_leftDown} +true if the right mouse button is currently pressed down. -TRUE if the left mouse button is currently pressed down. -\membersection{wxMouseEvent::m\_metaDown} +\membersection{wxMouseEvent::m\_metaDown}\label{wxmouseeventmmetadown} \member{bool}{m\_metaDown} -TRUE if the Meta key is pressed down. +true if the Meta key is pressed down. + -\membersection{wxMouseEvent::m\_shiftDown} +\membersection{wxMouseEvent::m\_shiftDown}\label{wxmouseeventmshiftdown} \member{bool}{m\_shiftDown} -TRUE if shift is pressed down. +true if shift is pressed down. + -\membersection{wxMouseEvent::m\_x} +\membersection{wxMouseEvent::m\_x}\label{wxmouseeventmx} -\member{float}{m\_x} +\member{long}{m\_x} X-coordinate of the event. -\membersection{wxMouseEvent::m\_y} -\member{float}{m\_y} +\membersection{wxMouseEvent::m\_y}\label{wxmouseeventmy} + +\member{long}{m\_y} Y-coordinate of the event. -\membersection{wxMouseEvent::wxMouseEvent} -\func{}{wxMouseEvent}{\param{WXTYPE}{ mouseEventType = 0}, \param{int}{ id = 0}} +\membersection{wxMouseEvent::m\_wheelRotation}\label{wxmouseeventmwheelrotation} + +\member{int}{m\_wheelRotation} + +The distance the mouse wheel is rotated. + + +\membersection{wxMouseEvent::m\_wheelDelta}\label{wxmouseeventmwheeldelta} + +\member{int}{m\_wheelDelta} + +The wheel delta, normally $120$. + + +\membersection{wxMouseEvent::m\_linesPerAction}\label{wxmouseeventmlinesperaction} + +\member{int}{m\_linesPerAction} + +The configured number of lines (or whatever) to be scrolled per wheel +action. + + + +\membersection{wxMouseEvent::wxMouseEvent}\label{wxmouseeventctor} + +\func{}{wxMouseEvent}{\param{WXTYPE}{ mouseEventType = 0}} Constructor. Valid event types are: @@ -111,217 +172,325 @@ Constructor. Valid event types are: \item {\bf wxEVT\_RIGHT\_UP} \item {\bf wxEVT\_RIGHT\_DCLICK} \item {\bf wxEVT\_MOTION} +\item {\bf wxEVT\_MOUSEWHEEL} \end{itemize} -\membersection{wxMouseEvent::AltDown} + +\membersection{wxMouseEvent::AltDown}\label{wxmouseeventaltdown} \func{bool}{AltDown}{\void} -Returns TRUE if the Alt key was down at the time of the event. +Returns true if the Alt key was down at the time of the event. + -\membersection{wxMouseEvent::Button} +\membersection{wxMouseEvent::Button}\label{wxmouseeventbutton} \func{bool}{Button}{\param{int}{ button}} -Returns TRUE if the identified mouse button is changing state. Valid -values of {\it button} are 1, 2 or 3 for left, middle and right -buttons respectively. +Returns true if the identified mouse button is changing state. Valid +values of {\it button} are: + +\begin{twocollist}\itemsep=0pt +\twocolitem{{\tt wxMOUSE\_BTN\_LEFT}}{check if left button was pressed} +\twocolitem{{\tt wxMOUSE\_BTN\_MIDDLE}}{check if middle button was pressed} +\twocolitem{{\tt wxMOUSE\_BTN\_RIGHT}}{check if right button was pressed} +\twocolitem{{\tt wxMOUSE\_BTN\_ANY}}{check if any button was pressed} +\end{twocollist} -Not all mice have middle buttons so a portable application should avoid -this one. -\membersection{wxMouseEvent::ButtonDClick}\label{buttondclick} +\membersection{wxMouseEvent::ButtonDClick}\label{wxmouseeventbuttondclick} -\func{bool}{ButtonDClick}{\param{int}{ but = -1}} +\func{bool}{ButtonDClick}{\param{int}{ but = wxMOUSE\_BTN\_ANY}} -If the argument is omitted, this returns TRUE if the event was a mouse +If the argument is omitted, this returns true if the event was a mouse double click event. Otherwise the argument specifies which double click event -was generated (1, 2 or 3 for left, middle and right buttons respectively). +was generated (see \helpref{Button}{wxmouseeventbutton} for the possible +values). + -\membersection{wxMouseEvent::ButtonDown} +\membersection{wxMouseEvent::ButtonDown}\label{wxmouseeventbuttondown} \func{bool}{ButtonDown}{\param{int}{ but = -1}} -If the argument is omitted, this returns TRUE if the event was a mouse +If the argument is omitted, this returns true if the event was a mouse button down event. Otherwise the argument specifies which button-down event -was generated (1, 2 or 3 for left, middle and right buttons respectively). +was generated (see \helpref{Button}{wxmouseeventbutton} for the possible +values). + -\membersection{wxMouseEvent::ButtonUp} + +\membersection{wxMouseEvent::ButtonUp}\label{wxmouseeventbuttonup} \func{bool}{ButtonUp}{\param{int}{ but = -1}} -If the argument is omitted, this returns TRUE if the event was a mouse +If the argument is omitted, this returns true if the event was a mouse button up event. Otherwise the argument specifies which button-up event -was generated (1, 2 or 3 for left, middle and right buttons respectively). +was generated (see \helpref{Button}{wxmouseeventbutton} for the possible +values). + + -\membersection{wxMouseEvent::ControlDown} +\membersection{wxMouseEvent::CmdDown}\label{wxmouseeventcmddown} + +\constfunc{bool}{CmdDown}{\void} + +Same as \helpref{MetaDown}{wxmouseeventmetadown} under Mac, same as +\helpref{ControlDown}{wxmouseeventcontroldown} elsewhere. + +\wxheading{See also} + +\helpref{wxKeyEvent::CmdDown}{wxkeyeventcmddown} + + +\membersection{wxMouseEvent::ControlDown}\label{wxmouseeventcontroldown} \func{bool}{ControlDown}{\void} -Returns TRUE if the control key was down at the time of the event. +Returns true if the control key was down at the time of the event. -\membersection{wxMouseEvent::Dragging} + +\membersection{wxMouseEvent::Dragging}\label{wxmouseeventdragging} \func{bool}{Dragging}{\void} -Returns TRUE if this was a dragging event (motion while a button is depressed). +Returns true if this was a dragging event (motion while a button is depressed). + +\wxheading{See also} + +\helpref{Moving}{wxmouseeventmoving} + \membersection{wxMouseEvent::Entering}\label{wxmouseevententering} \func{bool}{Entering}{\void} -Returns TRUE if the mouse was entering the window (MS Windows and Motif). +Returns true if the mouse was entering the window. See also \helpref{wxMouseEvent::Leaving}{wxmouseeventleaving}. + +\membersection{wxMouseEvent::GetButton}\label{wxmouseeventgetbutton} + +\constfunc{int}{GetButton}{\void} + +Returns the mouse button which generated this event or {\tt wxMOUSE\_BTN\_NONE} +if no button is involved (for mouse move, enter or leave event, for example). +Otherwise {\tt wxMOUSE\_BTN\_LEFT} is returned for the left button down, up and +double click events, {\tt wxMOUSE\_BTN\_MIDDLE} and {\tt wxMOUSE\_BTN\_RIGHT} +for the same events for the middle and the right buttons respectively. + + +\membersection{wxMouseEvent::GetPosition}\label{wxmouseeventgetposition} + +\constfunc{wxPoint}{GetPosition}{\void} + +\constfunc{void}{GetPosition}{\param{wxCoord*}{ x}, \param{wxCoord*}{ y}} + +\constfunc{void}{GetPosition}{\param{long*}{ x}, \param{long*}{ y}} + +Sets *x and *y to the position at which the event occurred. + +Returns the physical mouse position in pixels. + +Note that if the mouse event has been artificially generated from a special +keyboard combination (e.g. under Windows when the ``menu'' key is pressed), the +returned position is \texttt{wxDefaultPosition}. + + +\membersection{wxMouseEvent::GetLogicalPosition}\label{wxmouseeventgetlogicalposition} + +\constfunc{wxPoint}{GetLogicalPosition}{\param{const wxDC\&}{ dc}} + +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). + + + +\membersection{wxMouseEvent::GetLinesPerAction}\label{wxmouseeventgetlinesperaction} + +\constfunc{int}{GetLinesPerAction}{\void} + +Returns the configured number of lines (or whatever) to be scrolled per +wheel action. Defaults to three. + + +\membersection{wxMouseEvent::GetWheelRotation}\label{wxmouseeventgetwheelrotation} + +\constfunc{int}{GetWheelRotation}{\void} + +Get wheel rotation, positive or negative indicates direction of +rotation. Current devices all send an event when rotation is equal to ++/-WheelDelta, but this allows for finer resolution devices to be +created in the future. Because of this you shouldn't assume that one +event is equal to 1 line or whatever, but you should be able to either +do partial line scrolling or wait until +/-WheelDelta rotation values +have been accumulated before scrolling. + + +\membersection{wxMouseEvent::GetWheelDelta}\label{wxmouseeventgetwheeldelta} + +\constfunc{int}{GetWheelDelta}{\void} + +Get wheel delta, normally $120$. This is the threshold for action to be +taken, and one such action (for example, scrolling one increment) +should occur for each delta. + + \membersection{wxMouseEvent::GetX}\label{wxmouseeventgetx} -\func{float}{GetX}{\void} +\constfunc{long}{GetX}{\void} + +Returns X coordinate of the physical mouse event position. -Returns X coordinate of the mouse event position. \membersection{wxMouseEvent::GetY}\label{wxmouseeventgety} -\func{float}{GetY}{\void} +\func{long}{GetY}{\void} + +Returns Y coordinate of the physical mouse event position. -Returns Y coordinate of the mouse event position. -\membersection{wxMouseEvent::IsButton} +\membersection{wxMouseEvent::IsButton}\label{wxmouseeventisbutton} -\func{bool}{IsButton}{\void} +\constfunc{bool}{IsButton}{\void} -Returns TRUE if the event was a mouse button event (not necessarily a button down event - +Returns true if the event was a mouse button event (not necessarily a button down event - that may be tested using {\it ButtonDown}). + +\membersection{wxMouseEvent::IsPageScroll}\label{wxmouseeventispagescroll} + +\constfunc{bool}{IsPageScroll}{\void} + +Returns true if the system has been setup to do page scrolling with +the mouse wheel instead of line scrolling. + + \membersection{wxMouseEvent::Leaving}\label{wxmouseeventleaving} -\func{bool}{Leaving}{\void} +\constfunc{bool}{Leaving}{\void} -Returns TRUE if the mouse was leaving the window (MS Windows and Motif). +Returns true if the mouse was leaving the window. See also \helpref{wxMouseEvent::Entering}{wxmouseevententering}. -\membersection{wxMouseEvent::LeftDClick} -\func{bool}{LeftDClick}{\void} +\membersection{wxMouseEvent::LeftDClick}\label{wxmouseeventleftdclick} + +\constfunc{bool}{LeftDClick}{\void} -Returns TRUE if the event was a left double click. +Returns true if the event was a left double click. -\membersection{wxMouseEvent::LeftDown} -\func{bool}{LeftDown}{\void} +\membersection{wxMouseEvent::LeftDown}\label{wxmouseeventleftdown} -Returns TRUE if the left mouse button changed to down. +\constfunc{bool}{LeftDown}{\void} -\membersection{wxMouseEvent::LeftIsDown} +Returns true if the left mouse button changed to down. -\func{bool}{LeftIsDown}{\void} -Returns TRUE if the left mouse button is currently down, independent +\membersection{wxMouseEvent::LeftIsDown}\label{wxmouseeventleftisdown} + +\constfunc{bool}{LeftIsDown}{\void} + +Returns true if the left mouse button is currently down, independent of the current event type. -\membersection{wxMouseEvent::LeftUp} +Please notice that it is \emph{not} the same as +\helpref{LeftDown}{wxmouseeventleftdown} which returns \true if the event was +generated by the left mouse button being pressed. Rather, it simply describes +the state of the left mouse button at the time when the event was generated +(so while it will be true for a left click event, it can also be true for +a right click if it happened while the left mouse button was pressed). -\func{bool}{LeftUp}{\void} +This event is usually used in the mouse event handlers which process "move +mouse" messages to determine whether the user is (still) dragging the mouse. -Returns TRUE if the left mouse button changed to up. -\membersection{wxMouseEvent::MetaDown} +\membersection{wxMouseEvent::LeftUp}\label{wxmouseeventleftup} -\func{bool}{MetaDown}{\void} +\constfunc{bool}{LeftUp}{\void} -Returns TRUE if the Meta key was down at the time of the event. +Returns true if the left mouse button changed to up. -\membersection{wxMouseEvent::MiddleDClick} -\func{bool}{MiddleDClick}{\void} +\membersection{wxMouseEvent::MetaDown}\label{wxmouseeventmetadown} -Returns TRUE if the event was a middle double click. +\constfunc{bool}{MetaDown}{\void} -\membersection{wxMouseEvent::MiddleDown} +Returns true if the Meta key was down at the time of the event. -\func{bool}{MiddleDown}{\void} -Returns TRUE if the middle mouse button changed to down. +\membersection{wxMouseEvent::MiddleDClick}\label{wxmouseeventmiddledclick} -\membersection{wxMouseEvent::MiddleIsDown} +\constfunc{bool}{MiddleDClick}{\void} -\func{bool}{MiddleIsDown}{\void} +Returns true if the event was a middle double click. -Returns TRUE if the middle mouse button is currently down, independent -of the current event type. -\membersection{wxMouseEvent::MiddleUp} +\membersection{wxMouseEvent::MiddleDown}\label{wxmouseeventmiddledown} + +\constfunc{bool}{MiddleDown}{\void} + +Returns true if the middle mouse button changed to down. + -\func{bool}{MiddleUp}{\void} +\membersection{wxMouseEvent::MiddleIsDown}\label{wxmouseeventmiddleisdown} -Returns TRUE if the middle mouse button changed to up. +\constfunc{bool}{MiddleIsDown}{\void} -\membersection{wxMouseEvent::Moving} +Returns true if the middle mouse button is currently down, independent +of the current event type. + + +\membersection{wxMouseEvent::MiddleUp}\label{wxmouseeventmiddleup} -\func{bool}{Moving}{\void} +\constfunc{bool}{MiddleUp}{\void} -Returns TRUE if this was a motion event (no buttons depressed). +Returns true if the middle mouse button changed to up. -\membersection{wxMouseEvent::Position} -\func{void}{Position}{\param{float *}{x}, \param{float *}{y}} +\membersection{wxMouseEvent::Moving}\label{wxmouseeventmoving} -Sets *x and *y to the position at which the event occurred. If the -window is a window, the position is converted to logical units -(according to the current mapping mode) with scrolling taken into -account. To get back to device units (for example to calculate where on the -screen to place a dialog box associated with a window mouse event), use -\rtfsp{\bf wxDC::LogicalToDeviceX} and {\bf wxDC::LogicalToDeviceY}. +\constfunc{bool}{Moving}{\void} -For example, the following code calculates screen pixel coordinates -from the frame position, window view start (assuming the window is the only -subwindow on the frame and therefore at the top left of it), and the -logical event position. A menu is popped up at the position where the -mouse click occurred. (Note that the application should also check that -the dialog box will be visible on the screen, since the click could have -occurred near the screen edge!) +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 +\helpref{Dragging}{wxmouseeventdragging} returns \true. -\begin{verbatim} - float event_x, event_y; - event.Position(&event_x, &event_y); - frame->GetPosition(&x, &y); - window->ViewStart(&x1, &y1); - int mouse_x = (int)(window->GetDC()->LogicalToDeviceX(event_x + x - x1); - int mouse_y = (int)(window->GetDC()->LogicalToDeviceY(event_y + y - y1); - char *choice = wxGetSingleChoice("Menu", "Pick a node action", - no_choices, choices, frame, mouse_x, mouse_y); -\end{verbatim} +\membersection{wxMouseEvent::RightDClick}\label{wxmouseeventrightdclick} -\membersection{wxMouseEvent::RightDClick} +\constfunc{bool}{RightDClick}{\void} -\func{bool}{RightDClick}{\void} +Returns true if the event was a right double click. -Returns TRUE if the event was a right double click. -\membersection{wxMouseEvent::RightDown} +\membersection{wxMouseEvent::RightDown}\label{wxmouseeventrightdown} -\func{bool}{RightDown}{\void} +\constfunc{bool}{RightDown}{\void} -Returns TRUE if the right mouse button changed to down. +Returns true if the right mouse button changed to down. -\membersection{wxMouseEvent::RightIsDown} -\func{bool}{RightIsDown}{\void} +\membersection{wxMouseEvent::RightIsDown}\label{wxmouseeventrightisdown} -Returns TRUE if the right mouse button is currently down, independent +\constfunc{bool}{RightIsDown}{\void} + +Returns true if the right mouse button is currently down, independent of the current event type. -\membersection{wxMouseEvent::RightUp} -\func{bool}{RightUp}{\void} +\membersection{wxMouseEvent::RightUp}\label{wxmouseeventrightup} + +\constfunc{bool}{RightUp}{\void} + +Returns true if the right mouse button changed to up. -Returns TRUE if the right mouse button changed to up. -\membersection{wxMouseEvent::ShiftDown} +\membersection{wxMouseEvent::ShiftDown}\label{wxmouseeventshiftdown} -\func{bool}{ShiftDown}{\void} +\constfunc{bool}{ShiftDown}{\void} -Returns TRUE if the shift key was down at the time of the event. +Returns true if the shift key was down at the time of the event.