docs/ImageEditor-2.0.0-Migration-guide.md

There are a lot of changes for ImageEditor 2.0.0 including API changes and new features. This migration document will be nicely moving to v2.0.0.

New drawing mode change APIs

• New APIs

  • startDrawingMode(modeName) starts a drawing mode
  • stopDrawingMode() stops current drawing mode and back to 'NORMAL' mode
  • getDrawingMode() returns current drawing mode name.
  • getCropzoneRect() returns cropping rect in 'CROPPER' drawing mode.
  • crop(rect) crops image given area

• Removed APIs

  • startCropping, endCropping
  • startDrawingShapeMode, endDrawingShapeMode
  • startFreeDrawing, endFreeDrawing
  • startLineDrawing, endLineDrawing
  • startTextMode, endTextMode
  • endAll
  • endCropping is divided into three APIs

var rect = imageEditor.getCropzoneRect();
imageEditor.crop(rect).then(() => {
  imageEditor.stopDrawingMode();
});

Changed APIs

• removeActiveObject() ==> removeObject(id)
• getCurrentState() ==> getDrawingMode()

Use object is with all drawing APIs

• In versions prior to 1.4.1, the users should select an object and manipulate it which is called 'active object'. There was no way to manipulate non-selected object. After 2.0.0 version, you can manipulate not only selected object, but also non-selected objects by receiving the Object Id.
• To get the Object Id, use the parameter.id in Promise.then() and the event callback.

/*
{
    id: number
    type: type
    left: number,
    top: number,
    width: number,
    fill: string
    stroke: string
    strokeWidth: number
    opacity: number,

    // text object
    text: string,
    fontFamily: string,
    fontSize: number,
    fontStyle: string,
    fontWeight: string,
    textAlign: string,
    textDecoration: string
}
*/
imageEditor.on('objectActivated', function (props) {
  console.log(props);
  console.log(props.type);
  console.log(props.id);
});

imageEditor
  .addShape('circle', {
    fill: 'red',
    stroke: 'blue',
    strokeWidth: 3,
    rx: 10,
    ry: 100,
    isRegular: false,
  })
  .then(function (props) {
    console.log(props.id);

    imageEditor.changeShape(props.id, {
      // change circle
      fill: '#FFFF00',
      strokeWidth: 10,
    });
  });

Support Promise API

• All drawing APIs returns Promise and supports Undo/Redo.
• List of related APIs
  • addIcon, addImageObject, addShape, changeIconColor
  • changeShape, addText, changeText, changeTextStyle,
  • resizeCanvasDimension, applyFilter, removeFilter,
  • clearObjects, flipX, flipY, loadImageFromFile,
  • loadImageFromURL, redo, undo, removeObject,
  • resetFlip, rotate, setAngle, crop,
  • setObjectPosition, setObjectProperties

Changed event type

As-Is	To-Be	Change	Why & Purpose
activateText	addText	renamed	when mousedown event occurs in 'TEXT' drawing mode
addObject	-	removed	unnecessary
adjustObject	objectMoved	renamed changed	when user drags an object
adjustObject	objectScaled	renamed changed	when object is being scaled
applyFilter	-	removed	Replace it to applyFilter() Promise API
clearImage	-	removed	Replace it to loadImageFromFile(), loadImageFromURL() Promise API
clearObjects	-	removed	Replace it to clearObjects() Promise API
editText	textEditing	renamed	when textbox is being edited
emptyRedoStack	redoStackChanged	renamed changed	Replace it to redoStackChanged event with length 0
emptyUndoStack	undoStackChanged	renamed changed	Replace it to undoStackChanged event with length 0
endCropping	-	removed	unnecessary
endFreeDrawing	-	removed	unnecessary
endLineDrawing	-	removed	unnecessary
flipImage	-	removed	Replace it to flipX(), flipY() Promise API
loadImage	-	removed	Replace it to loadImageFromFile(), loadImageFromURL() Promise API
mousedown	mousedown	remained	just mousedown
pushRedoStack	redoStackChanged	renamed changed	redo change event
pushUndoStack	undoStackChanged	renamed changed	undo change event
removeObject	-	removed	Replace it to removeObject() Promise API
rotateImage	-	removed	Replace it to rotate(), setAngle() Promise API
selectObject	objectActivated	renamed changed	when user selects an object
startCropping	-	removed	unnecessary
startFreeDrawing	-	removed	unnecessary
startLineDrawing	-	removed	unnecessary