### proscene

# Class PSInteractiveFrame

- `PSFrame`
- - `proscene.PSInteractiveFrame`

Implemented Interfaces:
  Cloneable, PSMouseGrabber

`public class PSInteractiveFrame`
`extends PSFrame`
`implements PSMouseGrabber, Cloneable`

A PSInteractiveFrame is a PSFrame that can be rotated and translated using the mouse.

It converts the mouse motion into a translation and an orientation updates. A PSInteractiveFrame is used to move an object in the scene. Combined with object selection, its PSMouseGrabber properties and a dynamic update of the scene, the PSInteractiveFrame introduces a great reactivity in your processing applications.

  ## Nested Class Summary
  `class` | `PSInteractiveFrame.CoordinateSystemConvention` This enum defines the coordinate system convention which is defined as `LEFT_HANDED` by default (processing standard).

  ## Constructor Summary
  `PSInteractiveFrame()` Default constructor.

  ## Method Summary
  `void` | `addInMouseGrabberPool()` Adds the PSMouseGrabber in the `mouseGrabberPool()`.
  `void` | `checkIfGrabsMouse(int x, int y, PSCamera camera)` Implementation of the PSMouseGrabber main method.
  `void` | `clearMouseGrabberPool()` Clears the `mouseGrabberPool()`.
  `PSInteractiveFrame` | `clone()` Implementation of the clone method.
  `PSInteractiveFrame.CoordinateSystemConvention` | `coordinateSystemConvention()` Returns the coordinate system convention used by this PSInteractiveFrame.
  `List` | `getMouseGrabberPool()` See `PSMouseGrabber.getMouseGrabberPool()`.
  `boolean` | `grabsMouse()` Returns `true` when the PSMouseGrabber grabs the PScene's mouse events.
  `boolean` | `isInMouseGrabberPool()` Returns `true` if the PSMouseGrabber is currently in the `mouseGrabberPool()` list.
  `boolean` | `isSpinning()` Returns `true` when the PSInteractiveFrame is spinning.
  `void` | `mouseDoubleClickEvent(MouseEvent event, PSCamera camera)` Overloading of `PSMouseGrabber.mouseDoubleClickEvent(MouseEvent,PSCamera)`.
  `static List` | `mouseGrabberPool()` Static version of `getMouseGrabberPool()`.
  `void` | `mouseMoveEvent(MouseEvent event, PSCamera camera)` Modifies the PSInteractiveFrame according to the mouse motion.
  `void` | `mousePressEvent(MouseEvent event, PSCamera camera)` Initiates the PSInteractiveFrame mouse manipulation.
  `void` | `mouseReleaseEvent(MouseEvent event, PSCamera camera)` Stops the PSInteractiveFrame mouse manipulation.
  `void` | `mouseWheelEvent(MouseWheelEvent event, PSCamera camera)` Overloading of `PSMouseGrabber.mouseWheelEvent(MouseWheelEvent,PSCamera)`.
  `void` | `removeFromMouseGrabberPool()` Removes the PSMouseGrabber from the `mouseGrabberPool()`.
  `float` | `rotationSensitivity()` Returns the influence of a mouse displacement on the PSInteractiveFrame rotation.
  `void` | `setCoordinateSystemConvention(PSInteractiveFrame.CoordinateSystemConvention c)` Defines the coordinate system convention of this PSInteractiveFrame, i.e., how mouse displacements are mapped into the virtual world.
  `void` | `setGrabsMouse(boolean grabs)` Sets the `grabsMouse()` flag.
  `void` | `setRotationSensitivity(float sensitivity)` Defines the `rotationSensitivity()`.
  `void` | `setSpinningQuaternion(PSQuaternion spinningQuaternion)` Defines the `spinningQuaternion()`.
  `void` | `setSpinningSensitivity(float sensitivity)` Defines the `spinningSensitivity()`.
  `void` | `setTranslationSensitivity(float sensitivity)` Defines the `translationSensitivity()`.
  `void` | `setWheelSensitivity(float sensitivity)` Defines the `wheelSensitivity()`.
  `void` | `spin()` Rotates the PSInteractiveFrame by its `spinningQuaternion()`.
  `PSQuaternion` | `spinningQuaternion()` Returns the incremental rotation that is applied by `spin()` to the PSInteractiveFrame orientation when it `isSpinning()`.
  `float` | `spinningSensitivity()` Returns the minimum mouse speed required (at button release) to make the PSInteractiveFrame `spin()`.
  `void` | `startSpinning(int updateInterval)` Starts the spinning of the PSInteractiveFrame.
  `void` | `stopSpinning()` Stops the spinning motion started using `startSpinning(int)`.
  `float` | `translationSensitivity()` Returns the influence of a mouse displacement on the PSInteractiveFrame translation.

## Constructor Details

### PSInteractiveFrame

    public PSInteractiveFrame()

> Default constructor.

> The `translation()` is set to (0,0,0), with an identity `rotation()` (0,0,0,1) (see PSFrame constructor for details). The different sensitivities are set to their default values (see `rotationSensitivity()` , `translationSensitivity()`, `spinningSensitivity()` and `wheelSensitivity()`).

## Method Details

### addInMouseGrabberPool

    public void addInMouseGrabberPool()

> Adds the PSMouseGrabber in the `mouseGrabberPool()`.

> All created PSMouseGrabber are automatically added in the `mouseGrabberPool()` by the constructor. Trying to add a PSMouseGrabber that already `isInMouseGrabberPool()` has no effect.

> Use `removeFromMouseGrabberPool()` to remove the PSMouseGrabber from the list, so that it is no longer tested with `checkIfGrabsMouse(int,int,PSCamera)` by the PScene, and hence can no longer grab mouse focus. Use `isInMouseGrabberPool()` to know the current state of the PSMouseGrabber.

### checkIfGrabsMouse

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

> Implementation of the PSMouseGrabber main method.

> The PSInteractiveFrame `grabsMouse()` when the mouse is within a 10 pixels region around its `PSCamera.projectedCoordinatesOf(PVector)` `position()`.

### clearMouseGrabberPool

    public void clearMouseGrabberPool()

> Clears the `mouseGrabberPool()`.

> Use this method only if it is faster to clear the `mouseGrabberPool()` and then to add back a few PSMouseGrabbers than to remove each one independently. Use PScene.setMouseTracking(false) instead if you want to disable mouse grabbing.

### clone

    public PSInteractiveFrame clone()

> Implementation of the clone method.

> Calls `PSFrame.clone()` and makes a deep copy of the remaining object attributes except for `prevConstraint` (which is shallow copied).
> See Also:
>   `PSFrame.clone()`

### coordinateSystemConvention

    public PSInteractiveFrame.CoordinateSystemConvention coordinateSystemConvention()

> Returns the coordinate system convention used by this PSInteractiveFrame.
> See Also:
>   `setCoordinateSystemConvention(PSInteractiveFrame.CoordinateSystemConvention)`

### getMouseGrabberPool

    public List getMouseGrabberPool()

> See `PSMouseGrabber.getMouseGrabberPool()`.

### grabsMouse

    public boolean grabsMouse()

> Returns `true` when the PSMouseGrabber grabs the PScene's mouse events.

> This flag is set with `setGrabsMouse(boolean)` by the `checkIfGrabsMouse(int,int,PSCamera)` method.

### isInMouseGrabberPool

    public boolean isInMouseGrabberPool()

> Returns `true` if the PSMouseGrabber is currently in the `mouseGrabberPool()` list.

> Default value is `true`. When set to `false` using `removeFromMouseGrabberPool()`, the PScene no longer `checkIfGrabsMouse(int,int,PSCamera)` on this PSMouseGrabber. Use `addInMouseGrabberPool()` to insert it back.

### isSpinning

    public final boolean isSpinning()

> Returns `true` when the PSInteractiveFrame is spinning.

> During spinning, `spin()` rotates the PSInteractiveFrame by its `spinningQuaternion()` at a frequency defined when the PSInteractiveFrame `startSpinning(int)`.

> Use `startSpinning(int)` and `stopSpinning()` to change this state. Default value is `false`.

### mouseDoubleClickEvent

    public void mouseDoubleClickEvent(MouseEvent event,
                                      PSCamera camera)

> Overloading of `PSMouseGrabber.mouseDoubleClickEvent(MouseEvent,PSCamera)`.

> Left button double click aligns the PSInteractiveFrame with the `camera` axis (see `alignWithFrame(PSFrame)`). Right button projects the PSInteractiveFrame on the `camera` view direction.

### mouseGrabberPool

    public static List mouseGrabberPool()

> Static version of `getMouseGrabberPool()`.
> Returns:
>   `PSMouseGrabber.MouseGrabberPool`

### mouseMoveEvent

    public void mouseMoveEvent(MouseEvent event,
                               PSCamera camera)

> Modifies the PSInteractiveFrame according to the mouse motion.

> Actual behavior depends on mouse bindings. See the PScene documentation for details.

> The `camera` is used to fit the mouse motion with the display parameters.
> See Also:
>   `PSCamera.screenWidth()`, `PSCamera.screenHeight()`, `PSCamera.fieldOfView()`

### mousePressEvent

    public void mousePressEvent(MouseEvent event,
                                PSCamera camera)

> Initiates the PSInteractiveFrame mouse manipulation. Overloading of `PSMouseGrabber.mousePressEvent(MouseEvent,PSCamera)`. The mouse behavior depends on which button is pressed.
> See Also:
>   `mouseMoveEvent(MouseEvent,PSCamera)`, `mouseReleaseEvent(MouseEvent,PSCamera)`

### mouseReleaseEvent

    public void mouseReleaseEvent(MouseEvent event,
                                  PSCamera camera)

> Stops the PSInteractiveFrame mouse manipulation.

> Overloading of `PSMouseGrabber.mouseReleaseEvent(MouseEvent,PSCamera)`.

> If the action was ROTATE MouseAction, a continuous spinning is possible if the speed of the mouse cursor is larger than `spinningSensitivity()` when the button is released. Press the rotate button again to stop spinning.
> See Also:
>   `startSpinning(int)`, `isSpinning()`

### mouseWheelEvent

    public void mouseWheelEvent(MouseWheelEvent event,
                                PSCamera camera)

> Overloading of `PSMouseGrabber.mouseWheelEvent(MouseWheelEvent,PSCamera)`.

> Using the wheel is equivalent to a ZOOM MouseAction.
> See Also:
>   `setWheelSensitivity(float)`

### removeFromMouseGrabberPool

    public void removeFromMouseGrabberPool()

> Removes the PSMouseGrabber from the `mouseGrabberPool()`.

> See `addInMouseGrabberPool()` for details. Removing a PSMouseGrabber that is not in `mouseGrabberPool()` has no effect.

### rotationSensitivity

    public final float rotationSensitivity()

> Returns the influence of a mouse displacement on the PSInteractiveFrame rotation.

> Default value is 8.0. With an identical mouse displacement, a higher value will generate a larger rotation (and inversely for lower values). A 0.0 value will forbid PSInteractiveFrame mouse rotation (see also `constraint()`).
> See Also:
>   `setRotationSensitivity(float)`, `translationSensitivity()`, `spinningSensitivity()`, `wheelSensitivity()`

### setCoordinateSystemConvention

    public void setCoordinateSystemConvention(PSInteractiveFrame.CoordinateSystemConvention c)

> Defines the coordinate system convention of this PSInteractiveFrame, i.e., how mouse displacements are mapped into the virtual world.
> See Also:
>   `coordinateSystemConvention()`

### setGrabsMouse

    public void setGrabsMouse(boolean grabs)

> Sets the `grabsMouse()` flag. Normally used by `checkIfGrabsMouse(int,int,PSCamera)`.

### setRotationSensitivity

    public final void setRotationSensitivity(float sensitivity)

> Defines the `rotationSensitivity()`.

### setSpinningQuaternion

    public final void setSpinningQuaternion(PSQuaternion spinningQuaternion)

> Defines the `spinningQuaternion()`. Its axis is defined in the PSInteractiveFrame coordinate system.

### setSpinningSensitivity

    public final void setSpinningSensitivity(float sensitivity)

> Defines the `spinningSensitivity()`.

### setTranslationSensitivity

    public final void setTranslationSensitivity(float sensitivity)

> Defines the `translationSensitivity()`.

### setWheelSensitivity

    public final void setWheelSensitivity(float sensitivity)

> Defines the `wheelSensitivity()`.

### spin

    public void spin()

> Rotates the PSInteractiveFrame by its `spinningQuaternion()`. Called by a timer when the PSInteractiveFrame `isSpinning()`.

### spinningQuaternion

    public final PSQuaternion spinningQuaternion()

> Returns the incremental rotation that is applied by `spin()` to the PSInteractiveFrame orientation when it `isSpinning()`.

> Default value is a `null` rotation (identity PSQuaternion). Use `setSpinningQuaternion(PSQuaternion)` to change this value.

> The `spinningQuaternion()` axis is defined in the PSInteractiveFrame coordinate system. You can use `PSFrame.transformOfFrom(PVector,PSFrame)` to convert this axis from an other PSFrame coordinate system.

### spinningSensitivity

    public final float spinningSensitivity()

> Returns the minimum mouse speed required (at button release) to make the PSInteractiveFrame `spin()`.

> See `spin()`, `spinningQuaternion()` and `startSpinning(int)` for details.

> Mouse speed is expressed in pixels per milliseconds. Default value is 0.3 (300 pixels per second). Use setSpinningSensitivity() to tune this value. A higher value will make spinning more difficult (a value of 100.0 forbids spinning in practice).
> See Also:
>   `setSpinningSensitivity(float)`, `translationSensitivity()`, `rotationSensitivity()`, `wheelSensitivity()`

### startSpinning

    public void startSpinning(int updateInterval)

> Starts the spinning of the PSInteractiveFrame.

> This method starts a timer that will call `spin()` every `updateInterval` milliseconds. The PSInteractiveFrame `isSpinning()` until you call `stopSpinning()`.

### stopSpinning

    public final void stopSpinning()

> Stops the spinning motion started using `startSpinning(int)`. `isSpinning()` will return `false` after this call.

### translationSensitivity

    public final float translationSensitivity()

> Returns the influence of a mouse displacement on the PSInteractiveFrame translation.

> Default value is 1.0. You should not have to modify this value, since with 1.0 the PSInteractiveFrame precisely stays under the mouse cursor.

> With an identical mouse displacement, a higher value will generate a larger translation (and inversely for lower values). A 0.0 value will forbid PSInteractiveFrame mouse translation (see also `constraint()`).

> Note: When the PSInteractiveFrame is used to move a Camera (see the PSInteractiveCameraFrame class documentation), after zooming on a small region of your scene, the camera may translate too fast. For a camera, it is the PSCamera.revolveAroundPoint() that exactly matches the mouse displacement. Hence, instead of changing the `translationSensitivity()`, solve the problem by (temporarily) setting the `PSCamera.revolveAroundPoint()` to a point on the zoomed region).
> See Also:
>   `setTranslationSensitivity(float)`, `rotationSensitivity()`, `spinningSensitivity()`, `wheelSensitivity()`

processing library glgraphics by Andres Colubri. (c) 2008