### proscene

# Interface PSMouseGrabber

`public interface PSMouseGrabber`

Interface for objects that grab mouse focus in a PScene.

PSMouseGrabber are objects which react to the mouse cursor, usually when it hovers over them.

### How does it work ?

All the created PSMouseGrabbers are grouped in a mouse grabber pool. The PScene parse this pool, calling all the PSMouseGrabbers' `checkIfGrabsMouse(int,int,PSCamera)` methods that `setGrabsMouse(boolean)` if desired (method calls should actually be performed on concrete class instances such as PSInteractiveFrame).

When a PSMouseGrabber `grabsMouse()`, it becomes the `PScene.mouseGrabber()`. All the mouse events are then transmitted to it instead of being normally processed. This continues while `grabsMouse()` (updated using `checkIfGrabsMouse(int,int,PSCamera)`) returns `true`.

If you want to (temporarily) disable a specific PSMouseGrabbers, you can remove it from this pool using `removeFromMouseGrabberPool()`.

  ## Field Summary
  `static List` | `MouseGrabberPool`

  ## Method Summary
  `void` | `addInMouseGrabberPool()`
  `void` | `checkIfGrabsMouse(int x, int y, PSCamera camera)` Called by the PScene before they test if the PSMouseGrabber `grabsMouse()`.
  `void` | `clearMouseGrabberPool()`
  `List` | `getMouseGrabberPool()` Returns a list containing references to all the active PSMouseGrabbers.
  `boolean` | `grabsMouse()`
  `boolean` | `isInMouseGrabberPool()`
  `void` | `mouseDoubleClickEvent(MouseEvent event, PSCamera camera)` Callback method called when the PSMouseGrabber `grabsMouse()` and a mouse button is double clicked.
  `void` | `mouseMoveEvent(MouseEvent event, PSCamera camera)` Callback method called when the PSMouseGrabber `grabsMouse()` and the mouse is moved while a button is pressed.
  `void` | `mousePressEvent(MouseEvent event, PSCamera camera)` Callback method called when the PSMouseGrabber `grabsMouse()` and a mouse button is pressed.
  `void` | `mouseReleaseEvent(MouseEvent event, PSCamera camera)` Mouse release event callback method.
  `void` | `mouseWheelEvent(MouseWheelEvent event, PSCamera camera)` Callback method called when the MouseGrabber `grabsMouse()` and the mouse wheel is used.
  `void` | `removeFromMouseGrabberPool()`
  `void` | `setGrabsMouse(boolean grabs)`

## Field Details

### MouseGrabberPool

    public static final List MouseGrabberPool

## Method Details

### addInMouseGrabberPool

    public void addInMouseGrabberPool()

### checkIfGrabsMouse

    public void checkIfGrabsMouse(int x,
                                  int y,
                                  PSCamera camera)

> Called by the PScene before they test if the PSMouseGrabber `grabsMouse()`. Should `setGrabsMouse(boolean)` according to the mouse position.

> This is the core method of the PSMouseGrabber. Its goal is to update the `grabsMouse()` flag according to the mouse and PSMouseGrabber current positions, using `setGrabsMouse(boolean)`.

> `grabsMouse()` is usually set to `true` when the mouse cursor is close enough to the PSMouseGrabber position. It should also be set to `false` when the mouse cursor leaves this region in order to release the mouse focus.

> `x` and `y` are the mouse cursor coordinates ((0,0) corresponds to the upper left corner).

> A typical implementation will look like:

> `// (posX,posY) is the position of the PSMouseGrabber on screen.`
> `// Here, distance to mouse must be less than 10 pixels to activate the MouseGrabber.`
> `setGrabsMouse( PApplet.sqrt((x-posX)*(x-posX) + (y-posY)*(y-posY)) < 10);`

> If the PSMouseGrabber position is defined in 3D, use the `camera` parameter, corresponding to the calling PScene PSCamera. Project on screen and then compare the projected coordinates:

> `PVector proj = new PVector (camera.projectedCoordinatesOf(myPSMouseGrabber.frame().position());`
> `setGrabsMouse((PApplet.abs(x-proj.x) < 5) && (PApplet.(y-proj.y) < 2)); // Rectangular region`

### clearMouseGrabberPool

    public void clearMouseGrabberPool()

### getMouseGrabberPool

    public List getMouseGrabberPool()

> Returns a list containing references to all the active PSMouseGrabbers.

> Used by the PScene to parse all the PSMouseGrabbers and to check if any of them `grabsMouse()` `checkIfGrabsMouse(int,int,PSCamera)`.

> You should not have to directly use this list. Use `removeFromMouseGrabberPool()` and `addInMouseGrabberPool()` to modify this list.
> See Also:
>   `getMouseGrabberPool()`

### grabsMouse

    public boolean grabsMouse()

### isInMouseGrabberPool

    public boolean isInMouseGrabberPool()

### mouseDoubleClickEvent

    public void mouseDoubleClickEvent(MouseEvent event,
                                      PSCamera camera)

> Callback method called when the PSMouseGrabber `grabsMouse()` and a mouse button is double clicked.

### mouseMoveEvent

    public void mouseMoveEvent(MouseEvent event,
                               PSCamera camera)

> Callback method called when the PSMouseGrabber `grabsMouse()` and the mouse is moved while a button is pressed.

> This method will typically update the state of the PSMouseGrabber from the mouse displacement. See the `mousePressEvent(MouseEvent,PSCamera)` documentation for details.

### mousePressEvent

    public void mousePressEvent(MouseEvent event,
                                PSCamera camera)

> Callback method called when the PSMouseGrabber `grabsMouse()` and a mouse button is pressed.

> The PSMouseGrabber will typically start an action or change its state when a mouse button is pressed. `mouseMoveEvent(MouseEvent,PSCamera)` (called at each mouse displacement) will then update the PSMouseGrabber accordingly and `mouseReleaseEvent(MouseEvent,PSCamera)` (called when the mouse button is released) will terminate this action.

### mouseReleaseEvent

    public void mouseReleaseEvent(MouseEvent event,
                                  PSCamera camera)

> Mouse release event callback method.
> See Also:
>   `mousePressEvent(MouseEvent,PSCamera)`

### mouseWheelEvent

    public void mouseWheelEvent(MouseWheelEvent event,
                                PSCamera camera)

> Callback method called when the MouseGrabber `grabsMouse()` and the mouse wheel is used.

### removeFromMouseGrabberPool

    public void removeFromMouseGrabberPool()

### setGrabsMouse

    public void setGrabsMouse(boolean grabs)

processing library glgraphics by Andres Colubri. (c) 2008