Audio plugin host https://kx.studio/carla
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

juce_MouseEvent.h 16KB

9 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
10 years ago
10 years ago
10 years ago
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380
  1. /*
  2. ==============================================================================
  3. This file is part of the JUCE library.
  4. Copyright (c) 2015 - ROLI Ltd.
  5. Permission is granted to use this software under the terms of either:
  6. a) the GPL v2 (or any later version)
  7. b) the Affero GPL v3
  8. Details of these licenses can be found at: www.gnu.org/licenses
  9. JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  10. WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  11. A PARTICULAR PURPOSE. See the GNU General Public License for more details.
  12. ------------------------------------------------------------------------------
  13. To release a closed-source product which uses JUCE, commercial licenses are
  14. available: visit www.juce.com for more information.
  15. ==============================================================================
  16. */
  17. #ifndef JUCE_MOUSEEVENT_H_INCLUDED
  18. #define JUCE_MOUSEEVENT_H_INCLUDED
  19. //==============================================================================
  20. /**
  21. Contains position and status information about a mouse event.
  22. @see MouseListener, Component::mouseMove, Component::mouseEnter, Component::mouseExit,
  23. Component::mouseDown, Component::mouseUp, Component::mouseDrag
  24. */
  25. class JUCE_API MouseEvent
  26. {
  27. public:
  28. //==============================================================================
  29. /** Creates a MouseEvent.
  30. Normally an application will never need to use this.
  31. @param source the source that's invoking the event
  32. @param position the position of the mouse, relative to the component that is passed-in
  33. @param modifiers the key modifiers at the time of the event
  34. @param pressure the pressure of the touch or stylus, in the range 0 to 1. Devices that
  35. do not support force information may return 0.0, 1.0, or a negative value,
  36. depending on the platform
  37. @param eventComponent the component that the mouse event applies to
  38. @param originator the component that originally received the event
  39. @param eventTime the time the event happened
  40. @param mouseDownPos the position of the corresponding mouse-down event (relative to the component that is passed-in).
  41. If there isn't a corresponding mouse-down (e.g. for a mouse-move), this will just be
  42. the same as the current mouse-x position.
  43. @param mouseDownTime the time at which the corresponding mouse-down event happened
  44. If there isn't a corresponding mouse-down (e.g. for a mouse-move), this will just be
  45. the same as the current mouse-event time.
  46. @param numberOfClicks how many clicks, e.g. a double-click event will be 2, a triple-click will be 3, etc
  47. @param mouseWasDragged whether the mouse has been dragged significantly since the previous mouse-down
  48. */
  49. MouseEvent (MouseInputSource source,
  50. Point<float> position,
  51. ModifierKeys modifiers,
  52. float pressure,
  53. Component* eventComponent,
  54. Component* originator,
  55. Time eventTime,
  56. Point<float> mouseDownPos,
  57. Time mouseDownTime,
  58. int numberOfClicks,
  59. bool mouseWasDragged) noexcept;
  60. /** Destructor. */
  61. ~MouseEvent() noexcept;
  62. //==============================================================================
  63. /** The position of the mouse when the event occurred.
  64. This value is relative to the top-left of the component to which the
  65. event applies (as indicated by the MouseEvent::eventComponent field).
  66. This is a more accurate floating-point version of the position returned by
  67. getPosition() and the integer x and y member variables.
  68. */
  69. const Point<float> position;
  70. /** The x-position of the mouse when the event occurred.
  71. This value is relative to the top-left of the component to which the
  72. event applies (as indicated by the MouseEvent::eventComponent field).
  73. For a floating-point coordinate, see MouseEvent::position
  74. */
  75. const int x;
  76. /** The y-position of the mouse when the event occurred.
  77. This value is relative to the top-left of the component to which the
  78. event applies (as indicated by the MouseEvent::eventComponent field).
  79. For a floating-point coordinate, see MouseEvent::position
  80. */
  81. const int y;
  82. /** The key modifiers associated with the event.
  83. This will let you find out which mouse buttons were down, as well as which
  84. modifier keys were held down.
  85. When used for mouse-up events, this will indicate the state of the mouse buttons
  86. just before they were released, so that you can tell which button they let go of.
  87. */
  88. const ModifierKeys mods;
  89. /** The pressure of the touch or stylus for this event.
  90. The range is 0 (soft) to 1 (hard).
  91. If the input device doesn't provide any pressure data, it may return a negative
  92. value here, or 0.0 or 1.0, depending on the platform.
  93. */
  94. float pressure;
  95. /** The component that this event applies to.
  96. This is usually the component that the mouse was over at the time, but for mouse-drag
  97. events the mouse could actually be over a different component and the events are
  98. still sent to the component that the button was originally pressed on.
  99. The x and y member variables are relative to this component's position.
  100. If you use getEventRelativeTo() to retarget this object to be relative to a different
  101. component, this pointer will be updated, but originalComponent remains unchanged.
  102. @see originalComponent
  103. */
  104. Component* const eventComponent;
  105. /** The component that the event first occurred on.
  106. If you use getEventRelativeTo() to retarget this object to be relative to a different
  107. component, this value remains unchanged to indicate the first component that received it.
  108. @see eventComponent
  109. */
  110. Component* const originalComponent;
  111. /** The time that this mouse-event occurred. */
  112. const Time eventTime;
  113. /** The time that the corresponding mouse-down event occurred. */
  114. const Time mouseDownTime;
  115. /** The source device that generated this event. */
  116. MouseInputSource source;
  117. //==============================================================================
  118. /** Returns the x coordinate of the last place that a mouse was pressed.
  119. The coordinate is relative to the component specified in MouseEvent::component.
  120. @see getDistanceFromDragStart, getDistanceFromDragStartX, mouseWasDraggedSinceMouseDown
  121. */
  122. int getMouseDownX() const noexcept;
  123. /** Returns the y coordinate of the last place that a mouse was pressed.
  124. The coordinate is relative to the component specified in MouseEvent::component.
  125. @see getDistanceFromDragStart, getDistanceFromDragStartX, mouseWasDraggedSinceMouseDown
  126. */
  127. int getMouseDownY() const noexcept;
  128. /** Returns the coordinates of the last place that a mouse was pressed.
  129. The coordinates are relative to the component specified in MouseEvent::component.
  130. @see getDistanceFromDragStart, getDistanceFromDragStartX, mouseWasDraggedSinceMouseDown
  131. */
  132. Point<int> getMouseDownPosition() const noexcept;
  133. /** Returns the straight-line distance between where the mouse is now and where it
  134. was the last time the button was pressed.
  135. This is quite handy for things like deciding whether the user has moved far enough
  136. for it to be considered a drag operation.
  137. @see getDistanceFromDragStartX
  138. */
  139. int getDistanceFromDragStart() const noexcept;
  140. /** Returns the difference between the mouse's current x postion and where it was
  141. when the button was last pressed.
  142. @see getDistanceFromDragStart
  143. */
  144. int getDistanceFromDragStartX() const noexcept;
  145. /** Returns the difference between the mouse's current y postion and where it was
  146. when the button was last pressed.
  147. @see getDistanceFromDragStart
  148. */
  149. int getDistanceFromDragStartY() const noexcept;
  150. /** Returns the difference between the mouse's current postion and where it was
  151. when the button was last pressed.
  152. @see getDistanceFromDragStart
  153. */
  154. Point<int> getOffsetFromDragStart() const noexcept;
  155. /** Returns true if the user seems to be performing a drag gesture.
  156. This is only meaningful if called in either a mouseUp() or mouseDrag() method.
  157. It will return true if the user has dragged the mouse more than a few pixels
  158. from the place where the mouse-down occurred.
  159. Once they have dragged it far enough for this method to return true, it will continue
  160. to return true until the mouse-up, even if they move the mouse back to the same
  161. location at which the mouse-down happened. This means that it's very handy for
  162. objects that can either be clicked on or dragged, as you can use it in the mouseDrag()
  163. callback to ignore small movements they might make while trying to click.
  164. */
  165. bool mouseWasDraggedSinceMouseDown() const noexcept;
  166. /** Returns true if the mouse event is part of a click gesture rather than a drag.
  167. This is effectively the opposite of mouseWasDraggedSinceMouseDown()
  168. */
  169. bool mouseWasClicked() const noexcept;
  170. /** For a click event, the number of times the mouse was clicked in succession.
  171. So for example a double-click event will return 2, a triple-click 3, etc.
  172. */
  173. int getNumberOfClicks() const noexcept { return numberOfClicks; }
  174. /** Returns the time that the mouse button has been held down for.
  175. If called from a mouseDrag or mouseUp callback, this will return the
  176. number of milliseconds since the corresponding mouseDown event occurred.
  177. If called in other contexts, e.g. a mouseMove, then the returned value
  178. may be 0 or an undefined value.
  179. */
  180. int getLengthOfMousePress() const noexcept;
  181. /** Returns true if the pressure value for this event is meaningful. */
  182. bool isPressureValid() const noexcept;
  183. //==============================================================================
  184. /** The position of the mouse when the event occurred.
  185. This position is relative to the top-left of the component to which the
  186. event applies (as indicated by the MouseEvent::eventComponent field).
  187. For a floating-point position, see MouseEvent::position
  188. */
  189. Point<int> getPosition() const noexcept;
  190. /** Returns the mouse x position of this event, in global screen coordinates.
  191. The coordinates are relative to the top-left of the main monitor.
  192. @see getScreenPosition
  193. */
  194. int getScreenX() const;
  195. /** Returns the mouse y position of this event, in global screen coordinates.
  196. The coordinates are relative to the top-left of the main monitor.
  197. @see getScreenPosition
  198. */
  199. int getScreenY() const;
  200. /** Returns the mouse position of this event, in global screen coordinates.
  201. The coordinates are relative to the top-left of the main monitor.
  202. @see getMouseDownScreenPosition
  203. */
  204. Point<int> getScreenPosition() const;
  205. /** Returns the x coordinate at which the mouse button was last pressed.
  206. The coordinates are relative to the top-left of the main monitor.
  207. @see getMouseDownScreenPosition
  208. */
  209. int getMouseDownScreenX() const;
  210. /** Returns the y coordinate at which the mouse button was last pressed.
  211. The coordinates are relative to the top-left of the main monitor.
  212. @see getMouseDownScreenPosition
  213. */
  214. int getMouseDownScreenY() const;
  215. /** Returns the coordinates at which the mouse button was last pressed.
  216. The coordinates are relative to the top-left of the main monitor.
  217. @see getScreenPosition
  218. */
  219. Point<int> getMouseDownScreenPosition() const;
  220. //==============================================================================
  221. /** Creates a version of this event that is relative to a different component.
  222. The x and y positions of the event that is returned will have been
  223. adjusted to be relative to the new component.
  224. The component pointer that is passed-in must not be null.
  225. */
  226. MouseEvent getEventRelativeTo (Component* newComponent) const noexcept;
  227. /** Creates a copy of this event with a different position.
  228. All other members of the event object are the same, but the x and y are
  229. replaced with these new values.
  230. */
  231. MouseEvent withNewPosition (Point<float> newPosition) const noexcept;
  232. /** Creates a copy of this event with a different position.
  233. All other members of the event object are the same, but the x and y are
  234. replaced with these new values.
  235. */
  236. MouseEvent withNewPosition (Point<int> newPosition) const noexcept;
  237. //==============================================================================
  238. /** Changes the application-wide setting for the double-click time limit.
  239. This is the maximum length of time between mouse-clicks for it to be
  240. considered a double-click. It's used by the Component class.
  241. @see getDoubleClickTimeout, MouseListener::mouseDoubleClick
  242. */
  243. static void setDoubleClickTimeout (int timeOutMilliseconds) noexcept;
  244. /** Returns the application-wide setting for the double-click time limit.
  245. This is the maximum length of time between mouse-clicks for it to be
  246. considered a double-click. It's used by the Component class.
  247. @see setDoubleClickTimeout, MouseListener::mouseDoubleClick
  248. */
  249. static int getDoubleClickTimeout() noexcept;
  250. private:
  251. //==============================================================================
  252. const Point<float> mouseDownPos;
  253. const uint8 numberOfClicks, wasMovedSinceMouseDown;
  254. MouseEvent& operator= (const MouseEvent&);
  255. };
  256. //==============================================================================
  257. /**
  258. Contains status information about a mouse wheel event.
  259. @see MouseListener, MouseEvent
  260. */
  261. struct MouseWheelDetails
  262. {
  263. //==============================================================================
  264. /** The amount that the wheel has been moved in the X axis.
  265. If isReversed is true, then a negative deltaX means that the wheel has been
  266. pushed physically to the left.
  267. If isReversed is false, then a negative deltaX means that the wheel has been
  268. pushed physically to the right.
  269. */
  270. float deltaX;
  271. /** The amount that the wheel has been moved in the Y axis.
  272. If isReversed is true, then a negative deltaY means that the wheel has been
  273. pushed physically upwards.
  274. If isReversed is false, then a negative deltaY means that the wheel has been
  275. pushed physically downwards.
  276. */
  277. float deltaY;
  278. /** Indicates whether the user has reversed the direction of the wheel.
  279. See deltaX and deltaY for an explanation of the effects of this value.
  280. */
  281. bool isReversed;
  282. /** If true, then the wheel has continuous, un-stepped motion. */
  283. bool isSmooth;
  284. /** If true, then this event is part of the intertial momentum phase that follows
  285. the wheel being released. */
  286. bool isInertial;
  287. };
  288. #endif // JUCE_MOUSEEVENT_H_INCLUDED