@express-document-sdk / Editor

Class: Editor

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

Hierarchy

• ProxyLiveObject

  ↳ Editor

Accessors

context

• get context(): Context

User's current selection context

Returns

Context

documentRoot

• get documentRoot(): ExpressRootNode

Returns

ExpressRootNode

the root of the document.

Methods

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.

createGroup

▸ createGroup(): GroupNode

Returns

GroupNode

a group node.

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.

createLine

▸ createLine(): LineNode

Returns

LineNode

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

createPath

▸ createPath(path): PathNode

Parameters

Returns

PathNode

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

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.

createText

▸ createText(): TextNode

Returns

TextNode

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

loadBitmapImage

▸ loadBitmapImage(rendition): 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>

makeColorFill

▸ makeColorFill(color): ColorFill

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

Parameters

Returns

ColorFill

makeStroke

▸ makeStroke(options?): Stroke

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

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

Parameters

Returns

Stroke

a stroke configured with the given options.

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:

Copy
// 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);
    });
}
Copied to your clipboard
// 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.

Last updated 4/4/2024

Was this helpful?

Yes

No