G.M - The Global Mouse Input Manager Object

Description

G.M is the mouse input manager object. It captures and processes mouse input, making it accessible to game code.

You can use its variables to schedule mouse triggered logic within the normal flow of your game code, or have it execute mouse event triggered code immediately with hook functions.

See the tutorials for more details about using the mouse input manager.

Variables

(type: boolean)G.M.on

G.M.on is a boolean flag denoting that the mouse input manager is on.

It's not very useful at the moment, since the mouse input manager is always on, but this may change in the future.

(type: G.Gob)G.M.deselectGob

G.M.deselectGob is set to either NULL or a Gob, and is set manually.

When set to a Gob, mouse events inside that Gob's tag will not be cause text highlighting or selection to occur.

For example, click-dragging the mouse in an HTML page normally causes text to be highlighted, but as soon as the mouse moves inside G.M.deselectGob's tag, all highlighting will be cancelled.

Highlighting will still work outside G.M.deselectGob's tag, and the user can still use their keyboard to select all text (eg with CTL-A or CMD-A).

Setting this variable is a good idea for most games, because mouse clicks often perform unwanted highlighting on the game graphics, which looks ugly. G.M.deselectGob is normally set to the outer-most container Gob in a game.

See the tutorials for more details about using this variable.

(type: boolean)G.M.isPressed

G.M.isPressed is a boolean flag denoting that the mouse button is currently pressed.

This flag is set to true as soon as the mouse down event fires, and remains true as long as the button is down. It is set to false as soon as the mouse up event fires.

Use this variable in your code for continuous mouse down events such as automatic firing or Gob dragging.

Details about the mouse position and modifier keys pressed during the mouse down event are stored in G.M.down. See G.M.down for more details.

(type: boolean)G.M.setWasPressed

G.M.setWasPressed is boolean flag used internally by the hook function G.M.syncWasPressed().

It is set to true as soon as the mouse up event fires, and tells the mouse manager to set G.M.wasPressed to true at the end of the current game loop iteration.

You don't need to touch this variable.

(type: int)G.M.x

G.M.x is the current mouse x-coordinate, and is relative to the left side of the HTML document.

This value is set by G.M.mouseMoveEventHandler(e) every time the mouse moves.

G.M.x corresponds to a pixel value, eg, 5 == 5px.

(type: int)G.M.y

G.M.y is the current mouse y-coordinate, and is relative to the top of the HTML document.

This value is set by G.M.mouseMoveEventHandler(e) every time the mouse moves.

G.M.y corresponds to a pixel value, eg, 5 == 5px.

(type: boolean)G.M.wasPressed

G.M.wasPressed is a boolean flag denoting a mouse up event has fired; i.e., that the mouse button has just been released.

This flag is set to true at the very end of the game loop iteration in which the mouse up event fires, and remains true until the end of the following game loop iteration.

Use this variable in your code for instantaneous mouse events such as one-click-per-shot firing, or releasing a Gob from a dragging action.

Details about the mouse position and modifier keys pressed during the mouse up event are stored in G.M.up. See G.M.up for more details.

(type: object)G.M.down

G.M.down is an object that stores information about the last mouse down event. All values are overwritten by the next mouse down event.

This object contains:

  • x, the x-coordinate at the time of the mouse down event. It corresponds to a pixel value, eg, 5 == 5px.
  • y, the y-coordinate at the time of the mouse down event. It corresponds to a pixel value, eg, 5 == 5px.
  • t, the timestamp, in milliseconds, of the mouse down event.
  • altKey, a boolean flag denoting whether the ALT key was pressed at the time of the event.
  • ctrlKey, a boolean flag denoting whether the CTRL key was pressed at the time of the event.
  • shiftKey, a boolean flag denoting whether the SHIFT key was pressed at the time of the event.
  • fired, an internal boolean flag used by G.M.mouseDownEventHandler(e) to ensure that this event is not re-fired continuously during a single keydown event.

(type: object)G.M.up

G.M.up is an object that stores information about the last mouse up event. All values are overwritten by the next mouse up event.

This object contains:

  • x, the x-coordinate at the time of the mouse up event. It corresponds to a pixel value, eg, 5 == 5px.
  • y, the y-coordinate at the time of the mouse up event. It corresponds to a pixel value, eg, 5 == 5px.
  • t, the timestamp, in milliseconds, of the mouse up event.
  • altKey, a boolean flag denoting whether the ALT key was pressed at the time of the event.
  • ctrlKey, a boolean flag denoting whether the CTRL key was pressed at the time of the event.
  • shiftKey, a boolean flag denoting whether the SHIFT key was pressed at the time of the event.

(type: object)G.M.hooks

A 'hook' is just a way to call a function, in this case, at the time a mouse event fires. We call such functions 'hooks' for short.

G.M.hooks is an object containing all mouse event hook functions, organized into 2 sub-sets: up and down.

Hooks within a given sub-set do not fire in any particular sequence.

ALl G.M.up hooks are fired at the time of a mouse up event, and all G.M.down hooks are fired at the time of a mouse down event.

Normally, mouse event triggered code is scheduled inside of your G.Block.AI() or G.Gob.AI() functions, where it is logically connected to the object in your game. But you can also execute mouse triggered logic immediately, using a hook.

Mouse event hooks are set with G.M.addHook()/G.M.deleteHook().

Methods

(returns G.M)G.M.addHook(name, fn, type)

G.M.addHook(name, fn, type) adds a function to either the mouseup or mousedown event hook sets.

This function takes 3 arguments: the name of the hook, the hook function, and the set to which is to be added (i.e., its 'type'). Valid types are: 'up' and 'down'.

See G.M.hooks for more details about using mouse event hooks.

(returns G.M)G.M.deleteHook(name, type)

G.M.deleteHook(name, type) deletes a function from either the mouseup or mousedown event hook sets.

This function takes 2 arguments: the name of the hook and the set from which it is to be removed (i.e., its 'type'). Valid types are: 'up' and 'down'.

See G.M.hooks for more details about using mouse event hooks.

(returns undefined)G.M.start()

G.M.start() starts the mouse input manager.

This function is called automatically by GMP at start up, and you never need to call it explicitly. See the 'G.M - Supporting In-line Code' section, below, for more details.

(returns undefined)G.M.stop()

G.M.stop() stops the mouse input manager.

This function is called automatically by GMP inside of a stop hook, and you never need to call it explicitly. Note that there is no performance gain for turning off the mouse input manager, and you can always just it ignore it if you aren't using it. In other words, you really never need to call this function.

See the 'G.M - Supporting In-line Code' section, below, for more details about the stop hook.

(returns array)G.M.eventPosition(e)

G.M.eventPosition(e) returns the mouse position captured by event e.

It is a helper function used by the three mouse event handler functions, and is unlikely to be called directly.

(returns true)G.M.mouseDownEventHandler(e)

G.M.mouseDownEventHandler(e) captures and processes document.onmousedown event data.

GMP treats the mouse down event as instantaneous, updating G.M.down, G.M.isPressed and firing all functions in G.M.hooks.down exactly once, at the instant the mouse button is pressed. See these variables for more details about the information captured.

Note that G.M.isPressed will continue to equal true as long as the mouse stays down, allowing your code to treat a mouse down event as continuous.

(returns true)G.M.mouseUpEventHandler(e)

G.M.mouseUpEventHandler(e) captures and processes document.onmouseup event data.

(returns true)G.M.mouseMoveEventHandler(e)

G.M.mouseMoveEventHandler(e) captures and processes document.onmousemove event data.

(returns undefined)G.M.deselect()

G.M.deselect() blocks text selection by the mouse. This behaviour is limited to the inside of the tag specified by G.M.deselectGob.tag. If G.M.deselectGob is not set, then this function does nothing.

Without this function, mouse clicks often perform unwanted highlighting on the game graphics, which looks ugly.

G.M.deselect() is called by all three mouse event handler functions.

See G.M.deselectGob for more details.

(returns undefined)G.M.syncWasPressed()

G.M.syncWasPressed() is a system hook that sets G.M.wasPressed at the correct time.

This function is called automatically, and shouldn't be called in game code.

See G.M.wasPressed, G.M.setWasPressed and 'G.M - Supporting In-line Code' for more details.

Supporting In-line Code

There are 3 in-line chunks of code in the G.M section of gmp-engine.js.

The first is after the function definition for G.M.stop(): G.addHook('stopMouse', G.M.stop, 'stop'); This code adds the G.M.stop function as a stop hook. This hook de-registers the mouse event handlers when the player leaves the page. This helps stop memory leaks in older browsers (IE6).

The second in-line code block is after the function definition for G.M.syncMouseWasPressed(): G.addHook('syncMouseWasPressed', G.M.syncWasPressed, 'system'); This code adds G.M.syncWasPressed as a system hook. This hook sets G.M.wasPressed = 1 for one full loop iteration after a mouseup event. This ensures that all game code will have the opportunity to detect a mouse up or mouse click event for exactly one game loop iteration.

The last in-line code block is the last line of the G.M code definitions, and it simple starts the Mouse Input manager object: G.M.start();

Previous: G.Gob Next: G.KB