necouchman commented on a change in pull request #613:
URL: https://github.com/apache/guacamole-client/pull/613#discussion_r642123798
##########
File path: guacamole-common-js/src/main/webapp/modules/Mouse.js
##########
@@ -503,16 +425,355 @@ Guacamole.Mouse.State = function State(template) {
};
+/**
+ * All mouse buttons that may be represented by a
+ * {@link Guacamole.Mouse.State}.
+ *
+ * @readonly
+ * @enum
+ */
+Guacamole.Mouse.State.Buttons = {
+
+ /**
+ * The name of the {@link Guacamole.Mouse.State} property representing the
+ * left mouse button.
+ *
+ * @constant
+ * @type {String}
+ */
+ LEFT : 'left',
+
+ /**
+ * The name of the {@link Guacamole.Mouse.State} property representing the
+ * middle mouse button.
+ *
+ * @constant
+ * @type {String}
+ */
+ MIDDLE : 'middle',
+
+ /**
+ * The name of the {@link Guacamole.Mouse.State} property representing the
+ * right mouse button.
+ *
+ * @constant
+ * @type {String}
+ */
+ RIGHT : 'right',
+
+ /**
+ * The name of the {@link Guacamole.Mouse.State} property representing the
+ * up mouse button (the fourth mouse button, clicked when the mouse scroll
+ * wheel is scrolled up).
+ *
+ * @constant
+ * @type {String}
+ */
+ UP : 'up',
+
+ /**
+ * The name of the {@link Guacamole.Mouse.State} property representing the
+ * down mouse button (the fifth mouse button, clicked when the mouse scroll
+ * wheel is scrolled up).
+ *
+ * @constant
+ * @type {String}
+ */
+ DOWN : 'down'
+
+};
+
+/**
+ * Base event type for all mouse events. The mouse producing the event may be
+ * the user's local mouse (as with {@link Guacamole.Mouse}) or an emulated
+ * mouse (as with {@link Guacamole.Mouse.Touchpad}).
+ *
+ * @constructor
+ * @augments Guacamole.Event.DOMEvent
+ * @param {String} type
+ * The type name of the event ("mousedown", "mouseup", etc.)
+ *
+ * @param {Guacamole.Mouse.State} state
+ * The current mouse state.
+ *
+ * @param {Event|Event[]} [events=[]]
+ * The DOM events that are related to this event, if any.
+ */
+Guacamole.Mouse.Event = function MouseEvent(type, state, events) {
+
+ Guacamole.Event.DOMEvent.call(this, type, events);
+
+ /**
+ * The name of the event handler used by the Guacamole JavaScript API for
+ * this event prior to the migration to Guacamole.Event.Target.
+ *
+ * @private
+ * @constant
+ * @type {String}
+ */
+ var legacyHandlerName = 'on' + this.type;
+
+ /**
+ * The current mouse state at the time this event was fired.
+ *
+ * @type {Guacamole.Mouse.State}
+ */
+ this.state = state;
+
+ /**
+ * @inheritdoc
+ */
+ this.invokeLegacyHandler = function invokeLegacyHandler(target) {
+ if (target[legacyHandlerName]) {
+
+ this.preventDefault();
+ this.stopPropagation();
+
+ target[legacyHandlerName](this.state);
+
+ }
+ };
+
+};
+
+/**
+ * An object which can dispatch {@link Guacamole.Mouse.Event} objects
+ * representing mouse events. These mouse events may be produced from an actual
+ * mouse device (as with {@link Guacamole.Mouse}), from an emulated mouse
+ * device (as with {@link Guacamole.Mouse.Touchpad}, or may be programmatically
+ * generated (using functions like [dispatch()]{@link
Guacamole.Mouse.Event.Target#dispatch},
+ * [press()]{@link Guacamole.Mouse.Event.Target#press}, and
+ * [release()]{@link Guacamole.Mouse.Event.Target#release}).
+ *
+ * @constructor
+ * @augments Guacamole.Event.Target
+ */
+Guacamole.Mouse.Event.Target = function MouseEventTarget() {
+
+ Guacamole.Event.Target.call(this);
+
+ /**
+ * The current mouse state. The properties of this state are updated when
+ * mouse events fire. This state object is also passed in as a parameter to
+ * the handler of any mouse events.
+ *
+ * @type {Guacamole.Mouse.State}
+ */
+ this.currentState = new Guacamole.Mouse.State();
+
+ /**
+ * Fired whenever a mouse button is effectively pressed. Depending on the
+ * object dispatching the event, this can be due to a true mouse button
+ * press ({@link Guacamole.Mouse}), an emulated mouse button press from a
+ * touch gesture ({@link Guacamole.Mouse.Touchpad} and
+ * {@link Guacamole.Mouse.Touchscreen}), or may be programmatically
+ * generated through [dispatch()]{@link
Guacamole.Mouse.Event.Target#dispatch},
+ * [press()]{@link Guacamole.Mouse.Event.Target#press}, or
+ * [click()]{@link Guacamole.Mouse.Event.Target#click}.
+ *
+ * @event Guacamole.Mouse.Event.Target#mousedown
+ * @param {Guacamole.Mouse.Event} event
+ * The mousedown event that was fired.
+ */
+
Review comment:
I'm assuming that these are just for documentation purposes, with the
`@event` tag, but just wanted to make sure that it's expected that there isn't
any actual code being documented, here?
##########
File path: guacamole-common-js/src/main/webapp/modules/Mouse.js
##########
@@ -503,16 +425,355 @@ Guacamole.Mouse.State = function State(template) {
};
+/**
+ * All mouse buttons that may be represented by a
+ * {@link Guacamole.Mouse.State}.
+ *
+ * @readonly
+ * @enum
+ */
+Guacamole.Mouse.State.Buttons = {
+
+ /**
+ * The name of the {@link Guacamole.Mouse.State} property representing the
+ * left mouse button.
+ *
+ * @constant
+ * @type {String}
+ */
+ LEFT : 'left',
+
+ /**
+ * The name of the {@link Guacamole.Mouse.State} property representing the
+ * middle mouse button.
+ *
+ * @constant
+ * @type {String}
+ */
+ MIDDLE : 'middle',
+
+ /**
+ * The name of the {@link Guacamole.Mouse.State} property representing the
+ * right mouse button.
+ *
+ * @constant
+ * @type {String}
+ */
+ RIGHT : 'right',
+
+ /**
+ * The name of the {@link Guacamole.Mouse.State} property representing the
+ * up mouse button (the fourth mouse button, clicked when the mouse scroll
+ * wheel is scrolled up).
+ *
+ * @constant
+ * @type {String}
+ */
+ UP : 'up',
+
+ /**
+ * The name of the {@link Guacamole.Mouse.State} property representing the
+ * down mouse button (the fifth mouse button, clicked when the mouse scroll
+ * wheel is scrolled up).
+ *
+ * @constant
+ * @type {String}
+ */
+ DOWN : 'down'
+
+};
+
+/**
+ * Base event type for all mouse events. The mouse producing the event may be
+ * the user's local mouse (as with {@link Guacamole.Mouse}) or an emulated
+ * mouse (as with {@link Guacamole.Mouse.Touchpad}).
+ *
+ * @constructor
+ * @augments Guacamole.Event.DOMEvent
+ * @param {String} type
+ * The type name of the event ("mousedown", "mouseup", etc.)
+ *
+ * @param {Guacamole.Mouse.State} state
+ * The current mouse state.
+ *
+ * @param {Event|Event[]} [events=[]]
+ * The DOM events that are related to this event, if any.
+ */
+Guacamole.Mouse.Event = function MouseEvent(type, state, events) {
+
+ Guacamole.Event.DOMEvent.call(this, type, events);
+
+ /**
+ * The name of the event handler used by the Guacamole JavaScript API for
+ * this event prior to the migration to Guacamole.Event.Target.
+ *
+ * @private
+ * @constant
+ * @type {String}
+ */
+ var legacyHandlerName = 'on' + this.type;
+
+ /**
+ * The current mouse state at the time this event was fired.
+ *
+ * @type {Guacamole.Mouse.State}
+ */
+ this.state = state;
+
+ /**
+ * @inheritdoc
+ */
+ this.invokeLegacyHandler = function invokeLegacyHandler(target) {
+ if (target[legacyHandlerName]) {
+
+ this.preventDefault();
+ this.stopPropagation();
+
+ target[legacyHandlerName](this.state);
+
+ }
+ };
+
+};
+
+/**
+ * An object which can dispatch {@link Guacamole.Mouse.Event} objects
+ * representing mouse events. These mouse events may be produced from an actual
+ * mouse device (as with {@link Guacamole.Mouse}), from an emulated mouse
+ * device (as with {@link Guacamole.Mouse.Touchpad}, or may be programmatically
+ * generated (using functions like [dispatch()]{@link
Guacamole.Mouse.Event.Target#dispatch},
+ * [press()]{@link Guacamole.Mouse.Event.Target#press}, and
+ * [release()]{@link Guacamole.Mouse.Event.Target#release}).
+ *
+ * @constructor
+ * @augments Guacamole.Event.Target
+ */
+Guacamole.Mouse.Event.Target = function MouseEventTarget() {
+
+ Guacamole.Event.Target.call(this);
+
+ /**
+ * The current mouse state. The properties of this state are updated when
+ * mouse events fire. This state object is also passed in as a parameter to
+ * the handler of any mouse events.
+ *
+ * @type {Guacamole.Mouse.State}
+ */
+ this.currentState = new Guacamole.Mouse.State();
+
+ /**
+ * Fired whenever a mouse button is effectively pressed. Depending on the
+ * object dispatching the event, this can be due to a true mouse button
+ * press ({@link Guacamole.Mouse}), an emulated mouse button press from a
+ * touch gesture ({@link Guacamole.Mouse.Touchpad} and
+ * {@link Guacamole.Mouse.Touchscreen}), or may be programmatically
+ * generated through [dispatch()]{@link
Guacamole.Mouse.Event.Target#dispatch},
+ * [press()]{@link Guacamole.Mouse.Event.Target#press}, or
+ * [click()]{@link Guacamole.Mouse.Event.Target#click}.
+ *
+ * @event Guacamole.Mouse.Event.Target#mousedown
+ * @param {Guacamole.Mouse.Event} event
+ * The mousedown event that was fired.
+ */
+
+ /**
+ * Fired whenever a mouse button is effectively released. Depending on the
+ * object dispatching the event, this can be due to a true mouse button
+ * release ({@link Guacamole.Mouse}), an emulated mouse button release from
+ * a touch gesture ({@link Guacamole.Mouse.Touchpad} and
+ * {@link Guacamole.Mouse.Touchscreen}), or may be programmatically
+ * generated through [dispatch()]{@link
Guacamole.Mouse.Event.Target#dispatch},
+ * [release()]{@link Guacamole.Mouse.Event.Target#release}, or
+ * [click()]{@link Guacamole.Mouse.Event.Target#click}.
+ *
+ * @event Guacamole.Mouse.Event.Target#mouseup
+ * @param {Guacamole.Mouse.Event} event
+ * The mouseup event that was fired.
+ */
+
+ /**
+ * Fired whenever the mouse pointer is effectively moved. Depending on the
+ * object dispatching the event, this can be due to true mouse movement
+ * ({@link Guacamole.Mouse}), emulated mouse movement from
+ * a touch gesture ({@link Guacamole.Mouse.Touchpad} and
+ * {@link Guacamole.Mouse.Touchscreen}), or may be programmatically
+ * generated through [dispatch()]{@link
Guacamole.Mouse.Event.Target#dispatch},
+ * or [move()]{@link Guacamole.Mouse.Event.Target#move}.
+ *
+ * @event Guacamole.Mouse.Event.Target#mousemove
+ * @param {Guacamole.Mouse.Event} event
+ * The mousemove event that was fired.
+ */
+
+ /**
+ * Fired whenever the mouse pointer leaves the boundaries of the element
+ * being monitored for interaction. This will only ever be automatically
+ * fired due to movement of an actual mouse device via
+ * {@link Guacamole.Mouse} unless programmatically generated through
+ * [dispatch()]{@link Guacamole.Mouse.Event.Target#dispatch},
+ * or [out()]{@link Guacamole.Mouse.Event.Target#out}.
+ *
+ * @event Guacamole.Mouse.Event.Target#mouseout
+ * @param {Guacamole.Mouse.Event} event
+ * The mouseout event that was fired.
+ */
+
+ /**
+ * Presses the given mouse button, if it isn't already pressed. Valid
+ * button names are defined by {@link Guacamole.Mouse.State.Buttons} and
+ * correspond to the button-related properties of
+ * {@link Guacamole.Mouse.State}.
+ *
+ * @fires Guacamole.Mouse.Event.Target#mousedown
+ *
+ * @param {String} button
+ * The name of the mouse button to release, as defined by
+ * {@link Guacamole.Mouse.State.Buttons}.
+ *
+ * @param {Event|Event[]} [events=[]]
+ * The DOM events that are related to the mouse button press, if any.
+ */
+ this.press = function press(button, events) {
+ if (!this.currentState[button]) {
+ this.currentState[button] = true;
+ this.dispatch(new Guacamole.Mouse.Event('mousedown',
this.currentState, events));
+ }
+ };
+
+ /**
+ * Releases the given mouse button, if it isn't already released. Valid
+ * button names are defined by {@link Guacamole.Mouse.State.Buttons} and
+ * correspond to the button-related properties of
+ * {@link Guacamole.Mouse.State}.
+ *
+ * @fires Guacamole.Mouse.Event.Target#mouseup
+ *
+ * @param {String} button
+ * The name of the mouse button to release, as defined by
+ * {@link Guacamole.Mouse.State.Buttons}.
+ *
+ * @param {Event|Event[]} [events=[]]
+ * The DOM events related to the mouse button release, if any.
+ */
+ this.release = function release(button, events) {
+ if (this.currentState[button]) {
+ this.currentState[button] = false;
+ this.dispatch(new Guacamole.Mouse.Event('mouseup',
this.currentState, events));
+ }
+ };
+
+ /**
+ * Clicks (presses and releases) the given mouse button. Valid button
+ * names are defined by {@link Guacamole.Mouse.State.Buttons} and
+ * correspond to the button-related properties of
+ * {@link Guacamole.Mouse.State}.
+ *
+ * @fires Guacamole.Mouse.Event.Target#mousedown
+ * @fires Guacamole.Mouse.Event.Target#mouseup
+ *
+ * @param {String} button
+ * The name of the mouse button to release, as defined by
Review comment:
The name of the mouse button to _click_, I think?
##########
File path: guacamole-common-js/src/main/webapp/modules/Mouse.js
##########
@@ -503,16 +425,355 @@ Guacamole.Mouse.State = function State(template) {
};
+/**
+ * All mouse buttons that may be represented by a
+ * {@link Guacamole.Mouse.State}.
+ *
+ * @readonly
+ * @enum
+ */
+Guacamole.Mouse.State.Buttons = {
+
+ /**
+ * The name of the {@link Guacamole.Mouse.State} property representing the
+ * left mouse button.
+ *
+ * @constant
+ * @type {String}
+ */
+ LEFT : 'left',
+
+ /**
+ * The name of the {@link Guacamole.Mouse.State} property representing the
+ * middle mouse button.
+ *
+ * @constant
+ * @type {String}
+ */
+ MIDDLE : 'middle',
+
+ /**
+ * The name of the {@link Guacamole.Mouse.State} property representing the
+ * right mouse button.
+ *
+ * @constant
+ * @type {String}
+ */
+ RIGHT : 'right',
+
+ /**
+ * The name of the {@link Guacamole.Mouse.State} property representing the
+ * up mouse button (the fourth mouse button, clicked when the mouse scroll
+ * wheel is scrolled up).
+ *
+ * @constant
+ * @type {String}
+ */
+ UP : 'up',
+
+ /**
+ * The name of the {@link Guacamole.Mouse.State} property representing the
+ * down mouse button (the fifth mouse button, clicked when the mouse scroll
+ * wheel is scrolled up).
+ *
+ * @constant
+ * @type {String}
+ */
+ DOWN : 'down'
+
+};
+
+/**
+ * Base event type for all mouse events. The mouse producing the event may be
+ * the user's local mouse (as with {@link Guacamole.Mouse}) or an emulated
+ * mouse (as with {@link Guacamole.Mouse.Touchpad}).
+ *
+ * @constructor
+ * @augments Guacamole.Event.DOMEvent
+ * @param {String} type
+ * The type name of the event ("mousedown", "mouseup", etc.)
+ *
+ * @param {Guacamole.Mouse.State} state
+ * The current mouse state.
+ *
+ * @param {Event|Event[]} [events=[]]
+ * The DOM events that are related to this event, if any.
+ */
+Guacamole.Mouse.Event = function MouseEvent(type, state, events) {
+
+ Guacamole.Event.DOMEvent.call(this, type, events);
+
+ /**
+ * The name of the event handler used by the Guacamole JavaScript API for
+ * this event prior to the migration to Guacamole.Event.Target.
+ *
+ * @private
+ * @constant
+ * @type {String}
+ */
+ var legacyHandlerName = 'on' + this.type;
+
+ /**
+ * The current mouse state at the time this event was fired.
+ *
+ * @type {Guacamole.Mouse.State}
+ */
+ this.state = state;
+
+ /**
+ * @inheritdoc
+ */
+ this.invokeLegacyHandler = function invokeLegacyHandler(target) {
+ if (target[legacyHandlerName]) {
+
+ this.preventDefault();
+ this.stopPropagation();
+
+ target[legacyHandlerName](this.state);
+
+ }
+ };
+
+};
+
+/**
+ * An object which can dispatch {@link Guacamole.Mouse.Event} objects
+ * representing mouse events. These mouse events may be produced from an actual
+ * mouse device (as with {@link Guacamole.Mouse}), from an emulated mouse
+ * device (as with {@link Guacamole.Mouse.Touchpad}, or may be programmatically
+ * generated (using functions like [dispatch()]{@link
Guacamole.Mouse.Event.Target#dispatch},
+ * [press()]{@link Guacamole.Mouse.Event.Target#press}, and
+ * [release()]{@link Guacamole.Mouse.Event.Target#release}).
+ *
+ * @constructor
+ * @augments Guacamole.Event.Target
+ */
+Guacamole.Mouse.Event.Target = function MouseEventTarget() {
+
+ Guacamole.Event.Target.call(this);
+
+ /**
+ * The current mouse state. The properties of this state are updated when
+ * mouse events fire. This state object is also passed in as a parameter to
+ * the handler of any mouse events.
+ *
+ * @type {Guacamole.Mouse.State}
+ */
+ this.currentState = new Guacamole.Mouse.State();
+
+ /**
+ * Fired whenever a mouse button is effectively pressed. Depending on the
+ * object dispatching the event, this can be due to a true mouse button
+ * press ({@link Guacamole.Mouse}), an emulated mouse button press from a
+ * touch gesture ({@link Guacamole.Mouse.Touchpad} and
+ * {@link Guacamole.Mouse.Touchscreen}), or may be programmatically
+ * generated through [dispatch()]{@link
Guacamole.Mouse.Event.Target#dispatch},
+ * [press()]{@link Guacamole.Mouse.Event.Target#press}, or
+ * [click()]{@link Guacamole.Mouse.Event.Target#click}.
+ *
+ * @event Guacamole.Mouse.Event.Target#mousedown
+ * @param {Guacamole.Mouse.Event} event
+ * The mousedown event that was fired.
+ */
+
+ /**
+ * Fired whenever a mouse button is effectively released. Depending on the
+ * object dispatching the event, this can be due to a true mouse button
+ * release ({@link Guacamole.Mouse}), an emulated mouse button release from
+ * a touch gesture ({@link Guacamole.Mouse.Touchpad} and
+ * {@link Guacamole.Mouse.Touchscreen}), or may be programmatically
+ * generated through [dispatch()]{@link
Guacamole.Mouse.Event.Target#dispatch},
+ * [release()]{@link Guacamole.Mouse.Event.Target#release}, or
+ * [click()]{@link Guacamole.Mouse.Event.Target#click}.
+ *
+ * @event Guacamole.Mouse.Event.Target#mouseup
+ * @param {Guacamole.Mouse.Event} event
+ * The mouseup event that was fired.
+ */
+
+ /**
+ * Fired whenever the mouse pointer is effectively moved. Depending on the
+ * object dispatching the event, this can be due to true mouse movement
+ * ({@link Guacamole.Mouse}), emulated mouse movement from
+ * a touch gesture ({@link Guacamole.Mouse.Touchpad} and
+ * {@link Guacamole.Mouse.Touchscreen}), or may be programmatically
+ * generated through [dispatch()]{@link
Guacamole.Mouse.Event.Target#dispatch},
+ * or [move()]{@link Guacamole.Mouse.Event.Target#move}.
+ *
+ * @event Guacamole.Mouse.Event.Target#mousemove
+ * @param {Guacamole.Mouse.Event} event
+ * The mousemove event that was fired.
+ */
+
+ /**
+ * Fired whenever the mouse pointer leaves the boundaries of the element
+ * being monitored for interaction. This will only ever be automatically
+ * fired due to movement of an actual mouse device via
+ * {@link Guacamole.Mouse} unless programmatically generated through
+ * [dispatch()]{@link Guacamole.Mouse.Event.Target#dispatch},
+ * or [out()]{@link Guacamole.Mouse.Event.Target#out}.
+ *
+ * @event Guacamole.Mouse.Event.Target#mouseout
+ * @param {Guacamole.Mouse.Event} event
+ * The mouseout event that was fired.
+ */
+
+ /**
+ * Presses the given mouse button, if it isn't already pressed. Valid
+ * button names are defined by {@link Guacamole.Mouse.State.Buttons} and
+ * correspond to the button-related properties of
+ * {@link Guacamole.Mouse.State}.
+ *
+ * @fires Guacamole.Mouse.Event.Target#mousedown
+ *
+ * @param {String} button
+ * The name of the mouse button to release, as defined by
Review comment:
The name of the mouse button to _press_, perhaps?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
