v8.66.0

Search

Markup Editor Exported Methods And Properties

The functions, properties, and defaults related to markup editing that are exported by the Pintura module.

The markup helper methods make it easier to create and adjust the Markup Editor tools and shape style controls that are available in the annotate and decorate plugings.

Export Description
markup_editor_defaults An object containing default tools and shape styles.
markup_editor_locale_en_gb The English language configuration object for the Markup Editor. Required when manipulating shapes in Annotate and/or Decorate plugins.
createMarkupEditorToolbar(tools) A function that creates the default Markup Editor toolbar object.
createMarkupEditorToolStyles(styles) A function that creates the default Markup Editor tool styles object.
createMarkupEditorToolStyle(type, shape) A function that creates a new tool style object.
createMarkupEditorShapeStyleControls(controls) A function that creates a new shape style control configuration object.
shapeGetLevel A shape preprocessing helper function, pass in a shape and the current preprocessor options and it'll return the flipX, flipY, and rotation values to keep the shape level.
shapeGetLength Pass in a line shape to get the line length.
shapeGetCenter Pass in a shape to get the shape center position.
getShapeById(shapes, shapeId) Returns the shape in the shapes array with the given id.
updateShapeById(shapes, shapeId, updater) Updates the shape with given id in the supplied shape array, returns a new array. updater should be set to a function that receives the shape and returns an updated shape.
createRetouchShape(...) A helper function to create masked retouch shapes.
createMarkupEditorSelectionTools(action, options) Helper function to create brush, lassoo, rectangle, and ellipse tool buttons. Used in the Retouch util.
createMarkupEditorSelectionToolStyles(action, options) Helper function to create brush, lassoo, rectangle, and ellipse selection tool styles. Used in the Retouch util.

Helper methods to create style controls, these return a style control with the supplied options.

Export Description
createMarkupEditorBackgroundColorControl(colorOptions) Helper method to create the default background color control configuration.
createMarkupEditorStrokeColorControl(colorOptions) Helper method to create the default stroke color control configuration.
createMarkupEditorStrokeWidthControl(sizeOptions) Helper method to create the default stroke width control configuration.
createMarkupEditorLineStartStyleControl(styleOptions) Helper method to create the default line start control configuration.
createMarkupEditorLineEndStyleControl(options) Helper method to create the default line end control configuration.
createMarkupEditorFontColorControl(options) Helper method to create the default font color control configuration.
createMarkupEditorFontFamilyControl(options) Helper method to create the default font family control configuration. This control will automatically test if the defined fonts are available, if not, they will be automatically hidden.
createMarkupEditorFontStyleControl(options) Helper method to create the default font style control configuration.
createMarkupEditorFontSizeControl(options) Helper method to create the default font size control configuration.
createMarkupEditorTextAlignControl(options) Helper method to create the default text align control configuration.
createMarkupEditorOptionsControl(options, settings) Helper method to create a custom options control.
createMarkupEditorSelectionModeControl(options) Helper method to create a selection mode control.
createMarkupEditorBrushSizeControl(sizes) Helper method to create a brush size control.

Helper methods to transform readable option objects and arrays into options that can be consumed by shape controls.

Export Description
createMarkupEditorColorOptions(options) Helper method to create the default color options array.
createMarkupEditorFontSizeOptions(options) Helper method to create the default font size options array.
createMarkupEditorFontScaleOptions(options) Helper method to create the default font scale options array.
createMarkupEditorStrokeWidthOptions(options) Helper method to create the default stroke width options array.
createMarkupEditorStrokeScaleOptions(options) Helper method to create the default stroke scale options array.
createMarkupEditorFontFamilyOptions(options) Helper method to create the default font family options array.
createMarkupEditorFontStyleOptions(options) Helper method to create the default font style options array.
createMarkupEditorLineEndStyleOptions(options) Helper method to create the default line end style options array.

Create default sets of markup options.

Export Description
createDefaultColorOptions() Returns the default color options array.
createDefaultFontSizeOptions() Returns the default font size options array.
createDefaultFontScaleOptions() Returns the default font scale options array.
createDefaultStrokeWidthOptions() Returns the default stroke width options array.
createDefaultStrokeScaleOptions() Returns the default stroke scale options array.
createDefaultLineEndStyleOptions() Returns the default line end style options array.
createDefaultFontFamilyOptions() Returns the default font family options array.
createDefaultFontStyleOptions() Returns the default font style options array.
createDefaultTextAlignOptions() Returns the default text align options array.

markup_editor_defaults

This object contains the default markup editor settings.

<!DOCTYPE html>

<head>
    <link rel="stylesheet" href="./pintura.css" />
</head>

<style>
    .pintura-editor {
        height: 600px;
    }
</style>

<div id="editor"></div>

<script type="module">
    import {
        appendEditor,
        createDefaultImageReader,
        createDefaultImageWriter,
        createDefaultImageOrienter,
        createDefaultShapePreprocessor,
        setPlugins,
        plugin_annotate,
        plugin_crop,
        markup_editor_defaults,
        locale_en_gb,
        markup_editor_locale_en_gb,
        plugin_annotate_locale_en_gb,
        plugin_crop_locale_en_gb,
    } from './pintura.js';

    setPlugins(plugin_crop, plugin_annotate);

    const editor = appendEditor('#editor', {
        imageReader: createDefaultImageReader(),
        imageWriter: createDefaultImageWriter(),
        imageOrienter: createDefaultImageOrienter(),
        shapePreprocessor: createDefaultShapePreprocessor(),
        ...markup_editor_defaults,
        locale: {
            ...locale_en_gb,
            ...plugin_crop_locale_en_gb,
            ...plugin_annotate_locale_en_gb,
            ...markup_editor_locale_en_gb,
        },
        src: 'image.jpeg',
    });
</script>

createMarkupEditorToolbar

This is a helper function to create the Markup Editor toolbar. If no parameters are passed the function creates the default Markup Editor toolbar array.

We can assign the return value of this function to the markupEditorToolbar property to update the toolbar.

<!DOCTYPE html>

<head>
    <link rel="stylesheet" href="./pintura.css" />
</head>

<style>
    .pintura-editor {
        height: 600px;
    }
</style>

<div id="editor"></div>

<script type="module">
    import {
        appendDefaultEditor,
        createMarkupEditorToolbar,
    } from './pintura.js';

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        markupEditorToolbar: createMarkupEditorToolbar(),
    });
</script>

To create a custom toolbar we can either pass an array of strings or an array of arrays.

<!DOCTYPE html>

<head>
    <link rel="stylesheet" href="./pintura.css" />
</head>

<style>
    .pintura-editor {
        height: 600px;
    }
</style>

<div id="editor"></div>

<script type="module">
    import {
        appendDefaultEditor,
        createMarkupEditorToolbar,
    } from './pintura.js';

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        markupEditorToolbar: createMarkupEditorToolbar([
            'eraser',
            'sharpie',
            'rectangle',
        ]),
    });
</script>

Each tool key ('eraser', 'sharpie', 'rectangle') links to a label and icon in the markup locale file. It also links to a shape style for that key, this style is defined in the markupEditorToolStyles property.

To find the label and optional icon the first character of the tool key is automatically uppercased and then the key is appended to shapeLabelTool to get the label, and shapeIconTool to get the icon.

'sharpie' -> 'Sharpie' -> locale.shapeLabelToolSharpie
'sharpie' -> 'Sharpie' -> locale.shapeIconToolSharpie

We can also pass an array instead of a string. In this case the first index of the array should be the tool key.

The array can be either two or three items in length.

// The label for key 'sharpie' should be available in the locale object
createMarkupEditorToolbar([['sharpie', { disabled: true }]]);

// The label 'Pen' is used
createMarkupEditorToolbar([['sharpie', 'Pen']]);

// The label 'Pen' is used and the tool is disabled
createMarkupEditorToolbar([['sharpie', 'Pen', { disabled: true }]]);

The example below will define three tools and disable the eraser tool.

createMarkupEditorToolbar([
    ['eraser', { disabled: true }],
    'sharpie',
    'rectangle',
]);

In the example below we add a custom 'marker' tool. It'll use the label 'Marker' and the icon defined in the icon property. The style of the tool will be defined with key 'marker'.

createMarkupEditorToolbar([
    ['eraser', { disabled: true }],
    'sharpie',
    ['marker', 'Marker', { icon: '<g></g>' }]
    'rectangle',
]);

createMarkupEditorToolStyles

Running this helper function without parameters will return the default tool styles.

We can assign the return value of this function to the markupEditorToolStyles to update the tool default styles.

<!DOCTYPE html>

<head>
    <link rel="stylesheet" href="./pintura.css" />
</head>

<style>
    .pintura-editor {
        height: 600px;
    }
</style>

<div id="editor"></div>

<script type="module">
    import {
        appendDefaultEditor,
        createMarkupEditorToolStyle,
        createMarkupEditorToolStyles,
    } from './pintura.js';

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        markupEditorToolStyles: createMarkupEditorToolStyles(),
    });
</script>

We can add custom styles by passing a configuration object to the function, use the createMarkupEditorToolStyle function to create a custom style object.

The createMarkupEditorToolStyles function will merge the passed configuration object with the default tool styles. This allows adding tool styles or altering existing tool styles.

Let's take a look at the createMarkupEditorToolStyle function to see how we can assign a custom style.

createMarkupEditorToolStyle

The createMarkupEditorToolStyle function expects three parameters, the type of the shape, the shape properties that should be assigned and the shape options. The return value should be set to a tool key in the markupEditorToolStyles object.

Type can be either 'path', 'rectangle', 'ellipse', 'line', or 'text'. The function will return a set of default styles.

Below we create a custom "marker" tool and style. We use the disableStyle property to prevent adjusting the strokeWidth and strokeColor. We also use the createDefaultColorOptions function to set the default yellow color to the strokeColor of the shape.

<!DOCTYPE html>

<head>
    <link rel="stylesheet" href="./pintura.css" />
</head>

<style>
    .pintura-editor {
        height: 600px;
    }
</style>

<div id="editor"></div>

<script type="module">
    import {
        appendDefaultEditor,
        createDefaultColorOptions,
        createMarkupEditorToolStyle,
        createMarkupEditorToolStyles,
        createMarkupEditorToolbar,
    } from './pintura.js';

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        markupEditorToolStyles: createMarkupEditorToolStyles({
            // key, style
            marker: createMarkupEditorToolStyle('path', {
                strokeWidth: '5%',
                strokeColor: createDefaultColorOptions().yellow,
                disableStyle: ['strokeWidth'],
            }),
        }),
        markupEditorToolbar: createMarkupEditorToolbar([
            'eraser',
            'sharpie',
            // key, label
            ['marker', 'Marker'],
            'rectangle',
            'ellipse',
            'arrow',
            'text',
        ]),
    });
</script>

createMarkupEditorShapeStyleControls

The createMarkupEditorShapeStyleControls function creates the default set of shape style controls which can be assigned to the markupEditorShapeStyleControls property.

We can use this method to override default style options. Set a style property to false to disable it or set a property to a list of options to override the default options. We can also use this function to add custom option controls using createMarkupEditorOptionsControl

This will disable the fontFamily dropdown.

<!DOCTYPE html>

<head>
    <link rel="stylesheet" href="./pintura.css" />
</head>

<style>
    .pintura-editor {
        height: 600px;
    }
</style>

<div id="editor"></div>

<script type="module">
    import {
        appendDefaultEditor,
        createMarkupEditorShapeStyleControls,
    } from './pintura.js';

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        markupEditorShapeStyleControls: createMarkupEditorShapeStyleControls({
            fontFamilyOptions: false,
        }),
    });
</script>

This will change the default fontFamily dropdown options.

<!DOCTYPE html>

<head>
    <link rel="stylesheet" href="./pintura.css" />
</head>

<style>
    .pintura-editor {
        height: 600px;
    }
</style>

<div id="editor"></div>

<script type="module">
    import {
        appendDefaultEditor,
        createMarkupEditorShapeStyleControls,
    } from './pintura.js';

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        markupEditorShapeStyleControls: createMarkupEditorShapeStyleControls({
            fontFamilyOptions: [
                ['arial', 'Arial'],
                ['open-sans', 'Open Sans'],
                ['courier', 'Courier'],
                // Define additional custom fonts here
            ],
        }),
    });
</script>

This will enable a hex color input on the backgroundColor color picker control. The same can be used with createMarkupEditorColorControl, and createMarkupEditorStrokeColorControl.

<!DOCTYPE html>

<head>
    <link rel="stylesheet" href="./pintura.css" />
</head>

<style>
    .pintura-editor {
        height: 600px;
    }
</style>

<div id="editor"></div>

<script type="module">
    import {
        appendDefaultEditor,
        createDefaultColorOptions,
        createMarkupEditorBackgroundColorControl,
        createMarkupEditorColorOptions,
        createMarkupEditorShapeStyleControls,
    } from './pintura.js';

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        markupEditorShapeStyleControls: createMarkupEditorShapeStyleControls({
            backgroundColor: createMarkupEditorBackgroundColorControl(
                createMarkupEditorColorOptions(createDefaultColorOptions()),
                {
                    enableInput: true,
                }
            ),
        }),
    });
</script>

We can also enable a number input on the font size and line height controls, but only if we're using absolute number.

<!DOCTYPE html>

<head>
    <link rel="stylesheet" href="./pintura.css" />
</head>

<style>
    .pintura-editor {
        height: 600px;
    }
</style>

<div id="editor"></div>

<script type="module">
    import {
        appendDefaultEditor,
        createDefaultFontSizeOptions,
        createMarkupEditorFontSizeControl,
        createMarkupEditorFontSizeOptions,
        createMarkupEditorLineHeightControl,
        createMarkupEditorShapeStyleControls,
    } from './pintura.js';

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        markupEditorShapeStyleControls: createMarkupEditorShapeStyleControls({
            fontSize: createMarkupEditorFontSizeControl(
                createMarkupEditorFontSizeOptions(
                    createDefaultFontSizeOptions()
                ),
                {
                    enableInput: true,
                }
            ),
            lineHeight: createMarkupEditorLineHeightControl(
                createMarkupEditorFontSizeOptions(
                    createDefaultFontSizeOptions()
                ),
                {
                    enableInput: true,
                }
            ),
        }),
    });
</script>

createMarkupEditorOptionsControl

Creates a custom options control.

<!DOCTYPE html>

<head>
    <link rel="stylesheet" href="./pintura.css" />
</head>

<style>
    .pintura-editor {
        height: 600px;
    }
</style>

<div id="editor"></div>

<script type="module">
    import {
        appendDefaultEditor,
        createMarkupEditorShapeStyleControls,
    } from './pintura.js';

    const editor = appendDefaultEditor('#editor', {
        src: 'image.jpeg',
        imageAnnotation: [
            {
                x: 0,
                y: 0,
                width: 100,
                height: 100,
                backgroundColor: [1, 0, 0],
                // custom style property
                myStyle: 'my-foo-value',
            },
        ],
        markupEditorShapeStyleControls: createMarkupEditorShapeStyleControls({
            // custom control to change custom style property value
            myStyle: createMarkupEditorOptionsControl(
                [
                    ['my-foo-value', 'Foo'],
                    ['my-bar-value', 'Bar'],
                    ['my-baz-value', 'Baz'],
                ],
                {
                    title: 'My style',
                }
            ),
        }),
    });
</script>

createRetouchShape

A helper function to create masked retouch shapes, see Pintura example retouch for reference.

const retouchShape = await createRetouchShape(
    // image file to use as source
    imageFile,

    // the size of the image
    imageSize,

    // the image state to apply
    imageState,

    // the selection to use
    selection,

    // the inpainting funciton to call
    inpaint,

    // custom options
    options
);

The options object format.

Property Default value Description
retouches 
[]
 An array of retouches to render in the image.
padding 
15
 Padding to apply around mask.
didCreateDraft() 
() => undefined
 A hook to use for UI updates

How to use the function

import { createRetouchShape } from '@pqina/pintura';

// `editor` is a reference to a Pintura instance

const await retouchShape = createRetouchShape(
    // this passes the necessary information about the image to the shape helper function
    editor.imageFile,
    editor.imageSize,
    editor.imageState,

    // duplicate editor selection array because often we'll clear it after
    [...editor.imageSelection],

    // function that provides the ImageData
    (imageBlob, maskBlob, { shape, controller }) => {
        // here we can call a third-party service to manipulate the imageData

        // when we get new imageData back we can use it to update the `shape` backgroundImage

        // we can use controller.abort() to cancel
    },
    // optional options
    {
        // current retouches to render so existing retouches are used to calculate the new image
        retouches = editor.imageManipulation,

        // limit mask to this size (from center of mask shapes)
        maxSize = imageSize,

        // extra padding around mask area
        padding = 15,

        // hooks for ui updates
        didCreateDraft = (draft) => {
            // add the draft to the imageManipulation array so we can see changes right away
            editor.imageManipulation = [
                ...editor.imageManipulation,
                draftShape,
            ];
        },
    }
);

// now we have our final `retouchShape` we can update the imageManipulation array once more
editor.imageManipulation = editor.imageManipulation.map((shape) => {
    if (retouchShape.id !== shape.id) return shape;
    return retouchShape;
});

Markup option defaults

createDefaultColorOptions

Returns the following object of default color options.

// an object containing default color presets
{
    transparent: [1, 1, 1, 0],
    white: [1, 1, 1],
    silver: [0.8667, 0.8667, 0.8667],
    gray: [0.6667, 0.6667, 0.6667],
    black: [0, 0, 0],
    navy: [0, 0.1216, 0.2471],
    blue: [0, 0.4549, 0.851],
    aqua: [0.498, 0.8588, 1],
    teal: [0.2235, 0.8, 0.8],
    olive: [0.2392, 0.6, 0.4392],
    green: [0.1804, 0.8, 0.251],
    yellow: [1, 0.8627, 0],
    orange: [1, 0.5216, 0.1059],
    red: [1, 0.2549, 0.2118],
    maroon: [0.5216, 0.0784, 0.2941],
    fuchsia: [0.9412, 0.0706, 0.7451],
    purple: [0.6941, 0.051, 0.7882],
}

createDefaultFontSizeOptions

Returns the following array of fixed font sizes.

// An array of absolute font sizes
[16, 18, 20, 24, 30, 36, 48, 64, 72, 96, 144];

createDefaultFontScaleOptions

Returns the following object containing a selection of relative font sizes.

// An object describing relative sizes
{
    extraSmall: '2%',
    small: '4%',
    mediumSmall: '8%',
    medium: '10%',
    mediumLarge: '15%',
    large: '20%',
    extraLarge: '25%',
}

createDefaultLineScaleOptions

Returns the following object containing a selection of relative line heights.

// An object describing relative sizes
{
    extraSmall: '40%',
    small: '60%',
    mediumSmall: '100%',
    medium: '120%',
    mediumLarge: '140%',
    large: '180%',
    extraLarge: '220%',
}

createDefaultLineHeightOptions

Returns the following object containing a selection of absolute line heights.

// An array of line heights
[16, 18, 20, 24, 30, 36, 48, 64, 72, 96, 128, 144];

createDefaultStrokeScaleOptions

Returns the following object containing a selection of relative stroke widths.

// An object describing relative sizes
{
    extraSmall: '0.25%',
    small: '0.5%',
    mediumSmall: '1%',
    medium: '1.75%',
    mediumLarge: '2.5%',
    large: '3.5%',
    extraLarge: '5%',
}

createDefaultStrokeWidthOptions

Returns the following array of fixed stroke widths.

// An array of fixed stroke widths
[1, 2, 3, 4, 6, 8, 12, 16, 20, 24, 32, 48];

createDefaultLineEndStyleOptions

Returns the following array of line end styles.

// An array of line end styles
[
    'bar',
    'arrow',
    'arrowSolid',
    'circle',
    'circleSolid',
    'square',
    'squareSolid',
];

createDefaultFontFamilyOptions

Returns the following array of font families. The font family control automatically tests if a font family is available on the user device, if not, it will hide the option.

// An array of font family stacks
[
    [`Helvetica, Arial, Verdana, 'Droid Sans', sans-serif`, 'Sans Serif'],
    [`'Arial Black', 'Avenir-Black', 'Arial Bold'`, 'Black'],
    [`'Arial Narrow', 'Futura-CondensedMedium'`, 'Narrow'],
    [`'Trebuchet MS'`, 'Humanist'],
    [
        `Georgia, 'Avenir-Black', 'Times New Roman', 'Droid Serif', serif`,
        'Serif',
    ],
    [`Palatino`, 'Old-Style'],
    [`'Times New Roman', 'TimesNewRomanPSMT'`, 'Transitional'],
    [`Menlo, Monaco, 'Lucida Console', monospace`, 'Monospaced'],
    [`'Courier New', monospace`, 'Slab Serif'],
];

createDefaultFontStyleOptions

Returns the following array of font styles. These are applied to the fontStyle and fontWeight shape properties.

// An array of font styles
[
    ['normal', 'bold'],
    ['italic', 'normal'],
    ['italic', 'bold'],
];

createDefaultTextAlignOptions

Returns the following array.

// An array of text alignment options
['left', 'center', 'right'];