This is the archived documentation for Doka Image Editor v7.
Please visit pqina.nl/pintura/docs/ to see documentation for the latest version of Pintura Image Editor.
Events
Doka Image Editor exposes a list of events so we can interact and respond to the editor state appropriatly.
- Events overview
- Subscribing to events
- Events and JavaScript frameworks
- Editor events
- Modal events
- Markup editor events
Events overview
These are the events fired by the editor instance.
Name | Description |
---|---|
'loadstart' |
Fired when image loading starts. |
'loadabort' |
Fired when image loading is aborted. |
'loaderror' |
Fired when an error is thrown during image load. |
'loadprogress' |
Fired when loading of the image progresses. |
'load' |
Fired when an image has successfully loaded. |
'processstart' |
Fired when processing of an image starts. |
'processabort' |
Fired when processing of an image is aborted. |
'processerror' |
Fired when an error is thrown during image processing. |
'processprogress' |
Fired when processing of the image progresses. |
'process' |
Fired when an image has been processed. |
'undo' |
Fired on undo action. |
'redo' |
Fired on redo action. |
'revert' |
Fired on revert action. Will only be fired if willRevert resolves with true .
|
'destroy' |
Fired when the editor is destroyed. |
'close' |
Fired when the editor is closed with the close button. |
Instances created with the openEditor
JavaScript API fire a couple additional events.
When using the Markup Editor the following additional events are fired.
Name | Description |
---|---|
'addshape' |
Fired when a shape is added, receives added shape. |
'selectshape' |
Fired when a shape is selected, receives selected shape. |
'udpateshape' |
Fired when a shape is updated, receives updated shape. |
'removeshape' |
Fired when a shape is removed, receives removed shape. |
Subscribing to events
When using the native version of Doka Image Editor events can be subscribed to using the on
method exposed on the Doka Image Editor instance. An alternative method to subscribe to events is to use the handleEvent
property.
If we're using the Custom Elements API we can listen for events using an EventListener
.
Events always only return one value which is either passed as a parameter or set as the detail
property of the CustomEvent.
// doka instance
editor.on('load', (res) => {
console.log(res);
// logs: { src:…, dest:… , size:… }
});
Using the handleEvent
property.
// doka instance
editor.handleEvent = (type, detail) => {
if (type === 'process') {
// handle process event
}
};
The handleEvent
example below will log all fired events to console.
// doka instance
editor.handleEvent = console.log;
// logs: 'loadstart', undefined
// logs: 'loadprogress', { index: 0, task: 'any-to-file', … }
// logs: 'load', { src:…, dest:… , size:… }
// logs: …
Use addEventListener
with Custom Elements. Make sure to prefix events with doka:
.
<doka-image-editor src="my-image.jpeg"></doka-image-editor>
<script>
const editor = document.querySelector('doka-image-editor');
editor.addEventListener('doka:load', (e) => {
console.log(e.detail);
// logs: { src:…, dest:… , size:… }
});
</script>
Events and JavaScript frameworks
When using one of the included JavaScript framework components listening for events works exactly like you would expect for how components work in your framework of choice.
Please see your preferred framework configuration section for more details.
Editor events
loadstart
Fired when an image starts loading.
loadabort
Fired when the image load is aborted. For example when a new image is set while another image is still loading.
loaderror
Fired when the image load process throws an error.
loadprogress
Fired when the image load process makes progress. Receives the task
progress event. The task progress event has the following properties.
Name | Description |
---|---|
index |
The index of the task in the processing array. |
task |
The name of the task in the processing array. |
taskProgress |
The current progress of the task between 0 and 1 .
|
taskLengthComputable |
Is the length of this task computable, is true when the task length will be updated, the editor will show a progress indicator. If is false the editor will show a spinner.
|
timeStamp |
The time stamp of the event. |
Each task will fire at least a progress event with taskProgress set to 0
and a progress event with taskProgress set to 1
. The 0
progress event will always have taskLengthComputable
set to false
as the editor doesn't know if the length will be computable before the task runs. The taskLengthComputable
of the final progress event will either be false
or true
depending on if progress events were fired.
import { openEditor } from './doka.js';
const editor = openEditor({
src: './my-image.jpeg',
});
editor.on('loadprogress', console.log);
// logs: { index: 0, task: 'any-to-file' , taskProgress: 0, taskLengthComputable: false, timeStamp: 1614589213257 }
load
Fired when the src
image has finished loading, receives the imageReader
output object.
import { openEditor } from './doka.js';
const editor = openEditor({
src: './my-image.jpeg',
});
editor.on('load', console.log);
// logs: { src:…, dest:… , size:… }
processstart
Fired when an image starts processing.
processabort
Fired when image processing is aborted.
processerror
Fired when the image processing process throws an error.
processprogress
Fired when the image processing process makes progress.
process
Fired when the image has finished processing, receives the imageWriter
output object.
import { openEditor } from './doka.js';
const editor = openEditor({
src: './my-image.jpeg',
});
editor.on('process', console.log);
// logs: { src:…, dest:… , imageState:…, store:… }
editor.process();
Modal events
A list of events that are only used when the editor instance was created with the openEditor
method.
show
Fired when the modal is shown.
hide
Fired when the modal is hidden.
close
Fired when the modal is closed using the top left close button.
Markup editor events
addshape
Fired when a shape is added in the editor.
editor.on('addshape', (shape) => {
console.log('addshape', shape);
// logs: { /* shape properties */ }
});
selectshape
Fired when a shape is selected in the editor.
editor.on('selectshape', (shape) => {
console.log('selectshape', shape);
// logs: { /* shape properties */ }
});
udpateshape
Fired when a shape is updated in the editor.
editor.on('updateshape', (shape) => {
console.log('updateshape', shape);
// logs: { /* shape properties */ }
});
removeshape
Fired when a shape is removed in the editor.
editor.on('removeshape', (shape) => {
console.log('removeshape', shape);
// logs: { /* shape properties */ }
});