loading

Editor API

Overview

Pixo allows you to manipulate the image and Pixo’s Plugin Settings from your application, thanks to the exec command.

The interface of exec is the following:

pixo_instance.exec('COMMAND', { param: 'value' })

where pixo_instance is a reference to an object instance of Pixo.Bridge:

const pixo_instance = new Pixo.Bridge({ option: 'value' })

Check the documentation for Pixo.Bridge constructor.

Because of its asynchronous nature, exec returns a Promise, which can be awaited, so your program knows when the operation is completed:

pixo_instance.exec('COMMAND')
    .then(state => console.log('COMMAND completed', { state }))

The promise is resolved with the updated state of Pixo Editor.

The cool part here is that instead of awaiting every single operation, you can chain a bunch of operations, and this will guarantee you that they will be executed in the same order they are invoked:

pixo_instance.exec('COMMAND1')
   .exec('COMMAND2')
   .exec('COMMANDN')

But even cooler is the fact that you don’t have to chain the commands, and they will still be executed in the right order, one after another:

pixo_instance.exec('COMMAND1');
pixo_instance.exec('COMMAND2');
pixo_instance.exec('COMMANDN');

State

The State object contains information about the current state of Pixo Editor: the currently active plugin, property values of every plugin, history, global settings, error state, etc. You can use the State object to update your external editing controls for Pixo Editor.

Subscribing to changes

You can get the new state by providing onStateChange callback to Pixo.Bridge constructor:

const pixo = new Pixo.Bridge({
    //... other options
    onStateChange: state => {
        //do something with the updated state
    },
});

The onStateChange callback will be executed every time the state changes, no matter if the change is triggered by the user within Pixo Editor or by the exec() method.

Receiving the new state

The exec() method will return a promise, which resolves when the command is executed, with the updated state:

pixo_instance.exec('ANY_COMMAND')
    .then(state => console.log('ANY_COMMAND completed', { state }))

There is also a GET_STATE command which returns current state.

Updating the state

Updating state happens through the SET_STATE command, which accept the new state as parameter. The new state is merged into the old/current state recursively, so this means that you may pass a partial state object:

const newstate = { active_plugin: 'draw' };
pixo_instance.exec('SET_STATE', { state: new_state });

Structure

The state is a JavaScript Object having the following structure:

  • active_plugin String one of the following: “adjustments”, “filters”, “draw”, “crop”, “stickers”, “text”, “transform”, “frame”, “blur”, “shape”
  • collapsed_panel Boolean whether the Property Panel is collapsed or not
  • plugins Object containing data for most of Pixo’s feature plugins; has the following structure:
    • crop Object with the following structure:
      • orientation String one of the following: “portrait”, “landscape”
      • preset Number fixed crop ratio preset, e.g. 16 / 9, 4 / 3, etc.
      • ratio_locked Boolean
    • draw Object click to see structure
    • adjustments Object click to see structure
    • text Object click to see structure
    • filter String click to see possible values
    • frame Number selected frame index
    • shape String one of the following: “square”, “rectangle”, “circle”, “ellipse”, “roundsquare”, “roundrect”
  • history Object with the following structure:
    • length Number total history length
    • current Number current index in the history
  • error String error message (if there is an error, otherwise will be "")
  • track_history Boolean whether history is tracked or not

Command Index

Global operations

Getting & setting the State

pixo_instance.exec('GET_STATE')
    .then(state => { console.log('current state', state) });

When updating the state, the new state is merged into the old/current state recursively, so this means that you may pass a partial state object:

pixo_instance.exec('SET_STATE', { state: { active_plugin: 'draw' } });

More information about Pixo’s State.

Activate Plugin

pixo_instance.exec('ACTIVATE_PLUGIN', { plugin: 'filters' })

See list of available plugins.

Undo/Redo

pixo_instance.exec('UNDO')
pixo_instance.exec('REDO')

Enable/Disable history tracking

Pixo allows you to disable history (undo/redo) tracking, and enable it back at any time:

pixo_instance.exec('TRACK_HISTORY', { track_history: false })

Plugin operations

Select Filter

pixo_instance.exec('SELECT_FILTER', { name: 'Amarok' })

List of available filters:
  • None
  • Natural
  • Amarok
  • Klarendon
  • Larc
  • Mayfare
  • Autumn
  • Nightfall
  • Sepia
  • Grayscale
  • BlackWhite
  • Brownie
  • Vintage
  • Kodachrome
  • Technicolor
  • Polaroid
  • Reddish
  • Redify
  • Convolute-Sharpen
  • Convolute-ExtraSharp
  • Convolute-Light
  • Convolute-Dark
  • Convolute-Blur
  • Convolute-Emboss
  • Invert
  • Distressed

Insert Sticker

pixo_instance.exec('INSERT_STICKER', { src: 'https://pixoeditor.com/editor/shared/images/logo.png' })

Add Text

pixo_editor.exec('ADD_TEXT', { text: 'Lorem Ipsum' })

Set Text Property

pixo_editor.exec('SET_TEXT_PROPERTY', { propname: 'fontFamily', value: 'Arial' })

List of available property names and their possible values:
  • fontFamily String one of the following:
    • Arial
    • Verdana
    • Times New Roman
    • Georgia
    • Comic Sans MS
    • Pacifico
    • Roboto Condensed
    • Oswald
    • PT Sans
    • Open Sans Condensed
    • Ubuntu
    • PT Sans Narrow
    • Lobster
    • Yanone Kaffeesatz
    • Play
    • Amatic SC
    • Comfortaa
    • Poiret One
    • Russo One
    • Philosopher
    • Caveat
    • Jura
    • Marck Script
    • Bad Script
    • Montserrat Alternates
    • Neucha
    • Press Start 2P
    • Pattaya
  • fontSize Number from 10 to 100
  • lineHeight Number from -50 to 50
  • charSpacing Number
  • fontWeight String one of the following:
    • normal
    • bold
  • fontStyle String one of the following:
    • normal
    • italic
  • underline Boolean
  • linethrough Boolean
  • superscript Boolean
  • subscript Boolean
  • textAlign String one of the following:
    • left
    • center
    • right
  • fill String any valid CSS color (incl. rgba)
  • textShadow Boolean
  • textShadowColor String any valid CSS color (incl. rgba)
  • textShadowOffsetX Number from -20 to 20
  • textShadowOffsetY Number from -20 to 20
  • textShadowBlur Number from 0 to 12
  • textStroke Boolean
  • strokeWidth Number  from 0 to 12
  • textBackground Boolean
  • textBackgroundColor String any valid CSS color (incl. rgba)
  • background Boolean
  • backgroundColor String any valid CSS color (incl. rgba)

Select Frame

Pass the index of the frame to select:

pixo_instance.exec('SELECT_FRAME', { index: -1 })

-1 means no frame.

Select Shape

pixo_instance.exec('SELECT_SHAPE', { shape: 'circle' })

Available shapes:

  • rhombus
  • circle
  • ellipse
  • diamond
  • star
  • hexagon
  • octagon

Crop

To crop the image with specific crop aspect ratio:

pixo_instance.exec('CROP', { crop : { ratio: 16/9 } })

To crop the image with specific crop rectangle:

pixo_instance.exec('CROP', { crop : { left: 0, right: 0, width: 200, height: 200 } })

To set minimum and maximum crop rectangle dimensions:

pixo_instance.exec('SET_MIN_CROP_DIMENSIONS', { min_width: 150, min_height: 85 })
pixo_instance.exec('SET_MAX_CROP_DIMENSIONS', { max_width: 300, max_height: 169 })

To programatically toggle the aspect ratio lock:

pixo_instance.exec('TOGGLE_CROP_RATIO_LOCK')

Transform

To rotate the image:

pixo_instance.exec('TRANSFORM', { operation: 'rotate', direction: 'right' })

Possible directions: 'left' and 'right'.

To flip the image:

pixo_instance.exec('TRANSFORM', { operation: 'flip', direction: 'hor' })

Possible directions: 'hor' and 'ver'.

Color Adjustments

pixo_instance.exec('ADJUST', { propname: 'brightness', value: 0.05 })

List of property names and their value ranges:
  • brightness: -1 to 1
  • contrast: -1 to 1
  • hue-rotation: -2 to 2
  • saturation: -1 to 1
  • gamma-red: 0.01 to 2.2
  • gamma-green: 0.01 to 2.2
  • gamma-blue: 0.01 to 2.2
  • blur: 0 to 1
  • noise: 0 to 1000
  • pixelate: 2 to 20

Set Draw Property

pixo_instance.exec('SET_DRAWING_PROPERTY', { propname: 'linewidth', value: 20 })

List of property names and their values:
  • enabled Boolean
  • source String “brush” or “shape”
  • brushmode String one of the following:
    • Pencil
    • Circle
    • Spray
    • Blur
  • linewidth Number from 0 to 150
  • linecolor String any valid CSS color
  • shapecolor String any valid CSS color
  • shadowcolor String any valid CSS color
  • shadowwidth Number from 0 to 150
  • shadowoffset Number from 0 to 150
  • blur Number from 0 to 1

Insert Draw Shape

pixo_instance.exec('INSERT_DRAW_SHAPE', { value: 'rectangle' })

List with possible shapes to insert:

  • square
  • rectangle
  • circle
  • ellipse
  • roundsquare
  • roundrect