Painterro

Painterro requires a saveHandler to persist images. You can save via binary multipart/form-data (most efficient) or base64 JSON.

Binary Saving (Recommended)

Use image.asBlob() to send data via FormData.

var ptro = Painterro({
  saveHandler: function (image, done) {
    var formData = new FormData();
    formData.append('image', image.asBlob());
    var xhr = new XMLHttpRequest();
    xhr.open('POST', 'http://127.0.0.1:5000/save-as-binary/', true);
    xhr.onload = xhr.onerror = function () {
      done(true); // true hides painterro, false keeps it open
    };
    xhr.send(formData);
  }
});
ptro.show();

Base64 Saving

Use image.asDataURL() to send a base64 string via JSON.

var ptro = Painterro({
    saveHandler: function (image, done) {
      var xhr = new XMLHttpRequest();
      xhr.open("POST", "http://127.0.0.1:5000/save-as-base64/");
      xhr.setRequestHeader("Content-Type", "application/json");
      xhr.send(JSON.stringify({
        image: image.asDataURL()
      }));
      xhr.onload = function (e) {
        done(true);
      }
    }
});
ptro.show();

Smart Format Selection

To optimize file size, you can check for an alpha channel and choose between PNG and JPEG:

var ptro = Painterro({
  saveHandler: function (image, done) {
    const type = image.hasAlphaChannel() ? 'image/png' : 'image/jpeg';
    const blob = image.asBlob(type);
    // upload blob...
  }
});

To use Painterro, instantiate the PainterroProc class. You must provide a params object. If an id is not provided in params, Painterro will automatically generate a unique ID and append a new container to the document.body.

Key configuration options in params include:

• id: The ID of the HTML element where Painterro should be mounted.
• defaultTool: The name of the tool to activate by default.
• hiddenTools: An array of tool names to hide from the UI.
• saveHandler: A callback function triggered when the user clicks 'save'. It receives an imageSaver object and a callback to signal completion.
• onChange: A callback triggered when changes occur, receiving an object with image (an imageSaver), operationsDone, and realesedMemoryOperations.

const painterro = new PainterroProc({
  id: 'my-editor-id',
  defaultTool: 'brush',
  saveHandler: (imageSaver, done) => {
    // Handle the saved image
    const dataUrl = imageSaver.asDataURL('image/png');
    console.log('Saved image:', dataUrl);
    
    // Call done(true) to hide the editor, or done(false) to keep it open
    done(true);
  },
  onChange: ({ image, operationsDone }) => {
    console.log(`Operations completed: ${operationsDone}`);
  }
});

The Painterro instance provides methods to control visibility, tool settings, and image manipulation.

Core Methods

• .show([openImage, initialMimeType]): Shows the instance. openImage can be false (reopen last), a URL string, or any other value to clear content. initialMimeType helps identify the file type.
• .hide(): Hides the instance.
• .save(): Programmatically triggers the save process.
• .setZoom(zoomPercentage): Sets the current zoom level.

Tool Customization

• .setColor(options): Sets the color for line or bg targets. options is [target, colorWidgetState] where colorWidgetState is { palleteColor, alpha, alphaColor }.
• .setLineWidth(): Sets line width.
• .setArrowLength(): Sets arrow width.
• .setEraserWidth(): Sets eraser width.
• .setShadowOn(boolean): Enables/disables shadow for lines or arrows.

Image Scaling

• .doScale({ width, height, scale }):
  • Match width: .doScale({width: 100})
  • Fill width and height: .doScale({width: 11, height: 15})
  • Scale factor: .doScale({ scale: 2 })

var p = Painterro();
p.show();

Painterro provides several event hooks to react to user actions. Use these to handle saving, closing, or undo/redo operations.

Event Reference

Argument Shapes

{<exportable image>}

{
  image: {
   asBlob: (type, quality) => Blob,
   asDataURL: (type, quality) => string,
   suggestedFileName: (type) => string,
   hasAlphaChannel: () => boolean,
   getOriginalMimeType: () => string,
   getWidth: () => number,
   getHeight: () => number
  }
  operationsDone: number
}

{<current history state>}

{
  prev: <history state> | undefined,
  next: <history state> | undefined,
  prevCount: number,
  sizeh: number,
  sizew: number
}

The PainterroProc constructor accepts a params object to customize the editor's behavior and appearance.

Commonly used keys:

• id: (string) The ID of the target element.
• defaultTool: (string) The tool name to activate on startup.
• hiddenTools: (string[]) Array of tool names to exclude from the toolbar.
• saveHandler: (function) (imageSaver, done) => void. Required to handle saving logic.
• onBeforeClose: (function) (hasUnsaved, doClose) => void. Allows intercepting the close action (e.g., to show a 'Save changes?' dialog).
• onClose: (function) () => void. Called when the editor is closed.
• onChange: (function) ({ image, operationsDone, realesedMemoryOperations }) => void.
• styles: (string) Custom CSS to be injected into the editor.
• backplateImgUrl: (string) URL of an image to use as a background for the canvas.
• customTools: (Array<{name: string, callBack: Function, iconUrl?: string}>) Allows adding custom tools to the toolbar.