SceneApi

interface SceneApi

Functions

Link copied to clipboard
abstract fun addMarker(name: String, time: Double, duration: Double = 0.0)

Add a marker to the end of the current scene's marker list. Markers name points or spans on the scene timeline. Several markers may share a name. Experimental: this API may change in a minor release.

Link copied to clipboard
abstract suspend fun applyTemplate(templateUri: Uri)
abstract suspend fun applyTemplate(template: String)

Applies the contents of the given template scene to the currently loaded scene. This loads the template scene while keeping the design unit and page dimensions of the current scene. The content of the pages is automatically adjusted to fit the new dimensions. The current scene keeps its variables and value sets, and gains those of the template that it lacks.

Link copied to clipboard
abstract fun create(sceneLayout: SceneLayout = SceneLayout.FREE): DesignBlock

Create a new scene, along with its own camera.

abstract fun create(designUnit: DesignUnit, fontSizeUnit: FontUnit? = null, sceneLayout: SceneLayout = SceneLayout.FREE, angleUnit: AngleUnit = AngleUnit.RADIAN): DesignBlock

Create a new scene with explicit design, font-size and angle units.

Link copied to clipboard
abstract fun createForVideo(): DesignBlock

Create a new scene in video mode, along with its own camera.

Link copied to clipboard
abstract suspend fun createFromImage(imageUri: Uri, dpi: Float = 300.0f, pixelScaleFactor: Float = 1.0f, sceneLayout: SceneLayout = SceneLayout.FREE): DesignBlock

Loads the given image and creates a scene with a single page showing the image. Fetching the image may take an arbitrary amount of time, so the scene isn't immediately available.

Link copied to clipboard
abstract suspend fun createFromVideo(videoUri: Uri): DesignBlock

Loads the given video and creates a scene with a single page showing the video. Fetching the video may take an arbitrary amount of time, so the scene isn't immediately available.

Link copied to clipboard

Disables any previously set position clamping for the current scene.

Link copied to clipboard

Disables previously set zoom clamping for the current scene.

Link copied to clipboard
abstract fun disableZoomAutoFit(block: DesignBlock)

Disables any previously set zoom auto-fit.

Link copied to clipboard
abstract fun enableCameraPositionClamping(blocks: List<DesignBlock>, paddingLeft: Float = 0.0f, paddingTop: Float = 0.0f, paddingRight: Float = 0.0f, paddingBottom: Float = 0.0f, scaledPaddingLeft: Float = 0.0f, scaledPaddingTop: Float = 0.0f, scaledPaddingRight: Float = 0.0f, scaledPaddingBottom: Float = 0.0f)

Continually ensures the camera position to be within the width and height of the blocks axis-aligned bounding box. Without padding, this results in a tight clamp on the blocks. Disables any previously set camera position clamping in the scene and also takes priority over clamp camera commands.

Link copied to clipboard
abstract fun enableCameraZoomClamping(blocks: List<DesignBlock>, minZoomLimit: Float = -1.0F, maxZoomLimit: Float = -1.0F, paddingLeft: Float = 0.0f, paddingTop: Float = 0.0f, paddingRight: Float = 0.0f, paddingBottom: Float = 0.0f)

Continually ensures the zoom level of the camera in the active scene to be in the given range.

Link copied to clipboard
abstract fun enableZoomAutoFit(block: DesignBlock, axis: ZoomAutoFitAxis, paddingLeft: Float = 0.0f, paddingTop: Float = 0.0f, paddingRight: Float = 0.0f, paddingBottom: Float = 0.0f)

Continually adjusts the zoom level to fit the width or height of a block's axis-aligned bounding box. This only shows an effect if the zoom level is not handled/overwritten by the UI. Without padding, this results in a tight view on the block. No more than one block per scene can have zoom auto-fit enabled. Calling setZoomLevel or zoomToBlock disables the continuous adjustment.

Link copied to clipboard

Finds all blocks with the given kind sorted by distance to viewport center.

Link copied to clipboard

Finds all blocks with the given type sorted by distance to viewport center.

Link copied to clipboard
abstract fun get(): DesignBlock?

Return the currently active scene.

Link copied to clipboard
abstract fun getAngleUnit(): AngleUnit

Returns the angle unit of the current scene.

Link copied to clipboard

What the document stores about its CMYK profile.

Link copied to clipboard

How a color that the destination cannot reproduce is mapped into it.

Link copied to clipboard
abstract fun getCurrentPage(): DesignBlock?

Get the current page, i.e., the page of the first selected element if this page is at least 25% visible or, otherwise, the page nearest to the viewport center.

Link copied to clipboard

Get the pages that single page mode shows.

Link copied to clipboard
abstract fun getDesignUnit(): DesignUnit

Returns the design unit of the current scene.

Link copied to clipboard

Returns a slot's reference without loading it. Fallback profiles are not reported.

Link copied to clipboard
abstract fun getFontSizeUnit(): FontUnit

Returns the font-size unit of the current scene.

Link copied to clipboard
abstract fun getLayout(): SceneLayout

Get the current scene layout.

Link copied to clipboard
abstract fun getMarkers(): List<SceneMarker>

Get the markers of the current scene in the order they were added. Experimental: this API may change in a minor release.

Link copied to clipboard
abstract fun getMode(): SceneMode

Get the current scene mode.

Link copied to clipboard
abstract fun getPages(): List<DesignBlock>

Get the sorted list of pages in the scene.

Link copied to clipboard
abstract fun getZoomLevel(): Float

Get the zoom level of the scene or for a camera in the scene. Returns the current zoom level of the scene in unit dpx/dot. A zoom level of 2F results in one dot in the design to be two pixels on the screen.

Link copied to clipboard
abstract fun immediateZoomToBlock(block: DesignBlock, paddingLeft: Float = 0.0f, paddingTop: Float = 0.0f, paddingRight: Float = 0.0f, paddingBottom: Float = 0.0f, forceUpdate: Boolean = false)

Sets the zoom and focus to show a block. This only shows an effect if the zoom level is not handled/overwritten by the UI. Without padding, this results in a tight view on the block. It is set immediately and assumes that the block dimensions are known. The block should not be in pending state and it's layout should be up to date.

Link copied to clipboard

Whether conversion maps the black point of the source onto the destination.

Link copied to clipboard

Queries whether position clamping is enabled for blockOrScene.

Link copied to clipboard
abstract fun isCameraZoomClampingEnabled(blockOrScene: DesignBlock): Boolean

Queries whether zoom clamping is enabled.

Link copied to clipboard

Queries whether zoom auto-fit is enabled for block.

Link copied to clipboard
abstract suspend fun load(sceneUri: Uri, overrideEditorConfig: Boolean = false, waitForResources: Boolean = false, onProgress: (Int) -> Unit? = null): DesignBlock

Load a scene from the resource of a scene or archive file. The file will be fetched asynchronously by the engine and loaded as an archive or as a scene file depending on its content. This loads .imgly files as well as the legacy .scene and .zip formats.

abstract suspend fun load(scene: String, overrideEditorConfig: Boolean = false, waitForResources: Boolean = false, onProgress: (Int) -> Unit? = null): DesignBlock

Load the contents of a scene file.

Link copied to clipboard
abstract suspend fun loadArchive(archiveUri: Uri, overrideEditorConfig: Boolean = false, waitForResources: Boolean = false, onProgress: (Int) -> Unit? = null): DesignBlock

Load the contents of a scene previously saved as an archive.

Link copied to clipboard
abstract fun onActiveChanged(): Flow<Unit>

Subscribe to changes to be called whenever the active scene changes. This may happen upon scene load or creation of a new scene.

Link copied to clipboard
abstract fun onZoomLevelChanged(): Flow<Unit>

Subscribe to changes to the zoom level.

Link copied to clipboard
abstract fun removeCMYKProfile()

Removes the CMYK profile from the document.

Link copied to clipboard

Removes one profile and supersedes its pending assignment. Other slots stay unchanged. Removing Default/CMYK restores fallback resolution. Removing an empty slot succeeds.

Link copied to clipboard
abstract fun removeMarker(index: Int)

Remove a marker from the current scene. Experimental: this API may change in a minor release.

Link copied to clipboard
abstract suspend fun saveToArchive(scene: DesignBlock, options: SaveToArchiveOptions = SaveToArchiveOptions()): ByteBuffer

Saves the current scene and all of its referenced assets into an archive. The archive contains all assets, that were accessible when this function was called. Blocks in the archived scene reference assets relative from to the location of the scene file. These references are resolved when loading such a scene via load.

Link copied to clipboard
abstract suspend fun saveToString(scene: DesignBlock, allowedResourceSchemes: List<String> = listOf("blob", "bundle", "file", "http", "https")): String

Serializes the current scene into a string. Selection is discarded. If a resource uri has a scheme that is not in allowedResourceSchemes, an exception will be thrown.

abstract suspend fun saveToString(scene: DesignBlock, options: SaveToStringOptions): String

Serializes the current scene into a string with optional compression. Selection is discarded. If a resource uri has a scheme that is not in options.allowedResourceSchemes, an exception will be thrown.

Link copied to clipboard
abstract fun setAngleUnit(angleUnit: AngleUnit)

Sets the unit in which angles are interpreted on the current scene: the values of every angle property for BlockApi.setFloat / BlockApi.getFloat (rotation, transform/skew, effect/linear_wipe/angle, ...), their keyframe values, and BlockApi.setRotation / BlockApi.getRotation. The engine stores angles in radians and scene files keep their format; this only affects how values are interpreted at the API boundary. AngleUnit.RADIAN is the default.

Link copied to clipboard

Turns black point compensation of the document on or off.

Link copied to clipboard
abstract suspend fun setCMYKProfile(uri: Uri)

Loads the ICC profile at uri and makes it the CMYK profile of the document. Assigns to the slot with role Default and color space CMYK.

Link copied to clipboard

Makes the ICC profile in data the CMYK profile of the document. Assigns to the slot with role Default and color space CMYK.

Link copied to clipboard

Sets how a color that the destination cannot reproduce is mapped into it.

Link copied to clipboard
abstract fun setCurrentPages(pages: List<DesignBlock>)

Set the pages that single page mode shows. All other pages leave the view but stay in the document and in the saved file. Takes visible effect while the setting features/singlePageModeEnabled is enabled. Exporting a page holds that page, even while it is out of view. Exporting a scene holds every page, except pages hidden with setVisible.

Link copied to clipboard
abstract fun setDesignUnit(designUnit: DesignUnit)

Converts all values of the current scene into the given design unit.

Link copied to clipboard
abstract suspend fun setDocumentColorProfile(slot: ProfileSlot, uri: Uri)

Assigns an ICC profile to one document role and component space. Profiles save with the scene and are bundled into archives. Only Default/CMYK currently affects managed conversion; other slots store profiles without changing rendering or export. Failure or coroutine cancellation keeps the previous profile. Another assignment or removal in this slot, or scene replacement, supersedes pending loading. Other slots are independent. Undo and redo do not change profiles.

Link copied to clipboard

Assigns ICC bytes synchronously, with the same slots and persistence as setDocumentColorProfile. The engine copies the bytes and keeps one buffer per distinct profile for its lifetime. saveToString stores a buffer URI readable only by this engine; use an archive to retain bytes. To save a URL instead, upload the bytes that findAllTransientResources lists and call relocateResource before saving.

Link copied to clipboard
abstract fun setFontSizeUnit(fontSizeUnit: FontUnit)

Sets the unit in which font sizes for BlockApi.setTextFontSize / BlockApi.getTextFontSizes are interpreted. The engine continues to store font sizes in points internally; this only affects API-boundary interpretation.

Link copied to clipboard
abstract fun setLayout(layout: SceneLayout)

Set the scene layout. This will handle all necessary conversions including creating or destroying stack blocks and reparenting pages as needed. When transitioning from stack layouts (VerticalStack, HorizontalStack, DepthStack) to Free layout, the global positions of pages are preserved to maintain their visual appearance in the scene.

Link copied to clipboard
abstract fun setMode(mode: SceneMode)

Set the scene mode. Changing the scene mode affects how the engine processes and renders the scene:

Link copied to clipboard
abstract fun setZoomLevel(level: Float)

Set the zoom level of the scene, e.g., for headless versions. This only shows an effect if the zoom level is not handled/overwritten by the UI. Setting a zoom level of 2F results in one dot in the design to be two pixels on the screen.

Link copied to clipboard
abstract suspend fun zoomToBlock(block: DesignBlock, paddingLeft: Float = 0.0f, paddingTop: Float = 0.0f, paddingRight: Float = 0.0f, paddingBottom: Float = 0.0f)

Sets the zoom and focus to show a block. Without padding, this results in a tight view on the block. It is set asynchronous to ensure that the block dimensions are known.