img-butler

A React-based image manipulator, allowing users to examine a source image using a mouse, trackpad, or touch screen.

useImgButler()

Produces an tag. This contains a canvas to display and interact with your image.

Options:

| Name | Type | Default | Description | Notes | |-------------------|-------------|---------------------|---------------------------------------------------------------------------|--------------------------------------------------------------| | src | string | pipa-fria.png | The image's source URI. | | | title | string | undefined | A title to be drawn above the image as an <h2> element. | | | desc | string | undefined | A description to be drawn underneath the image as a <caption> element. | | | defaultPosition | object | [x:0,y:0] | Default position values for this image. | A position value of {x:0,y:0} is centered. | | positionBounds | object | [left:-100, right:100, top:100, bottom:-100] | The smallest and largest allowed values for this image's position. | A value of undefined indicates no bounds. Note that as zoomState changes, these bounds will also change to maintain relatively consistent bounds within the frame. | | defaultZoom | bool | 1 | Default zoom value for this image. | A zoom value of 1 guarantees the image is fully visible. | | zoomBounds | object | [min:0.5,max:5] | The smallest and largest allowed values for this image's zoom. | A value of undefined indicates no bounds. | | canDrag | bool | true | Can the user move the image using the drag gesture? | | | canPinch | bool | true | Can the user zoom the image using the pinch gesture? | | | points | Array<Point> | [] | A list of points to display on the map. See <Point/> below | | | onGesture | function | () => {} | Function callback for responding to Gesture events. See GestureEvent below| |

<Point />

This is a point that can be displayed on the map. It contains an optional tag, which may be toggled when the point is clicked.

Options:

| Name | Type | Default | Description | Notes | |-------------------|-------------|---------------------|---------------------------------------------------------------------------|--------------------------------------------------------------| | xPercentage | number | undefined | describes how far along the image's x axis the point should be placed | 0 is the left edge. 100 is the right edge | | yPercentage | number | undefined | describes how far along the image's y axis the point should be placed | 0 is the top edge. 100 is the bottom edge | | popup | <Popup/> | undefined | optional popup to open when the point is clicked. See <Popup/> below | | | size | number | 4 | describes the size of the point | | | sizeUnits | string | % | describes the units for size, relative to image width | size={4} sizeUnits={%} means the point is 4% of image width| | backroundColor | string | transparent | the background color for the point. generally will be transparent | | | iconSrc | string | star_PNG41474.png | The point's source URI, or text to display | | | iconType | string | img | The point's source URI | one of img, text. text allows you to use unicode | | startOpen | bool | true | If it has a popup, whether that popup should open when the point is first created| | | closeEvents | Array<DRAWABLE_EVENT>| [POPUP_OPEN, CREATE, ESCAPE, ENTER, CLICK, DRAWING_END, DRAWING_START]| The events that should cause the popup to close | See DrawableEvent below|
| onPopupOpen | function | () => {} | Optional callback that will be triggered when the popup opens | | | onPopupClose | function | () => {} | Optional callback that will be triggered when the popup closes | |

<Popup />

A popup that a <Point /> can accept. It can be used to encase other React tags.

Example

<Popup>
  <h1> hello! </h1>
  <input
    type="text"
    value={inputText}
    onChange={(e) => setInputText(e.target.value)}
  />
  <p> have a nice day! </p>
</Popup>

GestureEvent

Fired when a user-iput gesture detected on the image.

Fields:

| Name | Type | Description | Notes | |-------------------|----------------------|---------------------------------------------------------------------------|--------------------------------------------------------------| | eventType | MOTION | The type of event triggered | See MOTION Event Types options below | | x | number | where on the image's x axis the gesture occurs | | | y | number | where on the image's y axis the gesture occurs | | | target | number | where on the image's y axis the gesture occurs | |

MOTION Event Types:

| Name |Description | |-------------------|--------------------------------------------------------------------------------| | ZOOM_IN | Fired when a user zooms in on the image | | ZOOM_OUT | Fired when a user zooms out on the image | | ZOOM_RESET | Fired when a user resets the image's zoom level | | MOVE_UP | Fired when a user translates the images towards the top of the screen | | MOVE_DOWN | Fired when a user translates the images towards the bottom of the screen | | MOVE_LEFT | Fired when a user translates the images towards the left side of the screen | | MOVE_RIGHT | Fired when a user translates the images towards the right side of the screen | | MOVE_RESET | Fired when a user resets the x, y position of the image |

DrawableEvent

| Name | Type | Description | Notes | |-------------------|----------------------|---------------------------------------------------------------------------|--------------------------------------------------------------| | eventType | DRAWABLE_EVENT | The type of event triggered | See DRAWABLE_EVENT Event Types options below | | id | string | the id of the Drawable object firing this event | |

DRAWABLE_EVENT Event Types:

| Name |Description | |-------------------|--------------------------------------------------------------------------------| | POPUP_OPEN | Fired when a drawable's popup opens | | POPUP_CLOSE | Fired when a drawables's popup closes | | CREATE | Fired when a drawable is created | | ESCAPE | Fired when the escape key is input by user | | ENTER | Fired when the enter key is input by user | | CLICK | Fired when the user clicks on a Drawable | | DRAWING_END | Fired when isDrawing becomes false | | DRAWING_START | Fired when isDrawing becomes true |

External Control

The high-level concept is to call useImgButler() to create a <ImgButler/> tag, and populate it with the fields and/or objects you want.

Example:

const title = "My Cool Map";
const desc = "A map that is super cool";
const popup = <Popup>
  <p> popping up! </p>
</Popup>;
const points = [
  <Point
    xPercentage={50}
    yPercentage={50}
    popup={popup}
    startOpen={true}
  />
];
const src = require("../assets/my-map.png");
const onGesture = (e) => console.log(e);
const imgButler = useImgButler({ title, desc, points, src, onGesture });
...
<div className="app-scene">
  {imgButler}
</div>

Exports

The following items are exports of the img-butler package: | Name |Description | |-------------------|----------------------------------------------------| | MOTION | See above | | DRAWABLE_EVENT | See above | | GestureEvent | See above | | DrawableEvent | See above | | useImgButler | See above | | Point | See above | | Popup | See above |