figureone
    Preparing search index...

    Class default

    Gesture rectangle.

    This primitive creates a rectangle within which pan and zoom gestures can be captured (from mouse and touch events) and transformed into pan and zoom values. The pan and zoom values can be used to change Scene objects directly, or used for some custom purpose.

    The pan and zoom values are relative to the gesture rectangle and the Scene it is drawn with.

    Performing a drag gesture over half the width of the rectangle, will create a pan value that is half the width of the rectangle.

    Performing a 2x zoom gesture at a point within the rectangle will create a pan value that is the delta between the original rectangle center and the center of the new zoomed rectangle, and a magnification value of 2.

    Any combination of zoom and pan can be expressed as a pan value, that offsets the original rectangle such that when it is then zoomed, the zoom position will be at the same relative position of the original and zoomed rectangle.

    Whenever a gesture changes the pan or zoom, then 'pan' or 'zoom' notifications will be published by the primitive's NotificationManger (element.notifications).

    The handled gestures are:

    • Mouse wheel change (often used for zooming and panning with a mouse)
    • Drag (often used for panning with touch devices or a mouse)
    • Pinching (often used for zooming and panning on touch devices)

    A pan is an offset in xy.

    The gestures that can generate pan events are:

    • Mouse click then drag
    • Finger touch then drag (touch devices)
    • Mouse wheel change

    For the mouse click and drag, and finger touch and drag gestures, the pan value tracks the change in position of the mouse/finger in the gesture primitive rectangle. For example, if the rectangle has a width of 2, and the mouse or touch moves across half the width of the rectangle, then the pan offset will be 1.

    For the mouse wheel change, a wheelSensitivity value is used to speed up or slow down the pan.

    When a pan event happens, a 'pan' notification is published. The parameter passed to any subscribers is the pan offset value, but if more information is needed (like the pan delta from the last pan) then getPan() can be called.

    A zoom is a magnification at a point in the rectangle. The zoom point will stay stationary, while the other points around it spread out (when zooming in) or compress in (when zooming out). The zoom event thus includes a pan offset to ensure the zoom point stays stationary, as well as a magnification value.

    The gestures that can generate zoom events are:

    • Mouse wheel vertical change
    • Finger touch pinch

    A wheelSensitivity or pinchSenstivity value is used to speed up or slow down zooming.

    When a zoom event happens, a 'zoom' notification is published. The parameters passed to any subscribers are the zoom magnification value and pan offset, but if more information is needed (like the zoom position) then getZoom() can be called.

    Zoom and pan events can be used in many ways. One of the most common ways will be to change a Scene that contains one or more FigureElements allowing a user to pan or zoom through the scene.

    In such cases, the zoomScene() and panScene() methods can be used to do this directly.

    Alternately, a changeScene can be defined which will be automatically panned and zoomed by this primitive.

    In general the scene that is being used to draw the gesture primitive should not be panned or zoomed by the gesture primitive, as this will produce unexpected results (especially when panning). If the gesture primitive is setup to change the same scene as it uses itself, then it will assign itself a duplicate scene.

    // Gesture primitive pans and zooms a figure scene
    const figure = new Fig.Figure({ color: [1, 0, 0, 1] });

    // Elements within the figure to zoom and pan
    figure.add([
      { make: 'rectangle', width: 0.2, height: 0.2, position: [-0.3, 0] },
      { make: 'triangle', width: 0.2, height: 0.2, position: [0.02, -0.025] },
      { make: 'ellipse', width: 0.2, height: 0.2, position: [0.3, 0] },
    ])

    // Gesture Primitive
    figure.add({
      make: 'gesture',
      changeScene: figure.scene,
      pan: true,
      zoom: true,
    });

    // Using zoom and pan notifications when the gestures are confied
    // to a green rectangle
    const figure = new Fig.Figure({ color: [1, 0, 0, 1] });

    const gesture = figure.add({
      make: 'gesture',
      color: [0, 1, 0, 0.3],
      width: 0.5,
      height: 1,
      pan: true,
      zoom: true,
    });

    gesture.notifications.add(
      'pan', offset => console.log('Pan: ', offset.x, offset.y),
    );
    gesture.notifications.add(
      'zoom', (mag, offset) => console.log('Zoom: ', mag, offset.x, offset.y),
    );

    Hierarchy (View Summary)

    Index

    Methods

    setPosition setRotation setScale setTransform dim setDimColor undim setScenario saveScenario getPath pulse transformPoint spaceTransformMatrix getBorder getScale getRotation getPosition setFigurePosition setPositionToElement setTouchable setMove setMovable toggleShow getTransform isMoving isAnimating setAngleToDraw setColor show hide reset setScene setChangeScene zoomElement zoomScene panScene setZoomOptions setPanOptions setZoom setPan getZoom getPan

    Methods

    • Conveniently set the first scale of the element's transform.

      Parameters

      • scaleOrX: number | TypeParsablePoint

        horizontal scale - either define as full x-y point, or as a number. If scaleOrX is a number and y is null, then both x and y will be equally scaled

      • y: number | null = null

        y coordinate if scaleOrX is a number (null)

      • z: number = 1

      Returns void

    • Pulse element.

      An element can be pulsed in scale, a rotation or a translation.

      The scale pulse can either be a single pulse, or a number of copies with a range of scales - which has the effect of making regular polygons thick.

      Either pass in a callback, or an options object defining the pulse and callback.

      Parameters

      • optionsOrDone: OBJ_Pulse | (() => void) | null = null

      Returns void

    • Transform a point between 'draw', 'local', 'figure', 'gl' and 'pixel' spaces.

      plane is only needed when converting from pixel space (a 2D space) to 'figure', 'local' or 'draw' spaces (a 3D space). A ray from the pixel is drawn into the screen and the intersection with the defined plane is returned.

      'pixel' to 'gl' is also a 2D to 3D transformation, but in this case the XY plane at z = 0 is used in gl space.

      Parameters

      • point: TypeParsablePoint
      • fromSpace: "figure" | "pixel" | "gl" | "local" | "draw"

        space to convert point from

      • toSpace: "figure" | "pixel" | "gl" | "local" | "draw"

        space to convert point to

      • toSpacePlane: TypeParsablePlane = ...

      Returns Point

    • Return the first rotation in the element's transform.

      Parameters

      • normalize: "" | "0to360" | "-180to180" = ''

        how to normalize the returned angle where '' returns the raw angle

      Returns number

      scale

    • Get position of element

      By default the first translation of the element's transform is returned. This is effectively the element's location in 'local' coordinates.

      The position of the element relative to its horizontal and vertical bounds can also be returned. Use xAlign to find the x coordinate of the left, center, right or percentage width from left of the element. Use yAlign to find the bottom, middle, top or percentage height from bottom of the element.

      Parameters

      • space: TypeCoordinateSpace = 'local'

        the space to return the position in

      • xAlign: number | "left" | "right" | "center" | "location" = 'location'

        horizontal alignment of position. Use a number to define the horizontal position in percentage width from the left.

      • yAlign: number | "top" | "bottom" | "middle" | "location" = 'location'

        vertical alignment of position. Use a number to define the vertical position in percentage height from the bottom.

      Returns Point

    • Set angle to draw.

      Some primitive elements can be partially drawn to some angle.

      An angle of -1 represents the maximum angle allowed by the primitive.

      Parameters

      • angle: number = -1

        Angle to draw

      Returns void

    • Change the position and scale of an element to simulate it zooming.

      Note, the element will stay in the same space it was previously, and therefore moving it will be moving it in the same space.

      Often a better way to zoom an element (especially if more than one and interactivity is being used) is to zoom the scene the element(s) belong to.

      Parameters

      Returns void

    • Set zoom manually.

      Zoom magnitude can be set with zoom position or pan offset. Either a position or pan should be used (not both).

      NB: if manually creating positions or offsets, the position (p) to offset (o) for some zoom (z) conversion is:

       o = -(p / z - p)

 p = -o / (1/z - 1)

      Parameters

      Returns void

    • Returns {
          mag: number;
          offset: Point;
          last: {
              mag: number;
              normPosition: Point;
              position: Point;
              angle: number;
              distance: number;
          };
          current: {
              position: Point;
              normPosition: Point;
              angle: number;
              distance: number;
          };
      }

    Settings

    Member Visibility

    On This Page

    PanZoom
    Methods