v8.48.3

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.

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.

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>

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

<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>

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

<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>

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

<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>

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

<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>

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

<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.

This will disable the fontFamily dropdown.

<!DOCTYPE html>

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

<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>

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

<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>

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'];