From 19f85da0af02998aff2688259ecb96fa0e08c5ed Mon Sep 17 00:00:00 2001 From: Vamshi Date: Thu, 20 Nov 2025 23:41:28 +0530 Subject: [PATCH 1/3] Doc updates - New Express classes ExpressContext, ExpressEditor, ExpressViewport - New Classes StandaloneTextContentModel, ThreadedTextContentModel - ImageRectangleNode.fetchBitmapImage() experimental API - BitmapImage.data() experimental API --- gatsby-config.js | 32 +- .../document-apis/classes/BitmapImage.md | 16 + .../document-apis/classes/Context.md | 15 +- .../document-apis/classes/Editor.md | 14 +- .../document-apis/classes/ExpressContext.md | 149 +++++++ .../document-apis/classes/ExpressEditor.md | 358 +++++++++++++++++ .../{Viewport.md => ExpressViewport.md} | 5 +- .../document-apis/classes/GridCellNode.md | 4 +- .../classes/ImageRectangleNode.md | 16 + .../classes/MediaContainerNode.md | 4 +- .../classes/StandaloneTextContentModel.md | 358 +++++++++++++++++ .../classes/StandaloneTextNode.md | 22 +- .../document-apis/classes/TextNode.md | 2 +- .../classes/TextNodeContentModel.md | 9 +- .../classes/ThreadedTextContentModel.md | 363 ++++++++++++++++++ .../document-apis/classes/ThreadedTextNode.md | 16 +- .../interfaces/IMediaContainerNode.md | 4 +- .../document-apis/overview.md | 7 +- 18 files changed, 1336 insertions(+), 58 deletions(-) create mode 100644 src/pages/references/document-sandbox/document-apis/classes/ExpressContext.md create mode 100644 src/pages/references/document-sandbox/document-apis/classes/ExpressEditor.md rename src/pages/references/document-sandbox/document-apis/classes/{Viewport.md => ExpressViewport.md} (93%) create mode 100644 src/pages/references/document-sandbox/document-apis/classes/StandaloneTextContentModel.md create mode 100644 src/pages/references/document-sandbox/document-apis/classes/ThreadedTextContentModel.md diff --git a/gatsby-config.js b/gatsby-config.js index c26a9cb5b..d4d0eba19 100644 --- a/gatsby-config.js +++ b/gatsby-config.js @@ -146,6 +146,10 @@ module.exports = { title: "BaseNode", path: "references/document-sandbox/document-apis/classes/BaseNode.md", }, + { + title: "BitmapImage", + path: "references/document-sandbox/document-apis/classes/BitmapImage.md", + }, { title: "ColorUtils", path: "references/document-sandbox/document-apis/classes/ColorUtils.md", @@ -166,10 +170,22 @@ module.exports = { title: "EllipseNode", path: "references/document-sandbox/document-apis/classes/EllipseNode.md", }, + { + title: "ExpressContext", + path: "references/document-sandbox/document-apis/classes/ExpressContext.md", + }, + { + title: "ExpressEditor", + path: "references/document-sandbox/document-apis/classes/ExpressEditor.md", + }, { title: "ExpressRootNode", path: "references/document-sandbox/document-apis/classes/ExpressRootNode.md", }, + { + title: "ExpressViewport", + path: "references/document-sandbox/document-apis/classes/ExpressViewport.md", + }, { title: "FillableNode", path: "references/document-sandbox/document-apis/classes/FillableNode.md", @@ -242,6 +258,10 @@ module.exports = { title: "SolidColorShapeNode", path: "references/document-sandbox/document-apis/classes/SolidColorShapeNode.md", }, + { + title: "StandaloneTextContentModel", + path: "references/document-sandbox/document-apis/classes/StandaloneTextContentModel.md", + }, { title: "StandaloneTextNode", path: "references/document-sandbox/document-apis/classes/StandaloneTextNode.md", @@ -262,6 +282,14 @@ module.exports = { title: "TextNode", path: "references/document-sandbox/document-apis/classes/TextNode.md", }, + { + title: "TextNodeContentModel", + path: "references/document-sandbox/document-apis/classes/TextNodeContentModel.md", + }, + { + title: "ThreadedTextContentModel", + path: "references/document-sandbox/document-apis/classes/ThreadedTextContentModel.md", + }, { title: "ThreadedTextNode", path: "references/document-sandbox/document-apis/classes/ThreadedTextNode.md", @@ -278,10 +306,6 @@ module.exports = { title: "UnknownNode", path: "references/document-sandbox/document-apis/classes/UnknownNode.md", }, - { - title: "Viewport", - path: "references/document-sandbox/document-apis/classes/Viewport.md", - }, { title: "VisualNode", path: "references/document-sandbox/document-apis/classes/VisualNode.md", diff --git a/src/pages/references/document-sandbox/document-apis/classes/BitmapImage.md b/src/pages/references/document-sandbox/document-apis/classes/BitmapImage.md index fd7094de7..184e7717e 100644 --- a/src/pages/references/document-sandbox/document-apis/classes/BitmapImage.md +++ b/src/pages/references/document-sandbox/document-apis/classes/BitmapImage.md @@ -27,3 +27,19 @@ Original width of the bitmap in pixels. #### Returns `number` + +## Methods + +### data() + +• **data**(): `Promise`<`Blob`\> + + + +**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`. + +Fetches the bitmap data as a Blob. This will wait for the bitmap to be available if necessary. + +#### Returns + +`Promise`<`Blob`\> diff --git a/src/pages/references/document-sandbox/document-apis/classes/Context.md b/src/pages/references/document-sandbox/document-apis/classes/Context.md index 652ce8413..81f863f8d 100644 --- a/src/pages/references/document-sandbox/document-apis/classes/Context.md +++ b/src/pages/references/document-sandbox/document-apis/classes/Context.md @@ -4,20 +4,11 @@ Contains the user's current selection state, indicating the content they are focused on. -## Accessors - -### currentPage - -• `get` **currentPage**(): [`PageNode`](PageNode.md) - -#### Returns - -[`PageNode`](PageNode.md) +## Extended by -The currently viewed page. -To change the current page, call [Viewport.bringIntoView](Viewport.md#bringintoview) with an artboard or other content on that page. +- [`ExpressContext`](ExpressContext.md) ---- +## Accessors ### hasSelection diff --git a/src/pages/references/document-sandbox/document-apis/classes/Editor.md b/src/pages/references/document-sandbox/document-apis/classes/Editor.md index 4e0a9330f..266fb6eaa 100644 --- a/src/pages/references/document-sandbox/document-apis/classes/Editor.md +++ b/src/pages/references/document-sandbox/document-apis/classes/Editor.md @@ -4,6 +4,10 @@ Entry point for APIs that read or modify the document's content. +## Extended by + +- [`ExpressEditor`](ExpressEditor.md) + ## Accessors ### context @@ -20,11 +24,11 @@ User's current selection context ### documentRoot -• `get` **documentRoot**(): [`ExpressRootNode`](ExpressRootNode.md) +• `get` **documentRoot**(): [`BaseNode`](BaseNode.md) #### Returns -[`ExpressRootNode`](ExpressRootNode.md) +[`BaseNode`](BaseNode.md) the root of the document. @@ -69,7 +73,7 @@ This local client will act as having unsaved changes until the upload has finish #### Parameters -• **bitmapData**: `BitmapImage` +• **bitmapData**: [`BitmapImage`](BitmapImage.md) BitmapImage resource (e.g. returned from [loadBitmapImage](Editor.md#loadbitmapimage)). @@ -187,7 +191,7 @@ insertion parent. Recommend using `setPositionInParent` over `translation` to se ### loadBitmapImage() -• **loadBitmapImage**(`bitmapData`): `Promise`<`BitmapImage`\> +• **loadBitmapImage**(`bitmapData`): `Promise`<[`BitmapImage`](BitmapImage.md)\> Creates a bitmap image resource in the document, which can be displayed in the scenegraph by passing it to [createImageContainer](Editor.md#createimagecontainer) to create a MediaContainerNode. The same BitmapImage can be used to create multiple MediaContainerNodes. @@ -207,7 +211,7 @@ Encoded image data in PNG or JPEG format. #### Returns -`Promise`<`BitmapImage`\> +`Promise`<[`BitmapImage`](BitmapImage.md)\> --- diff --git a/src/pages/references/document-sandbox/document-apis/classes/ExpressContext.md b/src/pages/references/document-sandbox/document-apis/classes/ExpressContext.md new file mode 100644 index 000000000..d8abf0572 --- /dev/null +++ b/src/pages/references/document-sandbox/document-apis/classes/ExpressContext.md @@ -0,0 +1,149 @@ +[@express-document-sdk](../overview.md) / ExpressContext + +# Class: ExpressContext + +Contains The Express specific APIs related to the current selection state. + +## Extends + +- [`Context`](Context.md) + +## Accessors + +### currentPage + +• `get` **currentPage**(): [`PageNode`](PageNode.md) + +#### Returns + +[`PageNode`](PageNode.md) + +The currently viewed page. +To change the current page, call [ExpressViewport.bringIntoView](ExpressViewport.md#bringintoview) with an artboard or other content on that page. + +--- + +### hasSelection + +• `get` **hasSelection**(): `boolean` + +#### Returns + +`boolean` + +false if the current editable selection does not contain any nodes, otherwise true. + +--- + +### insertionParent + +• `get` **insertionParent**(): [`ContainerNode`](../interfaces/ContainerNode.md) + +#### Returns + +[`ContainerNode`](../interfaces/ContainerNode.md) + +the preferred parent to insert newly added content into (i.e., the location content would get inserted if a +user were to Paste or use the Shapes panel in the UI). This will vary depending on the user's current selection and +other UI state. + +--- + +### selection + +• `get` **selection**(): readonly [`Node`](Node.md)[] + +• `set` **selection**(`nodes`): `void` + +Sets the current selection to an array of [Node](Node.md). +Accepts a single node as a shortcut for a length-1 array `[node]` or +`undefined` as a shortcut for `[]`, which clears the selection. + +Only node(s) that meet the following criteria can be selected: + +- Nodes must be within the current artboard (nodes outside the active artboard are filtered out). +- A node cannot be selected if its ancestor is also selected (descendants are filtered out). +- Locked nodes are filtered out (but will still be included in selectionIncludingNonEditable). + +#### Parameters + +• **nodes**: `undefined` \| [`Node`](Node.md) \| readonly [`Node`](Node.md)[] + +#### Returns + +readonly [`Node`](Node.md)[] + +the current selection. Nodes that are locked or otherwise non-editable are never included in the regular +selection (see [selectionIncludingNonEditable](Context.md#selectionincludingnoneditable) to get any locked nodes the user may have clicked). + +--- + +### selectionIncludingNonEditable + +• `get` **selectionIncludingNonEditable**(): readonly [`Node`](Node.md)[] + +#### Returns + +readonly [`Node`](Node.md)[] + +the current selection *and* any locked nodes the user has attempted to select at the same time. This can +happen for example if the user clicks on a locked node or if the user drags a selection marquee that overlaps +locked nodes in addition to regular unlocked nodes. + +## Methods + +### off() + +• **off**(`eventName`, `handlerId`): `void` + +Unregisters handlers for editor events like selection change. + +#### Parameters + +• **eventName**: [`selectionChange`](../enumerations/EditorEvent.md#selectionchange) + +an editor event name. + +• **handlerId**: `string` + +a unique ID returned by `editor.context.on` API. +Callback that was previously registered will be removed and will no more be invoked when the event occurs. + +#### Returns + +`void` + +#### Inherited from + +[`Context`](Context.md).[`off`](Context.md#off) + +--- + +### on() + +• **on**(`eventName`, `callback`): `string` + +Registers a handler for editor events such as selection change. +The registered callback will be invoked when the specified event occurs. + +Note: Do not attempt to make changes to the document in response to a selection change callback because it may destabilize the application. + +#### Parameters + +• **eventName**: [`selectionChange`](../enumerations/EditorEvent.md#selectionchange) + +an editor event name. + +• **callback**: [`EditorEventHandler`](../type-aliases/EditorEventHandler.md) + +a callback to be registered for an editor event. + +#### Returns + +`string` + +a unique ID for the registered event handler. + +#### Inherited from + +[`Context`](Context.md).[`on`](Context.md#on) diff --git a/src/pages/references/document-sandbox/document-apis/classes/ExpressEditor.md b/src/pages/references/document-sandbox/document-apis/classes/ExpressEditor.md new file mode 100644 index 000000000..9578833d7 --- /dev/null +++ b/src/pages/references/document-sandbox/document-apis/classes/ExpressEditor.md @@ -0,0 +1,358 @@ +[@express-document-sdk](../overview.md) / ExpressEditor + +# Class: ExpressEditor + +Entry point for Express specific APIs that read or modify the document's content. + +## Extends + +- [`Editor`](Editor.md) + +## Accessors + +### context + +• `get` **context**(): [`ExpressContext`](ExpressContext.md) + +User's current selection context + +#### Returns + +[`ExpressContext`](ExpressContext.md) + +--- + +### documentRoot + +• `get` **documentRoot**(): [`ExpressRootNode`](ExpressRootNode.md) + +#### Returns + +[`ExpressRootNode`](ExpressRootNode.md) + +the root of the document. + +## Methods + +### createEllipse() + +• **createEllipse**(): [`EllipseNode`](EllipseNode.md) + +#### Returns + +[`EllipseNode`](EllipseNode.md) + +an ellipse node with default x/y radii, a black fill, and no initial stroke. +Transform values default to 0. + +#### Inherited from + +[`Editor`](Editor.md).[`createEllipse`](Editor.md#createellipse) + +--- + +### createGroup() + +• **createGroup**(): [`GroupNode`](GroupNode.md) + +#### Returns + +[`GroupNode`](GroupNode.md) + +a group node. + +#### Inherited from + +[`Editor`](Editor.md).[`createGroup`](Editor.md#creategroup) + +--- + +### createImageContainer() + +• **createImageContainer**(`bitmapData`, `options`): [`MediaContainerNode`](MediaContainerNode.md) + +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 + +• **bitmapData**: [`BitmapImage`](BitmapImage.md) + +BitmapImage resource (e.g. returned from [loadBitmapImage](Editor.md#loadbitmapimage)). + +• **options**= `{}` + +Additional configuration: + - initialSize - Size the image is displayed at. Must have the same aspect ratio as bitmapData. Defaults to the + size the image would be created at by a UI drag-drop gesture (typically the image's full size, but scaled down + if needed to stay below an application-defined size cap). + +• **options.initialSize?**: [`RectangleGeometry`](../interfaces/RectangleGeometry.md) + +#### Returns + +[`MediaContainerNode`](MediaContainerNode.md) + +MediaContainerNode representing the top container node of the multi-node structure. + +#### Inherited from + +[`Editor`](Editor.md).[`createImageContainer`](Editor.md#createimagecontainer) + +--- + +### createLine() + +• **createLine**(): [`LineNode`](LineNode.md) + +#### Returns + +[`LineNode`](LineNode.md) + +a line node with default start point and end point and a default stroke. +Transform values default to 0. + +#### Inherited from + +[`Editor`](Editor.md).[`createLine`](Editor.md#createline) + +--- + +### createPath() + +• **createPath**(`path`): [`PathNode`](PathNode.md) + +#### Parameters + +• **path**: `string` + +a string representing any [SVG path element](https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths). +Note that the path data will be normalized, and therefore the `path` getter may return a different SVG string from the path creation input. +For example, "M 10 80 Q 52.5 10, 95 80 T 180 80" becomes "M 10 80 C 38.33 33.33 66.67 33.33 95 80...". +Throws if the input is empty or is not legal SVG path syntax. + + + +Note: the visual top-left corner of a path may not be its local (0,0) origin point, so it's easiest to position +a newly created path using [Node.setPositionInParent](Node.md#setpositioninparent) rather than setting [Node.translation](Node.md#translation) directly. + +#### Returns + +[`PathNode`](PathNode.md) + +a path node with a default stroke and no initial fill. + +#### Inherited from + +[`Editor`](Editor.md).[`createPath`](Editor.md#createpath) + +--- + +### createRectangle() + +• **createRectangle**(): [`RectangleNode`](RectangleNode.md) + +#### Returns + +[`RectangleNode`](RectangleNode.md) + +a rectangle node with default width and height, a black fill, and no initial stroke. +Transform values default to 0. + +#### Inherited from + +[`Editor`](Editor.md).[`createRectangle`](Editor.md#createrectangle) + +--- + +### createText() + +#### createText() + +• **createText**(): [`StandaloneTextNode`](StandaloneTextNode.md) + +##### Returns + +[`StandaloneTextNode`](StandaloneTextNode.md) + +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. + +##### Inherited from + +[`Editor`](Editor.md).[`createText`](Editor.md#createtext) + +##### Deprecated + +- Initial text content is always expected so please use `createText(textContent: string): StandaloneTextNode`. + +#### createText(textContent) + +• **createText**(`textContent`): [`StandaloneTextNode`](StandaloneTextNode.md) + +##### Parameters + +• **textContent**: `string` + +the initial string to show. + +##### Returns + +[`StandaloneTextNode`](StandaloneTextNode.md) + +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. + +##### Inherited from + +[`Editor`](Editor.md).[`createText`](Editor.md#createtext) + +--- + +### loadBitmapImage() + +• **loadBitmapImage**(`bitmapData`): `Promise`<[`BitmapImage`](BitmapImage.md)\> + +Creates a bitmap image resource in the document, which can be displayed in the scenegraph by passing it to [createImageContainer](Editor.md#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](Editor.md#createimagecontainer). See [queueAsyncEdit](Editor.md#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 + +• **bitmapData**: `Blob` + +Encoded image data in PNG or JPEG format. + +#### Returns + +`Promise`<[`BitmapImage`](BitmapImage.md)\> + +#### Inherited from + +[`Editor`](Editor.md).[`loadBitmapImage`](Editor.md#loadbitmapimage) + +--- + +### makeColorFill() + +• **makeColorFill**(`color`): [`ColorFill`](../interfaces/ColorFill.md) + +Convenience helper to create a complete ColorFill value given just its color. + +#### Parameters + +• **color**: [`Color`](../interfaces/Color.md) + +The color to use for the fill. + +#### Returns + +[`ColorFill`](../interfaces/ColorFill.md) + +#### Inherited from + +[`Editor`](Editor.md).[`makeColorFill`](Editor.md#makecolorfill) + +--- + +### makeStroke() + +• **makeStroke**(`options`?): [`SolidColorStroke`](../interfaces/SolidColorStroke.md) + +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](../interfaces/SolidColorStroke.md) 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 + +• **options?**: `Partial`<[`SolidColorStroke`](../interfaces/SolidColorStroke.md)\> + +#### Returns + +[`SolidColorStroke`](../interfaces/SolidColorStroke.md) + +a stroke configured with the given options. + +#### Inherited from + +[`Editor`](Editor.md).[`makeStroke`](Editor.md#makestroke) + +--- + +### 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](Editor.md#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: +```js +// 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 + +• **lambda** + +a function which edits the document model. + +#### Returns + +`Promise`<`void`\> + +a Promise that resolves when the lambda has finished running, or rejects if the lambda throws an error. + +#### Inherited from + +[`Editor`](Editor.md).[`queueAsyncEdit`](Editor.md#queueasyncedit) diff --git a/src/pages/references/document-sandbox/document-apis/classes/Viewport.md b/src/pages/references/document-sandbox/document-apis/classes/ExpressViewport.md similarity index 93% rename from src/pages/references/document-sandbox/document-apis/classes/Viewport.md rename to src/pages/references/document-sandbox/document-apis/classes/ExpressViewport.md index 8ac8464f4..85c3f1b38 100644 --- a/src/pages/references/document-sandbox/document-apis/classes/Viewport.md +++ b/src/pages/references/document-sandbox/document-apis/classes/ExpressViewport.md @@ -1,6 +1,6 @@ -[@express-document-sdk](../overview.md) / Viewport +[@express-document-sdk](../overview.md) / ExpressViewport -# Class: Viewport +# Class: ExpressViewport Represents the area of the canvas that is currently visible on-screen. @@ -18,7 +18,6 @@ to further draw user's attention to the node, set it as the [Context.selection]( After this call, the value of [Context.insertionParent](Context.md#insertionparent) will always be the node containing [ArtboardNode](ArtboardNode.md). Note that the node might still not appear visible if: - - Its animation settings make it invisible at the beginning of the [ArtboardNode](ArtboardNode.md) "scene". - It is obscured underneath other artwork in the z-order. - It is hidden by a [GroupNode](GroupNode.md)'s mask or similar cropping. diff --git a/src/pages/references/document-sandbox/document-apis/classes/GridCellNode.md b/src/pages/references/document-sandbox/document-apis/classes/GridCellNode.md index cefac9e92..34976c6be 100644 --- a/src/pages/references/document-sandbox/document-apis/classes/GridCellNode.md +++ b/src/pages/references/document-sandbox/document-apis/classes/GridCellNode.md @@ -399,9 +399,9 @@ or top/bottom edges. Currently only supports images as the new media, but previo #### Parameters -• **media**: `BitmapImage` +• **media**: [`BitmapImage`](BitmapImage.md) -New content to display. Currently must be a BitmapImage. +New content to display. Currently must be a [BitmapImage](BitmapImage.md). #### Returns diff --git a/src/pages/references/document-sandbox/document-apis/classes/ImageRectangleNode.md b/src/pages/references/document-sandbox/document-apis/classes/ImageRectangleNode.md index 6b045089a..3b41bc8e2 100644 --- a/src/pages/references/document-sandbox/document-apis/classes/ImageRectangleNode.md +++ b/src/pages/references/document-sandbox/document-apis/classes/ImageRectangleNode.md @@ -362,6 +362,22 @@ Clone the entire parent MediaContainerNode instead. --- +### fetchBitmapImage() + +• **fetchBitmapImage**(): `Promise`<[`BitmapImage`](BitmapImage.md)\> + + + +**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`. + +Fetches the bitmap image resource used by this node. This will wait for the bitmap to be available if necessary. + +#### Returns + +`Promise`<[`BitmapImage`](BitmapImage.md)\> + +--- + ### localPointInNode() • **localPointInNode**(`localPoint`, `targetNode`): `Readonly`<[`Point`](../interfaces/Point.md)\> diff --git a/src/pages/references/document-sandbox/document-apis/classes/MediaContainerNode.md b/src/pages/references/document-sandbox/document-apis/classes/MediaContainerNode.md index 7b7c9705d..9bf8166ef 100644 --- a/src/pages/references/document-sandbox/document-apis/classes/MediaContainerNode.md +++ b/src/pages/references/document-sandbox/document-apis/classes/MediaContainerNode.md @@ -405,9 +405,9 @@ or top/bottom edges. Currently only supports images as the new media, but previo #### Parameters -• **media**: `BitmapImage` +• **media**: [`BitmapImage`](BitmapImage.md) -New content to display. Currently must be a BitmapImage. +New content to display. Currently must be a [BitmapImage](BitmapImage.md). #### Returns diff --git a/src/pages/references/document-sandbox/document-apis/classes/StandaloneTextContentModel.md b/src/pages/references/document-sandbox/document-apis/classes/StandaloneTextContentModel.md new file mode 100644 index 000000000..2fc59554e --- /dev/null +++ b/src/pages/references/document-sandbox/document-apis/classes/StandaloneTextContentModel.md @@ -0,0 +1,358 @@ +[@express-document-sdk](../overview.md) / StandaloneTextContentModel + +# Class: StandaloneTextContentModel + +StandaloneTextContentModel represents a complete piece of text content contained within a single [StandaloneTextNode](StandaloneTextNode.md). + +## Extends + +- [`TextNodeContentModel`](TextNodeContentModel.md) + +## Accessors + +### allTextNodes + +• `get` **allTextNodes**(): `Readonly`<`Iterable`<[`StandaloneTextNode`](StandaloneTextNode.md), `any`, `any`\>\> + +Get ordered list of all [TextNode](TextNode.md)s that display this text content in the scenegraph. This might be a single +[StandaloneTextNode](StandaloneTextNode.md) *or* a list of one or more [ThreadedTextNode](ThreadedTextNode.md)s. In the case of threaded text, the +text content starts in the first [ThreadedTextNode](ThreadedTextNode.md) "frame", and then flows into the second node once it has +filled the first one. The ending of the text content may not be visible at all, if the last "frame" is not large +enough to accommodate it. + +All linked ThreadedTextNodes that share a single TextContentModel must remain together within the same artboard. + +#### Returns + +`Readonly`<`Iterable`<[`StandaloneTextNode`](StandaloneTextNode.md), `any`, `any`\>\> + +--- + +### characterStyleRanges + +• `get` **characterStyleRanges**(): readonly [`CharacterStylesRange`](../interfaces/CharacterStylesRange.md)[] + +The character styles that are applied to different ranges of this text content. Each range starts immediately after +the previous one: they are always contiguous, and never overlap. + +When *setting* character styles, any style properties that are not provided are reset to their defaults (contrast to +[applyCharacterStyles](TextContentModel.md#applycharacterstyles) which preserves the text's existing styles for any fields not specified). If the ranges +do not cover the full length of the text, the last range is extended to cover all the remaining text. +When *getting* styles, all fields are always provided. + + + +Note: existing fonts used in the document, returned by this getter, are not guaranteed to be ones the current user +has rights to edit with. The *setter* only accepts the AvailableFont type which has been verified to be usable. + +• `set` **characterStyleRanges**(`styles`): `void` + +#### Parameters + +• **styles**: readonly [`CharacterStylesRangeInput`](../interfaces/CharacterStylesRangeInput.md)[] + +#### Returns + +readonly [`CharacterStylesRange`](../interfaces/CharacterStylesRange.md)[] + +--- + +### id + +• `get` **id**(): `string` + + + +**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`. + +A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is +moved to a different part of the document. + +To determine if two TextNodes are connected to the same TextContentModel, +check if both models have the same id. +Comparing two models using `===` will always fail. + +#### Returns + +`string` + +--- + +### paragraphStyleRanges + +• `get` **paragraphStyleRanges**(): readonly [`ParagraphStylesRange`](../interfaces/ParagraphStylesRange.md)[] + +The styles applied to different paragraphs of this text content. + +• `set` **paragraphStyleRanges**(`styles`): `void` + +Apply styles to different paragraphs of this text content. Any style properties that are not provided are reset to their defaults. +When **getting** styles, all properties are always provided. + +Paragraphs are separated by newline characters (`\n`). The ranges specified here should align with +those boundaries. If multiple ranges provided overlap a single paragraph, the first one to overlap is applied to the +entire paragraph. + +#### Throws + +if applying an ordered-list style when the text contains fonts that are unavailable to the current user. + +#### Parameters + +• **styles**: readonly [`ParagraphStylesRangeInput`](../interfaces/ParagraphStylesRangeInput.md)[] + +#### Returns + +readonly [`ParagraphStylesRange`](../interfaces/ParagraphStylesRange.md)[] + +--- + +### text + +• `get` **text**(): `string` + +The complete text string, which may span multiple [ThreadedTextNode](ThreadedTextNode.md) "frames" in the scenegraph. + +#### Throws + +The setter throws if the existing text contains fonts unavailable to the current user. +See [hasUnavailableFonts](TextContentModel.md#hasunavailablefonts). + +• `set` **text**(`textContent`): `void` + +#### Parameters + +• **textContent**: `string` + +#### Returns + +`string` + +## Methods + +### appendText() + +• **appendText**(`newText`): `void` + + + +**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`. + +Appends a new text string to the end of the text content. + +#### Parameters + +• **newText**: `string` + +The text to append. + +#### Returns + +`void` + +#### Inherited from + +[`TextNodeContentModel`](TextNodeContentModel.md).[`appendText`](TextNodeContentModel.md#appendtext) + +#### Throws + +if the existing text contains fonts unavailable to the current user. See [hasUnavailableFonts](TextContentModel.md#hasunavailablefonts). + +--- + +### applyCharacterStyles() + +• **applyCharacterStyles**(`styles`, `range`?): `void` + +Apply one or more styles to the characters in the given range, leaving any style properties that were not specified +unchanged. Does not modify any styles in the text outside this range. Contrast to the [characterStyleRanges](TextContentModel.md#characterstyleranges) +setter, which specifies new style range(s) for the entire text at once, and resets any unspecified properties back to +default styles. + +Explicitly specifying `link: ""` will remove any hyperlinks present in the existing text. If the `link` style +property is not specified at all, existing links are preserved. + +#### Parameters + +• **styles**: [`CharacterStylesInput`](../interfaces/CharacterStylesInput.md) + +The styles to apply. + +• **range?**: [`TextRange`](../interfaces/TextRange.md) + +The start and length of the character sequence to which the styles should be applied. +If no range is specified, styles will be applied to the entire text content flow. + +#### Returns + +`void` + +#### Inherited from + +[`TextNodeContentModel`](TextNodeContentModel.md).[`applyCharacterStyles`](TextNodeContentModel.md#applycharacterstyles) + +--- + +### applyParagraphStyles() + +• **applyParagraphStyles**(`styles`, `range`?): `void` + +Apply one or more styles to the paragraphs in the given range, leaving any style properties that were not specified +unchanged. Does not modify any styles in the text outside this range. Contrast to the [paragraphStyleRanges](TextContentModel.md#paragraphstyleranges) +setter, which specifies new style range(s) for the entire text at once, and resets any unspecified properties back to +default styles. + +#### Parameters + +• **styles**: [`ParagraphStylesInput`](../interfaces/ParagraphStylesInput.md) + +The styles to apply. + +• **range?**: [`TextRange`](../interfaces/TextRange.md) + +The start and length of character sequence to which the styles should be applied. Styles apply to any +paragraphs that even partially overlap this range. +If range is not specified, the styles will be applied to the entire text content flow. + +#### Returns + +`void` + +#### Inherited from + +[`TextNodeContentModel`](TextNodeContentModel.md).[`applyParagraphStyles`](TextNodeContentModel.md#applyparagraphstyles) + +#### Throws + +if applying an ordered-list style when the text contains fonts that are unavailable to the current user. + +--- + +### deleteText() + +• **deleteText**(`range`): `void` + + + +**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`. + +Deletes a range of text from the content. + +#### Parameters + +• **range**: [`TextRange`](../interfaces/TextRange.md) + +The range of text to delete. + +#### Returns + +`void` + +#### Inherited from + +[`TextNodeContentModel`](TextNodeContentModel.md).[`deleteText`](TextNodeContentModel.md#deletetext) + +#### Throws + +if the existing text contains fonts unavailable to the current user. See [hasUnavailableFonts](TextContentModel.md#hasunavailablefonts). + +--- + +### hasUnavailableFonts() + +• **hasUnavailableFonts**(): `boolean` + + + +**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`. + +Returns true if this text contains any fonts unavailable to the current user. +Currently, if any unavailable fonts are present, the text content cannot be modified and +certain styling changes are limited as well. To remove these restrictions, you must modify +the character styles to use only AvailableFonts. + +#### Returns + +`boolean` + +#### Inherited from + +[`TextNodeContentModel`](TextNodeContentModel.md).[`hasUnavailableFonts`](TextNodeContentModel.md#hasunavailablefonts) + +--- + +### insertText() + +• **insertText**(`newText`, `index`, `style`?): `void` + + + +**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`. + +Inserts a new text string into the text content at the specified index. + +#### Parameters + +• **newText**: `string` + +The text to insert. + +• **index**: `number` + +The index at which to insert the new text. + +• **style?**: [`CharacterStylesInput`](../interfaces/CharacterStylesInput.md) \| [`beforeInsertionPoint`](../namespaces/Constants/enumerations/TextStyleSource.md#beforeinsertionpoint) \| [`afterInsertionPoint`](../namespaces/Constants/enumerations/TextStyleSource.md#afterinsertionpoint) + +Style to use for the new text: either directly provides a style to use, or indicates which + existing text to match the style of. Default: `beforeInsertionPoint`. + +#### Returns + +`void` + +#### Inherited from + +[`TextNodeContentModel`](TextNodeContentModel.md).[`insertText`](TextNodeContentModel.md#inserttext) + +#### Throws + +if the existing text contains fonts unavailable to the current user. See [hasUnavailableFonts](TextContentModel.md#hasunavailablefonts). + +--- + +### replaceText() + +• **replaceText**(`newText`, `replaceRange`, `style`?): `void` + + + +**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`. + +Replaces a range of text with a new text string. + +#### Parameters + +• **newText**: `string` + +The text to replace the range with. + +• **replaceRange**: [`TextRange`](../interfaces/TextRange.md) + +The range of text to replace. + +• **style?**: [`CharacterStylesInput`](../interfaces/CharacterStylesInput.md) \| [`beforeInsertionPoint`](../namespaces/Constants/enumerations/TextStyleSource.md#beforeinsertionpoint) \| [`afterInsertionPoint`](../namespaces/Constants/enumerations/TextStyleSource.md#afterinsertionpoint) \| [`firstReplacedCharacter`](../namespaces/Constants/enumerations/TextStyleSource.md#firstreplacedcharacter) + +Style to use for the new text: either directly provides a style to use, or indicates which + existing text to match the style of. Default: `firstReplacedCharacter`. + +#### Returns + +`void` + +#### Inherited from + +[`TextNodeContentModel`](TextNodeContentModel.md).[`replaceText`](TextNodeContentModel.md#replacetext) + +#### Throws + +if the existing text contains fonts unavailable to the current user. See [hasUnavailableFonts](TextContentModel.md#hasunavailablefonts). diff --git a/src/pages/references/document-sandbox/document-apis/classes/StandaloneTextNode.md b/src/pages/references/document-sandbox/document-apis/classes/StandaloneTextNode.md index f47a0e270..cf510dc38 100644 --- a/src/pages/references/document-sandbox/document-apis/classes/StandaloneTextNode.md +++ b/src/pages/references/document-sandbox/document-apis/classes/StandaloneTextNode.md @@ -129,22 +129,14 @@ recommended to use this property only when the node is placed on a page. ### fullContent -• `get` **fullContent**(): [`TextNodeContentModel`](TextNodeContentModel.md) +• `get` **fullContent**(): [`StandaloneTextContentModel`](StandaloneTextContentModel.md) -The model containing the complete text string and its styles, only part of which may be visible within the bounds of -this specific TextNode "frame." The full text content flow may be split across multiple frames, and/or it may be clipped if a -fixed-size frame using [AreaTextLayout](../interfaces/AreaTextLayout.md) does not fit all the (remaining) text. - - - -Note: When traversing the scenegraph in search of text content, bear in mind that multiple TextNodes may refer to the -same single [TextNodeContentModel](TextNodeContentModel.md); this can give the impression that the same text is duplicated multiple times when it is -not. Use [TextNodeContentModel](TextNodeContentModel.md).id to determine whether a given piece of text content is unique or if it's already been -encountered before. +The model containing the complete text string and its styles, all which will be visible within the bounds of +this specific StandaloneTextNode. #### Returns -[`TextNodeContentModel`](TextNodeContentModel.md) +[`StandaloneTextContentModel`](StandaloneTextContentModel.md) --- @@ -352,8 +344,6 @@ boundsInParent. Note: The top-left of the orphaned TextNode may be different from the top-left of the node placed on a page. It is recommended to use this property only when the node is placed on a page. - - Note: this value is usually not (0,0) due to the way text layout is defined. --- @@ -480,13 +470,13 @@ The node must be attached to a page as the copy will be added as a sibling. • **isStandaloneText**(): `this is StandaloneTextNode` -Helper method to determine if the text is standalone. +Always returns true for this StandaloneTextNode, indicating that it is not part of a multi-frame text flow. #### Returns `this is StandaloneTextNode` -#### Inherited from +#### Overrides [`TextNode`](TextNode.md).[`isStandaloneText`](TextNode.md#isstandalonetext) diff --git a/src/pages/references/document-sandbox/document-apis/classes/TextNode.md b/src/pages/references/document-sandbox/document-apis/classes/TextNode.md index 6f2aa6514..5f85df56f 100644 --- a/src/pages/references/document-sandbox/document-apis/classes/TextNode.md +++ b/src/pages/references/document-sandbox/document-apis/classes/TextNode.md @@ -135,7 +135,7 @@ recommended to use this property only when the node is placed on a page. ### fullContent -• `get` **fullContent**(): [`TextNodeContentModel`](TextNodeContentModel.md) +• `get` `abstract` **fullContent**(): [`TextNodeContentModel`](TextNodeContentModel.md) The model containing the complete text string and its styles, only part of which may be visible within the bounds of this specific TextNode "frame." The full text content flow may be split across multiple frames, and/or it may be clipped if a diff --git a/src/pages/references/document-sandbox/document-apis/classes/TextNodeContentModel.md b/src/pages/references/document-sandbox/document-apis/classes/TextNodeContentModel.md index fefaa3046..f25046688 100644 --- a/src/pages/references/document-sandbox/document-apis/classes/TextNodeContentModel.md +++ b/src/pages/references/document-sandbox/document-apis/classes/TextNodeContentModel.md @@ -1,6 +1,6 @@ [@express-document-sdk](../overview.md) / TextNodeContentModel -# Class: TextNodeContentModel +# Class: `abstract` TextNodeContentModel Represents a complete piece of text content, which may be contained within a single [StandaloneTextNode](StandaloneTextNode.md) *or* split across multiple [ThreadedTextNode](ThreadedTextNode.md) frames for display. @@ -10,11 +10,16 @@ Use this model to get or modify the text string and the style ranges applied to - [`TextContentModel`](TextContentModel.md) +## Extended by + +- [`StandaloneTextContentModel`](StandaloneTextContentModel.md) +- [`ThreadedTextContentModel`](ThreadedTextContentModel.md) + ## Accessors ### allTextNodes -• `get` **allTextNodes**(): `Readonly`<`Iterable`<[`TextNode`](TextNode.md), `any`, `any`\>\> +• `get` `abstract` **allTextNodes**(): `Readonly`<`Iterable`<[`TextNode`](TextNode.md), `any`, `any`\>\> Get ordered list of all [TextNode](TextNode.md)s that display this text content in the scenegraph. This might be a single [StandaloneTextNode](StandaloneTextNode.md) *or* a list of one or more [ThreadedTextNode](ThreadedTextNode.md)s. In the case of threaded text, the diff --git a/src/pages/references/document-sandbox/document-apis/classes/ThreadedTextContentModel.md b/src/pages/references/document-sandbox/document-apis/classes/ThreadedTextContentModel.md new file mode 100644 index 000000000..c3ec14888 --- /dev/null +++ b/src/pages/references/document-sandbox/document-apis/classes/ThreadedTextContentModel.md @@ -0,0 +1,363 @@ +[@express-document-sdk](../overview.md) / ThreadedTextContentModel + +# Class: ThreadedTextContentModel + +ThreadedTextContentModel represents a complete piece of text content that is split across multiple +[ThreadedTextNode](ThreadedTextNode.md) frames for display. This subclass provides a mutable allFrames list +that supports adding, removing, and reordering text frames. + +The append and insert operations will automatically parent the new frame to the same parent as the +reference frame and place it in the correct z-order. + +## Extends + +- [`TextNodeContentModel`](TextNodeContentModel.md) + +## Accessors + +### allTextNodes + +• `get` **allTextNodes**(): `Readonly`<`Iterable`<[`ThreadedTextNode`](ThreadedTextNode.md), `any`, `any`\>\> + +Get ordered list of all [TextNode](TextNode.md)s that display this text content in the scenegraph. This might be a single +[StandaloneTextNode](StandaloneTextNode.md) *or* a list of one or more [ThreadedTextNode](ThreadedTextNode.md)s. In the case of threaded text, the +text content starts in the first [ThreadedTextNode](ThreadedTextNode.md) "frame", and then flows into the second node once it has +filled the first one. The ending of the text content may not be visible at all, if the last "frame" is not large +enough to accommodate it. + +All linked ThreadedTextNodes that share a single TextContentModel must remain together within the same artboard. + +#### Returns + +`Readonly`<`Iterable`<[`ThreadedTextNode`](ThreadedTextNode.md), `any`, `any`\>\> + +--- + +### characterStyleRanges + +• `get` **characterStyleRanges**(): readonly [`CharacterStylesRange`](../interfaces/CharacterStylesRange.md)[] + +The character styles that are applied to different ranges of this text content. Each range starts immediately after +the previous one: they are always contiguous, and never overlap. + +When *setting* character styles, any style properties that are not provided are reset to their defaults (contrast to +[applyCharacterStyles](TextContentModel.md#applycharacterstyles) which preserves the text's existing styles for any fields not specified). If the ranges +do not cover the full length of the text, the last range is extended to cover all the remaining text. +When *getting* styles, all fields are always provided. + + + +Note: existing fonts used in the document, returned by this getter, are not guaranteed to be ones the current user +has rights to edit with. The *setter* only accepts the AvailableFont type which has been verified to be usable. + +• `set` **characterStyleRanges**(`styles`): `void` + +#### Parameters + +• **styles**: readonly [`CharacterStylesRangeInput`](../interfaces/CharacterStylesRangeInput.md)[] + +#### Returns + +readonly [`CharacterStylesRange`](../interfaces/CharacterStylesRange.md)[] + +--- + +### id + +• `get` **id**(): `string` + + + +**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`. + +A unique identifier for this node that stays the same when the file is closed & reopened, or if the node is +moved to a different part of the document. + +To determine if two TextNodes are connected to the same TextContentModel, +check if both models have the same id. +Comparing two models using `===` will always fail. + +#### Returns + +`string` + +--- + +### paragraphStyleRanges + +• `get` **paragraphStyleRanges**(): readonly [`ParagraphStylesRange`](../interfaces/ParagraphStylesRange.md)[] + +The styles applied to different paragraphs of this text content. + +• `set` **paragraphStyleRanges**(`styles`): `void` + +Apply styles to different paragraphs of this text content. Any style properties that are not provided are reset to their defaults. +When **getting** styles, all properties are always provided. + +Paragraphs are separated by newline characters (`\n`). The ranges specified here should align with +those boundaries. If multiple ranges provided overlap a single paragraph, the first one to overlap is applied to the +entire paragraph. + +#### Throws + +if applying an ordered-list style when the text contains fonts that are unavailable to the current user. + +#### Parameters + +• **styles**: readonly [`ParagraphStylesRangeInput`](../interfaces/ParagraphStylesRangeInput.md)[] + +#### Returns + +readonly [`ParagraphStylesRange`](../interfaces/ParagraphStylesRange.md)[] + +--- + +### text + +• `get` **text**(): `string` + +The complete text string, which may span multiple [ThreadedTextNode](ThreadedTextNode.md) "frames" in the scenegraph. + +#### Throws + +The setter throws if the existing text contains fonts unavailable to the current user. +See [hasUnavailableFonts](TextContentModel.md#hasunavailablefonts). + +• `set` **text**(`textContent`): `void` + +#### Parameters + +• **textContent**: `string` + +#### Returns + +`string` + +## Methods + +### appendText() + +• **appendText**(`newText`): `void` + + + +**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`. + +Appends a new text string to the end of the text content. + +#### Parameters + +• **newText**: `string` + +The text to append. + +#### Returns + +`void` + +#### Inherited from + +[`TextNodeContentModel`](TextNodeContentModel.md).[`appendText`](TextNodeContentModel.md#appendtext) + +#### Throws + +if the existing text contains fonts unavailable to the current user. See [hasUnavailableFonts](TextContentModel.md#hasunavailablefonts). + +--- + +### applyCharacterStyles() + +• **applyCharacterStyles**(`styles`, `range`?): `void` + +Apply one or more styles to the characters in the given range, leaving any style properties that were not specified +unchanged. Does not modify any styles in the text outside this range. Contrast to the [characterStyleRanges](TextContentModel.md#characterstyleranges) +setter, which specifies new style range(s) for the entire text at once, and resets any unspecified properties back to +default styles. + +Explicitly specifying `link: ""` will remove any hyperlinks present in the existing text. If the `link` style +property is not specified at all, existing links are preserved. + +#### Parameters + +• **styles**: [`CharacterStylesInput`](../interfaces/CharacterStylesInput.md) + +The styles to apply. + +• **range?**: [`TextRange`](../interfaces/TextRange.md) + +The start and length of the character sequence to which the styles should be applied. +If no range is specified, styles will be applied to the entire text content flow. + +#### Returns + +`void` + +#### Inherited from + +[`TextNodeContentModel`](TextNodeContentModel.md).[`applyCharacterStyles`](TextNodeContentModel.md#applycharacterstyles) + +--- + +### applyParagraphStyles() + +• **applyParagraphStyles**(`styles`, `range`?): `void` + +Apply one or more styles to the paragraphs in the given range, leaving any style properties that were not specified +unchanged. Does not modify any styles in the text outside this range. Contrast to the [paragraphStyleRanges](TextContentModel.md#paragraphstyleranges) +setter, which specifies new style range(s) for the entire text at once, and resets any unspecified properties back to +default styles. + +#### Parameters + +• **styles**: [`ParagraphStylesInput`](../interfaces/ParagraphStylesInput.md) + +The styles to apply. + +• **range?**: [`TextRange`](../interfaces/TextRange.md) + +The start and length of character sequence to which the styles should be applied. Styles apply to any +paragraphs that even partially overlap this range. +If range is not specified, the styles will be applied to the entire text content flow. + +#### Returns + +`void` + +#### Inherited from + +[`TextNodeContentModel`](TextNodeContentModel.md).[`applyParagraphStyles`](TextNodeContentModel.md#applyparagraphstyles) + +#### Throws + +if applying an ordered-list style when the text contains fonts that are unavailable to the current user. + +--- + +### deleteText() + +• **deleteText**(`range`): `void` + + + +**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`. + +Deletes a range of text from the content. + +#### Parameters + +• **range**: [`TextRange`](../interfaces/TextRange.md) + +The range of text to delete. + +#### Returns + +`void` + +#### Inherited from + +[`TextNodeContentModel`](TextNodeContentModel.md).[`deleteText`](TextNodeContentModel.md#deletetext) + +#### Throws + +if the existing text contains fonts unavailable to the current user. See [hasUnavailableFonts](TextContentModel.md#hasunavailablefonts). + +--- + +### hasUnavailableFonts() + +• **hasUnavailableFonts**(): `boolean` + + + +**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`. + +Returns true if this text contains any fonts unavailable to the current user. +Currently, if any unavailable fonts are present, the text content cannot be modified and +certain styling changes are limited as well. To remove these restrictions, you must modify +the character styles to use only AvailableFonts. + +#### Returns + +`boolean` + +#### Inherited from + +[`TextNodeContentModel`](TextNodeContentModel.md).[`hasUnavailableFonts`](TextNodeContentModel.md#hasunavailablefonts) + +--- + +### insertText() + +• **insertText**(`newText`, `index`, `style`?): `void` + + + +**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`. + +Inserts a new text string into the text content at the specified index. + +#### Parameters + +• **newText**: `string` + +The text to insert. + +• **index**: `number` + +The index at which to insert the new text. + +• **style?**: [`CharacterStylesInput`](../interfaces/CharacterStylesInput.md) \| [`beforeInsertionPoint`](../namespaces/Constants/enumerations/TextStyleSource.md#beforeinsertionpoint) \| [`afterInsertionPoint`](../namespaces/Constants/enumerations/TextStyleSource.md#afterinsertionpoint) + +Style to use for the new text: either directly provides a style to use, or indicates which + existing text to match the style of. Default: `beforeInsertionPoint`. + +#### Returns + +`void` + +#### Inherited from + +[`TextNodeContentModel`](TextNodeContentModel.md).[`insertText`](TextNodeContentModel.md#inserttext) + +#### Throws + +if the existing text contains fonts unavailable to the current user. See [hasUnavailableFonts](TextContentModel.md#hasunavailablefonts). + +--- + +### replaceText() + +• **replaceText**(`newText`, `replaceRange`, `style`?): `void` + + + +**IMPORTANT:** This is currently ***experimental only*** and should not be used in any add-ons you will be distributing until it has been declared stable. To use it, you will first need to set the `experimentalApis` flag to `true` in the [`requirements`](../../../manifest/index.md#requirements) section of the `manifest.json`. + +Replaces a range of text with a new text string. + +#### Parameters + +• **newText**: `string` + +The text to replace the range with. + +• **replaceRange**: [`TextRange`](../interfaces/TextRange.md) + +The range of text to replace. + +• **style?**: [`CharacterStylesInput`](../interfaces/CharacterStylesInput.md) \| [`beforeInsertionPoint`](../namespaces/Constants/enumerations/TextStyleSource.md#beforeinsertionpoint) \| [`afterInsertionPoint`](../namespaces/Constants/enumerations/TextStyleSource.md#afterinsertionpoint) \| [`firstReplacedCharacter`](../namespaces/Constants/enumerations/TextStyleSource.md#firstreplacedcharacter) + +Style to use for the new text: either directly provides a style to use, or indicates which + existing text to match the style of. Default: `firstReplacedCharacter`. + +#### Returns + +`void` + +#### Inherited from + +[`TextNodeContentModel`](TextNodeContentModel.md).[`replaceText`](TextNodeContentModel.md#replacetext) + +#### Throws + +if the existing text contains fonts unavailable to the current user. See [hasUnavailableFonts](TextContentModel.md#hasunavailablefonts). diff --git a/src/pages/references/document-sandbox/document-apis/classes/ThreadedTextNode.md b/src/pages/references/document-sandbox/document-apis/classes/ThreadedTextNode.md index 851b81f18..fee6899ed 100644 --- a/src/pages/references/document-sandbox/document-apis/classes/ThreadedTextNode.md +++ b/src/pages/references/document-sandbox/document-apis/classes/ThreadedTextNode.md @@ -127,21 +127,21 @@ recommended to use this property only when the node is placed on a page. ### fullContent -• `get` **fullContent**(): [`TextNodeContentModel`](TextNodeContentModel.md) +• `get` **fullContent**(): [`ThreadedTextContentModel`](ThreadedTextContentModel.md) The model containing the complete text string and its styles, only part of which may be visible within the bounds of -this specific TextNode "frame." The full text content flow may be split across multiple frames, and/or it may be clipped if a +this specific ThreadedTextNode "frame." The full text content flow may be split across multiple frames, and/or it may be clipped if a fixed-size frame using [AreaTextLayout](../interfaces/AreaTextLayout.md) does not fit all the (remaining) text. -Note: When traversing the scenegraph in search of text content, bear in mind that multiple TextNodes may refer to the -same single [TextNodeContentModel](TextNodeContentModel.md); this can give the impression that the same text is duplicated multiple times when it is -not. Use [TextNodeContentModel](TextNodeContentModel.md).id to determine whether a given piece of text content is unique or if it's already been +Note: When traversing the scenegraph in search of text content, bear in mind that multiple ThreadedTextNodes may refer to the +same single [ThreadedTextContentModel](ThreadedTextContentModel.md); this can give the impression that the same text is duplicated multiple times when it is +not. Use [ThreadedTextContentModel](ThreadedTextContentModel.md).id to determine whether a given piece of text content is unique or if it's already been encountered before. #### Returns -[`TextNodeContentModel`](TextNodeContentModel.md) +[`ThreadedTextContentModel`](ThreadedTextContentModel.md) --- @@ -484,13 +484,13 @@ Helper method to determine if the text is standalone. • **isThreadedText**(): `this is ThreadedTextNode` -Helper method to determine if the text is in a flow. +Always returns true for this ThreadedTextNode, indicating that it is part of a multi-frame text flow. #### Returns `this is ThreadedTextNode` -#### Inherited from +#### Overrides [`TextNode`](TextNode.md).[`isThreadedText`](TextNode.md#isthreadedtext) diff --git a/src/pages/references/document-sandbox/document-apis/interfaces/IMediaContainerNode.md b/src/pages/references/document-sandbox/document-apis/interfaces/IMediaContainerNode.md index 41d7ee603..605af7634 100644 --- a/src/pages/references/document-sandbox/document-apis/interfaces/IMediaContainerNode.md +++ b/src/pages/references/document-sandbox/document-apis/interfaces/IMediaContainerNode.md @@ -42,9 +42,9 @@ or top/bottom edges. Currently only supports images as the new media, but previo #### Parameters -• **media**: `BitmapImage` +• **media**: [`BitmapImage`](../classes/BitmapImage.md) -New content to display. Currently must be a BitmapImage. +New content to display. Currently must be a [BitmapImage](../classes/BitmapImage.md). #### Returns diff --git a/src/pages/references/document-sandbox/document-apis/overview.md b/src/pages/references/document-sandbox/document-apis/overview.md index 75fd7a7d0..2798ee4c4 100644 --- a/src/pages/references/document-sandbox/document-apis/overview.md +++ b/src/pages/references/document-sandbox/document-apis/overview.md @@ -27,12 +27,16 @@ - [AvailableFont](classes/AvailableFont.md) - [BaseFont](classes/BaseFont.md) - [BaseNode](classes/BaseNode.md) +- [BitmapImage](classes/BitmapImage.md) - [ColorUtils](classes/ColorUtils.md) - [ComplexShapeNode](classes/ComplexShapeNode.md) - [Context](classes/Context.md) - [Editor](classes/Editor.md) - [EllipseNode](classes/EllipseNode.md) +- [ExpressContext](classes/ExpressContext.md) +- [ExpressEditor](classes/ExpressEditor.md) - [ExpressRootNode](classes/ExpressRootNode.md) +- [ExpressViewport](classes/ExpressViewport.md) - [FillableNode](classes/FillableNode.md) - [Fonts](classes/Fonts.md) - [GridCellNode](classes/GridCellNode.md) @@ -52,17 +56,18 @@ - [RectangleNode](classes/RectangleNode.md) - [RestrictedItemList](classes/RestrictedItemList.md) - [SolidColorShapeNode](classes/SolidColorShapeNode.md) +- [StandaloneTextContentModel](classes/StandaloneTextContentModel.md) - [StandaloneTextNode](classes/StandaloneTextNode.md) - [StrokableNode](classes/StrokableNode.md) - [StrokeShapeNode](classes/StrokeShapeNode.md) - [TextContentModel](classes/TextContentModel.md) - [TextNode](classes/TextNode.md) - [TextNodeContentModel](classes/TextNodeContentModel.md) +- [ThreadedTextContentModel](classes/ThreadedTextContentModel.md) - [ThreadedTextNode](classes/ThreadedTextNode.md) - [UnavailableFont](classes/UnavailableFont.md) - [UnknownMediaRectangleNode](classes/UnknownMediaRectangleNode.md) - [UnknownNode](classes/UnknownNode.md) -- [Viewport](classes/Viewport.md) - [VisualNode](classes/VisualNode.md) ## Interfaces From 36ef20c707ccf74f3bc721fb59d0e515ea631d42 Mon Sep 17 00:00:00 2001 From: Vamshi Date: Thu, 20 Nov 2025 23:53:30 +0530 Subject: [PATCH 2/3] lint fix --- .../document-apis/classes/ExpressContext.md | 2 +- .../document-apis/classes/ExpressEditor.md | 10 ++++++---- .../document-apis/classes/ExpressViewport.md | 1 + 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/src/pages/references/document-sandbox/document-apis/classes/ExpressContext.md b/src/pages/references/document-sandbox/document-apis/classes/ExpressContext.md index d8abf0572..674b82501 100644 --- a/src/pages/references/document-sandbox/document-apis/classes/ExpressContext.md +++ b/src/pages/references/document-sandbox/document-apis/classes/ExpressContext.md @@ -86,7 +86,7 @@ selection (see [selectionIncludingNonEditable](Context.md#selectionincludingnone readonly [`Node`](Node.md)[] -the current selection *and* any locked nodes the user has attempted to select at the same time. This can +the current selection _and_ any locked nodes the user has attempted to select at the same time. This can happen for example if the user clicks on a locked node or if the user drags a selection marquee that overlaps locked nodes in addition to regular unlocked nodes. diff --git a/src/pages/references/document-sandbox/document-apis/classes/ExpressEditor.md b/src/pages/references/document-sandbox/document-apis/classes/ExpressEditor.md index 9578833d7..1dfe8b32d 100644 --- a/src/pages/references/document-sandbox/document-apis/classes/ExpressEditor.md +++ b/src/pages/references/document-sandbox/document-apis/classes/ExpressEditor.md @@ -88,9 +88,10 @@ BitmapImage resource (e.g. returned from [loadBitmapImage](Editor.md#loadbitmapi • **options**= `{}` Additional configuration: - - initialSize - Size the image is displayed at. Must have the same aspect ratio as bitmapData. Defaults to the - size the image would be created at by a UI drag-drop gesture (typically the image's full size, but scaled down - if needed to stay below an application-defined size cap). + +- `initialSize` - Size the image is displayed at. Must have the same aspect ratio as `bitmapData`. Defaults to the + size the image would be created at by a UI drag-drop gesture (typically the image's full size, but scaled down + if needed to stay below an application-defined size cap). • **options.initialSize?**: [`RectangleGeometry`](../interfaces/RectangleGeometry.md) @@ -316,13 +317,14 @@ asynchronous operation such as [loadBitmapImage](Editor.md#loadbitmapimage), any 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. +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: + ```js // Assume insertImage() is called from your UI code, and given a Blob containing image data async function insertImage(blob) { diff --git a/src/pages/references/document-sandbox/document-apis/classes/ExpressViewport.md b/src/pages/references/document-sandbox/document-apis/classes/ExpressViewport.md index 85c3f1b38..76501e2b1 100644 --- a/src/pages/references/document-sandbox/document-apis/classes/ExpressViewport.md +++ b/src/pages/references/document-sandbox/document-apis/classes/ExpressViewport.md @@ -18,6 +18,7 @@ to further draw user's attention to the node, set it as the [Context.selection]( After this call, the value of [Context.insertionParent](Context.md#insertionparent) will always be the node containing [ArtboardNode](ArtboardNode.md). Note that the node might still not appear visible if: + - Its animation settings make it invisible at the beginning of the [ArtboardNode](ArtboardNode.md) "scene". - It is obscured underneath other artwork in the z-order. - It is hidden by a [GroupNode](GroupNode.md)'s mask or similar cropping. From 869647b119ccb6d3cfcc7800ac70bdc45e16abfc Mon Sep 17 00:00:00 2001 From: Vamshi Date: Fri, 21 Nov 2025 00:12:55 +0530 Subject: [PATCH 3/3] Update StandaloneTextNode.md --- .../document-apis/classes/StandaloneTextNode.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/pages/references/document-sandbox/document-apis/classes/StandaloneTextNode.md b/src/pages/references/document-sandbox/document-apis/classes/StandaloneTextNode.md index cf510dc38..8aadd6b94 100644 --- a/src/pages/references/document-sandbox/document-apis/classes/StandaloneTextNode.md +++ b/src/pages/references/document-sandbox/document-apis/classes/StandaloneTextNode.md @@ -344,6 +344,8 @@ boundsInParent. Note: The top-left of the orphaned TextNode may be different from the top-left of the node placed on a page. It is recommended to use this property only when the node is placed on a page. + + Note: this value is usually not (0,0) due to the way text layout is defined. ---