View Javadoc
1   /*
2    * Copyright (c) 2002-2026 Gargoyle Software Inc.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * https://www.apache.org/licenses/LICENSE-2.0
8    *
9    * Unless required by applicable law or agreed to in writing, software
10   * distributed under the License is distributed on an "AS IS" BASIS,
11   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12   * See the License for the specific language governing permissions and
13   * limitations under the License.
14   */
15  package org.htmlunit.javascript.host.event;
16  
17  import static org.htmlunit.javascript.configuration.SupportedBrowser.FF;
18  import static org.htmlunit.javascript.configuration.SupportedBrowser.FF_ESR;
19  
20  import java.util.ArrayList;
21  
22  import org.htmlunit.corejs.javascript.Context;
23  import org.htmlunit.corejs.javascript.Function;
24  import org.htmlunit.corejs.javascript.Scriptable;
25  import org.htmlunit.corejs.javascript.ScriptableObject;
26  import org.htmlunit.corejs.javascript.VarScope;
27  import org.htmlunit.html.DomNode;
28  import org.htmlunit.javascript.JavaScriptEngine;
29  import org.htmlunit.javascript.configuration.JsxClass;
30  import org.htmlunit.javascript.configuration.JsxConstant;
31  import org.htmlunit.javascript.configuration.JsxConstructor;
32  import org.htmlunit.javascript.configuration.JsxFunction;
33  import org.htmlunit.javascript.configuration.JsxGetter;
34  import org.htmlunit.javascript.host.html.HTMLElement;
35  
36  /**
37   * JavaScript object representing a Mouse Event.
38   * For general information on which properties and functions should be supported, see
39   * <a href="http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-MouseEvent">DOM Level 2 Events</a>.
40   *
41   * @author Marc Guillemot
42   * @author Ahmed Ashour
43   * @author Frank Danek
44   * @author Ronald Brill
45   */
46  @JsxClass
47  public class MouseEvent extends UIEvent {
48  
49      /** Constant for {@code MOZ_SOURCE_UNKNOWN}. */
50      @JsxConstant({FF, FF_ESR})
51      public static final int MOZ_SOURCE_UNKNOWN = 0;
52      /** Constant for {@code MOZ_SOURCE_MOUSE}. */
53      @JsxConstant({FF, FF_ESR})
54      public static final int MOZ_SOURCE_MOUSE = 1;
55      /** Constant for {@code MOZ_SOURCE_PEN}. */
56      @JsxConstant({FF, FF_ESR})
57      public static final int MOZ_SOURCE_PEN = 2;
58      /** Constant for {@code MOZ_SOURCE_ERASER}. */
59      @JsxConstant({FF, FF_ESR})
60      public static final int MOZ_SOURCE_ERASER = 3;
61      /** Constant for {@code MOZ_SOURCE_CURSOR}. */
62      @JsxConstant({FF, FF_ESR})
63      public static final int MOZ_SOURCE_CURSOR = 4;
64      /** Constant for {@code MOZ_SOURCE_TOUCH}. */
65      @JsxConstant({FF, FF_ESR})
66      public static final int MOZ_SOURCE_TOUCH = 5;
67      /** Constant for {@code MOZ_SOURCE_KEYBOARD}. */
68      @JsxConstant({FF, FF_ESR})
69      public static final int MOZ_SOURCE_KEYBOARD = 6;
70  
71      /** The click event type, triggered by {@code onclick} event handlers. */
72      public static final String TYPE_CLICK = "click";
73  
74      /** The dblclick event type, triggered by {@code ondblclick} event handlers. */
75      public static final String TYPE_DBL_CLICK = "dblclick";
76  
77      /** The mouse over event type, triggered by {@code onmouseover} event handlers. */
78      public static final String TYPE_MOUSE_OVER = "mouseover";
79  
80      /** The mouse move event type, triggered by {@code onmousemove} event handlers. */
81      public static final String TYPE_MOUSE_MOVE = "mousemove";
82  
83      /** The mouse out event type, triggered by {@code onmouseout} event handlers. */
84      public static final String TYPE_MOUSE_OUT = "mouseout";
85  
86      /** The mouse down event type, triggered by {@code onmousedown} event handlers. */
87      public static final String TYPE_MOUSE_DOWN = "mousedown";
88  
89      /** The mouse up event type, triggered by {@code onmouseup} event handlers. */
90      public static final String TYPE_MOUSE_UP = "mouseup";
91  
92      /** The context menu event type, triggered by {@code oncontextmenu} event handlers. */
93      public static final String TYPE_CONTEXT_MENU = "contextmenu";
94  
95      /** The code for left mouse button. */
96      public static final int BUTTON_LEFT = 0;
97  
98      /** The code for middle mouse button. */
99      public static final int BUTTON_MIDDLE = 1;
100 
101     /** The code for right mouse button. */
102     public static final int BUTTON_RIGHT = 2;
103 
104     /** The event's screen coordinates; initially {@code null} and lazily initialized for performance reasons. */
105     private Integer screenX_;
106     private Integer screenY_;
107 
108     /** The event's client coordinates; initially {@code null} and lazily initialized for performance reasons. */
109     private Integer clientX_;
110     private Integer clientY_;
111 
112     /** The button code according to W3C (0: left button, 1: middle button, 2: right button). */
113     private int button_;
114 
115     /** The buttons being depressed (if any) when the mouse event was fired. */
116     private int buttons_;
117 
118     /** Switch to disable label handling if we already processing the event triggered from label processing. */
119     private boolean processLabelAfterBubbling_ = true;
120 
121     /** Whether or not the "meta" key was pressed during the firing of the event. */
122     private boolean metaKey_;
123 
124     /**
125      * Used to build the prototype.
126      */
127     public MouseEvent() {
128         super();
129         screenX_ = Integer.valueOf(0);
130         screenY_ = Integer.valueOf(0);
131         setDetail(1);
132     }
133 
134     /**
135      * JavaScript constructor.
136      *
137      * @param type the event type
138      * @param details the event details (optional)
139      */
140     @Override
141     @JsxConstructor
142     public void jsConstructor(final String type, final ScriptableObject details) {
143         super.jsConstructor(JavaScriptEngine.toString(type), details);
144         if (details != null && !JavaScriptEngine.isUndefined(details)) {
145             final Object screenX = details.get("screenX", details);
146             if (NOT_FOUND != screenX) {
147                 screenX_ = JavaScriptEngine.toInt32(screenX);
148             }
149 
150             final Object screenY = details.get("screenY", details);
151             if (NOT_FOUND != screenX) {
152                 screenY_ = JavaScriptEngine.toInt32(screenY);
153             }
154 
155             final Object clientX = details.get("clientX", details);
156             if (NOT_FOUND != clientX) {
157                 clientX_ = JavaScriptEngine.toInt32(clientX);
158             }
159 
160             final Object clientY = details.get("clientY", details);
161             if (NOT_FOUND != clientX) {
162                 clientY_ = JavaScriptEngine.toInt32(clientY);
163             }
164 
165             final Object button = details.get("button", details);
166             if (NOT_FOUND != button) {
167                 button_ = JavaScriptEngine.toInt32(button);
168             }
169 
170             final Object buttons = details.get("buttons", details);
171             if (NOT_FOUND != buttons) {
172                 buttons_ = JavaScriptEngine.toInt32(buttons);
173             }
174 
175             setAltKey(JavaScriptEngine.toBoolean(details.get("altKey")));
176             setCtrlKey(JavaScriptEngine.toBoolean(details.get("ctrlKey")));
177             setMetaKey(JavaScriptEngine.toBoolean(details.get("metaKey")));
178             setShiftKey(JavaScriptEngine.toBoolean(details.get("shiftKey")));
179         }
180     }
181 
182     /**
183      * Creates a new event instance.
184      * @param domNode the DOM node that triggered the event
185      * @param type the event type
186      * @param shiftKey true if SHIFT is pressed
187      * @param ctrlKey true if CTRL is pressed
188      * @param altKey true if ALT is pressed
189      * @param button the button code, must be {@link #BUTTON_LEFT}, {@link #BUTTON_MIDDLE} or {@link #BUTTON_RIGHT}
190      * @param detail the detail value
191      */
192     public MouseEvent(final DomNode domNode, final String type, final boolean shiftKey,
193         final boolean ctrlKey, final boolean altKey, final int button, final int detail) {
194 
195         super(domNode, type);
196         setShiftKey(shiftKey);
197         setCtrlKey(ctrlKey);
198         setAltKey(altKey);
199 
200         if (button != BUTTON_LEFT && button != BUTTON_MIDDLE && button != BUTTON_RIGHT) {
201             throw new IllegalArgumentException("Invalid button code: " + button);
202         }
203         button_ = button;
204 
205         setDetail(detail);
206     }
207 
208     /**
209      * The horizontal coordinate at which the event occurred relative to the DOM implementation's client area.
210      * @return the horizontal coordinate
211      */
212     @JsxGetter
213     public int getClientX() {
214         if (clientX_ == null) {
215             clientX_ = Integer.valueOf(getScreenX());
216         }
217         return clientX_.intValue();
218     }
219 
220     /**
221      * Sets the clientX value.
222      * @param value the clientX value
223      */
224     public void setClientX(final int value) {
225         clientX_ = value;
226     }
227 
228     /**
229      * The horizontal coordinate at which the event occurred relative to the origin of the screen
230      * coordinate system. The value of this attribute is initialized lazily, in order to optimize
231      * performance (it requires CSS parsing).
232      *
233      * @return the horizontal coordinate
234      */
235     @JsxGetter
236     public int getScreenX() {
237         if (screenX_ == null) {
238             final HTMLElement target = (HTMLElement) getTarget();
239             screenX_ = Integer.valueOf(target.getPosX() + 10);
240         }
241         return screenX_.intValue();
242     }
243 
244     /**
245      * Returns the horizontal coordinate of the event relative to whole document.
246      * @return the horizontal coordinate (currently the same as {@link #getScreenX()})
247      * @see <a href="https://developer.mozilla.org/en-US/docs/DOM/event.pageX">Mozilla doc</a>
248      */
249     @JsxGetter
250     public int getPageX() {
251         return getScreenX();
252     }
253 
254     /**
255      * The vertical coordinate at which the event occurred relative to the DOM implementation's client area.
256      * @return the horizontal coordinate
257      */
258     @JsxGetter
259     public int getClientY() {
260         if (clientY_ == null) {
261             clientY_ = Integer.valueOf(getScreenY());
262         }
263         return clientY_.intValue();
264     }
265 
266     /**
267      * Sets the clientY value.
268      * @param value the clientY value
269      */
270     public void setClientY(final int value) {
271         clientY_ = value;
272     }
273 
274     /**
275      * The vertical coordinate at which the event occurred relative to the origin of the screen
276      * coordinate system. The value of this attribute is initialized lazily, in order to optimize
277      * performance (it requires CSS parsing).
278      *
279      * @return the vertical coordinate
280      */
281     @JsxGetter
282     public int getScreenY() {
283         if (screenY_ == null) {
284             final HTMLElement target = (HTMLElement) getTarget();
285             screenY_ = Integer.valueOf(target.getPosY() + 10);
286         }
287         return screenY_.intValue();
288     }
289 
290     /**
291      * Returns the vertical coordinate of the event relative to the whole document.
292      * @return the horizontal coordinate (currently the same as {@link #getScreenY()})
293      * @see <a href="https://developer.mozilla.org/en-US/docs/DOM/event.pageY">Mozilla doc</a>
294      */
295     @JsxGetter
296     public int getPageY() {
297         return getScreenY();
298     }
299 
300     /**
301      * Gets the button code.
302      * @return the button code
303      */
304     @JsxGetter
305     public int getButton() {
306         return button_;
307     }
308 
309     /**
310      * Sets the button code.
311      * @param value the button code
312      */
313     public void setButton(final int value) {
314         button_ = value;
315     }
316 
317     /**
318      * Gets the button code.
319      * @return the button code
320      */
321     @JsxGetter
322     public int getButtons() {
323         return buttons_;
324     }
325 
326     /**
327      * Sets the button code.
328      * @param value the button code
329      */
330     public void setButtons(final int value) {
331         buttons_ = value;
332     }
333 
334     /**
335      * Special for FF (old stuff from Netscape time).
336      * @see <a href="http://unixpapa.com/js/mouse.html">Javascript Madness: Mouse Events</a>
337      * @return the button code
338      */
339     @Override
340     public int getWhich() {
341         return button_ + 1;
342     }
343 
344     /**
345      * Implementation of the DOM Level 2 Event method for initializing the mouse event.
346      *
347      * @param type the event type
348      * @param bubbles can the event bubble
349      * @param cancelable can the event be canceled
350      * @param view the view to use for this event
351      * @param detail the detail to set for the event
352      * @param screenX the initial value of screenX
353      * @param screenY the initial value of screenY
354      * @param clientX the initial value of clientX
355      * @param clientY the initial value of clientY
356      * @param ctrlKey is the control key pressed
357      * @param altKey is the alt key pressed
358      * @param shiftKey is the shift key pressed
359      * @param metaKey is the meta key pressed
360      * @param button what mouse button is pressed
361      * @param relatedTarget is there a related target for the event
362      */
363     @JsxFunction
364     public void initMouseEvent(
365             final String type,
366             final boolean bubbles,
367             final boolean cancelable,
368             final Object view,
369             final int detail,
370             final int screenX,
371             final int screenY,
372             final int clientX,
373             final int clientY,
374             final boolean ctrlKey,
375             final boolean altKey,
376             final boolean shiftKey,
377             final boolean metaKey,
378             final int button,
379             final Object relatedTarget) {
380         initUIEvent(type, bubbles, cancelable, view, detail);
381         screenX_ = Integer.valueOf(screenX);
382         screenY_ = Integer.valueOf(screenY);
383         clientX_ = Integer.valueOf(clientX);
384         clientY_ = Integer.valueOf(clientY);
385         setCtrlKey(ctrlKey);
386         setAltKey(altKey);
387         setShiftKey(shiftKey);
388         setMetaKey(metaKey);
389         button_ = button;
390         // Ignore the relatedTarget parameter; we don't support it yet.
391     }
392 
393     /**
394      * Returns the mouse event currently firing, or {@code null} if no mouse event is being processed.
395      * @return the mouse event currently firing
396      */
397     @SuppressWarnings("unchecked")
398     public static MouseEvent getCurrentMouseEvent() {
399         final Context context = Context.getCurrentContext();
400         if (context != null) {
401             final ArrayList<Event> events = (ArrayList<Event>) context.getThreadLocal(KEY_CURRENT_EVENT);
402             if (events != null && !events.isEmpty()) {
403                 final int lastIdx = events.size() - 1;
404                 final Event lastEvent = events.get(lastIdx);
405                 if (lastEvent instanceof MouseEvent event) {
406                     return event;
407                 }
408             }
409         }
410         return null;
411     }
412 
413     /**
414      * Returns {@code true} if the specified event type should be managed as a mouse event.
415      * @param type the type of event to check
416      * @return {@code true} if the specified event type should be managed as a mouse event
417      */
418     public static boolean isMouseEvent(final String type) {
419         return TYPE_CLICK.equals(type)
420             || TYPE_MOUSE_OVER.equals(type)
421             || TYPE_MOUSE_MOVE.equals(type)
422             || TYPE_MOUSE_OUT.equals(type)
423             || TYPE_MOUSE_DOWN.equals(type)
424             || TYPE_MOUSE_UP.equals(type)
425             || TYPE_CONTEXT_MENU.equals(type);
426     }
427 
428     /**
429      * {@inheritDoc} Overridden to modify browser configurations.
430      */
431     @Override
432     @JsxGetter
433     public boolean isAltKey() {
434         return super.isAltKey();
435     }
436 
437     /**
438      * {@inheritDoc} Overridden to modify browser configurations.
439      */
440     @Override
441     @JsxGetter
442     public boolean isCtrlKey() {
443         return super.isCtrlKey();
444     }
445 
446     /**
447      * {@inheritDoc} Overridden to modify browser configurations.
448      */
449     @Override
450     @JsxGetter
451     public boolean isShiftKey() {
452         return super.isShiftKey();
453     }
454 
455     /**
456      * {@inheritDoc} Overridden take care of click events.
457      */
458     @Override
459     public boolean processLabelAfterBubbling() {
460         return MouseEvent.TYPE_CLICK  == getType() && processLabelAfterBubbling_;
461     }
462 
463     /**
464      * Disable the lable processing if we are already processing one.
465      */
466     public void disableProcessLabelAfterBubbling() {
467         processLabelAfterBubbling_ = false;
468     }
469 
470     /**
471      * Returns whether or not the "meta" key was pressed during the event firing.
472      * @return whether or not the "meta" key was pressed during the event firing
473      */
474     @JsxGetter
475     public boolean isMetaKey() {
476         return metaKey_;
477     }
478 
479     /**
480      * Sets whether the Meta key was pressed during this event.
481      *
482      * @param metaKey whether the Meta key was pressed during this event
483      */
484     protected void setMetaKey(final boolean metaKey) {
485         metaKey_ = metaKey;
486     }
487 
488     /**
489      * Returns the current state of the specified modifier key.
490      *
491      * @param context the JavaScript context
492      * @param scope the scope
493      * @param thisObj the scriptable
494      * @param args the arguments passed into the method; the key value of the modifier
495      *        (e.g. {@code Shift} or {@code Control})
496      * @param function the function
497      * @return {@code true} if the modifier is active
498      * @see <a href="https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/getModifierState">MDN</a>
499      */
500     @JsxFunction
501     public static boolean getModifierState(final Context context, final VarScope scope,
502             final Scriptable thisObj, final Object[] args, final Function function) {
503         if (!(thisObj instanceof MouseEvent event)) {
504             throw JavaScriptEngine.typeError("Illegal invocation");
505         }
506         return getModifierState("MouseEvent", args,
507                 event.isShiftKey(), event.isCtrlKey(), event.isAltKey(), event.isMetaKey());
508     }
509 }