@express-document-sdk

Class: Editor

Entry point for APIs that read or modify the document's content.

Extends

• unknown

Extended by

• ExpressEditor

Constructors

Constructor

new Editor(): Editor;

Returns

Editor

Inherited from

ProxyLiveObject.constructor

Accessors

context

Get Signature

get context(): Context;

User's current selection context

Returns

Context

Methods

queueAsyncEdit()

queueAsyncEdit(lambda): Promise<void>;

Enqueues a function to be run at a later time when edits to the user's document may be performed. You can always edit the document immediately when invoked in response to your add-on's UI code. However, if you delay to await an asynchronous operation such as loadBitmapImage, any edits following this pause must be scheduled using queueAsyncEdit(). This ensures the edit is properly tracked for saving and undo.

The delay before your edit function is executed is typically just a few milliseconds, so it will appear instantaneous to users. However, note that queueAsyncEdit() will return before your function has been run. If you need to trigger any code after the edit has been performed, either include this in the lambda you are enqueuing or await the Promise returned by queueAsyncEdit().

Generally, calling any setter or method is treated as an edit; but simple getters may be safely called at any time.

Example of typical usage:

// Assume insertImage() is called from your UI code, and given a Blob containing image data
async function insertImage(blob) {
    // This function was invoked from the UI iframe, so we can make any edits we want synchronously here.
    // Initially load the bitmap - an async operation
    const bitmapImage = await editor.loadBitmapImage(blob);

    // Execution doesn't arrive at this line until an async delay, due to the Promise 'await' above

    // Further edits need to be queued to run at a safe time
    editor.queueAsyncEdit(() => {
         // Create scenenode to display the image, and add it to the current artboard
         const mediaContainer = editor.createImageContainer(bitmapImage);
         editor.context.insertionParent.children.append(mediaContainer);
    });
}

Parameters

Returns

Promise<void>

a Promise that resolves when the lambda has finished running, or rejects if the lambda throws an error.

createText()

Call Signature

createText(): StandaloneTextNode;

Returns

StandaloneTextNode

a text node with default styles. The text content is initially empty, so the text node will be invisible until its fullContent property's text is set. Creates auto-width text, so the node's width will automatically adjust to accommodate whatever text is set.

Deprecated

• Initial text content is always expected so please use createText(textContent: string): StandaloneTextNode.

Call Signature

createText(textContent): StandaloneTextNode;

Parameters

Returns

StandaloneTextNode

a text node with default styles. Creates auto-width text, so the node's width will automatically adjust to accommodate the given text content.

Note: the registration point of this text node is not guaranteed to be at the top-left of the bounding box of its insertion parent. Recommend using setPositionInParent over translation to set the position.

createEllipse()

createEllipse(): EllipseNode;

Returns

EllipseNode

an ellipse node with default x/y radii, a black fill, and no initial stroke. Transform values default to 0.

createRectangle()

createRectangle(): RectangleNode;

Returns

RectangleNode

a rectangle node with default width and height, a black fill, and no initial stroke. Transform values default to 0.

createLine()

createLine(): LineNode;

Returns

LineNode

a line node with default start point and end point and a default stroke. Transform values default to 0.

createGroup()

createGroup(): GroupNode;

Returns

GroupNode

a group node.

makeColorFill()

makeColorFill(color): ColorFill;

Convenience helper to create a complete ColorFill value given just its color.

Parameters

Returns

ColorFill

createImageContainer()

createImageContainer(bitmapData, options): MediaContainerNode;

Creates a bitmap image, represented as a multi-node MediaContainerNode structure. Always creates a "full-frame," uncropped image initially, but cropping can be changed after it is created by modifying the properties of the container's mediaRectangle and maskShape children.

Image creation involves some asynchronous steps. The image will be visible in this client almost instantly, but will render as a gray placeholder on other clients until it has been uploaded to DCX and then downloaded by those clients. This local client will act as having unsaved changes until the upload has finished.

Parameters

Returns

MediaContainerNode

MediaContainerNode representing the top container node of the multi-node structure.

loadBitmapImage()

loadBitmapImage(bitmapData): Promise<BitmapImage>;

Creates a bitmap image resource in the document, which can be displayed in the scenegraph by passing it to createImageContainer to create a MediaContainerNode. The same BitmapImage can be used to create multiple MediaContainerNodes.

Because the resulting BitmapImage is returned asynchronously, to use it you must schedule an edit lambda to run at a safe later time in order to call createImageContainer. See queueAsyncEdit.

Further async steps to upload image resource data may continue in the background after this call's Promise resolves, but the resulting BitmapImage can be used right away (via the queue API noted above). The local client will act as having unsaved changes until all the upload steps have finished.

Parameters

Returns

Promise<BitmapImage>

makeStroke()

makeStroke(options?): SolidColorStroke;

Convenience helper to create a complete SolidColorStroke value given just a subset of its fields. All other fields are populated with default values.

See SolidColorStroke for more details on the options fields. Defaults:

• color has default value DEFAULT_STROKE_COLOR if none is provided.
• width has default value DEFAULT_STROKE_WIDTH if none is provided.
• position has default value center if none is provided.
• dashPattern has default value [] if none is provided.
• dashOffset has default value 0 if none is provided. This field is ignored if no dashPattern was provided.
• type has default value SolidColorStroke.type if none is provided. This field shouldn't be set to any other value.

Parameters

Returns

SolidColorStroke

a stroke configured with the given options.

createThreadedText()

createThreadedText(
   parentNode, 
   textContent, 
   geometry?): ThreadedTextNode;

Experimental

data-slots=text

data-variant=warning

Parameters

Returns

ThreadedTextNode

A new ThreadedTextNode that is part of a threaded text flow.

Throws

if parentNode is not provided or is not a valid container node.

Throws

if textContent is empty or invalid.

createPath()

createPath(path): PathNode;

Parameters

Returns

PathNode

a path node with a default stroke and no initial fill.